Dock — منوی پایینی شیشه‌ای

پیش‌نمایش زنده

همه محورهای داک را ترکیب کنید. تم و حالت روز/شب از تنظیمات سریع خود داک سایت (پایین صفحه) گرفته می‌شود.

وضعیت‌های آیتم

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

واکنش‌گرایی

دسکتاپ: نوار سه‌ناحیه‌ای با برچسب در hover. تبلت: شناور و فشرده. موبایل: تمام‌عرض منهای حاشیه، برچسب زیر آیکون همیشه دیده می‌شود، هر کلید ۴۴px (حداقل هدف لمسی)، و با احترام به safe-area.

• hover فقط با ماوس: روی لمس، حالت hover پس از ضربه نمی‌چسبد؛ کادر یا جابه‌جایی آیکون باقی نمی‌ماند.
• برچسب زیر آیکون: ثابت است و با حالت‌های hover و فوکوس جابه‌جا نمی‌شود.
• نشانگر «باز / صفحه فعلی»: در حالت برچسب زیر آیکون، بالای آیکون می‌نشیند تا روی متن نیفتد.
• پنل پوشه: هر آیتم یک ستون وسط‌چین است؛ برچسب زیر آیکون دقیقاً در مرکز آن.
• ساعت فشرده: یک کلید ۴۴px با صفحهٔ عقربه‌ای وسط.

کلیدهای ثابت

پنج کلید در همهٔ تم‌ها در یک موقعیت‌اند: منو و جستجو سمت آغاز، صدا · پروفایل · ساعت سمت پایان. تم فقط نمایش هر کلید را تعیین می‌کند (با dock.slots)، نه جای آن را.

گروه‌بندی و پوشه

اگر آیتم‌ها در عرض ردیف جا نشوند، آیتم‌های گروه‌پذیر از انتها زیر یک پوشه می‌روند (مثل پوشهٔ لانچر). کلیک روی پوشه، پنلی بالای داک باز می‌کند که همان آیتم‌ها را قابل کلیک نشان می‌دهد. کلیدهای ثابت و آیتم‌های غیرگروه‌پذیر هرگز زیر پوشه نمی‌روند. در موبایل همین قاعده است؛ کلیدهای ثابت برچسب ندارند تا در ردیف جا شوند.

لمس طولانی و نام آیکون

روی لمس، فشردن بیش از ~۴۵۰ms نام آیکون را بالای آن نشان می‌دهد؛ با رها کردن ناپدید می‌شود و کلیک بعد از آن فعال نمی‌شود. روی پوشه، نام آیتم‌های داخلش دیده می‌شود. ماوس همان tooltip با hover را دارد.

جستجوی پیشوندی منو

کلید منو نقشه سایت را باز می‌کند. جستجو فقط وقتی فعال می‌شود که روی فیلد جستجو بزنید؛ آنگاه کیبورد حروف زیرش باز می‌شود. مثل کیبورد صفحهٔ خودرو، فقط حروفی نشان داده می‌شوند که ادامه دارند، به ترتیب الفبا (فارسی، سپس لاتین). نقشه همان چیدمان را دارد و فقط فیلتر می‌شود. پنل منو تا سقف صفحه بلند می‌شود تا کیبورد جا شود.

قانون فیلتر: حرف بعدی فقط وقتی نشان داده می‌شود که با پیشوند فعلی حداقل یک کلمه از منو شروع شود. کلمه‌ها از ابتدا تطبیق داده می‌شوند، نه از وسط؛ «ی» و «ک» عربی و فارسی یکسان‌سازی می‌شوند؛ نیم‌فاصله داخل کلمه‌های مرکب حفظ می‌شود.

import { DockPanel } from '@tokapps/tuk/dock';// پنل منو بلند است تا سقف صفحه؛ کیبورد جستجو داخلش باز می‌شود<DockPanel open={panel === 'launcher'} onClose={closePanel} label="نقشه سایت" tall>  <LauncherPanel /></DockPanel>

فقط یک سطح باز

در هر لحظه فقط یک سطح از داک باز است: پنل (منو، تنظیمات، ساعت، پروفایل)، پوشه، ورق کشیدنی یا برگهٔ داک. باز شدن هر کدام، بقیه را می‌بندد؛ مثلاً باز کردن پوشه، ورق منوی کامل را می‌بندد.

دکمه اسکرول همراه داک

وقتی به بالای صفحه رسیدیم، «برو پایین» با یک انیمیشن نرم سمت راست داک وارد می‌شود؛ وقتی به پایین رسیدیم، «برو بالا».

ماده و دسترس‌پذیری

شیشه = پس‌زمینه نیمه‌شفاف + blur + اشباع + خط مویی + درخشش لبه بالا + سایه شناور. هرجا شفافیت به خوانایی آسیب بزند، به سطح مات برمی‌گردد.

تم‌های محصول

داک کد خودش را برای هیچ محصولی عوض نمی‌کند؛ فقط توکن تم عوض می‌شود.

موبایل: کشیدن به بالا

در موبایل ردیف فقط کلیدهای ثابت و پوشه است. دستگیره بالای داک را به بالا بکشید (یا بزنید) تا منوی کامل بخش‌ها و تنظیمات سریع باز شود. بار اول یک انیمیشن انگشت آموزش می‌دهد.

سیاست داک هر تم

هر تم در فراداده‌اش (packages/theme-<id>/src/meta.ts → dock) مشخص می‌کند کدام کلیدهای ثابت دیده شوند و کدام آیتم‌ها اجازه دارند زیر پوشه بروند. TUK هیچ‌کدام را خودسرانه تعیین نمی‌کند.

ساعت هر تم

ساعت داک از فراداده همان تم می‌آید: تقویم (شمسی یا میلادی) و نمایش (عددی یا عقربه‌ای). در صفحهٔ تنظیمات داک، کاربر هر دو را بازنویسی می‌کند. ساعت عقربه‌ای در موبایل یک کلید ۴۴px است و صفحه‌اش وسط آن.

قرارداد تم: چه چیزی عوض می‌شود

هر تم فقط از راه فراداده و توکن‌هایش داک را تغییر می‌دهد؛ ساختار و رفتار ثابت‌اند.

• قابل تغییر در تم: dock.slotsکپی کد (نمایش هر کلید ثابت)، dock.groupableکپی کد (آیتم‌های گروه‌پذیر)، dockClockکپی کد (تقویم و نمایش ساعت).
• توکن‌ها (theme.cssکپی کد): شکل، شیشه، سایه، مدت و منحنی حرکت، صدای کلیک داک؛ همه از نوع --tds-dock-*کپی کد.
• هویت حرکت: dock-clock.cssکپی کد (حرکت عقربه‌ها) و dock-sheet.cssکپی کد (برگهٔ داک). فعلاً فقط تم tokapps هویت برگه دارد؛ بقیه حرکت خنثی.
• ثابت و غیرقابل تغییر در تم: موقعیت و ترتیب کلیدهای ثابت، ساختار DOM و ARIA، رفتار پوشه و لمس طولانی، اندازه‌های لمسی (۴۴px در موبایل)، و اینکه یک سطح باز است.
• هنوز در نقشه: هویت حرکتی پوشه و پنل منو؛ فعلاً بنیان ثابت است.

// packages/theme-funding/src/meta.tsexport const meta: ProductThemeMeta = {  id: 'funding',  // …  dockClock: { calendar: 'gregorian', face: 'analog' },  dock: {    // کلیدهای ثابت: موقعیت ثابت است؛ فقط نمایششان را تم تعیین می‌کند    slots: { menu: true, search: true, mode: true, sound: false, profile: true, clock: true },    // فقط این آیتم‌ها (با name) زیر پوشه می‌روند؛ 'section:*' پیشوندی است    groupable: ['section:*'],  },};

/* packages/theme-funding/src/theme.css — فقط توکن‌های مجاز داک */[data-theme="funding"] {  --tds-dock-radius: var(--tds-radius-xl);     /* شکل */  --tds-dock-blur: 14px;                       /* شیشه */  --tds-dock-transition: 220ms;                /* حرکت (زمان و منحنی) */}

کلید منو

کلید منو پنل شیشه‌ای بلندی را باز می‌کند؛ نقشه سایت با همان چیدمان. جستجو از بالای نقشه فعال می‌شود (بخش «جستجوی پیشوندی منو»).

پنهان‌شدن خودکار

اختیاری؛ برای صفحه‌های خواندنی طولانی. هرگز وقتی فوکوس کیبورد داخل داک است پنهان نمی‌شود.

داخل قاب به پایین اسکرول کنید: داک پنهان می‌شود؛ با اسکرول به بالا، نزدیک شدن نشانگر به لبه پایین یا فوکوس کیبورد برمی‌گردد.

هشدار روی داک

نوع تازه‌ای از Toast: آیکون‌ها از دو طرف بیرون می‌روند و محو می‌شوند، رنگ کل داک با گرادیان نرم و زنده (رنگ وضعیت تا دو پله عمیق‌تر) می‌آید. داک از قاعده «بدون گرادیان» مستثناست. معادل متنی با aria-live اعلام می‌شود و رنگ تنها نشانه نیست (آیکون + برچسب).

توکن‌ها

همه در packages/tokens/src/component/dock.css. کامپوننت جز این‌ها هیچ مقداری مصرف نمی‌کند.

استفاده و قواعد

import { Dock, DockItem, DockSeparator, DockClock, type DockSlots } from '@tokapps/tuk/dock';

/* سیاست تم: از packages/theme-<id>/src/meta.ts → dock */
const { slots, groupable } = themeDock(theme);

<Dock
  slots={{                                   // موقعیت ثابت؛ تم فقط نمایش را تعیین می‌کند
    menu:    slots.menu    ? <DockItem icon={<Icon name="launcher" size="auto" />} label="منو" onClick={openMenu} /> : undefined,
    search:  slots.search  ? <DockItem icon={<Icon name="search" size="auto" />} label="جستجو" onClick={openSearch} /> : undefined,
    mode:    slots.mode    ? <DockItem icon={modeIcon} label="حالت شب" onClick={toggleMode} /> : undefined,
    sound:   slots.sound   ? <DockItem icon={soundIcon} label="صدا" aria-pressed={sound} onClick={toggleSound} /> : undefined,
    profile: slots.profile ? <DockProfileItem /> : undefined,
    clock:   slots.clock   ? <DockClock calendar="jalali" face="digital" compact /> : undefined,
  }}
  groupable={groupable}                      // فقط این نام‌ها زیر پوشه می‌روند (section:* پیشوندی است)
  tray={<DockSeparator />}
>
  <DockItem name="section:components" href="/components" icon={<Icon name="docs.components" size="auto" />} label="کامپوننت‌ها" />
  {/* حالت روز/شب هم کلید ثابت است: slots.mode */}
</Dock>

/* هشدار روی داک (سراسری، مثل startBusy) */
import { dockAlert } from '@tokapps/tuk/dock';
const a = dockAlert({ tone: 'success', text: 'ذخیره شد' });                 // چند ثانیه، بازگشت نرم
const p = dockAlert({ tone: 'danger', text: 'اتصال قطع شد', mode: 'persistent' });
p.update({ tone: 'success', text: 'وصل شد' }); p.dismiss();

/* هر صفحه: فضای زیر داک را خالی نگه دار */
<main data-dock-reserve>…</main>