فهرست وظیفه‌ها (TaskList)

معرفی

TaskList یک کانتینر domain-agnostic برای گروه‌بندی هر نوع item است. از طریق groupBy(item) آیتم‌ها bucket می‌شوند و توسط renderItem کارت‌ها رندر می‌شوند — یعنی می‌تواند JobCard، PostCard، AlertRuleCard یا هر کارت سفارشی را نمایش دهد.

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

• داشبورد ops برای job pipeline (queued / running / done)
• moderation queue کامنت‌ها (pending review / approved / rejected)
• task board ساده با kanban یا flat layout

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

• اگر نیاز به drag-drop بین ستون‌ها دارید — TaskList صرفاً presentational است؛ DnD را در سطح consumer wire کنید
• برای جدول داده — از DataTable استفاده کنید
• برای infinite scroll feed — از PostList استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، فهرست را به‌صورت زنده مشاهده کنید.

استفاده

import { TaskList, type TaskListGroup } from '@parto-system-design/ui'

interface Task {
  id: string
  title: string
  status: 'queued' | 'running' | 'done'
}

const tasks: Task[] = [
  /* ... */
]
const groups: TaskListGroup[] = [
  { id: 'queued', label: 'در صف', accent: '--sentiment-neutral' },
  { id: 'running', label: 'در حال اجرا', accent: '--brand-default' },
  { id: 'done', label: 'تکمیل شد', accent: '--sentiment-positive' },
]

;<TaskList
  items={tasks}
  groups={groups}
  groupBy={(t) => t.status}
  renderItem={(task) => <TaskCard task={task} />}
  getItemKey={(task) => task.id}
/>

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

کانبان (پیش‌فرض)

<TaskList
  variant="kanban"
  items={tasks}
  groups={groups}
  groupBy={(t) => t.status}
  renderItem={(t) => <JobCard {...t} />}
  getItemKey={(t) => t.id}
/>

Flat با sticky group headers

<TaskList
  variant="flat"
  items={tasks}
  groups={groups}
  groupBy={(t) => t.status}
  renderItem={renderItem}
  getItemKey={(t) => t.id}
/>

Auto-derive groups (بدون groups prop)

<TaskList items={tasks} groupBy={(t) => t.status} renderItem={renderItem} getItemKey={(t) => t.id} />
// ستون‌ها بر اساس مقادیر unique خود groupBy ساخته می‌شوند

ستون placeholder بدون آیتم

<TaskList
  items={tasks}
  groups={[
    { id: 'queued', label: 'در صف' },
    { id: 'running', label: 'در حال اجرا' },
    { id: 'done', label: 'تکمیل شد' },
    { id: 'archived', label: 'بایگانی', emptyState: <Empty>هیچ موردی بایگانی نشده</Empty> },
  ]}
  groupBy={(t) => t.status}
  renderItem={renderItem}
  getItemKey={(t) => t.id}
/>

بدون شمارش

<TaskList showCounts={false} {...rest} />

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

جدول ویژگی‌ها

TaskListGroup

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

• هر ستون/گروه به‌صورت <section> با data-group-id رندر می‌شود — landmark navigation معنادار است.
• شمار آیتم با aria-label کامل (مثلاً «۳ مورد») تأمین می‌شود — screen reader هم عدد و هم suffix می‌خواند.
• ترتیب tab روی renderItem-ها بستگی به محتوای کارت دارد — کارت‌ها باید focus management خودشان را داشته باشند.
• variant flat از position: sticky برای header استفاده می‌کند — keyboard scroll به‌صورت طبیعی کار می‌کند.

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

• JobCard — کارتی که معمولاً درون TaskList رندر می‌شود (با status badge، progress، actions)
• PostList — برای فید پست‌های پیوسته (نه گروه‌بندی-شده)
• ActionTimeline — برای تاریخچه‌ی اجرای task، نه task pipeline
• DataTable — اگر data tabular است نه kanban