جریان وضعیت (StatusFlow)

معرفی

StatusFlow تجسم یک pipeline چندمرحله‌ای است — کاربر اجرا نمی‌کند، سیستم اجرا می‌کند و StatusFlow به کاربر نشان می‌دهد «کجای زنجیره هستیم». هر مرحله وضعیت مستقل خود را دارد: pending | running | completed | failed | skipped | warning | paused. درون مرحله‌ی running می‌توانید درصد پیشرفت را نیز نمایش دهید.

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

• Pipeline تحلیل async (کامنت‌سنج: واکشی → پردازش → برچسب‌زنی → بازبینی → گزارش)
• چرخه‌ی lifecycle worker (Booster: login → 2FA → warmup → HASE → operational)
• stage‌های ارزیابی پیج (ارزیابی: PENDING → PROCESSING → COMPLETED|FAILED با زیرمرحله‌ها)
• جایی که می‌خواهید بگویید «در مرحله‌ی 3 از 5 هستیم و 45٪ از آن انجام شده»

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

• چرخه‌ای که کاربر خودش پیش می‌برد (wizard: Next/Previous) — از Stepper استفاده کنید
• فقط یک وضعیت (running/completed/failed) دارید — از JobCardStatusBadge کافی است
• pipeline بی‌شمار مرحله (>8) — در فضای افقی جا نمی‌شود، از orientation="vertical" استفاده کنید یا درخت tree نشان دهید

زمین بازی

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

استفاده

حالت data-driven (پیش‌فرض)

import { StatusFlow } from '@partodata/ui'

export function AnalysisPipeline() {
  return (
    <StatusFlow
      stages={[
        { id: 'fetch', label: 'دریافت کامنت‌ها', status: 'completed', description: '1,250 کامنت' },
        { id: 'parse', label: 'پردازش فایل', status: 'completed' },
        { id: 'label', label: 'برچسب‌زنی', status: 'running', progress: 45 },
        { id: 'review', label: 'بازبینی', status: 'pending' },
        { id: 'report', label: 'گزارش', status: 'pending' },
      ]}
    />
  )
}

حالت composition (برای سفارشی‌سازی per-stage)

<StatusFlow>
  <StatusFlowStage id="a" label="دریافت" status="completed" />
  <StatusFlowStage id="b" label="پردازش" status="completed" />
  <StatusFlowStage id="c" label="تحلیل" status="running" progress={60} />
  <StatusFlowStage id="d" label="تحویل" status="pending" />
</StatusFlow>

هفت وضعیت canonical

StageStatusKey: pending | running | completed | failed | skipped | warning | paused

• pending — هنوز شروع نشده. مارکر خاموش، کانکتور خاکستری یک‌دست.
• running — در حال اجرا. مارکر برند با spinner، کانکتور بعد از آن dashed.
• completed — با موفقیت تمام شد. ✓ سبز.
• failed — خطا. × قرمز، کانکتور هم قرمز.
• skipped — رد شده (مثلاً تنظیمات بود خاموش). خط تیره خاموش.
• warning — تمام شد ولی با هشدار. مثلث هشدار، کانکتور زرد.
• paused — منتظر (rate-limit، دخالت کاربر). آیکون Pause، کانکتور dashed زرد.

عمودی (برای سایدبار یا فضاهای باریک)

در حالت عمودی، label به سمت انتهای منطقی (inset-inline-end) قرار می‌گیرد و کانکتور یک خط عمودی است. بهترین برای سایدبار پروفایل یا drawer جزئیات.

اندازه‌ها

• sm — مارکر 20px، مناسب ردیف‌های فشرده داخل JobCard یا لیست
• md (پیش‌فرض) — مارکر 28px، استاندارد
• lg — مارکر 36px، برای صفحات اختصاصی pipeline

ترکیب با JobCard

الگوی معمول: JobCard یک شاخص وضعیت کلی (running/completed/failed) دارد، و StatusFlow زیر Header، جزئیات pipeline را باز می‌کند. از size="sm" استفاده کنید تا ارتفاع کارت زیاد نشود.

مراحل قابل‌کلیک

با onStageSelect مارکرها به دکمه تبدیل می‌شوند. مناسب برای باز کردن Drawer جزئیات هر مرحله یا تنظیمات آن.

Props

StatusFlow

StatusFlowStageData

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

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

• Root یک <ol> با data-orientation + data-size است و role="list" را صریح اعلام می‌کند — screen reader «لیست مرتبی از ... مرحله» را اعلام می‌کند. این نقشِ صریح لازم است، چون root در هر دو جهت display: flex است و WebKit (Safari/VoiceOver) نقش ضمنی list را از چنین فهرستی حذف می‌کند
• هر مرحله یک <li> با role="listitem" صریح و aria-label="{label} — {statusLabel}" است
• مرحله‌ی running دارای aria-current="step" است
• وقتی onStageSelect تنظیم باشد، مارکرها به <button> تبدیل می‌شوند با focus ring درست
• spinner روی مارکر running با motion-safe:animate-spin ست شده — در prefers-reduced-motion ساکن می‌ماند
• رنگ نه تنها راه تمایز: هر وضعیت آیکون معنایی اختصاصی دارد + متن وضعیت به عنوان aria-label خوانده می‌شود
• کانکتورها aria-hidden="true" هستند (زینتی)

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

• Stepper — برای wizard کاربرمحور (Next/Previous)؛ StatusFlow برای pipeline سیستمی
• JobCard — StatusFlow معمولاً زیر JobCardHeader قرار می‌گیرد تا جزئیات چرخه‌عمر را به یک شاخص کلی (JobCardStatusBadge) اضافه کند
• Progress — progress bar خطی تک‌متغیره؛ StatusFlow برای multi-stage
• Breadcrumb — مسیر ناوبری URL-driven؛ مفهوماً متفاوت