سل‌های جدول داده (DataTableCells)

معرفی

DataTable v2 با cell renderer های زیر می‌تواند inline charts و badges در ستون‌ها داشته باشد. هر renderer یک wrapper نازک روی کامپوننت‌های موجود DS است که برای استفاده در سلول جدول بهینه شده — اندازه ثابت، بدون margin/padding خارجی، typography یکدست.

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

• وقتی ستونی از جدول باید متریک، روند یا وضعیت را فشرده نمایش دهد (مثل نرخ تعامل کمپین تخفیف فصلی یا وضعیت رونمایی محصول) — footprint و typography از پیش برای سلول و هر دو تراکم جدول tune شده است (بخش «تراکم و ارتفاع ردیف»)
• وقتی همان الگوی بصری در چند جدول تکرار می‌شود — استفاده از renderer آماده، یکدستی density و alignment را تضمین می‌کند
• وقتی می‌خواهید کامپوننت DS موجود (Sparkline، SeverityBadge، Progress و …) را بدون tune دستی اندازه و فاصله داخل سلول بیاورید

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

• برای layout سفارشی سلول (چند خط متن، دکمه عملیات، ترکیب آزاد چند عنصر) — یک custom cell با JSX خودتان در cell() برگردانید
• خارج از DataTable — نسخه standalone همان کامپوننت (Sparkline، SeverityBadge، Progress و …) را استفاده کنید
• وقتی سلول به تعامل نیاز دارد (ویرایش inline، منوی عملیات) — این rendererها صرفاً نمایشی هستند

هفت cell renderer:

• SparklineCell — sparkline + مقدار اختیاری (مثل 3.2٪)
• TrendCell — arrow up/down/flat با مقدار absolute (پشتیبانی از invert برای متریک معکوس و tone برای رنگ جدا از جهت، neutral برای حجم)
• SeverityCell — SeverityBadge در ردیف، با برچسب اختیاری
• SentimentCell — Distribution kind="sentiment" در عرض ثابت (پیش‌فرض 80px)، هم‌تراکم با جدول
• FlowCell — Distribution kind="flow" در عرض ثابت (پیش‌فرض 96px)، هم‌تراکم با جدول
• ProgressCell — Progress bar افقی + مقدار ٪
• StatDeltaCell — مقدار اصلی + delta arrow کنار هم

تراکم و ارتفاع ردیف

هر renderer زیر سقف محتوای ردیف می‌ماند تا همهٔ ردیف‌ها یک ارتفاع داشته باشند (نسخهٔ 4.0). جدول default برای محتوا 35 پیکسل جا دارد (44 منهای 8 پیکسل فاصلهٔ بالا و پایین و 1 پیکسل خط زیر ردیف) و جدول compact 27 پیکسل (36 − 8 − 1). محتوای 1 پیکسل بلندتر، ردیف را 1 پیکسل بلندتر می‌کند و virtualize.rowHeight دیگر درست نیست.

• SentimentCell و FlowCell تراکم جدولی را که در آن هستند می‌خوانند (بیرون از جدول مثل default). راهنمای رنگ‌ها در حالت stacked به عرض سلول می‌شکند؛ فقط خط اولش دیده می‌شود، بقیه برای صفحه‌خوان می‌ماند و نام قابل دسترس نوار کل تفکیک را با درصد اعلام می‌کند.
• با variant="compact" برچسب‌ها هرگز به خط بعد نمی‌روند و width حداقل عرض است؛ ستون به اندازهٔ برچسب‌ها پهن می‌شود.
• variant="bars" برای نمای جزئیات است (کارت، ردیف بازشده)، نه ردیف جدول: ردیف را بلند می‌کند.
• تایپوگرافی. مقدار اصلی هر سلول هم‌اندازهٔ متن جدول است (14 پیکسل، در جدول compact 13 پیکسل)، مثل عددهای ستون کناری. پسوند و دلتای کنار آن اندازهٔ caption (12 پیکسل) دارند. SeverityCell بدون label، برچسبِ خودِ نشان سطح را نمایش می‌دهد (12 پیکسل، مثل هر نشان دیگری در ردیف).

زمین بازی

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

استفاده

'use client'
import { DataTable, SparklineCell, TrendCell, SeverityCell, SentimentCell, ProgressCell } from '@partodata/ui'
;<DataTable
  columns={[
    { id: 'name', header: 'نام', cell: (r) => r.name },
    {
      id: 'engagement',
      header: 'تعامل',
      cell: (r) => <SparklineCell data={r.history} value={r.eRate} suffix="٪" />,
    },
    {
      id: 'growth',
      header: 'رشد',
      cell: (r) => <TrendCell comparisonLabel="نسبت به 7 روز قبل" value={r.growthDelta} suffix="٪" />,
    },
    {
      id: 'status',
      header: 'وضعیت',
      cell: (r) => <SeverityCell severity={r.status} label={r.statusLabel} />,
    },
    {
      id: 'sentiment',
      header: 'احساسات',
      cell: (r) => <SentimentCell data={r.sentimentBreakdown} />,
    },
    {
      id: 'progress',
      header: 'پیشرفت',
      cell: (r) => <ProgressCell value={r.progressPct} variant="success" />,
    },
  ]}
  data={rows}
/>

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

SparklineCell

<SparklineCell
  data={[1.2, 1.5, 1.8, 2.1, 2.4]}
  value={2.4}
  suffix="٪"
  variant="area" // یا 'line' (پیش‌فرض) یا 'bars'
  width={64} // px
  height={18} // px
/>

TrendCell

<TrendCell comparisonLabel="نسبت به 7 روز قبل" value={12} suffix="٪" />        // ↑ 12٪ (سبز)
<TrendCell comparisonLabel="نسبت به 7 روز قبل" value={-8} suffix="٪" />        // ↓ 8٪ (قرمز)
<TrendCell comparisonLabel="نسبت به 7 روز قبل" value={-3} invert suffix="٪" /> // ↓ 3٪ → سبز (چون نرخ خطا کمتر = بهتر)
<TrendCell comparisonLabel="نسبت به 7 روز قبل" value={0} />                    // ━ خنثی

SeverityCell

<SeverityCell severity="urgent" label="فوری" />
<SeverityCell severity="medium" />          // برچسب خود نشان («متوسط»)
<SeverityCell severity="low" label="پایین" />

SentimentCell / FlowCell

<SentimentCell
  data={{ positive: 50, negative: 20, neutral: 30 }}
  variant="stacked"   // یا 'bars' یا 'compact'
  width={80}
/>

<FlowCell
  data={{ 'pro-gov': 45, 'internal-critic': 25, 'external-opponent': 20, grey: 10 }}
  variant="stacked"
  width={96}
/>

ProgressCell

<ProgressCell value={67} />                    // پیش‌فرض primary
<ProgressCell value={92} variant="success" />
<ProgressCell value={42} variant="warning" />
<ProgressCell value={67} showValue={false} /> // فقط بار، بدون متن

StatDeltaCell

import { StatDeltaCell, formatLargeNumber } from '@partodata/ui'

<StatDeltaCell comparisonLabel="نسبت به 7 روز قبل" value={formatLargeNumber(1240, 'fa')} formatValue={false} delta={12} deltaSuffix="٪" />
// نمایش: 1.2 هزار   +12٪

<StatDeltaCell comparisonLabel="نسبت به 7 روز قبل" value={1240} />
// نمایش: 1,240   (formatValue پیش‌فرض true است — گروه‌بندی هزارگان با کاما، نه با «٬» فارسی)

<StatDeltaCell comparisonLabel="نسبت به 7 روز قبل" value={500} />
// نمایش: 500   (بدون delta)

<StatDeltaCell comparisonLabel="نسبت به 7 روز قبل" value={45} delta={-8} invertDelta />
// نمایش: 45   ↑ 8 (سبز چون invert)

Props

SparklineCell

TrendCell

SeverityCell

SentimentCell

FlowCell

ProgressCell

StatDeltaCell

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

• هر cell یک data-slot="<name>-cell" دارد — برای CSS/telemetry.
• متن مقدار همیشه با اعداد محلی فرمت می‌شود.
• TrendCell جهت را با آیکون + رنگ منتقل می‌کند، نه فقط رنگ.
• SparklineCell بدون value یک role="img" با نام محلی‌شده می‌گیرد (یا aria-label خودتان)؛ وقتی value نمایش داده می‌شود، خودِ عدد محتوای قابل دسترس است و نمودار تزئینی می‌ماند.
• SeverityCell سطح را با آیکون + برچسب منتقل می‌کند، نه فقط رنگ.

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

• DataTable — جدول اصلی که این cellها در آن استفاده می‌شوند
• Sparkline — sparkline standalone
• TrendIndicator — trend indicator standalone
• SeverityBadge — status badge standalone
• Distribution — distribution مستقل
• Progress — bar پیشرفت standalone