Calendar — تقویم تسک و رویداد

تقویم TDS کارهای کاربر را روی زمان می‌چیند. اولین نما امروز است: فهرست مرتب کارهای امروز، مثل تقویم گوگل. نماهای هفته و ماه نقطه‌های رنگی زیر هر روز دارند؛ کلیک روی روز، فهرست کارهایش را به‌صورت آکاردئون درست زیر همان ردیف باز می‌کند.

وضعیت: beta · لایه: ۳ (@tokapps/tuk/data-displayکپی کد) · کد: packages/tuk/src/data-display/calendar/کپی کد

import { Calendar } from '@tokapps/tuk';

سه نما

دکمهٔ «امروز» همیشه به امروز برمی‌گردد. تقویم با system="jalali"کپی کد (پیش‌فرض) ماه‌ها و روزهای شمسی را نشان می‌دهد و با system="gregorian"کپی کد میلادی.

نقطه‌ها و آکاردئون روز

• هر تسک یا رویداد یک نقطه دارد؛ تا سه نقطه دیده می‌شود و بقیه با +nکپی کد.
• رنگ نقطه از toneکپی کد می‌آید؛ پیش‌فرض تسک brandکپی کد و رویداد infoکپی کد است. رنگ تنها نشانه نیست: در فهرست، هر آیتم نوعش («تسک» یا «رویداد») و وضعیتش («انجام شد») را به متن نشان می‌دهد.
• کلیک روی روز: اگر باز نیست، باز می‌شود؛ اگر باز است، بسته می‌شود. فقط یک روز همزمان باز است.
• روز بدون کار هم قابل انتخاب است؛ آکاردئونش پیام «برای این روز کاری ثبت نشده است» را نشان می‌دهد.
• در نمای ماه، آکاردئون بین ردیف‌ها می‌نشیند؛ محتوای ماه زیرش جابه‌جا می‌شود، نه اینکه پنجره‌ای جدا باز شود.

داده: چطور تسک و رویداد را روی تقویم بچینیم

هر آیتم یک CalendarItemکپی کد است. تقویم خودش داده را نگه نمی‌دارد؛ شما آرایه را از API یا state می‌دهید و هر بار که تغییر کرد دوباره رندر می‌شود.

نمونه: تبدیل پاسخ API به آیتم‌های تقویم

import { Calendar, type CalendarItem } from '@tokapps/tuk';type TaskDto = { id: string; title: string; dueAt: string; allDay: boolean; completed: boolean };/** پاسخ سرور را به آیتم تقویم تبدیل کن؛ تاریخ‌ها را Date بساز */export function toCalendarItems(tasks: TaskDto[]): CalendarItem[] {  return tasks.map((t) => ({    id: t.id,    title: t.title,    start: new Date(t.dueAt),    allDay: t.allDay,    kind: 'task',    done: t.completed,  }));}export function MyCalendar({ tasks }: { tasks: TaskDto[] }) {  return <Calendar aria-label="کارهای من" items={toCalendarItems(tasks)} />;}

نمونه: رویداد چندروزه و تمام‌روز

const items: CalendarItem[] = [  // روی سه روز نشان داده می‌شود؛ در نما تمام‌روز است  { id: 'conf', title: 'کنفرانس سالانه', start: new Date(2026, 10, 3), end: new Date(2026, 10, 5), allDay: true, kind: 'event', tone: 'success' },  // ساعت‌دار؛ در نمای امروز بعد از تمام‌روزها  { id: 'demo', title: 'دموی محصول', start: new Date(2026, 10, 4, 15, 30), end: new Date(2026, 10, 4, 16, 15), kind: 'event', description: 'اتاق ۲' },];

حالت‌ها

نمونه‌های قابل‌کپی

۱. نمای ماه (پیش‌فرض)

import { Calendar, type CalendarItem } from '@tokapps/tuk';export function Basic({ items }: { items: CalendarItem[] }) {  return <Calendar aria-label="تقویم کارها" items={items} />;}

۲. شروع از نمای هفته یا امروز

<Calendar aria-label="تقویم هفته" items={items} defaultView="week" /><Calendar aria-label="کارهای امروز" items={items} defaultView="today" />

۳. تیک زدن انجام تسک (حالت کنترل‌شده در state)

import { useState } from 'react';import { Calendar, type CalendarItem } from '@tokapps/tuk';export function TodoCalendar({ initial }: { initial: CalendarItem[] }) {  const [items, setItems] = useState(initial);  return (    <Calendar      aria-label="تسک‌های من"      items={items}      onItemToggle={(item, done) =>        setItems((prev) => prev.map((i) => (i.id === item.id ? { ...i, done } : i)))      }    />  );}

۴. انتخاب آیتم (مثلاً باز کردن جزئیات)

<Calendar  aria-label="رویدادها"  items={items}  onItemSelect={(item) => router.push(`/tasks/${item.id}`)}/>

۵. تقویم میلادی

<Calendar aria-label="Calendar" system="gregorian" items={items} />

۶. کنترل نما و تاریخ از بیرون

import { useState } from 'react';import { Calendar, type CalendarItem, type CalendarView } from '@tokapps/tuk';export function ControlledCalendar({ items }: { items: CalendarItem[] }) {  const [view, setView] = useState<CalendarView>('month');  const [date, setDate] = useState(() => new Date());  return (    <>      <p>{view === 'month' ? 'نمای ماه' : 'نمای دیگر'}</p>      <Calendar aria-label="تقویم" items={items} view={view} onViewChange={setView} date={date} onDateChange={setDate} />    </>  );}

۷. دکمهٔ اضافه در سربرگ

<Calendar  aria-label="تقویم"  items={items}  headerActions={<Button variant="secondary" onClick={openNewTask}>تسک جدید</Button>}/>

۸. رندر سفارشی هر آیتم

renderItemکپی کد فقط محتوای داخل هر ردیف را عوض می‌کند؛ زمان و چک‌باکس را خودتان باید بسازید یا کنار آن بگذارید.

<Calendar  aria-label="تقویم"  items={items}  renderItem={(item) => (    <span>      <strong>{item.title}</strong> — <span>{item.done ? 'تمام' : 'باز'}</span>    </span>  )}/>

۹. برچسب‌ها و ارقام لاتین

<Calendar  aria-label="Calendar"  items={items}  labels={{ today: 'Today', week: 'Week', month: 'Month', goToday: 'Today', empty: 'Nothing scheduled', agendaEmpty: 'Nothing today.' }}  digits={(s) => s.replace(/[۰-۹]/g, (d) => String('۰۱۲۳۴۵۶۷۸۹'.indexOf(d)))}/>

۱۰. هفته از یکشنبه

<Calendar aria-label="تقویم" items={items} weekStartsOn={0} />

استفاده در داک TDS

ساعت داک (DockClockکپی کد) با کلیک، همین تقویم را در پنل داک باز می‌کند؛ دکمهٔ تنظیمات سربرگ به تقویم ساعت و تاریخ می‌رود (شمسی یا میلادی، عددی یا عقربه‌ای).

import { useState } from 'react';import { Calendar, type CalendarItem } from '@tokapps/tuk';import { DockPanel, DockClock } from '@tokapps/tuk/dock';export function DockCalendar({ items }: { items: CalendarItem[] }) {  const [open, setOpen] = useState(false);  return (    <>      <DockClock calendar="jalali" face="digital" open={open} onClick={() => setOpen((v) => !v)} />      <DockPanel open={open} onClose={() => setOpen(false)} label="تقویم">        <Calendar aria-label="تقویم" items={items} />      </DockPanel>    </>  );}

موبایل

• سربرگ زیر هم می‌شود: عنوان، سپس سه نما در یک ردیف تمام‌عرض، سپس ناوبری.
• شبکهٔ ماه و هفته ستون‌های برابر دارند؛ هر روز حداقل 2.75remکپی کد (بیش از حداقل هدف لمسی) است.
• در موبایل، آکاردئون روز تمام‌عرض است و فهرست با فاصلهٔ بیشتر برای لمس.
• با پنل داک، کل تقویم در بدنهٔ پنل اسکرول می‌شود؛ نیازی به کشیدن تودرتو نیست.

RTL و جهت

• هفته از شنبه شروع می‌شود (weekStartsOn={6}کپی کد)؛ در RTL ستون اول سمت راست است.
• فلش‌های ناوبری صفحه‌کلید با dirکپی کد تنظیم می‌شوند: فلش چپ در RTL به روز بعد می‌رود.
• نام ماه‌ها و روزها فارسی‌اند؛ digitsکپی کد اعداد را به فارسی یا لاتین تبدیل می‌کند.

کیبورد و صفحه‌خوان

• Tabکپی کد بین تب‌های نما، دکمه‌های ناوبری و روزها. تب‌ها role="tab"کپی کد با aria-selectedکپی کد و aria-controlsکپی کد هستند.
• در شبکهٔ روزها: فلش‌ها حرکت می‌کنند (با جهت RTL)، ArrowUpکپی کد و ArrowDownکپی کد یک هفته، Homeکپی کد و Endکپی کد ابتدا و انتهای شبکه.
• هر روز دکمه است با برچسب کامل: تاریخ و تعداد موارد؛ aria-expandedکپی کد و aria-controlsکپی کد وضعیت آکاردئون را می‌گویند.
• آکاردئون role="region"کپی کد با نام تاریخ روز است.
• عنوان بازه aria-live="polite"کپی کد است؛ با جابه‌جایی ماه یا هفته خوانده می‌شود.
• چک‌باکس هر تسک نام دارد: «عنوان: انجام شد».

چاپ

نمای ماه ایستا چاپ می‌شود؛ آکاردئون‌ها هم در چاپ دیده می‌شوند. رنگ‌ها تک‌رنگ هم خوانده می‌شوند چون تعداد موارد و برچسب نوع متنی است.

تم و توکن‌ها

Calendar بنیان ثابت دارد؛ تم فقط توکن‌ها را تنظیم می‌کند.

فهرست کامل: Calendar.tokens.tsکپی کد و packages/tokens/src/component/calendar.cssکپی کد.

API

جزئیات نوع‌ها: Calendar.types.tsکپی کد. قرارداد دسترس‌پذیری: Calendar.a11y.tsکپی کد.

آزمون

• منطق تاریخ (شمسی/میلادی، طول ماه، شبکهٔ هفته، گروه‌بندی چندروزه): Calendar.test.tsxکپی کد.
• رندر هر سه نما و حالت‌های خالی، و onItemToggleکپی کد فقط برای تسک‌ها.