پالت دستور (CommandPalette)

معرفی

CommandPalette یک دیالوگ جستجوی سراسری است که به کاربر اجازه می‌دهد در یک‌جا به همه‌ی مسیرها، عملیات، و تنظیمات محصول سریع دسترسی داشته باشد. با Ctrl/⌘ + K باز می‌شود، آیتم‌ها را گروه‌بندی می‌کند، انتخاب‌های اخیر را به خاطر می‌سپارد، و جستجو نسبت به ارقام فارسی/عربی و حروف ی/ک مقاوم است.

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

• در لایه‌ی App Shell برای دسترسی فوری کاربران حرفه‌ای به هر جای محصول
• برای اجرای عملیات سریع (ساخت هشدار، تغییر فیلتر، رفتن به گزارش) بدون ترک صفحه‌ی فعلی
• در محصولات داشبوردیِ متراکم که ناوبری چندسطحی دارند

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

• برای جستجو در محتوا (پست‌ها، کامنت‌ها) — از SearchInput یا صفحه‌ی جستجو استفاده کنید
• به‌جای فیلترپنل — فیلترها نیازمند چندین ورودی هم‌زمان هستند؛ پالت برای کنش‌های تک‌مرحله‌ای است
• در محصولات ساده با کمتر از ۵ مسیر — hamkari overkill محسوب می‌شود

زمین بازی

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

استفاده

'use client'
import * as React from 'react'
import { LayoutDashboard, Plus, Settings } from 'lucide-react'
import { CommandPalette, type CommandPaletteItem } from '@parto-system-design/ui'

function AppShell() {
  const [open, setOpen] = React.useState(false)
  const items: CommandPaletteItem[] = [
    {
      id: 'nav-dashboard',
      label: 'داشبورد',
      icon: LayoutDashboard,
      group: 'ناوبری',
      shortcut: 'mod+d',
      onSelect: () => router.push('/'),
    },
    {
      id: 'action-new-alert',
      label: 'ایجاد هشدار',
      icon: Plus,
      group: 'عملیات',
      shortcut: 'mod+shift+n',
      onSelect: () => openNewAlertDialog(),
    },
    {
      id: 'pref-settings',
      label: 'تنظیمات',
      icon: Settings,
      group: 'ترجیحات',
      onSelect: () => router.push('/settings'),
    },
  ]
  return <CommandPalette open={open} onOpenChange={setOpen} items={items} />
}

میان‌بر سراسری

به‌صورت پیش‌فرض، Ctrl/⌘ + K پالت را باز/بسته می‌کند. با shortcut می‌توانید آن را تغییر دهید یا با shortcut={false} به‌طور کامل غیرفعال کنید (وقتی می‌خواهید خودتان useHotkeys را در جای دیگر وصل کنید).

<CommandPalette items={items} shortcut="mod+shift+p" />  // بازنگاری میان‌بر
<CommandPalette items={items} shortcut={false} />         // بدون میان‌بر

جستجوی فارسی-آگاه

فیلتر پیش‌فرض نسبت به این تفاوت‌ها مقاوم است:

• ارقام فارسی/عربی (۱۲۳ ≡ ١٢٣ ≡ 123)
• حروف یای/کاف عربی در مقابل فارسی (ي ≡ ی و ك ≡ ک)
• اِعراب (حرکات)

هم‌چنین می‌توانید کلمات کلیدی اضافی (ترجمه، اختصار، تگ) را به keywords بدهید تا جستجوپذیری آیتم بیشتر شود:

{
  id: 'nav-dashboard',
  label: 'داشبورد',
  keywords: ['dashboard', 'home', 'خانه', 'نمای کلی'],
  onSelect: () => ...,
}

اخیرها

به‌صورت پیش‌فرض، ۵ آیتم آخرِ انتخاب‌شده در localStorage با کلید parto:cmdk:recents ذخیره می‌شود و وقتی ورودی جستجو خالی باشد، در بالای لیست به عنوان گروه «اخیر» ظاهر می‌شود.

// غیرفعال کردن اخیرها
<CommandPalette items={items} recents={false} />

// تنظیم تعداد یا کلید
<CommandPalette items={items} recents={{ max: 10, key: 'my-app:cmdk' }} />

میان‌بر هر آیتم

هر آیتم می‌تواند یک shortcut برای نمایش داشته باشد. این فقط برای نمایش است — بایند کردن میان‌بر به callback آیتم بر عهده‌ی host است (با useHotkeys). دلیل: پالت بخشی از App Shell است؛ بایند کردن میان‌بر باید از نقطه‌ای انجام شود که مسیریابی/مودال‌های محصول در دسترسش باشد.

// در App Shell:
useHotkeys('mod+d', () => router.push('/'))
useHotkeys('mod+shift+n', openNewAlertDialog)

// در CommandPalette:
items: [
  { id: 'nav-dashboard', label: 'داشبورد', shortcut: 'mod+d', ... },
  { id: 'action-new-alert', label: 'ایجاد هشدار', shortcut: 'mod+shift+n', ... },
]

Props

CommandPaletteItem

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

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

• دیالوگ دارای DialogTitle و DialogDescription مخفی (sr-only) برای صفحه‌خوان است
• ناوبری با Arrow Up/Down، Enter برای انتخاب، Escape برای بستن
• میان‌بر سراسری در فیلدهای ورودی هم کار می‌کند (مودیفایر دارد)
• انیمیشن‌های باز/بسته به prefers-reduced-motion احترام می‌گذارند

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

• Command — primitive پایه (cmdk). CommandPalette یک composite روی آن است
• useHotkeys — برای ثبت میان‌برهای سراسری و محلی
• SearchInput — برای جستجو در محتوا (نه دستورات)