@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/data-table.md

@@ -0,0 +1,474 @@
+# DataTable
+
+> A data grid built on TanStack react-table v8, composed over the Table primitives — sorting, filtering (text + per-column), column visibility, row selection, pagination, optional row expansion (row-level or an in-cell expand trigger), column resizing, drag-to-reorder columns, and sticky (pinned) columns. Renders a built-in trailing action column (the column-settings cog in the header, a per-row overflow-actions trigger in each row) and per-header capability-hint tooltips, and navigates rows with a roving tabindex. Ships with companion parts (column header, toolbar, pagination, view options, expand trigger, bulk-actions bar). Also supports server-driven usage: rendering from an externally-built TanStack `table` instance, manual (server-driven) sorting, infinite-scroll pagination, and custom row/empty-state rendering. Ported from the legacy shadcn-uikit `data-table`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.42.0
+
+## Import
+
+```tsx
+import { DataTable } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<DataTable columns={columns} data={rows} />
+```
+
+A data grid built on TanStack react-table v8, composed over the Table
+primitives — sorting, filtering, column visibility, row selection, pagination,
+optional row expansion, column resizing, and sticky (pinned) columns.
+
+> **Status: draft (design-pending v1).** Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `data-table`. Adds no color of its own — it
+> composes already-themed ui-react components. Reconcile with
+> `/figma-component DataTable <url> --update` once a mockup lands.
+
+## When to use
+
+- Tabular data that needs interaction — sorting, filtering, selection, paging,
+  column resizing, drag-to-reorder columns, or a few columns pinned while the
+  rest scroll horizontally.
+
+## When not to use
+
+- A simple static table — use the `Table` primitives directly.
+- A key/value list or cards layout — a table is the wrong shape.
+- Grouped/aggregated rows — **not available yet** (deferred to a future
+  revision); do not rely on them. (Drag-to-reorder columns _is_ supported now,
+  via `enableColumnReordering`.)
+
+## Parts
+
+| Export                    | Purpose                                                                                                                                                                                                                                   |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DataTable`               | The grid. Owns table state by default (`columns` / `data`), or renders a caller-built `table` instance. Supports resizing, pinned columns, server-driven sorting/pagination, and custom row/empty-state rendering.                        |
+| `DataTableColumnHeader`   | A sortable column header — single-click toggle (↑/↓/↕). Use in a column's `header`.                                                                                                                                                       |
+| `DataTableToolbar`        | Search box + per-column filters + applied-filter chips. Takes a `table` instance.                                                                                                                                                         |
+| `DataTablePagination`     | Selection count, rows-per-page, page controls. Takes a `table`.                                                                                                                                                                           |
+| `DataTableViewOptions`    | Column-visibility menu (a thin TanStack adapter over the `TableViewOptions` primitive). Pass `iconOnly` for the cog trigger that belongs in the trailing settings column.                                                                 |
+| `DataTableExpandTrigger`  | A chevron toggle wired to a row's expansion state, placed inside a column's `cell` render function.                                                                                                                                       |
+| `DataTableBulkActionsBar` | A selection-aware bar above the grid: the consumer's bulk actions in a `<fieldset>` disabled until a selection is active, plus the selection summary and a Deselect control (or `loadedLabel` when nothing is selected). Takes a `table`. |
+| `isBulkSelectionActive`   | The single predicate for the bulk-selection threshold (one or more rows selected). Pass it to `TableActionsCell`'s `bulkSelectionActive` rather than re-deriving it.                                                                      |
+
+`DataTable` manages its own table state by default. The companion parts
+operate on a TanStack `table` instance you build with `useReactTable` — render
+them around a `DataTable` (or your own `<Table>`), passing the same instance.
+Pass that same instance to `DataTable`'s own `table` prop to have it render
+from it too (see **Server-driven usage** below).
+
+## Server-driven usage
+
+- **External `table`** — pass an externally-built TanStack `table` instance
+  via the `table` prop and DataTable renders from it as-is, owning no state of
+  its own. Use this to share one instance across `DataTable` and its companion
+  parts, or when the caller needs full control (e.g. a table already wired to
+  a URL/query-state hook). Several props become no-ops when `table` is passed
+  — see `table`'s own description in `api.yaml`.
+- **Manual sorting** — set `manualSorting` and drive `sorting` /
+  `onSortingChange` yourself; DataTable skips its own comparator so already
+  server-sorted `data` isn't re-sorted client-side.
+- **Infinite scroll** — set `paginationMode="infinite"` and pass the full
+  accumulated `data`, `hasNextPage`, `isLoadingMore`, and an `onLoadMore`
+  callback. DataTable renders a sentinel row that calls `onLoadMore` once it
+  scrolls into view, and a trailing loading row while `isLoadingMore` is true.
+  The sentinel needs at least one row already rendered — it can't drive an
+  empty table's very first fetch, so seed the first page yourself (e.g. on
+  mount). Pass `loadMoreRootMargin` (e.g. `'400px'`) to fire `onLoadMore`
+  before the sentinel is literally visible, so the fetch has a head start on
+  the user's scroll — tune it relative to your page size, since a large
+  margin with small pages can trigger several `onLoadMore` calls back-to-back
+  as the user scrolls normally. Does not compose with virtualization — for a
+  very large accumulated list, virtualize the raw `Table` primitives yourself
+  (e.g. `useVirtualizer` from `@tanstack/react-virtual`) instead.
+- **Custom rows** — `renderRow` swaps in a fully custom row, bypassing
+  DataTable's per-cell `flexRender` path (and, as a result, its own row
+  expansion — a row rendered via `renderRow` must implement any expanded
+  content itself). `renderEmptyState` swaps in a custom "no data" row,
+  receiving `hasFilters` so the caller can distinguish "no data at all" from
+  "no matches".
+
+## Advanced columns
+
+- **Column resizing** — set `enableColumnResizing` on `DataTable` to render a
+  drag handle at the trailing edge of each resizable header (TanStack's native
+  `columnResizing`). Pass `onColumnSizingChange` to persist widths.
+- **Sticky (pinned) columns** — set `meta.pin: 'left' | 'right'` on a
+  `ColumnDef`. DataTable drives TanStack's native column-pinning and renders the
+  column as `position: sticky` cells with an opaque row background.
+- **Wrapping columns** — set `meta.wrap: true` on a `ColumnDef` to let that
+  column's header and cell content wrap onto multiple lines instead of
+  truncating, mirroring the `Table` primitives' `wrap` prop.
+- **Expandable column** — put a `DataTableExpandTrigger` in a column's `cell`
+  render function so the expand affordance sits in a real column instead of a
+  whole-row click. It reads `row.getCanExpand()` / `getIsExpanded()` and calls
+  `row.toggleExpanded()`; the row-level `getRowCanExpand` / `renderExpandedRow`
+  contract is unchanged.
+- **Per-column filtering** — pass filter fields as `children` to
+  `DataTableToolbar`. They render inside a `FilterSearchFilters` popover (wire
+  each field via `useFilterSearchFilters()` keyed by column id), and the toolbar
+  renders a `FilterSearchAppliedFilters` chip row below itself. `filtersLabel`
+  and `getFilterChipLabel` customize the trigger and chip labels.
+
+## Example
+
+```tsx
+import { DataTable, DataTableColumnHeader } from '@acronis-platform/ui-react';
+import type { ColumnDef } from '@tanstack/react-table';
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'name',
+    header: ({ column }) => (
+      <DataTableColumnHeader column={column} title="Name" />
+    ),
+    meta: { pin: 'left' }, // sticky column
+  },
+  { accessorKey: 'amount', header: 'Amount' },
+];
+
+// Resizable, with the first column pinned left
+<DataTable columns={columns} data={payments} enableColumnResizing />;
+```
+
+For a toolbar + pagination, build a `table` with `useReactTable` and pass it to
+`DataTableToolbar` / `DataTablePagination` alongside the grid; pass filter fields
+as `children` of the toolbar for per-column filtering.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `columns` | `ColumnDef<TData, TValue>[]` | — | no | TanStack column definitions (header / cell renderers, accessors). Required unless `table` (an externally-built instance) is passed. |
+| `data` | `TData[]` | — | no | The row data. Required unless `table` is passed. |
+| `resize-column-label` | `string` | `'Resize column'` | no | Accessible name of a column's resize handle (`enableColumnResizing` only). Override to localize. |
+| `empty-label` | `string` | `'No results.'` | no | Text of the default empty-state row; ignored when `renderEmptyState` is given. Override to localize. |
+| `rows-per-page-label` | `string` | `'Rows per page'` | no | On the pagination part — label of the rows-per-page select (also its accessible name). Override to localize. The pagination part also takes `first-page-label`, `previous-page-label`, `next-page-label`, `last-page-label`, `page-label` and `summary-label`. `summary-label` is `(selected: number, total: number) => string`, always called with concrete counts — unlike `TablePagination`'s `(selectedRows: number | undefined, totalRows: number) => string | null`, it never receives `undefined`/`null`. |
+| `expand-label` | `string` | `'Expand row'` | no | On the expand-trigger part — accessible name while the row is collapsed. Override to localize. |
+| `collapse-label` | `string` | `'Collapse row'` | no | On the expand-trigger part — accessible name while the row is expanded. Override to localize. |
+| `sort-label` | `(title: string) => string` | `(title) => `Sort by ${title}`` | no | On the column-header part — builds the accessible label of the sort toggle from the column title. Override to localize. |
+| `table` | `Table<TData>` | — | no | Render from an externally-built TanStack `table` instance instead of DataTable's own — DataTable then owns no state. Makes the following no-ops (configure the equivalent on the external instance instead): columnVisibility, onColumnVisibilityChange, onColumnSizingChange, enableColumnResizing, getRowCanExpand, manualSorting, sorting, onSortingChange, paginationMode, onLoadMore, loadMoreRootMargin, hasNextPage, isLoadingMore. meta.pin-driven column pinning is also skipped — pin/unpin the external instance directly via TanStack's `column.pin()`. |
+| `getRowCanExpand` | `(row: Row<TData>) => boolean` | — | no | Enables row expansion for rows that return true. Pair with renderExpandedRow. |
+| `renderExpandedRow` | `(row: Row<TData>) => ReactNode` | — | no | Renders the detail content for an expanded row. |
+| `striped` | `boolean` | `false` | no | Alternating row backgrounds (borrowed from the Vue AvTable). |
+| `bordered` | `boolean` | `false` | no | Vertical borders between columns (rows already have horizontal borders). |
+| `highlightCurrentRow` | `boolean` | `false` | no | Highlight the row the user last clicked (the "current" row). |
+| `skeleton` | `boolean` | `false` | no | Render placeholder skeleton rows instead of data (loading state). |
+| `skeletonRows` | `number` | `5` | no | Number of skeleton rows when skeleton is set. |
+| `enableColumnResizing` | `boolean` | `false` | no | Opt in to interactive column resizing — renders a drag handle at the trailing edge of each resizable header (TanStack's native `columnResizing`, `columnResizeMode: 'onChange'`). |
+| `enableColumnReordering` | `boolean` | `false` | no | Opt in to column reordering by dragging a header cell onto another one (native HTML5 drag-and-drop driving TanStack's `columnOrder`; the dragged header dims while the gesture is in flight). Pinned columns are excluded — they're anchored to a table edge by definition. Pointer-only: there is no keyboard equivalent yet. No-op when `table` is passed. |
+| `columnOrder` | `ColumnOrderState` | — | no | Controlled column-order state; pairs with `onColumnOrderChange` (e.g. to persist the user's order). Uncontrolled (internal state) when omitted. No-op when `table` is passed. |
+| `rowSelection` | `RowSelectionState` | — | no | Controlled row-selection state; pairs with `onRowSelectionChange` (e.g. to share one selection state with an external `useReactTable` instance that feeds a composed toolbar/bulk-actions bar). Uncontrolled (internal state) when omitted. |
+| `hideActionColumn` | `boolean` | `false` | no | Hide the trailing sticky action column — the column-visibility cog in the header and each row's overflow-actions ellipsis. Shown by default. No-op when `table` is passed (build the column into that instance's own `columns` instead). |
+| `renderRowActions` | `(row: Row<TData>) => ReactNode` | — | no | Renders the content of a row's overflow-actions menu (e.g. Edit/Delete items), opened from the ellipsis trigger in the trailing action column. Omit to render that row without a trigger — the 48px column is still reserved. Suppressed (like the trigger itself) while a bulk selection is active, per `TableActionsCell`. |
+| `rowActionsLabel` | `string` | `'Row actions'` | no | Accessible name of a row's overflow-actions trigger. Override to localize. |
+| `columnSettingsLabel` | `string` | — | no | Accessible name of the action column's column-visibility trigger. Override to localize; falls through to the view-options part's own default ("Column settings") when omitted. |
+| `headerHints` | `Partial<DataTableHeaderHints>` | `{ sort: { label: 'Sort column', action: 'Click' }, reorder: { label: 'Reorder column', action: 'Drag' }, resize: { label: 'Resize column', action: 'Drag border' } }` | no | Copy of the tooltip shown while a header cell is hovered/focused — one `{ label, action }` line per capability that column actually has (`sort` / `reorder` / `resize`). Merged over the defaults, so any subset can be overridden to localize; a column with no capability shows no tooltip at all. |
+| `bulkSelectionActive` | `boolean` | `false` | no | On the `TableActionsCell` part — suppress this row's actions because a *bulk* selection is in play. The cell still reserves its 48px column but renders no children and no hover/press tint. Pass `isBulkSelectionActive(table)` (exported alongside DataTable) rather than re-deriving the threshold: **one or more rows selected**, including exactly one. |
+| `meta.pin` | `'left' | 'right'` | — | no | Set on a `ColumnDef.meta` (not a DataTable prop) — pins the column to a table edge. DataTable drives TanStack's native column-pinning and renders the column as `position: sticky` cells with an opaque row background. |
+| `meta.wrap` | `boolean` | — | no | Set on a `ColumnDef.meta` (not a DataTable prop) — allows a column's header and cell content to wrap onto multiple lines instead of truncating, mirroring the `Table` primitives' `wrap` prop. |
+| `children` | `ReactNode` | — | no | On DataTableToolbar — filter fields rendered inside a `FilterSearchFilters` popover (wire each to a column via `useFilterSearchFilters()` keyed by column id). When provided, the toolbar renders the filter popover plus a `FilterSearchAppliedFilters` chip row below it. |
+| `filtersLabel` | `ReactNode` | `'Filters'` | no | On DataTableToolbar — label for the filters trigger button. |
+| `getFilterChipLabel` | `(key: string, value: unknown) => ReactNode` | — | no | On DataTableToolbar — formats an applied-filter chip's label (defaults to "<id>: <value>"). |
+| `selectedLabel` | `(count: number) => string` | `(count) => `${count} item${count === 1 ? '' : 's'} selected:`` | no | On DataTableBulkActionsBar — builds the trailing selection summary from `table.getSelectedRowModel().rows.length`. Override to localize. The bar also takes `clear-label` (default "Deselect"), the trailing control that calls `table.resetRowSelection()`, and `children` — the bulk actions, rendered *leading* (ahead of the trailing summary/Deselect group, which is pushed to the far edge with `ms-auto`) and wrapped in a native `<fieldset disabled>` while nothing is selected, so every nested control picks up the disabled state without per-action wiring. The bar is not rendered by DataTable: the consumer mounts it over the same external `table` instance that feeds the checkbox column (see the `data-table-bulk-actions` pattern). It is **always mounted** — it never renders nothing. Instead it toggles between two states on `isBulkSelectionActive(table)` (one or more rows selected): with nothing selected the actions are disabled and the trailing side shows `loadedLabel`; from the first selected row on, the actions enable and the trailing side shows the selection summary plus the clear control. |
+| `loadedLabel` | `ReactNode` | — | no | On DataTableBulkActionsBar — trailing text shown in place of the selection summary while nothing is selected (e.g. "25 of 1250 items loaded"). Omit to render nothing in that state. Override to localize. |
+| `manualSorting` | `boolean` | `false` | no | Opt out of client-side sorting — pass already-sorted `data` and drive sorting via `sorting`/`onSortingChange` (e.g. mapped to a server query by the caller). Mapping sort state to a query and refetching stays the caller's job. No-op when `table` is passed. |
+| `sorting` | `SortingState` | — | no | Controlled sorting state; pairs with `onSortingChange`. Uncontrolled (internal state) when omitted. No-op when `table` is passed. |
+| `renderRow` | `(row: Row<TData>, rowIndex: number) => ReactNode` | — | no | Renders a full row, bypassing DataTable's default per-cell `flexRender` path entirely. Use to swap in a custom, independently memoizable row component — the caller owns the row's markup and equality semantics. Reuse the exported `getCellStyle` / `getPinnedStyle` / `getColumnWidth` helpers to match DataTable's default cell styling if desired. Also bypasses `renderExpandedRow` — a row rendered via `renderRow` never gets an expanded-content row appended; read `row.getIsExpanded()` and render it yourself if needed. |
+| `renderEmptyState` | `(context: { hasFilters: boolean }) => ReactNode` | — | no | Renders a custom empty state instead of the default "No results." row. Receives `hasFilters` (whether any column filter is currently applied) so the caller can distinguish "no data at all" from "no matches" — the copy/wording/localization stays the caller's job. |
+| `paginationMode` | `'page' | 'infinite'` | `'page'` | no | `'page'` keeps today's client-paginated behavior. `'infinite'` omits the paginated row model — `data` is the full accumulated array the caller appends to on each `onLoadMore` — and renders a sentinel row that calls `onLoadMore` once it scrolls into view. The sentinel requires at least one row already rendered, so it cannot drive an empty table's very first fetch — seed the first page yourself (e.g. on mount) and use `onLoadMore` for subsequent pages. No-op when `table` is passed. Does not compose with virtualization; for a large accumulated list, virtualize the raw `Table` primitives yourself instead. |
+| `loadMoreRootMargin` | `string` | — | no | Expands the sentinel's `IntersectionObserver` root margin (native CSS margin syntax, e.g. "400px") so `onLoadMore` fires before the sentinel is literally visible, reducing how often the trailing loading row is seen. `paginationMode="infinite"` only; no-op when `table` is passed. How far this actually prefetches also depends on page size — a large margin with small pages can trigger several `onLoadMore` calls back-to-back as the user scrolls normally, which is expected; tune it relative to page size. |
+| `hasNextPage` | `boolean` | `false` | no | Whether more rows are available to load. `paginationMode="infinite"` only. |
+| `isLoadingMore` | `boolean` | `false` | no | Whether a load is in flight — suppresses further `onLoadMore` calls and renders a trailing loading row. `paginationMode="infinite"` only. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onColumnOrderChange` | `ColumnOrderState (TanStack OnChangeFn)` | Passthrough for the `columnOrder` state; pairs with `columnOrder`. Fires with the new order after a header drop when `enableColumnReordering` is set. No-op when `table` is passed. |
+| `onRowSelectionChange` | `RowSelectionState (TanStack OnChangeFn)` | Passthrough for the `rowSelection` state; pairs with `rowSelection`. |
+| `onColumnSizingChange` | `ColumnSizingState (TanStack OnChangeFn)` | Passthrough for the `columnSizing` state so a consumer can persist column widths when `enableColumnResizing` is set. |
+| `onSortingChange` | `SortingState (TanStack OnChangeFn)` | Passthrough for the `sorting` state; pairs with `sorting`. No-op when `table` is passed. |
+| `onLoadMore` | `undefined` | Called when the infinite-scroll sentinel intersects the viewport. `paginationMode="infinite"` only. Requires at least one row already rendered — never fires from an empty table. The fetch-more call, cursor/offset tracking, dedup, and accumulating `data` stay the caller's job. |
+
+## Behavior
+
+DataTable renders a TanStack react-table over the Table primitives. By default
+the grid state (sorting, filtering, visibility, selection, pagination,
+expansion) lives in the component; the companion parts operate on a
+caller-built `table` instance. DataTable can also render from a caller-built
+`table` instance itself (see "Render from an external table instance" below),
+in which case it owns none of that state.
+
+```gherkin
+Scenario: Render rows
+  Given columns and data
+  Then the headers and a row per datum render
+```
+
+```gherkin
+Scenario: Empty
+  Given an empty data array
+  Then a single "No results." row spans only the visible columns
+```
+
+```gherkin
+Scenario: Custom empty state
+  Given renderEmptyState is provided
+  When there are no rows to render
+  Then renderEmptyState is called with hasFilters (whether a column filter is applied)
+  And its return value replaces the default "No results." row
+```
+
+```gherkin
+Scenario: Render from an external table instance
+  Given a `table` instance built by the caller with useReactTable
+  When it is passed to DataTable's `table` prop
+  Then DataTable renders from that instance and owns no state of its own
+  And columnVisibility/onColumnVisibilityChange, onColumnSizingChange,
+      enableColumnResizing, getRowCanExpand, manualSorting, sorting,
+      onSortingChange, and paginationMode-related props are no-ops
+  And DataTable does not drive column pinning from meta.pin on that instance —
+      the caller pins/unpins its own columns via TanStack's column.pin()
+```
+
+```gherkin
+Scenario: Manual (server-side) sorting
+  Given manualSorting and controlled sorting/onSortingChange
+  When the user clicks a DataTableColumnHeader
+  Then onSortingChange fires with the next sort
+  And DataTable does not reorder the rows itself (no client-side comparator runs)
+```
+
+```gherkin
+Scenario: Custom row rendering
+  Given renderRow is provided
+  Then each row is rendered by calling renderRow(row, rowIndex)
+  And DataTable's own per-cell flexRender/pinning/styling path is skipped for that row
+  And no expanded-content row is appended even if getRowCanExpand returns true for it —
+      the caller must read row.getIsExpanded() and render it themselves inside renderRow
+```
+
+```gherkin
+Scenario: Infinite scroll
+  Given paginationMode="infinite" and hasNextPage is true
+  And at least one row is already rendered
+  Then a sentinel row renders as the last row of the body
+  When the sentinel scrolls into view and isLoadingMore is false
+  Then onLoadMore fires
+  And no further onLoadMore calls fire while isLoadingMore is true
+  When isLoadingMore is true
+  Then a trailing loading row renders below the sentinel
+```
+
+```gherkin
+Scenario: Infinite scroll cannot drive the very first fetch
+  Given paginationMode="infinite", data=[], and hasNextPage is true
+  Then no sentinel renders (rows.length is 0) — the default "No results." row renders instead
+  And onLoadMore never fires
+  # The caller must seed the first page itself (e.g. on mount); the sentinel
+  # only drives subsequent pages once at least one row exists.
+```
+
+```gherkin
+Scenario: Prefetching ahead of the literal scroll position
+  Given paginationMode="infinite" and loadMoreRootMargin="400px"
+  Then the sentinel's IntersectionObserver root margin is expanded by that amount
+  And onLoadMore can fire before the sentinel is literally visible in the viewport
+  # How far ahead this effectively prefetches also depends on page size — a
+  # large margin with small pages can trigger several onLoadMore calls
+  # back-to-back as the user scrolls normally; that is expected.
+```
+
+```gherkin
+Scenario: Sort a column in a single click
+  Given a column whose header is a DataTableColumnHeader
+  And the column is unsorted (a muted up/down arrow)
+  When the user clicks the header once
+  Then the rows reorder ascending and the header shows an up arrow in the active blue
+  When the user clicks the header again
+  Then the rows reorder descending and the header shows a down arrow in the active blue
+```
+
+```gherkin
+Scenario: Hide a column
+  Given the toolbar's view-options menu
+  When the user unchecks the column
+  Then that column is removed from the grid
+```
+
+```gherkin
+Scenario: Filter via the toolbar
+  Given a DataTableToolbar with searchKey="email"
+  When the user types into the search box
+  Then only rows whose email matches remain
+  And a Reset button clears the filter (when no filter fields are provided)
+```
+
+```gherkin
+Scenario: Per-column filtering
+  Given a DataTableToolbar given filter-field children
+  And each field is wired to a column via useFilterSearchFilters() by column id
+  When the user sets a field in the filters popover
+  Then that column's filter is committed to the table (the text searchKey is preserved)
+  And an applied-filter chip appears in the row below the toolbar
+  When the user removes the chip
+  Then that column's filter clears
+```
+
+```gherkin
+Scenario: Paginate
+  Given a DataTablePagination bound to the table
+  When the user clicks next / prev / first / last
+  Then the visible page of rows changes
+  And the rows-per-page select changes the page size
+```
+
+```gherkin
+Scenario: Expand a row
+  Given getRowCanExpand returns true and renderExpandedRow is provided
+  When a row is toggled expanded
+  Then a detail row renders beneath it spanning all columns
+```
+
+```gherkin
+Scenario: Expand from a column trigger
+  Given a column whose cell renders a DataTableExpandTrigger
+  And getRowCanExpand returns true and renderExpandedRow is provided
+  When the user clicks the chevron trigger in that cell
+  Then the row toggles expanded (aria-expanded flips) and the detail row renders
+  And the trigger renders nothing for a row that can't expand
+```
+
+```gherkin
+Scenario: Resize a column
+  Given a DataTable with enableColumnResizing
+  When the user drags the handle at a header's trailing edge
+  Then that column's width changes live (columnResizeMode: "onChange")
+  And onColumnSizingChange fires so a consumer can persist the widths
+```
+
+```gherkin
+Scenario: Reorder a column by dragging its header
+  Given a DataTable with enableColumnReordering
+  Then every non-pinned header cell is draggable and shows the grab cursor
+      (cursor-grab; cursor-grabbing while pressed)
+  When the user drags one header and drops it on another
+  Then the dragged column moves to the drop target's position (headers and body cells alike)
+  And onColumnOrderChange fires with the new order so a consumer can persist it
+  And a pinned column is never draggable — it is anchored to a table edge
+  # Pointer-only: there is no keyboard equivalent for the gesture yet.
+```
+
+```gherkin
+Scenario: Row actions vs. bulk actions — the selection threshold
+  Given a table with a selection column, per-row TableActionsCell actions, and a
+      DataTableBulkActionsBar over the same table instance
+  When nothing is selected
+  Then every row shows its own actions
+  And the bulk-actions bar is mounted in its idle state — the bulk actions are
+      disabled (a native <fieldset disabled>) and the trailing side shows
+      `loadedLabel` instead of a selection summary
+  When exactly one row is selected
+  Then the bulk scope is active: the bar's actions enable and its trailing side
+      shows the selection summary plus the clear control
+  And the per-row actions are suppressed on every row — the cell keeps its 48px
+      column but renders no trigger and no hover/press tint
+  When further rows are selected, or the header select-all checkbox is checked
+  Then nothing changes but the count in the selection summary
+  # One predicate owns this: isBulkSelectionActive(table) = one or more rows
+  # selected. TableActionsCell takes it as its `bulkSelectionActive` prop; the bar
+  # derives it internally. Consumers do not re-derive the threshold.
+  # The bar is always mounted — it never renders nothing, it only switches state.
+```
+
+```gherkin
+Scenario: Sticky (pinned) columns
+  Given columns with meta.pin = "left" and/or "right"
+  When the grid scrolls horizontally
+  Then the pinned columns stay fixed at their edges (position: sticky)
+  And their cells keep an opaque row background so scrolled cells don't show through
+```
+
+```gherkin
+Scenario: Wrapping columns
+  Given a column with meta.wrap = true
+  Then that column's header and cell content wrap onto multiple lines instead of truncating
+```
+
+```gherkin
+Scenario: Select rows
+  Given a selection column with checkboxes
+  When rows are checked
+  Then they are tinted and the pagination shows "N of M row(s) selected"
+```
+
+```gherkin
+Scenario: Selection counts under an active filter — two deliberate scopes
+  Given rows are selected and a column filter is then applied that hides some of them
+  Then DataTableBulkActionsBar's selection summary still counts the *whole*
+      selection, filtered-out rows included (table.getSelectedRowModel())
+  And isBulkSelectionActive(table) reads that same unfiltered selection, so the
+      per-row actions stay suppressed even if every selected row is filtered out of view
+  But DataTablePagination's summary counts only the *currently filtered*
+      selection (table.getFilteredSelectedRowModel())
+  So the two counts can legitimately disagree while a filter is active
+  # By design, not a bug: a bulk action applies to everything the user has
+  # selected, not just to what the current filter leaves visible, while the
+  # pagination summary describes the page/filter the user is looking at.
+```
+
+## Accessibility
+
+- Renders a real `<table>` via the Table primitives, so column headers and cells
+  carry native table semantics for assistive tech.
+- The sort control is a real `<button>` that toggles the sort on a single click
+  (and Enter/Space); it carries an `aria-label` ("Sort by <title>") and the sort
+  direction is conveyed by the arrow icon alongside the always-rendered text title.
+- Pagination controls are icon buttons with explicit labels ("Go to next page",
+  etc.); the rows-per-page control is a labelled select.
+- Selection checkboxes need an `aria-label` ("Select row" / "Select all") since
+  they have no visible label in the cell.
+- The view-options menu is keyboard-navigable (Base UI menu).
+- `DataTableExpandTrigger` is a real `<button>` carrying `aria-expanded` and an
+  "Expand row" / "Collapse row" label; it renders nothing for a row that can't
+  expand.
+- The column resize handle is a `role="separator"` with `aria-orientation`
+  vertical and an "Resize column" label (override via `resizeColumnLabel`)
+  (`enableColumnResizing`).
+- **Row navigation uses a roving tabindex**: exactly one data row is a Tab stop
+  (`tabIndex={0}`, the rest `-1`), and Arrow Up / Arrow Down move both DOM focus
+  and which row that is. Focusing a row by click syncs the roving index too,
+  so the last-interacted row stays the Tab stop. The index is clamped against the
+  live row count, so filtering or paging to fewer rows can't leave it pointing
+  past the end.
+- The trailing action column's controls are labelled buttons: the header's
+  column-visibility cog (`columnSettingsLabel`) and each row's overflow-actions
+  ellipsis (`rowActionsLabel`), both overridable to localize.
+- Each header cell's capability hint is a `Tooltip` on the cell itself, so it is
+  announced on keyboard focus as well as hover; a column with no capability
+  renders no tooltip.
+- Per-column filter fields live in a keyboard-navigable `FilterSearchFilters`
+  popover; each applied-filter chip below the toolbar removes its own filter.
+- The infinite-scroll loading row (`paginationMode="infinite"`, `isLoadingMore`)
+  carries `role="status"`/`aria-live="polite"` with an `sr-only` "Loading more
+  rows…" text, so a screen-reader user is told a fetch is in flight without
+  having to notice the animated placeholder.
+
+## Known limitations
+
+- **Column reordering (`enableColumnReordering`) is pointer-only.** It is native
+  HTML5 drag-and-drop on the header cells, with no keyboard equivalent — a
+  keyboard-only user cannot reorder columns. Resizing (arrow keys on the handle)
+  and sorting (Enter/Space on the header button) are unaffected, and the reorder
+  hint in the header tooltip describes a gesture only a pointer user can perform.
+  Recorded here deliberately: closing the gap needs a designed keyboard model
+  (e.g. a move-mode toggle plus arrow-key steps), not a spot fix.
+
+## Contrast
+
+DataTable composes already-themed components; their tokens meet contrast in light
+and dark. The wrapper border (`--ui-border-on-surface-border`) and muted
+empty-state / pagination text (`--ui-text-on-surface-secondary`) meet the
+relevant contrast over the page surface.