درخت ناوبری (NavTree)

معرفی

NavTree درخت ناوبری درون یک ابزار است. سه ویژگی کلیدی:

1. تودرتویی چندسطحی — NavItem که NavItemهای دیگر را به‌عنوان children دارد، خودکار به parent قابل‌جمع‌شدن تبدیل می‌شود؛ depth بدون محدودیت.
2. کاسکید حالت فعال — وقتی activePath با یک leaf تودرتو match می‌کند، همه‌ی parentها به‌طور خودکار expand می‌شوند و data-active-within می‌گیرند (highlight ملایم‌تر از leaf فعال).
3. گروه‌های قابل‌جمع‌شدن — NavGroup با heading قابل‌کلیک؛ کل گروه را باز/بسته می‌کند .

چه زمانی استفاده کنیم:

• درخت عمیق (3+ سطح) درون یک ابزار، مثل درخت منابع رصد (رصد → منابع → تلویزیون)
• ابزاری که کاربر باید یک نقطه‌ی عمیق در درخت را bookmark کند و هنگام بازگشت به‌طور خودکار ببیند
• پنل‌های کناری طولانی درون ابزار که نیاز به group collapse دارند

چه زمانی استفاده نکنیم:

• منوی اصلی برنامه → ProductFrame
• ناوبری تخت با کمتر از 8 آیتم — Tabs یا SecondaryNav
• ناوبری اصلی برنامه — از ProductFrame (نوار ناوبری و ناوبری دوم) استفاده کنید
• ناوبری bottom-tab موبایل — از الگوی اختصاصی استفاده کنید (NavTree عمودی است)

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

'use client'
import { usePathname } from 'next/navigation'
import { NavTree, NavTreeProvider, NavGroup, NavItem } from '@partodata/ui'
import { Newspaper, Radio, Tv } from 'lucide-react'

// Inside the sources page of a monitoring tool: its own deep tree, next to the page content. The product's main
// menu is ProductFrame's. The tree stays in the page's flow (not fixed to the viewport over the frame's menu).
// `aria-label`: the tree is named after what it navigates.
export function SourcesTree() {
  const pathname = usePathname()

  return (
    <div className="rounded-lg border p-2">
          <NavTreeProvider activePath={pathname}>
            <NavTree aria-label="منابع">
              <NavGroup heading="منابع رسانه‌ای">
                <NavItem href="/sources/press" icon={Newspaper}>
                  مطبوعات
                </NavItem>
                <NavItem icon={Tv}>
                  تلویزیون
                  <NavItem href="/sources/tv/news">خبری</NavItem>
                  <NavItem href="/sources/tv/sports">ورزشی</NavItem>
                </NavItem>
              </NavGroup>

              <NavGroup heading="صوتی" defaultOpen={false}>
                <NavItem href="/sources/radio" icon={Radio}>
                  رادیو
                </NavItem>
              </NavGroup>
            </NavTree>
          </NavTreeProvider>
    </div>
  )
}

کاسکید حالت فعال (خودکار)

وقتی activePath مطابق یک leaf تودرتو باشد، همه‌ی parent های بالای آن به‌طور خودکار data-active-within می‌گیرند و expand می‌شوند. دکمه‌های بالا را در دموی زیر تغییر دهید تا رفتار را ببینید:

جزئیات الگوریتم:

• matchStrategy="prefix" (پیش‌فرض): /clusters هم برای /clusters و هم برای /clusters/42 فعال می‌شود. فقط مرز segment رعایت می‌شود (یعنی /cl با /clusters match نمی‌شود).
• matchStrategy="exact": فقط تطابق دقیق.

گروه‌های قابل‌جمع‌شدن

• heading نمایش یک ردیف سرگروه و به‌طور پیش‌فرض قابل‌کلیک (collapse/expand)
• collapsible={false} heading را static می‌کند
• defaultOpen={false} برای بسته بودن در رندر اول
• open + onOpenChange برای کنترل controlled

Props

NavTreeProvider

NavGroup

NavItem

NavSeparator

خط جداکننده‌ی افقی (<hr>) برای تفکیک بصری بخش‌های ناوبری درون درخت. فقط ویژگی‌های استاندارد <hr> را می‌پذیرد.

درون یک صفحه

NavTree ستونی از خود صفحه است که روی موبایل بالای محتوا و از md کنار آن می‌نشیند؛ <main> دوم و نوار چسبیده به viewport ندارد (زیر منوی قاب پنهان می‌شود). عنوان و پانویس درخت، عناصر خود صفحه‌اند.

<div className="flex flex-col rounded-lg border md:flex-row">
  <div className="w-full border-b p-2 md:w-64 md:border-e md:border-b-0">
    <NavTreeProvider activePath={pathname}>
      <NavTree aria-label="منابع">...</NavTree>
    </NavTreeProvider>
  </div>
  <div className="min-w-0 flex-1 p-4">{/* محتوای منبع انتخاب‌شده */}</div>
</div>

راهنمای استفاده

دسترسی‌پذیری

• NavTree یک لندمارک <nav> است؛ با aria-label (یا aria-labelledby) آن را به نام چیزی که پیمایش می‌کند بنامید، مثل aria-label="منابع". بدون نام، درون صفحهٔ ProductFrame «ناوبری صفحه» نام می‌گیرد (نام «ناوبری اصلی» مال منوی قاب است و دو لندمارک هم‌نام نمی‌سازد) و بیرون از آن «ناوبری اصلی»
• parent NavItem بدون href/onClick (صرفاً اطلاع‌رسانی): کل ردیف یک دکمه است با aria-expanded؛ کلیک، Space و Enter آن را toggle می‌کنند
• parent NavItem با href یا onClick (یعنی خودش هم مقصد ناوبری/عمل است): ردیف به دو المان مجزا تقسیم می‌شود — برچسب اصلی (<a>/<button> واقعی که ناوبری می‌کند) و یک دکمهٔ کوچک جداگانه با aria-expanded برای باز/بسته‌کردن زیرمنو؛ چون دو المان تعاملی نمی‌توانند تودرتو باشند
• active leaf دارای data-active="true" — بصری و برای automated testing
• chevron بصری در RTL به شکل صحیح می‌چرخد (left → down در باز، rotate-90 در بسته)

محدودیت‌های فعلی

• جستجو در درخت هنوز ارائه نشده. برنامه‌ی بعدی: NavSearch ورودی که لیست را filter می‌کند و parent های مرتبط را باز نگه می‌دارد. (فاز 1.1 روادمپ — مرحله‌ی بعد)
• Drag-reorder آیتم‌ها در نظر نیست — این یک UI ناوبری است نه یک tree builder.

کامپوننت‌های مرتبط

• قاب محصول (ProductFrame) — منوی اصلی برنامه (nav، با children برای پیوندهای هر بخش)
• ProductFrame — قاب برنامه با ناوبری اصلی
• PageHeader — مسیر فعلی صفحه (breadcrumb) در breadcrumbs سربرگ صفحه