فید فعالیت (ActionTimeline)

معرفی

ActionTimeline یک لیست زمانی از رویدادها است. هر آیتم یک مارکر با آیکون وضعیت، یک عنوان (subject + verb + object)، یک timestamp نسبی، و به‌صورت اختیاری پیش‌نمایش متنی (مثل محتوای کامنت)، تگ دسته‌بندی، و دکمه‌های action دارد. از سه پنل audit شده استخراج شد:

• Booster — لاگ عملیات per-worker (لایک، کامنت، فالو، ...)
• کامنت‌سنج — رویدادهای چرخه‌عمر تحلیل (شروع، اتمام، خطا)
• ارزیابی — audit log اجرای ارزیابی‌ها

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

• فید فعالیت‌های اخیر در داشبورد
• Audit trail یک entity (مثل تاریخچه‌ی یک worker یا کمپین)
• Activity tab داخل یک Drawer/Dialog جزئیات
• لاگ real-time رویدادهای سیستم (با aria-live از بیرون)

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

• برای نمایش مراحل یک pipeline از StatusFlow استفاده کنید (رویداد نیست، stage است)
• برای توییت/پست از PostCard استفاده کنید
• برای لیست notification از NotificationCenter استفاده کنید (محور: mark-as-read, dismiss, filter)
• اگر همه‌ی آیتم‌ها هم‌نوع و بدون timestamp معنادار هستند، یک <ul> ساده با DataTable کفایت می‌کند

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

data-driven (پیش‌فرض)

import { ActionTimeline } from '@parto-system-design/ui'

export function RecentActivity({ events }) {
  return (
    <ActionTimeline
      items={events.map((e) => ({
        id: e.id,
        status: e.outcome, // 'success' | 'failed' | 'pending' | 'warning' | 'info'
        title: e.summary,
        description: e.detail,
        preview: e.commentText, // snippet shown in a muted box
        tag: e.type, // 'Instagram', 'AI', ...
        timestamp: e.createdAt, // Date | ISO string | epoch ms
      }))}
    />
  )
}

composition

<ActionTimeline>
  <ActionTimelineItem id="a" status="success" title="ورود worker موفق" timestamp={Date.now() - 60_000} />
  <ActionTimelineItem id="b" status="pending" title="در حال warmup" timestamp={Date.now()} tag="warmup" />
</ActionTimeline>

گروه‌بندی روزانه

با groupBy="day" هدرهای sticky روزانه ظاهر می‌شوند — «امروز»، «دیروز»، یا تاریخ کامل (Jalali برای fa/ar، گریگوری برای en). آیتم‌ها باید به ترتیب نزولی timestamp مرتب شده باشند (ActionTimeline خودش مرتب نمی‌کند).

چگالی (density)

• compact — مناسب sidebar یا لیست متراکم inside drawer
• default — متن عادی، برای فیدهای داشبورد
• spacious — در صفحات اختصاصی audit با پیش‌نمایش‌های طولانی

پنج وضعیت canonical

ActionStatusKey: success | failed | pending | warning | info

این‌ها سبک‌تر از JobStatusKey هستند چون یک event اتمیک است (چیزی مثل «paused» برای یک event خاص معنا ندارد). با توکن‌های --sentiment-positive، --destructive-default، --brand-default، --warning-default، و --foreground-lighter map می‌شوند.

اکشن‌های inline

actions یک slot جانبی است که در انتهای ردیف نمایش داده می‌شود. کلیک روی این slot propagate نمی‌شود — بنابراین وقتی onItemSelect هم تنظیم است، هندلر row trigger نمی‌شود. مناسب «تلاش مجدد»، «مشاهده گزارش»، «پنهان کردن».

حالت خالی

وقتی items خالی یا تعریف‌نشده است، یک متن پیش‌فرض («هیچ رویدادی ثبت نشده») نشان داده می‌شود. با emptyState می‌توانید نود دلخواه جایگزین کنید (مثل یک <Empty> با illustration).

Props

ActionTimeline

ActionTimelineItemData

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

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

• Root <ol> با data-density + data-group-by
• هر آیتم <li> با aria-label="{statusLabel}: {title}" — screen reader وضعیت + عنوان را در کنار هم اعلام می‌کند
• timestamp در <time dateTime={ISO}> با title absolute (هاور tooltip نشان می‌دهد Jalali کامل)
• مارکرها aria-hidden هستند (اطلاعات در aria-label و متن تکرار شده)
• spinner روی status pending با motion-safe:animate-spin — prefers-reduced-motion safe
• وقتی onItemSelect تنظیم باشد، بدنه‌ی آیتم به <button> تبدیل می‌شود با focus ring
• actions slot با onClick={e.stopPropagation()} wrapped — کلیک دکمه‌ها trigger row نمی‌کند

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

• StatusFlow — برای نمایش مرحله‌های یک pipeline نه event history
• NotificationCenter — اگر آیتم‌ها mark-as-read و dismiss دارند
• JobCard — برای هر job احتمالاً یک «تاریخچه‌ی اقدامات» داخلی می‌خواهید؛ ActionTimeline درون آن قرار می‌گیرد
• PostCard — برای نمایش پست کامل، نه event atomic