فهرستِ مطالبِ کنارِ صفحه با یک ریلِ نقطه‌چین و یک هواپیمای کاغذی که با اسکرول رویش سفر می‌کند: نرم جلو می‌رود، روی زیرسرفصل‌ها می‌پیچد و اگر برگردید می‌چرخد و برمی‌گردد.

وابستگی‌ها

نوع تعامل

با اسکرولِ صفحه (یا ظرفی که با `containerRef` می‌دهید) هواپیما روی ریل جلو می‌رود و بخشِ پیموده‌شده پر می‌شود؛ هر سرفصلی که به خطِ دید برسد، ردیفش فعال و پررنگ می‌شود و `aria-current` هم می‌گیرد. روی هر ردیف بزنید تا صفحه تا همان سرفصل روان اسکرول شود؛ تا اولین اسکرولِ شما هواپیما روی همان ردیف می‌ماند، چون سرفصل‌های نزدیکِ پایان تا لنگرِ بالا نمی‌آیند. اگر به سمتِ بالا برگردید، هواپیما سرِ ریل می‌چرخد و رو‌به‌بالا برمی‌گردد — و با `prefers-reduced-motion` سفر و چرخش حذف می‌شود و هواپیما بی‌حرکت جابه‌جا می‌شود.

پراپ‌ها

گزینه‌هایی که می‌تونی به کامپوننت بدی؛ ستاره‌دارها اجباری‌اند.

نصب

{
  "registries": {
    "@farsify": "https://farsify.ir/r/{name}.json"
  }
}

نمونه

"use client";

import { useRef } from "react";
import { RailToc } from "@/components/farsify/rail-toc";

const SECTIONS = [
  { id: "intro", label: "مقدمه" },
  { id: "install", label: "نصب" },
  { id: "config", label: "پیکربندی" },
  { id: "theme", label: "رنگ و تم", depth: 1 },
  { id: "faq", label: "پرسش‌های پرتکرار" },
];

export function ArticleToc() {
  return <RailToc items={SECTIONS} />;
}

// خطِ دید پایین‌تر، زیرسرفصل‌های عمیق‌تر و عنوانِ دلخواه
<RailToc items={SECTIONS} offset={140} indent={22} title="فهرستِ این راهنما" />

// رنگِ هواپیما — تنها رنگِ تزئینیِ کامپوننت
<RailToc items={SECTIONS} planeColor="#0a84ff" />

// داخلِ پنلی که خودش اسکرول می‌شود — ظرف را بدهید تا اندازه از همان خوانده شود
const scrollerRef = useRef<HTMLDivElement>(null);
<RailToc items={SECTIONS} containerRef={scrollerRef} />

نکته‌ها

• ریل در راست‌به‌چپ کنارِ لبهٔ راست (سمتِ شروع) می‌نشیند و تورفتگی به سمتِ چپ می‌رود؛ آینه‌سازی روی یک لایهٔ تزئینیِ `-scale-x-100` انجام می‌شود، پس هیچ مختصاتی را دستی نگردانید و خودِ فهرست هم با `dir` هر دو جهت کار می‌کند.
• `id` هر آیتم باید همان شناسهٔ سرفصلِ واقعی در صفحه باشد؛ آیتمی که عنصرش پیدا نشود در محاسبهٔ پیشرفت نادیده گرفته می‌شود و هواپیما رویش نمی‌ایستد.
• برای صفحه‌ای که خودش اسکرول می‌شود (نه پنجره) `containerRef` را بدهید و مطمئن شوید ظرف `position: relative` یا هر لنگرِ هندسیِ دیگری که لازم دارید را دارد؛ اندازه‌گیری با `offsetTop`ِ ردیف‌های فهرست انجام می‌شود و به اسکرولِ ظرف کاری ندارد.
• پهنای ستون را خودِ کامپوننت نمی‌سازد؛ با `className="w-56"` یا هر عرضی که به متنِ فارسی‌تان جا بدهد ببندید تا برچسب‌های بلند سالم بشکنند.
• با `prefers-reduced-motion` سفرِ فنری و چرخش حذف می‌شوند؛ فهرست، پر شدنِ ریل و `aria-current` سرِ جایشان می‌مانند.
• `planeColor` تنها رنگِ کامپوننت است و روی خودِ هواپیما می‌نشیند، نه ریل؛ ریل از رنگِ متنِ تم ساخته می‌شود تا هم‌نشینیِ دو رنگ در یک ستون شلوغ نشود. برای هواپیمای برند، همان `var(--brand)`ِ پروژه‌تان را بدهید.

مجوز

کد بعد از نصب مالِ خودته؛ هر تغییری خواستی بده و توی پروژه‌ی خودت نگهش دار. برای پروژه‌های شخصی و تجاری آزاده، حتی اگه کدت بسته باشه. فقط اسم و لینک فارسی‌فای رو یه جا توی پروژه نگه دار.