راهنمای میانبرها (ShortcutsCheatsheet)

معرفی

ShortcutsCheatsheet یک Dialog کمکی آماده است که فهرست کامل ترکیب‌های keyboard فعال روی صفحه را — از HotkeyProvider می‌خواند و گروه‌بندی‌شده نمایش می‌دهد. با Shift+? باز می‌شود (قابل تغییر) یا از طریق یک trigger دلخواه.

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

• اپ شما از HotkeyProvider + useHotkey() استفاده می‌کند و می‌خواهید یک صفحه‌ی «راهنمای میانبرها» بدون نوشتن layout از صفر داشته باشید
• می‌خواهید کاربران keyboard-first بتوانند با یک فشار (?) همه‌ی ترکیب‌های موجود را کشف کنند
• می‌خواهید کنترل کامل روی state باز/بسته یا override لیست hotkeyها (برای preview یا تست) داشته باشید

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

• اگر اپ‌تان از HotkeyProvider استفاده نمی‌کند → registry خالی است و فقط empty state نمایش داده می‌شود؛ اول HotkeyProvider را اضافه کنید
• برای نمایش یک ترکیب تکی داخل دکمه یا تولتیپ → از KeyboardShortcut + formatHotkey() مستقیماً استفاده کنید، نه یک Dialog کامل
• برای منوی command با اجرای مستقیم عملیات (نه فقط نمایش) → CommandPalette مناسب‌تر است

استفاده

import { HotkeyProvider, ShortcutsCheatsheet, useHotkey } from '@partodata/ui'

function App() {
  return (
    <HotkeyProvider>
      <ShortcutsCheatsheet />
      <Page />
    </HotkeyProvider>
  )
}

function Page() {
  useHotkey('palette', 'mod+k', () => setOpen(true), {
    description: 'باز کردن پالت دستور',
    group: 'سراسری',
  })
  return null
}

با mount شدن، هیچ trigger مرئی رندر نمی‌شود — باز شدن فقط از دو راه ممکن است: فشردن ترکیب پیش‌فرض Shift+? (تا وقتی HotkeyProvider بالادست موجود باشد)، یا پاس‌دادن یک trigger مرئی خودتان:

<ShortcutsCheatsheet trigger={<Button variant="outline">میانبرها</Button>} />

حالت‌ها و انواع

با trigger مرئی

وقتی trigger پاس داده شود، همان node به‌عنوان DialogTrigger رندر می‌شود و کلیک روی آن Dialog را باز می‌کند — علاوه بر ترکیب کیبورد.

<ShortcutsCheatsheet trigger={<Button size="sm">نمایش میانبرها</Button>} />

state کنترل‌شده

const [open, setOpen] = React.useState(false)
;<ShortcutsCheatsheet open={open} onOpenChange={setOpen} />

override کامل لیست hotkeyها

اگر hotkeys را مستقیم بدهید، registry نادیده گرفته می‌شود — مناسب preview یا تست:

<ShortcutsCheatsheet hotkeys={[{ id: 'save', combo: 'mod+s', description: 'ذخیره', group: 'سند' }]} />

empty state

وقتی هیچ hotkey ثبت‌شده‌ای نباشد (یا shortcut={false} باشد و registry خالی باشد)، به‌جای لیست، یک Empty state نمایش داده می‌شود که با prop emptyState قابل override است.

چندزبانه (locale)

عنوان، توضیح و متن empty state با locale (fa / ar / en) خودکار تغییر می‌کنند؛ ترتیب گروه‌ها بر اساس ترتیب register شدن hotkeyها است، نه الفبا.

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

Props

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

• روی Dialog ساخته شده — Esc، focus trap، و aria-labelledby/aria-describedby به DialogTitle/DialogDescription به‌صورت خودکار توسط primitive زیرین تأمین می‌شود.
• هر گروه یک <h4> معنادار دارد و ردیف‌ها با <dl>/<dt>/<dd> سمانتیک markup می‌شوند — screen readerها جفت «توضیح ↔ ترکیب» را به‌درستی اعلام می‌کنند.
• ردیف‌های enabled: false با data-disabled و کاهش opacity مشخص می‌شوند تا واضح باشد آن ترکیب موقتاً غیرفعال است.
• چون trigger پیش‌فرض مخفی است، اگر trigger سفارشی ندهید، تنها راه دسترسی برای کاربر موس/تاچ که ترکیب کیبورد را نمی‌داند از بین می‌رود — طبق «راهنمای استفاده» بالا همیشه یک trigger مرئی هم اضافه کنید.

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

• registry پایه که این کامپوننت از آن می‌خواند → HotkeyProvider
• فرمت یک ترکیب به‌صورت خطی در متن → KeyboardShortcut
• منوی command با اجرای مستقیم عملیات → CommandPalette