سلول وضعیت (StatusCell)

معرفی

هر جدول عملیاتی یک ستون وضعیت دارد. StatusCell همان را یک‌جا و قاعده‌مند می‌کند: یک نقطه با یکی از چهار رنگ معنایی گرامر (سبز، کهربایی، آبی، قرمز) یا خاکستری خنثی، برچسب متنی با وزن 400 و یک caption کم‌رنگ‌تر برای دلیل یا گام بعد («پایان: 2 روز دیگر»).

سه قاعده در خودِ کامپوننت است، نه در سلیقهٔ هر صفحه:

• رنگ فقط از tone می‌آید؛ رنگ دلخواه ممکن نیست. tone ناشناخته خنثی رسم می‌شود و در توسعه هشدار می‌دهد.
• رنگ تنها معنا نمی‌دهد: label الزامی و همیشه متن است و نقطه aria-hidden است.
• متن وزن 400 است و caption با foreground-lighter؛ نقطهٔ پالس برای حالتِ «در حال انجام» است و زیر prefers-reduced-motion ساکن می‌ماند.

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

• ستون وضعیت یک جدول یا فهرست («فعال»، «نیاز به ورود»، «سوخته · قفل»)
• هر جایی که حالت یک موجودیت با «نقطه + برچسب» نشان داده می‌شود
• نشانگر کنار یک برچسب (StatusDot)، مثل «تغییرات ذخیره‌نشده»

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

• برای حالت‌های چندمرحله‌ای با پیشرفت هر مرحله — از StatusFlow استفاده کنید
• برای اولویت یا فوریت — از SeverityBadge استفاده کنید
• برای شمار یا برچسب دسته‌بندی — از Badge استفاده کنید
• برای رنگ تزئینی یا دسته‌بندیِ بی‌معنا؛ رنگ معنایی فقط برای وضعیت است

زمین بازی

استفاده

import { StatusCell } from '@partodata/ui'

// سلول یک ستون جدول
<StatusCell tone="success" label="فعال" />
<StatusCell tone="destructive" label="سوخته · قفل" caption="قفل تا 3 روز دیگر" />
<StatusCell tone="info" label="در حال ورود" pulse />

در ستون یک DataTable یا Table:

const columns = [
  { id: 'handle', header: 'اکانت', cell: (row) => row.handle },
  {
    id: 'status',
    header: 'وضعیت',
    cell: (row) => <StatusCell tone={TONE[row.state]} label={LABEL[row.state]} />,
  },
]

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

چهار رنگ و خنثی

گرامر بصری سقف چهار رنگ معنایی در یک صفحه‌نمایش می‌گذارد؛ خاکستری شمرده نمی‌شود.

نقطهٔ تنها

StatusDot همان نقطهٔ 8px است، بدون برچسب، برای کنار متنی که خودتان می‌نویسید. چون رنگ به‌تنهایی معنا ندارد، همیشه کنار متن بگذارید.

رفتار

• برچسب و caption در سلول بریده می‌شوند (truncate) و در صورت رشته بودن، متن کامل در title می‌آید؛ سلول هرگز دو سطری نمی‌شود.
• نقطه با خط اول برچسب هم‌تراز است، نه با مرکز برچسب و caption.
• پالس حلقه‌ای هم‌رنگ است که بزرگ می‌شود و محو می‌شود؛ با motion-safe اجرا می‌شود و برای کاربرِ «کاهش حرکت» حذف است.
• جهت: فقط ویژگی‌های منطقی؛ در RTL نقطه در ابتدای سطر (سمت راست) و در LTR در سمت چپ است.
• رقم: رقم‌ها ASCII نوشته می‌شوند و فونت آن‌ها را فارسی نشان می‌دهد.

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

Props

StatusCell

StatusDot

نقطهٔ دست‌ساز

قاعدهٔ ESLint parto/no-handmade-status-dot عنصر DOM خالیِ گرد 6 تا 10 پیکسلی با رنگ پرکنندهٔ وضعیت (bg-success، bg-warning، bg-info، bg-destructive) را گزارش می‌کند.

// ❌ دست‌ساز
<span className="size-2 rounded-full bg-success" />

// ✅
<StatusCell tone="success" label="فعال" />

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

• نقطه aria-hidden است؛ صفحه‌خوان فقط برچسب و caption را می‌خواند، پس معنا هرگز فقط در رنگ نیست.
• StatusCell تعاملی نیست و فوکوس نمی‌گیرد؛ اگر سلول لینک یا دکمه است، آن را خودتان دورش بگذارید.
• پالس برای کاربرِ «کاهش حرکت» حذف می‌شود و حالت تنها با رنگ و برچسب خوانده می‌شود.
• رنگ نقطه یک نشانهٔ غیرمتنی است و به‌تنهایی لازم نیست؛ تفاوت بین حالت‌ها در متن هم آمده است.

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

• حالت چندمرحله‌ای با درصد پیشرفت هر مرحله → StatusFlow، نه چند StatusCell پشت هم
• اولویت و فوریت (فوری/بالا/متوسط/پایین) → SeverityBadge
• شمار یا برچسب به‌شکل قرص → Badge؛ حالتِ یک ردیف جدول → StatusCell
• جدول خودش → DataTable (ستون وضعیت یک cell با StatusCell است)