برنامه‌های داک (Dock Apps)

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

قانون (AGENTS §۷): هر برنامه همیشه در برگهٔ پایینی داک (DockSheet) باز می‌شود. برنامه پنل شناور ندارد؛ باتن‌شیت همان داک شیشه‌ای است که زنده تغییر شکل می‌دهد.

وضعیت: beta · لایه: ۳ (@tokapps/tuk/dockکپی کد) · الگوی آمادهٔ لایهٔ ۴: @tokapps/patternsکپی کد (DockAppsکپی کد)

نمونهٔ زنده

همین دو برنامه روی داک مستندات هم ثبت شده‌اند: نشان علاقه‌مندی‌ها و کارها را روی داک پایین ببینید. اینجا فرم و فهرست را داخل صفحه هم می‌بینید:

نمای کلی API

کمترین نمونه

'use client';import { Icon } from '@tokapps/icons';import { Dock, DockAppHost, defineDockApp, useDockAppItems, useDockAppState, useRegisterDockApp } from '@tokapps/tuk/dock';function MyApp({ ctx }: { ctx: import('@tokapps/tuk/dock').DockAppContext }) {  const [count, setCount] = useDockAppState('counter', 0);  return (    <button type="button" onClick={() => setCount(count + 1)}>      شمارنده: {count}    </button>  );}const counterApp = defineDockApp({  id: 'counter',  label: 'شمارنده',  icon: <Icon name="add" size="auto" />,  onMount: (ctx) => ctx.setBadge(0),  render: (ctx) => <MyApp ctx={ctx} />,});export function DockWithApps() {  useRegisterDockApp(counterApp);  const appItems = useDockAppItems();  return (    <>      <Dock>        {[...items, ...appItems]}      </Dock>      <DockAppHost />    </>  );}

نکته: آدم‌های آماده (DockAppItemکپی کد) را با useDockAppItems()کپی کد در آرایهٔ children بپاشید تا هر آیتم یک فرزند مستقل بماند و گروه‌بندی/پوشهٔ داک درست کار کند. <DockApps />کپی کد را فقط وقتی به‌عنوان یک فرزند بگذارید که گروه‌بندی مهم نیست.

فیلدهای DockAppکپی کد

ctxکپی کد برنامه:

interface DockAppContext {  id: string;  open(): void; close(): void; toggle(): void;  setBadge(badge?: string | number): void;  sheet(options: DockSheetOptions): DockSheetHandle;  alert(options: DockAlertOptions): DockAlertHandle;}

وضعیت پایدار

useDockAppStateکپی کد وضعیت برنامه را زیر فضای نام tds:dock-app:<id>کپی کد نگه می‌دارد؛ در SSR پیش‌فرض می‌رندر می‌شود و در کلاینت بازیابی می‌شود. JSON خراب یا نبود localStorageکپی کد به پیش‌فرض امن برمی‌گردد.

const [items, setItems, reset] = useDockAppState<readonly string[]>('my-app', []);

الگوی آماده: علاقه‌مندی‌ها و کارها

پکیج @tokapps/patternsکپی کد دو برنامهٔ آمادهٔ لایهٔ ۴ می‌دهد که دقیقاً روی همین API ساخته شده‌اند. بنیان بصری‌شان از خود TDS است (Buttonکپی کد/IconButtonکپی کد/Inputکپی کد/Checkboxکپی کد/EmptyStateکپی کد و <Icon>کپی کد)؛ این الگو فقط چیدمان را می‌چیند و هیچ کنترل خامی نمی‌سازد (قانون AGENTS.mdکپی کد §۶.۵):

import { createBookmarksApp, createTodosApp } from '@tokapps/patterns';import { DockAppHost, useDockAppItems, useRegisterDockApp } from '@tokapps/tuk/dock';useRegisterDockApp(createBookmarksApp({  current: () => ({ href: location.pathname, label: 'صفحهٔ فعلی' }),}));useRegisterDockApp(createTodosApp());

• createBookmarksAppکپی کد — افزودن صفحهٔ فعلی، فهرست، حذف و پاک‌کردن همه؛ نشان = تعداد ذخیره‌ها. currentکپی کد می‌تواند تابع باشد تا با هر ناوبری، بدون ثبت دوبارهٔ برنامه، به‌روز بماند.
• createTodosAppکپی کد — افزودن کار، انجام‌شده/نشده، حذف؛ نشان = کارهای باقی‌مانده.

افزودن آیکون یا اکشن به داک

علاوه بر «برنامه» (که همیشه در برگهٔ پایینی باز می‌شود)، داک یک نقطهٔ توسعهٔ سبک برای آیکون/کنش سریع دارد: هر اکشن فقط یک آیتم داک است که با کلیک کاری می‌کند (بدون سطح، بدون چرخهٔ عمر برنامه).

فیلدهای DockActionکپی کد: idکپی کد، labelکپی کد، iconکپی کد، onSelect()کپی کد، zoneکپی کد (startکپی کد | itemsکپی کد | trayکپی کد)، orderکپی کد، badgeکپی کد، activeکپی کد و enabledکپی کد.

'use client';import { Icon } from '@tokapps/icons';import { useDockActionItems, useDockActionList, useRegisterDockAction } from '@tokapps/tuk/dock';function Dock() {  // اکشن ساده: سنجاق کردن صفحهٔ فعلی  useRegisterDockAction({    id: 'pin-page',    label: 'سنجاق کردن این صفحه به داک',    icon: <Icon name="star" size="auto" />,    onSelect: () => pin(location.pathname),  });  // فهرست پویا (مثلاً از «صفحات مورد علاقه»):  const pinned = useBookmarks().filter((b) => b.pinned).map((b) => ({    id: `pin:${b.href}`,    label: b.label,    icon: <Icon name="star" size="auto" />,    onSelect: () => location.assign(b.href),  }));  useDockActionList(pinned);  return <Dock>{[...items, ...useDockActionItems()]}</Dock>;}

نمونهٔ آماده: در الگوی علاقه‌مندی‌ها، هر قلم یک دکمهٔ «سنجاق به داک» دارد؛ usePinnedDockActions('bookmarks')کپی کد از @tokapps/patternsکپی کد همان فهرست را به‌صورت DockAction[]کپی کد برمی‌گرداند و با useDockActionListکپی کد روی داک می‌نشیند (در همین سایت زنده است).

قواعد

• برنامه هرگز data-tdsکپی کد بنیان داک را بازنویسی نمی‌کند و رنگ/گرادیان خام نمی‌نویسد.
• هر برنامه همیشه در برگهٔ پایینی داک (openDockSheetکپی کد) باز می‌شود؛ پنل شناور برای برنامه ممنوع است.
• برگهٔ برنامه Escape، دکمهٔ بستن، کشیدن به پایین و کلیک‌بیرون (اگر dismissableکپی کد باشد) دارد.
• کاهش حرکت و کنتراست بالا از خود داک می‌آید؛ برنامه فقط از توکن‌های معنایی استفاده می‌کند.
• حداکثر یک سطح برنامه هم‌زمان باز است (همان «سطح فعال داک»).