نوار ابزار جدول داده (DataTableToolbar)

معرفی

دو کامپوننت جانبی برای استفاده در toolbar بالای DataTable. هر دو روی API های موجود DataTable (columnVisibility prop) و export utilityها (CSV/TSV builders) سوار شده‌اند.

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

• برای جدول‌های ستون‌زیاد که کاربر باید ستون‌های نمایشی را خودش انتخاب کند (مانند گزارش کمپین تخفیف فصلی با ده‌ها ستون متریک)
• زمانی که کاربر به خروجی داده‌ی جدول نیاز دارد — CSV برای Excel یا کپی TSV برای paste در Sheets/Notion
• وقتی می‌خواهید کنترل‌های جدول را در یک نوار ابزار واحد و یکدست بالای DataTable جمع کنید

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

• برای جدول‌های کوچک با ستون‌های ثابت و اندک — dropdown مدیریت ستون فقط پیچیدگی اضافه می‌کند
• برای خروجی PDF یا XLSX — این کامپوننت فقط CSV/TSV تولید می‌کند؛ از کتابخانه‌ی external با یک Button معمولی استفاده کنید
• وقتی export باید سمت سرور انجام شود — DataTableExportButton فقط همان data سمت کلاینت را serialize می‌کند؛ در جدول‌های server-paged یعنی فقط صفحه‌ی جاری

زمین بازی

با تغییر variant و size، نوار ابزار را به‌صورت زنده مشاهده کنید.

استفاده

import { DataTable, DataTableColumnVisibilityToggle, DataTableExportButton } from '@partodata/ui'

هر دو کامپوننت controlled و بدون state داخلی هستند: DataTableColumnVisibilityToggle همان object مربوط به columnVisibility را دریافت می‌کند که به خود DataTable می‌دهید، و DataTableExportButton همان تعاریف columns و data جدول را (در صورت نیاز با exportValue برای سلول‌های React-element). هر دو را در یک container با flex items-center gap-2 در سمت end بالای جدول کنار هم قرار دهید. جزئیات API و مثال هر کدام در دو بخش بعدی آمده است.

DataTableColumnVisibilityToggle

Dropdown با checkbox برای روشن/خاموش کردن هر ستون + دکمه‌ی Reset.

import { DataTable, DataTableColumnVisibilityToggle } from '@partodata/ui'

const [visible, setVisible] = React.useState<Record<string, boolean>>({})
const visibility = { visible, onVisibilityChange: setVisible }

<div className="flex items-center gap-2">
  <DataTableColumnVisibilityToggle columns={columns} visibility={visibility} />
</div>

<DataTable columns={columns} data={data} columnVisibility={visibility} />

DataTableExportButton

Dropdown با دو گزینه: Download CSV (فایل با BOM-prefixed UTF-8، مناسب Excel فارسی) و Copy as TSV (کلیپبورد، مناسب paste به Sheets/Notion). از buildCsv / buildTsv / downloadFile helpers هم به‌صورت standalone export شده‌اند.

import { DataTableExportButton } from '@partodata/ui'
;<DataTableExportButton
  filename="comments-2026-04.csv"
  data={rows}
  columns={[
    { id: 'name', header: 'نام', cell: (r) => r.name, exportValue: (r) => r.name },
    { id: 'sentiment', header: 'احساس', cell: (r) => r.sentiment, exportValue: (r) => r.sentiment },
    { id: 'count', header: 'تعداد', cell: (r) => r.count, exportValue: (r) => r.count },
  ]}
/>

ستون‌ها از همان DataTableColumn معمول استفاده می‌کنند (id + header + cell). اگر می‌خواهید مقدار export شده با مقدار رندر تفاوت داشته باشد، exportValue را تعریف کنید — در غیر این صورت cell به‌صورت پیش‌فرض serialize می‌شود.

برای PDF/Excel xlsx، DS قصد ندارد library سنگین وارد کند — از npm package های external استفاده کنید (xlsx، pdfmake) و آنها را با خود <Button> invoke کنید.

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

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

DataTableColumnVisibilityToggle

DataTableExportButton

Helperهای standalone

• buildCsv(columns, data) → string — تولید CSV با escape مناسب (کاما، نقل قول، newline)
• buildTsv(columns, data) → string — تولید TSV (tab-separated)
• downloadFile(filename, content, mime?) — trigger دانلود مرورگر با BOM برای UTF-8

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

• هر دو کامپوننت روی Radix DropdownMenu ساخته شده‌اند — open/close با Enter/Space روی trigger، navigation با Arrow keys، Escape برای close.
• آیکون‌های Settings2 و Download با aria-hidden="true" رندر می‌شوند؛ متن دکمه (label یا locale-aware fallback) مسئول a11y است.
• DropdownMenuCheckboxItem در ColumnVisibilityToggle خود role="menuitemcheckbox" و aria-checked معنادار را تأمین می‌کند.
• پس از انتخاب CSV/TSV، menu بسته می‌شود ولی هیچ live announcement خودکار نیست؛ برای داده‌ی بزرگ یک Toast با feedback نمایش دهید (به راهنمای استفاده مراجعه کنید).
• در RTL، align="end" روی DropdownMenuContent به سمت start منطقی align می‌شود — physical right/left استفاده نشده.

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

• خود جدول → DataTable
• مقایسه‌ی ردیف‌های انتخاب‌شده → TableComparisonView
• سلول‌های inline (sparkline، trend، sentiment) → DataTableCells (در manifest)