prime-ui-kit 0.7.13 → 0.9.1

package/src/components/data-table/COMPONENT.md

@@ -1,140 +1,245 @@
 # DataTable
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** data-display
+**Kind:** composite
 
-## About
+> A data table with sorting, pages or infinite scroll, row selection, nested rows and loading / empty / error states.
 
-`DataTable.Root` renders a semantic `<table>` inside a scroll viewport, with optional client-side sorting, classic pagination or infinite-scroll slicing, sticky header and sticky first column, and a footer with row counts (and pagination or infinite-scroll hints).
+## When to use
+- Lists of records with several attributes to compare: orders, invoices, users, campaigns.
+- Data that needs sorting, paging, bulk selection or a filter toolbar.
+- Hierarchical rows (`getRowChildren`) or rows with a detail panel (`renderExpanded`).
+- Wide numeric reports with a sticky head and first column.
 
-- **Use** when you need sortable tabular data with built-in pagination or “load more while scrolling” without building table chrome from scratch.
-- **Use** when row hover / column hover highlights or zebra striping should stay consistent with kit tokens via `size` and `ControlSizeProvider`.
-- **Use** when the first column must stay visible during horizontal scroll (`stickyFirstColumn`).
-- **Do not use** when you need arbitrary column pinning, resizable columns, or spreadsheet-style keyboard grid navigation — the table does not implement those.
-- **Do not use** when sorting or filtering must run on the server only without mirroring logic in the parent — sorting is applied in memory to the `rows` you pass; supply pre-sorted data or control `sort` yourself and replace `rows` accordingly.
-- **Do not use** when you need a loading overlay on top of already rendered rows — `loading` only affects the body when there are zero rows to display.
-- **Empty state:** for a **plain** message in the table body use **`emptyText`**. For an **illustrated** empty state (icon, **`h2`**, actions) render [`EmptyPage`](../empty-page/COMPONENT.md) in the surrounding layout or conditionally **instead of** the table when `rows.length === 0` and not `loading`.
-
-## Composition
-
-- **Public API** — a single compound entry: `DataTable` with `Root` (`DataTableRoot`). There are no other exported subcomponents.
-- **Structure** — `ControlSizeProvider` wraps a root `div` (data attributes for size, dividers, header visibility, stickiness, table width mode, hover highlights, zebra). Inside: `ScrollContainer` viewport → `<table>`, optional `<thead>` (`<th>` per column), `<tbody>` with rows, and an `aria-hidden` sentinel at the bottom when `infiniteScroll` is on (for `IntersectionObserver` or scroll fallback).
-- **Footer** — always shows a “shown range / total” line; if not `infiniteScroll` and `showPagination` and there is more than one page, it renders `Pagination.Root`; in infinite mode it may show a short status when more rows can be revealed or loaded.
-
-### Playground snippets
-
-Demos match **`playground/sections/DataTableSection.tsx`** (order and intent). Snippets under **`playground/snippets/data-table/`** use `@/` imports; runnable twins under **`examples/`** use **`prime-ui-kit`** (shared layout tokens in [`examples/examples-demos.module.css`](./examples/examples-demos.module.css) where needed).
-
-| Block | Snippet | Runnable example |
-| --- | --- | --- |
-| **Sizes** | [`sizes.tsx`](../../../playground/snippets/data-table/sizes.tsx) | [`examples/sizes.tsx`](./examples/sizes.tsx) — `size` `s`–`xl`; `Tag` / `Badge` inherit `ControlSizeProvider`; `paginationSize` follows table `size`. |
-| **Divider styles** | [`divider-styles.tsx`](../../../playground/snippets/data-table/divider-styles.tsx) | [`examples/divider-styles.tsx`](./examples/divider-styles.tsx) — `dividerStyle` `standard` / `dashed` / `dotted` / `none`. |
-| **States** | [`states.tsx`](../../../playground/snippets/data-table/states.tsx) | [`examples/states.tsx`](./examples/states.tsx) — `loading` + `loadingText` vs `emptyText`. |
-| **Sticky + headers** | [`sticky-and-headers.tsx`](../../../playground/snippets/data-table/sticky-and-headers.tsx) | [`examples/sticky-and-headers.tsx`](./examples/sticky-and-headers.tsx) — `showHeader`, `stickyHeader`, `stickyFirstColumn` with `infiniteScroll` + `scrollHeight`. |
-| **Controlled** | [`controlled.tsx`](../../../playground/snippets/data-table/controlled.tsx) | [`examples/controlled-sort-and-page.tsx`](./examples/controlled-sort-and-page.tsx) — `sort` / `onSortChange` / `page` / `onPageChange` (parent resets page on sort). |
-| **Composition** | [`composition.tsx`](../../../playground/snippets/data-table/composition.tsx) | [`examples/composition.tsx`](./examples/composition.tsx) — rich `header` / `cell`, `getRowKey`, `onRowClick`, `onCellClick` (+ keyboard). |
-| **Full width** | [`full-width.tsx`](../../../playground/snippets/data-table/full-width.tsx) | [`examples/full-width.tsx`](./examples/full-width.tsx) — narrow parent; default `fillWidth`. |
-| **Highlight + striped** | [`highlight-and-striped.tsx`](../../../playground/snippets/data-table/highlight-and-striped.tsx) | [`examples/highlight-and-striped.tsx`](./examples/highlight-and-striped.tsx) — toggles for `highlightRowOnHover`, `highlightColumnOnHover`, `striped`. |
-| **Infinite scroll** | [`infinite-scroll.tsx`](../../../playground/snippets/data-table/infinite-scroll.tsx) | [`examples/infinite-scroll-load-more.tsx`](./examples/infinite-scroll-load-more.tsx) — `infiniteScroll`, `hasMore`, `loadingMore`, `onLoadMore`, `scrollHeight` (snippet uses a larger generated dataset; same props). |
-| **Sort + pagination (uncontrolled)** | [`sorting-pagination.tsx`](../../../playground/snippets/data-table/sorting-pagination.tsx) | [`examples/sorting-pagination.tsx`](./examples/sorting-pagination.tsx) — `defaultSort` and built-in `Pagination`. |
-
-### Extra recipes (`examples/`)
-
-| Recipe | File | Notes |
-| --- | --- | --- |
-| Sticky header + first column (compact) | [`sticky-header-first-column.tsx`](./examples/sticky-header-first-column.tsx) | Russian copy; one combined sticky demo (subset of the snippet tour above). |
-| Orders + row open affordance | [`canonical-orders.tsx`](./examples/canonical-orders.tsx) | `defaultSort`, `pageSize`, `onRowClick`, `Tag` / `Badge` cells. |
-| Row selection with `Checkbox` | [`row-selection.tsx`](./examples/row-selection.tsx) | No built-in multi-select; header + row checkboxes in column definitions. |
-
-### Minimal example
+## When not to use
+- One or two KPIs → use [Card](../card/COMPONENT.md).
+- A short list of events without columns → use [Timeline](../timeline/COMPONENT.md).
+- A page with nothing to show yet (first run, no permissions) → use [EmptyPage](../empty-page/COMPONENT.md); inside a table pass it to `empty`.
+- Page navigation outside a table → use [Pagination](../pagination/COMPONENT.md).
+- Picking values from a list → use [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md).
 
+## Import
 ```tsx
 import { DataTable, type DataTableColumn } from "prime-ui-kit";
-
-type Row = { id: string };
-
-const columns: DataTableColumn<Row>[] = [{ id: "id", header: "ID", accessor: "id" }];
-const rows: Row[] = [{ id: "1" }];
-
-export function Example() {
-  return <DataTable.Root columns={columns} rows={rows} />;
-}
 ```
+Exported types: `DataTableColumn<Row>`, `DataTableProps<Row>`, `DataTableSortState`, `DataTableOrder`, `DataTableLabels`.
 
-## Rules
-
-- Pass **`columns`** with unique **`id`** and **`header`** for every column; **`accessor`** (key or function), **`cell`**, **`sortable`**, and the rest are optional.
-- **Sort** — controlled: `sort` + `onSortChange`. Uncontrolled initial order: `defaultSort` (default `null`). Clicking a sortable header cycles **asc → desc → none** for that column; changing sort sets the page to **1** in paginated mode.
-- **Page** — controlled: `page` + `onPageChange`. Uncontrolled: `defaultPage` (default `1`). Page index is clamped when row count changes. Toggling **`infiniteScroll`** resets the visible slice; leaving infinite mode resets page to **1** via internal effect.
-- **Infinite scroll** — set `infiniteScroll`. The visible slice grows by **`infiniteBatchSize`** up to the current **`rows.length`** first; when the slice shows all local rows and **`hasMore`**, **`onLoadMore`** runs when the sentinel intersects (or on near-bottom scroll if `IntersectionObserver` is missing). **`initialVisibleRows`** defaults to **`pageSize`** when omitted.
-- **`loading`** — shows **`loadingText`** in a single spanning row only when there are no displayed rows yet; it does not dim existing rows.
-- **Empty** — when not loading and there are no rows, **`emptyText`** is shown in a spanning row.
-- **Row keys** — provide **`getRowKey`** for stable identity; otherwise React **`key`** falls back to the row **index** (fragile if row order changes).
-- **Localization** — default **`loadingText`**, **`emptyText`**, footer range text, and infinite-scroll hints are **Russian** in the implementation; override with props where needed.
-- **Accessibility** — sortable headers use an inner control pattern inside **`th`** with **`scope="col"`**; sort icons are **`aria-hidden`**. Cells with **`onCellClick`** get **`role="button"`**, **`tabIndex={0}`**, and **Enter / Space**. There is no **`grid`** role or arrow-key cell navigation.
+## Anatomy
+```
+DataTable                           card-fill block, radius 12, clips its content
+├── toolbar                         optional panel above the table (search, filters, bulk actions)
+├── scroll viewport                 ScrollContainer, both axes
+│   └── table
+│       ├── thead                   [select all] [toggle] head cells; sortable heads hold a button
+│       └── tbody                   rows · sub-rows · detail rows · skeleton / empty / error row
+└── footer                          range «Показано 1–5 из 23» · Pagination · infinite-scroll status
+```
+DataTable is a single component: columns are data (`DataTableColumn<Row>[]`), not child parts.
 
 ## API
 
-### DataTable.Root
-
-| Prop | Type | Default | Required | Description |
-| --- | --- | --- | --- | --- |
-| columns | `DataTableColumn<Row>[]` | — | Yes | Column definitions |
-| rows | `Row[]` | — | Yes | Data rows (sorted in memory when `sort` applies) |
-| size | `DataTableSize` | `"m"` | No | Row density; forwarded to nested `Pagination` unless `paginationSize` is set |
-| className | `string` | — | No | Class on the outer wrapper |
-| showHeader | `boolean` | `true` | No | Render `<thead>` |
-| stickyHeader | `boolean` | `false` | No | Sticky header row |
-| stickyFirstColumn | `boolean` | `false` | No | Sticky first column (and corner cell when header is sticky) |
-| getRowKey | `(row: Row, index: number) => React.Key` | — | No | Stable row key; default is index |
-| onRowClick | `(row: Row, index: number, event: React.MouseEvent<HTMLTableRowElement>) => void` | — | No | Row click handler |
-| loading | `boolean` | `false` | No | Loading state when no rows are displayed |
-| loadingText | `React.ReactNode` | `"Загрузка данных…"` | No | Message in loading state |
-| emptyText | `React.ReactNode` | `"Нет данных для отображения."` | No | Message when there are no rows |
-| dividerStyle | `DataTableDividerStyle` | `"standard"` | No | Cell border style: `standard`, `dashed`, `dotted`, `none` |
-| sort | `DataTableSortState` | — | No | Controlled sort (`null` or `{ columnId, order }`) |
-| defaultSort | `DataTableSortState` | `null` | No | Initial sort when uncontrolled |
-| onSortChange | `(sort: DataTableSortState) => void` | — | No | Sort change callback |
-| page | `number` | — | No | Controlled current page (1-based) |
-| defaultPage | `number` | `1` | No | Initial page when uncontrolled |
-| onPageChange | `(page: number) => void` | — | No | Page change callback |
-| pageSize | `number` | `10` | No | Rows per page in pagination mode; also default for `initialVisibleRows` in infinite mode |
-| showPagination | `boolean` | `true` | No | Show `Pagination` when not in infinite mode and `totalPages > 1` |
-| siblingCount | `number` | `1` | No | Page window size passed to `Pagination.Root` |
-| paginationSize | `DataTableSize` | — | No | Pagination size; defaults to root `size` |
-| infiniteScroll | `boolean` | `false` | No | Scroll viewport with growing slice / `onLoadMore` |
-| initialVisibleRows | `number` | `pageSize` | No | Initial number of rows shown in infinite mode |
-| infiniteBatchSize | `number` | `20` | No | Rows added per reach-end step before `onLoadMore` |
-| hasMore | `boolean` | `false` | No | Server has more data after current `rows` |
-| loadingMore | `boolean` | `false` | No | While an async `onLoadMore` is in progress |
-| onLoadMore | `() => void \| Promise<void>` | — | No | Fetch next chunk when local slice is exhausted |
-| scrollHeight | `number \| string` | `360` | No | Max height of the scroll viewport in infinite mode |
-| fillWidth | `boolean` | `true` | No | When `true`, table is full container width; extra space is distributed by the browser’s automatic table layout (`table-layout: auto`) from cell content and `width` / `minWidth` / `maxWidth`. When `false`, table width follows content (`max-content`) |
-| highlightRowOnHover | `boolean` | `true` | No | Row hover highlight |
-| highlightColumnOnHover | `boolean` | `false` | No | Column hover highlight (header + cells) |
-| striped | `boolean` | `false` | No | Alternating row backgrounds |
-
-### `DataTableColumn<Row>`
-
-| Field | Type | Default | Required | Description |
-| --- | --- | --- | --- | --- |
-| id | `string` | — | Yes | Column id (used for sort state and DOM data attributes) |
-| header | `React.ReactNode` | — | Yes | Header content |
-| accessor | `keyof Row \| ((row: Row) => unknown)` | — | No | Value for default cell text and sort (unless `sortAccessor` / `sortComparator` override) |
-| cell | `(row: Row) => React.ReactNode` | — | No | Custom cell render |
-| sortable | `boolean` | `false` | No | Header toggles sort on click |
-| sortAccessor | `(row: Row) => unknown` | — | No | Value used for sorting (and default sort comparison) instead of `accessor` |
-| sortComparator | `(a: Row, b: Row, order: DataTableOrder) => number` | — | No | Custom comparator; when set, default primitive compare is not used |
-| align | `DataTableCellAlign` | `"start"` | No | `start`, `center`, or `end` |
-| width | `string` | — | No | Column width on `th` / `td` (CSS `width`) |
-| minWidth | `string` | — | No | Minimum column width on `th` / `td` |
-| maxWidth | `string` | — | No | Maximum column width on `th` / `td` |
-| onHeaderClick | `(event: React.MouseEvent<HTMLTableCellElement>) => void` | — | No | Fires on header click before sort handling |
-| onCellClick | `(row: Row, event: React.MouseEvent<HTMLTableCellElement> \| React.KeyboardEvent<HTMLTableCellElement>) => void` | — | No | Makes the cell focusable and keyboard-activable |
-
-Exported types: `DataTableSortState`, `DataTableOrder`, `DataTableSize`, `DataTableCellAlign`, `DataTableDividerStyle`, `DataTableRootProps`, `DataTableColumn`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### DataTable
+Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an optional toolbar, a scrolling `<table>` and a footer (range, Pagination, infinite-scroll status); passes its tier to the controls inside.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `DataTableColumn<Row>[]` | — (required) | Column definitions, see `DataTableColumn<Row>`. |
+| `rows` | `Row[]` | — (required) | Data; sorted in memory when a sort is set. |
+| `getRowKey` | `(row: Row, index: number) => Key` | — | Stable row id (position by default); selection, expansion and the enter animation of new rows are keyed by it. Pass it whenever sorting, selection or expansion is used. |
+| `getRowLabel` | `(row: Row) => string` | — | Human row name for the checkbox and toggle names (`{label}` in `labels`). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Density and control tier: rows from 36 · 36 · 44 · 52 · 52 px; passed to checkboxes, toggles, Pagination and nested controls. |
+| `paging` | `"pages" \| "infinite" \| "none"` | `"pages"` | `pages` — Pagination in the footer when there is more than one page; `infinite` — rows are revealed while scrolling; `none` — every row at once. |
+| `pageSize` | `number` | `10` | Rows per page; also the first batch with `paging="infinite"`. |
+| `page` | `number` | — | Current page (1-based), controlled. |
+| `defaultPage` | `number` | `1` | Initial page, uncontrolled. |
+| `onPageChange` | `(page: number) => void` | — | Page change from the pager; a sort change also returns to page 1. |
+| `sort` | `DataTableSortState` | — | Current sort, controlled: `{ columnId, order: "asc" \| "desc" }` or `null`. |
+| `defaultSort` | `DataTableSortState` | `null` | Initial sort, uncontrolled. |
+| `onSortChange` | `(sort: DataTableSortState) => void` | — | A head click cycles asc → desc → none. |
+| `loading` | `boolean` | `false` | Skeleton rows while there are no rows; with rows only `aria-busy`. |
+| `loadingRows` | `number` | `min(pageSize, 5)` | Number of skeleton rows. |
+| `empty` | `ReactNode` | `labels.empty` | Empty-state content: a string goes into a compact EmptyPage, a node (e.g. a full `EmptyPage`) is rendered as is. |
+| `error` | `ReactNode` | — | Load error: replaces the body with the message in `role="alert"`. |
+| `toolbar` | `ReactNode` | — | Panel above the table (search, filters, bulk actions); stacks below 30rem of table width. |
+| `selectable` | `boolean` | `false` | Leading checkbox column with «select all», Shift range, press-and-drag and Space. |
+| `selected` | `Key[]` | — | Selected row ids, controlled. |
+| `defaultSelected` | `Key[]` | `[]` | Initially selected ids, uncontrolled. |
+| `onSelectedChange` | `(selected: Key[]) => void` | — | Selection change. |
+| `getRowChildren` | `(row: Row) => Row[] \| undefined` | — | Sub-rows rendered under the parent with the same columns, indented by depth. |
+| `renderExpanded` | `(row: Row) => ReactNode` | — | Full-width detail row under an expanded row. |
+| `isRowExpandable` | `(row: Row) => boolean` | — | Which rows get an expand toggle; by default rows with sub-rows, or every row with `renderExpanded`. |
+| `expanded` | `Key[]` | — | Expanded row ids, controlled. |
+| `defaultExpanded` | `Key[]` | `[]` | Initially expanded ids, uncontrolled. |
+| `onExpandedChange` | `(expanded: Key[]) => void` | — | Expansion change. |
+| `infiniteBatchSize` | `number` | `20` | Rows revealed per scroll step. |
+| `hasMore` | `boolean` | `false` | More rows can be loaded from the server. |
+| `loadingMore` | `boolean` | `false` | A server batch is loading: footer status, `aria-busy`. |
+| `onLoadMore` | `() => void \| Promise<void>` | — | Called at the end when every loaded row is shown and `hasMore` is set. |
+| `scrollHeight` | `number \| string` | `360 with paging="infinite"` | Max height of the scroll viewport (number = px). |
+| `stickyHeader` | `boolean` | `false` | The head sticks while the body scrolls. |
+| `stickyFirstColumn` | `boolean` | `false` | The first column (with the selection and toggle columns) sticks while scrolling sideways. |
+| `showHeader` | `boolean` | `true` | Render `<thead>`. |
+| `fullWidth` | `boolean` | `true` | The table spans its container; `false` sizes it by its content. |
+| `rowDividers` | `boolean` | `true` | Hairlines between rows. |
+| `columnDividers` | `boolean` | `true` | Hairlines between content columns. |
+| `striped` | `boolean` | `false` | Every second row one opaque step off the table fill. |
+| `highlightRowOnHover` | `boolean` | `true` | Row wash on hover (and a pressed wash on clickable rows). |
+| `highlightColumnOnHover` | `boolean` | `false` | Column wash under the pointer (head and cells). |
+| `onRowClick` | `(row: Row, index: number, event: MouseEvent<HTMLTableRowElement>) => void` | — | Row click; rows get a pointer cursor. |
+| `labels` | `Partial<DataTableLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the root `<div>`. |
+
+### DataTableColumn<Row>
+One column of `columns`: data, not a part.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | — (required) | Unique column id (sort state, `data-column-id`). |
+| `header` | `ReactNode` | — (required) | Head content. |
+| `accessor` | `keyof Row \| ((row: Row) => unknown)` | — | Cell value (rendered as text, `—` for empty) and the default sort value. |
+| `cell` | `(row: Row) => ReactNode` | — | Custom cell content. |
+| `sortable` | `boolean` | — | The head becomes a sort button with `aria-sort`. |
+| `sortAccessor` | `(row: Row) => unknown` | — | Value to sort by instead of `accessor`. |
+| `sortComparator` | `(a: Row, b: Row, order: DataTableOrder) => number` | — | Custom comparison. |
+| `align` | `"start" \| "center" \| "end"` | `"start" ("end" with numeric)` | Cell alignment; heads do not follow it. |
+| `headerAlign` | `"start" \| "center" \| "end"` | `"start"` | Head alignment; the sort icon stays at the end edge. |
+| `numeric` | `boolean` | — | Tabular figures, no wrapping, end alignment unless `align` is set. |
+| `truncate` | `boolean` | — | One line with an ellipsis; width from `maxWidth` (or `width`); string values get a `title`. |
+| `grow` | `boolean` | — | Takes the free width and wraps its text; the table then fills its container. With `minWidth` it never gets narrower: below that the table scrolls instead of cells overlapping. |
+| `width · minWidth · maxWidth` | `string` | — | CSS sizes of the column (`"14rem"`). |
+
+## Variants
+
+### size (density)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | rows from 36, head 28, text 12/16, cell padding 8 | very dense admin grids | |
+| `s` | rows from 36, head 32, text 13/20 | dense back-office lists, narrow containers | |
+| `m` | rows from 44, head 36 (13/20 head text), cells 14/20 | most tables | yes |
+| `l` | rows from 52, head 40, text 16/24 | spacious lists, large avatars | |
+| `xl` | rows from 52, head 48, text 16/24, cell padding 16 | large touch-friendly tables | |
+
+Row height is a minimum: cells pad vertically by (row height − control one tier down) / 2, so one text line or a control one tier down keeps the tier height and taller content grows the row. Checkboxes use the table tier; expand toggles are square ghost Buttons one tier down (`xs` for xs–m, `s` for l–xl).
+
+Column widths come from the content and then hold still: once rows are laid out the widths are frozen, so searching, filtering, paging and opening sub-rows do not move the columns. A column widens when new content no longer fits, never narrows; widths are measured again when the column set or the container width changes. `grow` columns keep taking the free width.
+
+### paging
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `pages` | `pageSize` rows, footer range and Pagination (compact on narrow widths) | tables people return to and reference | yes |
+| `infinite` | rows revealed while scrolling in a `scrollHeight` window, footer status | logs and feeds | |
+| `none` | every row, no footer | short lists, reports in a scroll window | |
+
+### column `align`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | text at the start | text columns | yes (non-numeric) |
+| `center` | centered | short symmetric values | |
+| `end` | at the end | numbers, money (set by `numeric`) | yes (`numeric`) |
+
+Heads keep `start` whatever the cell alignment, with the sort icon at the end edge; set `headerAlign` only for a deliberate exception.
+
+### Flags
+| Flag | Looks like when on | Use when | Default |
+|---|---|---|---|
+| `rowDividers` | hairlines between rows | default; off together with `striped` | `true` |
+| `columnDividers` | hairlines between content columns (none inside the lead columns) | default; off for 2–3 column key/value lists | `true` |
+| `striped` | every second row one opaque step off the fill | long numeric grids | `false` |
+| `highlightRowOnHover` | `fill-subtle` wash on the hovered row | interactive lists | `true` |
+| `highlightColumnOnHover` | `fill-subtle` wash on the hovered column | comparison tables | `false` |
+| `stickyHeader` · `stickyFirstColumn` | opaque sticky head / first column with a hairline edge | long / wide tables in a `scrollHeight` window | `false` |
+| `showHeader` | head row shown | off only for self-explanatory key/value tables | `true` |
+| `fullWidth` | spans the container; `false` = content width | `false` for short lookup tables in wide layouts | `true` |
+| column `numeric` | tabular figures, end-aligned, no wrap | numbers, money | — |
+| column `truncate` | one line with an ellipsis and a `title` | long names in narrow columns | — |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| loading (no rows) | `loading` | skeleton rows (`data-skeleton`), `role="status"` with `labels.loading`, `aria-busy` on the table, `data-loading` on the root |
+| loading more | `loading` with rows, `loadingMore` | `aria-busy`; footer `labels.loadingMore` |
+| empty | no rows and not loading | compact EmptyPage with `empty` or `labels.empty` (`role="status"`), or the `empty` node |
+| error | `error` | body replaced by a `role="alert"` message in `danger-text`; range and infinite status hidden |
+| sorted | `sort` / `defaultSort` | `aria-sort` and `data-sorted` on the head; the sort icon: unsorted `text-disabled`, hover `text-muted`, sorted `text-secondary` — never accent |
+| selected | `selected` / `defaultSelected` | `aria-selected` rows with `accent-soft` fill; polite `labels.selectedCount` |
+| expanded | `expanded` / `defaultExpanded` | `data-expanded` on the parent row (one step darker); toggle `aria-expanded`, chevron turns 90° |
+| new rows | rows mounted by an expand or new in `rows` (by `getRowKey`) | `data-animate`: cells drop in from above (`enterMotion`); detail panels open and close through `grid-template-rows` (`data-state` on the detail row; it unmounts after the close) |
+| state swap | the body moves between loading, rows, empty and error | the body fades in over `base` (opacity only, the same swap motion as [Crossfade](../crossfade/COMPONENT.md)); the head stays still; nothing moves on the first render |
+
+Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data-sticky-header`, `data-sticky-first-column`, `data-table-width` (`fill` · `auto` · `grow`), `data-highlight-row`, `data-highlight-column`, `data-striped`, `data-loading`, `data-selectable`, `data-expandable`, `data-dragging` (while drag-selecting). Sorting and paging swap rows instantly; everything is still under `prefers-reduced-motion`.
+
+## Layout & spacing
+- The root fills its container on `--prime-color-card-bg`, radius 12, and clips full-bleed head and rows; on a card or a modal it becomes a sunken block — never wrap it in a Card.
+- Toolbar padding `--prime-space-3` × cell padding, items `gap: --prime-space-2`; below 30rem of table width toolbar and footer stack.
+- The footer has a hairline on top: range on the left, Pagination on the right. The range shows only with more than one page or with infinite scroll.
+- Columns scroll sideways inside the table; pin the identifying column with `stickyFirstColumn`. Works from 320 px.
+- Cell content: text, two-line text (title + `caption`), an Avatar with text, a Badge, or a control one tier down (`s` in an `m` table). Toolbar controls use `s` in an `m` table.
+- Column widths: `width` / `minWidth` / `maxWidth` strings; never size cells with custom CSS.
+- Sub-rows indent by `--dt-indent` per level (avatar of the tier + gap); override it on the root for other leading content.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through sort buttons, checkboxes and expand toggles. |
+| `Enter` · `Space` | Sorts by the column or toggles the row. |
+| `Space` | Toggles the focused row checkbox. |
+| `Shift + Space` | Selects the range from the last toggled row. |
+
+### ARIA
+- Native `<table>` semantics; head cells are `scope="col"`; sortable heads hold a `<button>` and expose `aria-sort`; the whole head cell shows the inset focus ring.
+- Row checkboxes are named by `labels.selectRow` with `{label}` from `getRowLabel` (pass it so the names are unique); the head checkbox by `labels.selectAll`, `indeterminate` on a partial selection.
+- After a selection change a polite live region announces `labels.selectedCount`; selected rows carry `aria-selected`.
+- The expand toggle is a button with `aria-expanded`, `aria-controls` (detail row or sub-rows) and `labels.expand` / `labels.collapse`.
+- Loading sets `aria-busy` and a `labels.loading` status; the error is `role="alert"`; the default empty state is `role="status"`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `loading` | `"Загрузка данных…"` | Screen-reader status while skeleton rows are shown. |
+| `empty` | `"Нет данных для отображения."` | Default empty-state text. |
+| `range` | `"Показано {from}–{to} из {total}"` | Footer range line; `{from}`, `{to}`, `{total}` are replaced. |
+| `loadingMore` | `"Догружаем строки…"` | Footer status while `loadingMore`. |
+| `scrollForMore` | `"Прокрутите вниз для загрузки"` | Footer hint when more rows can appear by scrolling. |
+| `selectAll` | `"Выбрать все строки"` | Name of the head «select all» checkbox. |
+| `selectRow` | `"Выбрать строку {label}"` | Name of a row checkbox; `{label}` is `getRowLabel(row)`, empty without it. |
+| `selectedCount` | `"Выбрано: {count}"` | Polite announcement after the selection changes. |
+| `expand` | `"Развернуть строку {label}"` | Name of the toggle of a collapsed row. |
+| `collapse` | `"Свернуть строку {label}"` | Name of the toggle of an expanded row. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Recent orders: sortable columns, a status Badge, numeric sums and five rows per page — `columns`, `getRowKey`, `pageSize`. |
+| [sizes.tsx](examples/sizes.tsx) | Every density: rows from 36 to 52 px, the head at the control height of the tier — `size`. |
+| [numeric.tsx](examples/numeric.tsx) | An inventory report: number columns align to the end in tabular figures, a long name stays on one line with a title — `numeric`, `truncate`, `maxWidth`. |
+| [content-width.tsx](examples/content-width.tsx) | A short lookup table sized by its content with a centered column, and a `grow` column that takes the free width and wraps — `fullWidth`, `align`, `grow`. |
+| [appearance.tsx](examples/appearance.tsx) | Row styling: zebra rows without lines, a column wash under the pointer, a headless key/value list — `striped`, `rowDividers`, `highlightColumnOnHover`, `columnDividers`, `showHeader`. |
+| [toolbar.tsx](examples/toolbar.tsx) | A campaign list with search, a status filter and export above the table; the empty text when nothing matches — `toolbar`, `empty`. |
+| [selection.tsx](examples/selection.tsx) | Team members with checkboxes: Shift+click range, press-and-drag, «select all» and bulk actions in the toolbar — `selectable`, `selected`, `onSelectedChange`, `getRowLabel`. |
+| [nested-rows.tsx](examples/nested-rows.tsx) | Partners with their expense lines: sub-rows indented under the parent's name, a chevron toggle, together with selection and sorting — `getRowChildren`, `expanded`, `onExpandedChange`. |
+| [detail-panel.tsx](examples/detail-panel.tsx) | Order details in a full-width row under an expanded order, aligned with the first content column — `renderExpanded`, `defaultExpanded`. |
+| [sticky.tsx](examples/sticky.tsx) | Monthly sales by region in a 280 px window: the head and the region column stay while scrolling both ways — `stickyHeader`, `stickyFirstColumn`, `scrollHeight`. |
+| [infinite-scroll.tsx](examples/infinite-scroll.tsx) | An audit log that reveals loaded rows in batches and then asks the server for more — `paging`, `infiniteBatchSize`, `hasMore`, `loadingMore`, `onLoadMore`. |
+| [states.tsx](examples/states.tsx) | Loading skeleton, an empty period and a load error with a retry: the head stays, only the body changes — `loading`, `loadingRows`, `empty`, `error`. |
+| [controlled.tsx](examples/controlled.tsx) | Sort and page owned by the parent (a URL or a store): a header click goes asc → desc → none, a new sort returns to page 1 — `sort`, `onSortChange`, `page`, `onPageChange`. |
+| [narrow.tsx](examples/narrow.tsx) | A 320 px support queue: columns scroll inside the table with the first one pinned, the toolbar and footer reflow and the pager turns compact — `stickyFirstColumn`, `size`. |
+
+## Mistakes
+- No `getRowKey` with `selectable`, expansion or sorting → selection follows positions, not records.
+- Numbers in a plain column → set `numeric` (alignment and tabular figures).
+- A custom «Ничего не найдено» row inside `rows` → use `empty`.
+- A spinner instead of rows → use `loading` (the skeleton keeps the head and the layout).
+- Wrapping the table in a Card for a border → the table is already a bounded block.
+- A custom checkbox column → use `selectable` (range, drag and announcements built in).
+- A long table in a `scrollHeight` window without `stickyHeader` → the head scrolls away.
+- `paging="none"` for hundreds of rows → use `pages` or `infinite`.
 
 ## Related
-
-- [Pagination](../pagination/COMPONENT.md) — used under the table for page navigation.
-- [EmptyPage](../empty-page/COMPONENT.md) — rich empty state (icon, title, CTA) outside or instead of `emptyText`.
-- [LinkButton](../link-button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Tag](../tag/COMPONENT.md) — common cell content; they pick up size from the table’s `ControlSizeProvider` unless overridden.
+- **Built from:** [Checkbox](../checkbox/COMPONENT.md), [Button](../button/COMPONENT.md), [Pagination](../pagination/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md) (loading rows, in the table tier)
+- **See also:** [SmartFilter](../smart-filter/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [Card](../card/COMPONENT.md)

package/src/components/data-table/examples/appearance.tsx

@@ -0,0 +1,62 @@
+/** Row styling: zebra rows without lines, a column wash under the pointer, a headless key/value list — `striped`, `rowDividers`, `highlightColumnOnHover`, `columnDividers`, `showHeader`. */
+import { DataTable, type DataTableColumn, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Shift = { day: string; morning: number; evening: number; night: number };
+
+const SHIFTS: Shift[] = [
+  { day: "Понедельник", morning: 12, evening: 9, night: 4 },
+  { day: "Вторник", morning: 11, evening: 10, night: 4 },
+  { day: "Среда", morning: 13, evening: 8, night: 3 },
+  { day: "Четверг", morning: 12, evening: 9, night: 5 },
+];
+
+const COLUMNS: DataTableColumn<Shift>[] = [
+  { id: "day", header: "День", accessor: "day" },
+  { id: "morning", header: "Утро", accessor: "morning", numeric: true },
+  { id: "evening", header: "Вечер", accessor: "evening", numeric: true },
+  { id: "night", header: "Ночь", accessor: "night", numeric: true },
+];
+
+export default function DataTableAppearanceExample() {
+  return (
+    <>
+      <div className={styles.specimen}>
+        <DataTable
+          columns={COLUMNS}
+          rows={SHIFTS}
+          getRowKey={(row) => row.day}
+          striped
+          rowDividers={false}
+        />
+        <Typography as="span" variant="caption" tone="muted">
+          striped · rowDividers=&#123;false&#125;
+        </Typography>
+      </div>
+      <div className={styles.specimen}>
+        <DataTable
+          columns={COLUMNS}
+          rows={SHIFTS}
+          getRowKey={(row) => row.day}
+          highlightColumnOnHover
+        />
+        <Typography as="span" variant="caption" tone="muted">
+          highlightColumnOnHover
+        </Typography>
+      </div>
+      <div className={styles.specimen}>
+        <DataTable
+          columns={COLUMNS}
+          rows={SHIFTS}
+          getRowKey={(row) => row.day}
+          columnDividers={false}
+          showHeader={false}
+        />
+        <Typography as="span" variant="caption" tone="muted">
+          columnDividers=&#123;false&#125; · showHeader=&#123;false&#125;
+        </Typography>
+      </div>
+    </>
+  );
+}

package/src/components/data-table/examples/content-width.tsx

@@ -0,0 +1,65 @@
+/** A short lookup table sized by its content with a centered column, and a `grow` column that takes the free width and wraps — `fullWidth`, `align`, `grow`. */
+import { DataTable, type DataTableColumn, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+type Task = { id: string; task: string; hours: number; note: string };
+
+const TASKS: Task[] = [
+  {
+    id: "T-12",
+    task: "Сверстать отчёт по спринту",
+    hours: 3,
+    note: "Сводка по закрытым задачам, графики скорости команды и список того, что переносится в следующий спринт.",
+  },
+  {
+    id: "T-13",
+    task: "Проверить миграции БД",
+    hours: 1.5,
+    note: "Прогнать миграции на копии продовой базы и сравнить время выполнения с прошлым релизом.",
+  },
+  {
+    id: "T-14",
+    task: "Обновить подсказки в форме входа",
+    hours: 2,
+    note: "Тексты ошибок и подсказок под полями, согласовать формулировки с поддержкой.",
+  },
+];
+
+const HOURS = new Intl.NumberFormat("ru-RU", { maximumFractionDigits: 1 });
+
+const LOOKUP_COLUMNS: DataTableColumn<Task>[] = [
+  { id: "id", header: "Задача", accessor: "id" },
+  { id: "task", header: "Описание", accessor: "task" },
+  { id: "hours", header: "Часы", align: "center", cell: (row) => HOURS.format(row.hours) },
+];
+
+const NOTE_COLUMNS: DataTableColumn<Task>[] = [
+  { id: "id", header: "Задача", accessor: "id" },
+  { id: "task", header: "Название", accessor: "task" },
+  { id: "note", header: "Комментарий", accessor: "note", grow: true },
+];
+
+export default function DataTableContentWidthExample() {
+  return (
+    <>
+      <div className={styles.specimen}>
+        <DataTable
+          columns={LOOKUP_COLUMNS}
+          rows={TASKS}
+          getRowKey={(row) => row.id}
+          fullWidth={false}
+        />
+        <Typography as="span" variant="caption" tone="muted">
+          fullWidth=&#123;false&#125; · align="center"
+        </Typography>
+      </div>
+      <div className={styles.specimen}>
+        <DataTable columns={NOTE_COLUMNS} rows={TASKS} getRowKey={(row) => row.id} />
+        <Typography as="span" variant="caption" tone="muted">
+          grow
+        </Typography>
+      </div>
+    </>
+  );
+}

package/src/components/data-table/examples/controlled.tsx

@@ -0,0 +1,56 @@
+/** Sort and page owned by the parent (a URL or a store): a header click goes asc → desc → none, a new sort returns to page 1 — `sort`, `onSortChange`, `page`, `onPageChange`. */
+import { DataTable, type DataTableColumn, type DataTableSortState } from "prime-ui-kit";
+import * as React from "react";
+
+type Order = { id: number; customer: string; city: string; total: number };
+
+const CUSTOMERS = ["Анна Соколова", "Борис Кравец", "Вера Львова", "Глеб Миронов", "Дарья Носова"];
+const CITIES = ["Москва", "Казань", "Самара", "Томск", "Пермь"];
+
+const ORDERS: Order[] = Array.from({ length: 23 }, (_, i) => ({
+  id: 5000 + i,
+  customer: CUSTOMERS[i % CUSTOMERS.length],
+  city: CITIES[(i * 3) % CITIES.length],
+  total: 1200 + ((i * 7919) % 48_000),
+}));
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const COLUMNS: DataTableColumn<Order>[] = [
+  { id: "id", header: "№", accessor: "id", sortable: true, numeric: true, width: "5rem" },
+  { id: "customer", header: "Покупатель", accessor: "customer", sortable: true },
+  { id: "city", header: "Город", accessor: "city", sortable: true },
+  {
+    id: "total",
+    header: "Сумма",
+    accessor: "total",
+    sortable: true,
+    numeric: true,
+    cell: (row) => RUB.format(row.total),
+  },
+];
+
+export default function DataTableControlledExample() {
+  const [sort, setSort] = React.useState<DataTableSortState>({ columnId: "total", order: "desc" });
+  const [page, setPage] = React.useState(1);
+
+  return (
+    <DataTable
+      columns={COLUMNS}
+      rows={ORDERS}
+      getRowKey={(row) => row.id}
+      sort={sort}
+      onSortChange={(next) => {
+        setSort(next);
+        setPage(1);
+      }}
+      page={page}
+      onPageChange={setPage}
+      pageSize={5}
+    />
+  );
+}