prime-ui-kit 0.14.0 → 0.16.0

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

@@ -52,7 +52,7 @@ Columns are data (`DataTableColumn<Row>[]`), not child parts. The one part, `Dat
 <!-- 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.
+Generic `DataTable<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 |
 |---|---|---|---|
@@ -63,9 +63,9 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | `rows` | `Row[]` | — (required) | Data; sorted in memory when a sort is set. With `source="server"` — the page (or the loaded batches) as the server returned it. |
 | `source` | `"client" \| "server"` | `"client"` | Who sorts and pages the rows. `client`: the table sorts `rows` and slices pages. `server`: `rows` is one page, already sorted; `sort` / `page` changes are the request, `rowCount` drives Pagination. |
 | `rowCount` | `number` | `rows.length` | Total rows on the server (`source="server"`): the page count and «Показано {from}–{to} из {total}». |
-| `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. |
+| `getRowKey` | `(row: Row, index: number) => Key` | — | Stable row id (position by default; sub-rows too, `index` among siblings); 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 (`--prime-table-row-height-<size>`); passed to checkboxes, toggles, Pagination and nested controls. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Density and control tier: rows from 36 · 36 · 44 · 52 · 52 px (`--prime-table-row-height-<size>`); passed to checkboxes, toggles, Pagination and nested controls. Without it the tier of the host. |
 | `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"` (with `source="server"` every loaded row is shown). |
 | `page` | `number` | — | Current page (1-based), controlled. |
@@ -77,7 +77,7 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | `loading` | `boolean` | `false` | Skeleton rows while there are no rows; with rows on screen (a refetch, another server page) they stay and the table gets `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"`. |
+| `loadError` | `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. |
@@ -93,8 +93,8 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | `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. A returned promise shows the loading status until it settles. |
-| `scrollHeight` | `number \| string \| "fill"` | `360 with paging="infinite"` | Max height of the scroll viewport (number = px); `"fill"` — the table takes the height of its flex / grid parent (or a sized block), the rows scroll inside, infinite paging follows it. |
+| `onLoadMore` | `() => void \| Promise<void>` | — | Called at the end when every loaded row is shown and `hasMore` is set. A returned promise shows the loading status until it settles; a rejected one stops asking until the rows change. |
+| `scrollHeight` | `number \| string \| "fill"` | `360` with `paging="infinite"`, else none | Max height of the scroll viewport (number = px); `"fill"` — the table takes the height of its flex / grid parent (or a sized block), the rows scroll inside, infinite paging follows it. |
 | `stickyHeader` | `boolean` | `false` | The head sticks while the body scrolls (with `scrollHeight`); on screens lower than 480px it scrolls with the rows. |
 | `stickyFirstColumn` | `boolean` | `false` | The first visible column (with the selection and toggle columns) sticks while scrolling sideways; the start edge shadow falls from its end edge. |
 | `showHeader` | `boolean` | `true` | Render `<thead>`. |
@@ -106,15 +106,16 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | `highlightColumnOnHover` | `boolean` | `false` | Column wash under the pointer (head and cells). |
 | `getRowHref` | `(row: Row) => string` | — | The row is a link: a real `<a>` in the key cell (first visible column), and the same link covers the whole row. Keep controls out of the key cell. |
 | `onRowClick` | `(row: Row, index: number, event: DataTableRowClickEvent) => void` | — | Opens a row in place (a drawer, a panel) on a click, Enter or Space; never from a control inside the row. With `getRowHref` it gets plain clicks: `event.preventDefault()` routes in the app. |
-| `isRowClickable` | `(row: Row) => boolean` | `every row` | Which rows open (`getRowHref` and `onRowClick` alike); `false` for a total or a service row — no link, no focus, no cursor. |
+| `isRowClickable` | `(row: Row) => boolean` | every row | Which rows open (`getRowHref` and `onRowClick` alike); `false` for a total or a service row — no link, no focus, no cursor. |
 | `getRowGroup` | `(row: Row) => string \| number` | — | Group key of a row: each group gets a header row and its own `<tbody>`. Groups keep the order in which they first appear in `rows`; a sort orders the rows inside each group; a group split by paging repeats its header. |
-| `renderGroupHeader` | `(group: DataTableGroup<Row>) => ReactNode` | `the group key` | Content of a group header; `group.rows` holds every row of the group (all pages) for totals. Children are laid out start / end in the visible width. |
+| `renderGroupHeader` | `(group: DataTableGroup<Row>) => ReactNode` | the group key | Content of a group header; `group.rows` holds every row of the group (all pages) for totals. Children are laid out start / end in the visible width. |
 | `stickyGroupHeaders` | `boolean` | `false` | Group headers stick under the head (or the top edge) while their rows scroll. |
 | `collapsedGroups` | `(string \| number)[]` | — | Collapsed group keys, controlled. Any prop of this triad makes groups fold: a chevron toggle leads each header, rows fold like sub-rows. «Select all» and paging still count collapsed rows. |
 | `defaultCollapsedGroups` | `(string \| number)[]` | — | Initially collapsed group keys, uncontrolled; `[]` — every group open but foldable. |
 | `onCollapsedGroupsChange` | `(collapsedGroups: (string \| number)[]) => void` | — | The collapsed group keys changed (a group header toggle). |
 | `labels` | `Partial<DataTableLabels>` | — | Built-in strings, see Labels. |
-| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the root `<div>`. |
+| `className` | `string` | — | Class on the root `<div>`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | The other attributes of the root `<div>`. |
 
 ### DataTable.ColumnsMenu
 `ref` → `HTMLButtonElement` (the trigger). The column chooser of the table it sits in: a Button opening a Dropdown with a check item per column. Writes the table's hidden columns; throws outside a DataTable `toolbar`.
@@ -125,10 +126,12 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Alignment to the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix it. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children">` | — | `className`, `aria-label` and the other attributes of the trigger button. |
 
-### DataTableColumn<Row>
+### Types
+
+#### `DataTableColumn<Row>`
 One column of `columns`: data, not a part.
 
-| Prop | Type | Default | Description |
+| Field | Type | Default | Description |
 |---|---|---|---|
 | `id` | `string` | — (required) | Unique column id (sort state, `data-column-id`). |
 | `header` | `ReactNode` | — (required) | Head content. |
@@ -137,8 +140,9 @@ One column of `columns`: data, not a part.
 | `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. |
+| `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. |
+| `hideHeader` | `boolean` | `false` | `header` names the column for assistive tech only (an action column): the head cell looks empty. |
 | `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. |
@@ -157,6 +161,8 @@ One column of `columns`: data, not a part.
 | `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 | |
 
+Without `size` the table takes the tier of its host (a sized form, panel or popover), else `m`.
+
 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 of a fixed small tier (`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 later content does not fit it, never narrows; widths are measured again when the column set or the container width changes. `grow` columns keep taking the free width.
@@ -231,23 +237,23 @@ Heads keep `start` whatever the cell alignment, with the sort icon at the end ed
 | 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 | `loadingMore`, or a pending promise from `onLoadMore` | `aria-busy`; footer `labels.loadingMore`; no new request until it settles (after a rejection, until the rows change) |
+| loading more | `hasMore` with every loaded row shown calls `onLoadMore`; `loadingMore`, or its pending promise | `aria-busy`; footer `labels.loadingMore`; no new request until it settles (after a rejection, until the rows change) |
 | refreshing | `loading` with rows on screen (a refetch, another server page or sort) | the rows, head, toolbar and footer stay; `aria-busy` on the table, `data-loading` on the root — no skeleton |
 | new server page | `source="server"` and `rows` replaced (not appended) | the body remounts with the swap fade (`swapMotion`), the viewport scrolls to its top; no per-row enter |
 | empty | no rows and not loading | compact EmptyPage with `empty` or `labels.empty` (`role="status"`), or the `empty` node; centred in the visible width, not across every column of a wide table |
-| error | `error` | body replaced by a `role="alert"` message in `danger-text`, centred in the visible width; range and infinite status hidden |
+| error | `loadError` | body replaced by a `role="alert"` message in `danger-text`, centred in the visible width; 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` |
+| selected | `selectable` with `selected` / `defaultSelected` | `data-selectable` on the root, a leading checkbox column; `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 new in `rows` (by `getRowKey`) | `data-animate`: top-level cells drop in from above (`enterMotion`) |
-| sub-rows and detail panels | an expand / a collapse | both fold open and shut through `grid-template-rows` (0fr ↔ 1fr) with the fade on the same `base` curve; the row height and padding live inside the track, so nothing is left to jump. Sub-rows: `data-fold` on the row (`opening` · `open` · `closed`); a collapsed row's sub-rows stay mounted until the fold ends. Detail row: `data-state`; it unmounts after the close |
+| sub-rows and detail panels | an expand / a collapse | both fold open and shut through the kit's Disclosure (`0fr ↔ 1fr`, the fade and a short slide on the same `base` clock; a detail opens on the enter curve); the row height and padding live inside the fold, so nothing is left to jump. Sub-rows: `data-fold` on the row (`open` · `closed`), every cell's content a Disclosure; a collapsed row's sub-rows stay mounted until the fold ends. Detail row: `data-state`; it unmounts after the close |
 | overflowing sideways | the table is wider than its viewport | `data-overflow-start` (scrolled from the start) and `data-overflow-end` (more to the end) on the root: a soft shadow over that edge, from the end edge of the sticky first column for the start; fades in and out over `fast` |
 | hidden columns | `hiddenColumns` / `defaultHiddenColumns`, `DataTable.ColumnsMenu` | the listed columns (except `hideable: false`) are not rendered in the head, rows, skeleton or state rows; widths are measured again; a sort by a hidden column keeps the row order |
 | opening rows | `getRowHref` / `onRowClick`, `isRowClickable` | `data-clickable` (pointer, pressed wash) on rows that open; link rows: `data-link`, an `<a data-row-link>` in every content cell; in-place rows: `tabindex="0"`. Focus (the link, or the row) rings the whole row with the hover wash |
 | grouped | `getRowGroup` | one `<tbody>` per group run on screen, opened by a `<th scope="rowgroup">` row one ladder step off the table; `data-sticky` on it with `stickyGroupHeaders` |
 | collapsed group | `collapsedGroups` / `defaultCollapsedGroups` | `data-collapsed` on the group header row, its toggle `aria-expanded="false"` with the chevron at rest; the group's `<tbody>` holds the header alone, its rows only lay out the column widths in the hidden measuring body. Its rows fold away and back like sub-rows (`data-fold`, `base`), whether a toggle or the owner changed the keys. «Select all» still takes the rows of collapsed groups; paging still counts them |
 | reorderable | `onReorder` (not with `getRowChildren` / `renderExpanded`) | `data-reorderable` on the root; a leading handle column (drag by the handle, a touch hold, Alt + ↑ / ↓ on it); each run of rows (the page, or each group) is a `Dnd.Sortable` `<tbody>`, so with `getRowGroup` rows move inside their group; a row put last on a page stands in front of the first row of the next page; a lifted row leaves a dashed gap row across every column, its neighbours glide (`base`), the copy flies in a one-row table at the row's column widths and sets down on its new place; a keyboard move glides the same way |
-| saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy`, its cells at 60% and a Spinner in its handle cell; a rejection glides it back |
+| saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy`, its cells at 60% and its grip busy (Dnd: a spinner in the disabled handle); a rejection glides it back |
 | reorder off | a sort by a column | the handles are disabled with a Tooltip (`labels.reorderSorted`); no drag, no Alt + arrows |
 | heatmap cell | column `scale` and a numeric value (`sortAccessor`, else `accessor`) | `data-scale="1"…"5"` on the cell: its base is `--prime-color-chart-scale-<n>`, text `--prime-color-chart-scale-fg` on 4–5; the range spans all rows (or the fixed `min` / `max`), so paging and sorting never change a shade; the value stays in the cell, non-numbers stay plain |
 | filling the parent | `scrollHeight="fill"` | `data-scroll-height="fill"` on the root; the viewport takes the free height |
@@ -259,7 +265,7 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 - The root is a layer of the surface ladder (`data-depth`, one above its host): it fills its container on `--prime-color-layer-current`, radius 12, and clips full-bleed head and rows; zebra rows and the sticky column are one ladder step off it, the head two. On a card or in a modal it is the next layer by itself — 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, never the page; pin the identifying column with `stickyFirstColumn`. Works from 320 px.
+- Columns scroll sideways inside the table, never the page; pin the identifying column with `stickyFirstColumn`. A 320 px column holds the table without breaking it.
 - While columns are hidden past an edge, that edge shows a `--prime-space-4` shadow (`--prime-color-bg-edge-shadow`) over the content; it takes no space and follows RTL. With `stickyFirstColumn` the start shadow falls from the pinned column's end edge.
 - Fewer columns, less scrolling: put `DataTable.ColumnsMenu` in `toolbar` (the key column `hideable: false`). The kit stores nothing: keep `onHiddenColumnsChange`'s list where the app keeps settings and pass it back as `hiddenColumns`. Never hide columns silently by width.
 - `DataTable.ColumnsMenu` is an outline neutral Button one tier below the table (the `view.columns` icon, `labels.columns`); its Dropdown lists every column and ends with `labels.showAllColumns`. A `hideable: false` column stays checked and disabled, and the last visible column cannot be hidden. With `align="auto"` a trigger near the end of the screen lines up the panel's end edge and the panel grows toward the start, and the other way near the start.
@@ -278,6 +284,8 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the toolbar (`DataTable.ColumnsMenu`), sort buttons, row handles, checkboxes, expand toggles, row links, rows that open in place and Pagination. |
@@ -288,6 +296,8 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 | `Escape` | Cancels a row drag; the row goes back to its place. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Native `<table>` semantics; head cells are `scope="col"` (the empty handle-column cell is a `<td>`); sortable heads hold a `<button>` and expose `aria-sort`; the whole head cell shows the inset focus ring.
 - A link row has one link for assistive tech: the `<a>` in the key cell, named by its text. Its copies over the other cells are `aria-hidden` and `tabindex="-1"`, so the pointer can use the whole row. An in-place row is focusable itself (`tabindex="0"`) and reads as its cells. Either way the focused row shows a ring around all its cells.
 - A row never opens from a control inside it (links, buttons, fields, `label`, `summary`, ARIA widgets, `data-row-click-ignore`), from a text selection, or from a React event that bubbled out of a portal (a ⋯ menu item).
@@ -327,7 +337,7 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 |---|---|
 | [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`. |
+| [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, formatted cells sort by their raw number and article numbers in natural order — `numeric`, `truncate`, `maxWidth`, `sortAccessor`, `sortComparator`. |
 | [heatmap.tsx](examples/heatmap.tsx) | Deals closed per manager and month as a heatmap: each count shades its cell on the chart scale and stays readable in it — `scale`, `numeric`. |
 | [trend.tsx](examples/trend.tsx) | Clients with revenue by month as a compact Sparkline in a cell of each row, next to the half-year total — `cell`, `width`. |
 | [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`. |
@@ -335,7 +345,7 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 | [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`. |
+| [detail-panel.tsx](examples/detail-panel.tsx) | Order details in a full-width row under an expanded order, aligned with the first content column; a cancelled order has nothing to show and gets no toggle — `renderExpanded`, `defaultExpanded`, `isRowExpandable`. |
 | [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`. |
 | [row-link.tsx](examples/row-link.tsx) | Invoices whose rows are links: ⌘-click or a middle click opens a new tab, a plain click routes inside the app, the totals row and the ⋯ menu never open a row — `getRowHref`, `onRowClick`, `isRowClickable`. |
 | [row-open.tsx](examples/row-open.tsx) | Deals that open in a side panel: a click, or Enter and Space on the focused row; the panel keeps the last deal while it slides away — `onRowClick`. |
@@ -345,9 +355,10 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 | [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`. |
 | [server.tsx](examples/server.tsx) | A CRM deal list the server sorts, pages and searches; a new search returns to page 1 — `source`, `rowCount`, `sort`, `page`, `loading`. |
 | [fill-height.tsx](examples/fill-height.tsx) | An audit log that fills the height of its panel and loads older entries while scrolling; the status shows while the request is pending — `scrollHeight`, `paging`, `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`. |
+| [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`, `loadError`. |
+| [controlled.tsx](examples/controlled.tsx) | Sort, page and the column choice 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`, `hiddenColumns`, `onHiddenColumnsChange`. |
 | [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`. |
+| [screen.tsx](examples/screen.tsx) | A list page: the title, a line of figures, search, filters and the one primary action in the app header, a DataTable of invoices with statuses, row actions, pages and a filtered empty state — `empty`, `pageSize`, `stickyFirstColumn`. |
 
 ## Mistakes
 - No `getRowKey` with `selectable`, expansion or sorting → selection follows positions, not records.
@@ -377,5 +388,5 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 - A new search that keeps the current page → set `page` to 1 together with the search.
 
 ## Related
-- **Built from:** [Checkbox](../checkbox/COMPONENT.md), [Button](../button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md) (`DataTable.ColumnsMenu`), [Pagination](../pagination/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading status, selection announcement), [Skeleton](../skeleton/COMPONENT.md) (loading rows, in the table tier), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable as="tbody"`, `Dnd.Handle`), [Tooltip](../tooltip/COMPONENT.md) and [Spinner](../spinner/COMPONENT.md) (handle hint and busy state), Icon (sort arrows, the expand chevron, the `DataTable.ColumnsMenu` trigger); `useVirtualRows` (the window of a long body)
+- **Built from:** [Checkbox](../checkbox/COMPONENT.md), [Button](../button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md) (`DataTable.ColumnsMenu`), [Pagination](../pagination/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading status, selection announcement), [Skeleton](../skeleton/COMPONENT.md) (loading rows, in the table tier), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable as="tbody"`, `Dnd.Handle`), [Tooltip](../tooltip/COMPONENT.md) (handle hint), Icon (sort arrows, the expand chevron, the `DataTable.ColumnsMenu` trigger); `useVirtualRows` (the window of a long body)
 - **See also:** [Sparkline](../sparkline/COMPONENT.md) (`layout="compact"` in a cell), [SmartFilter](../smart-filter/COMPONENT.md), [PageToolbar](../page-toolbar/COMPONENT.md), [Gantt](../gantt/COMPONENT.md), [Kanban](../kanban/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [Card](../card/COMPONENT.md)

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** Sort, page and the column choice 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`, `hiddenColumns`, `onHiddenColumnsChange`. */
 import { DataTable, type DataTableColumn, type DataTableSortState } from "prime-ui-kit";
 import * as React from "react";
 
@@ -21,7 +21,15 @@ const RUB = new Intl.NumberFormat("ru-RU", {
 });
 
 const COLUMNS: DataTableColumn<Order>[] = [
-  { id: "id", header: "№", accessor: "id", sortable: true, numeric: true, width: "5rem" },
+  {
+    id: "id",
+    header: "№",
+    accessor: "id",
+    sortable: true,
+    numeric: true,
+    width: "5rem",
+    hideable: false,
+  },
   { id: "customer", header: "Покупатель", accessor: "customer", sortable: true },
   { id: "city", header: "Город", accessor: "city", sortable: true },
   {
@@ -37,12 +45,16 @@ const COLUMNS: DataTableColumn<Order>[] = [
 export default function DataTableControlledExample() {
   const [sort, setSort] = React.useState<DataTableSortState>({ columnId: "total", order: "desc" });
   const [page, setPage] = React.useState(1);
+  const [hiddenColumns, setHiddenColumns] = React.useState<string[]>(["city"]);
 
   return (
     <DataTable
       columns={COLUMNS}
       rows={ORDERS}
       getRowKey={(row) => row.id}
+      toolbar={<DataTable.ColumnsMenu />}
+      hiddenColumns={hiddenColumns}
+      onHiddenColumnsChange={setHiddenColumns}
       sort={sort}
       onSortChange={(next) => {
         setSort(next);

package/src/components/data-table/examples/detail-panel.tsx

@@ -1,7 +1,5 @@
-/** Order details in a full-width row under an expanded order, aligned with the first content column — `renderExpanded`, `defaultExpanded`. */
-import { DataTable, type DataTableColumn, Typography } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Order details in a full-width row under an expanded order, aligned with the first content column; a cancelled order has nothing to show and gets no toggle — `renderExpanded`, `defaultExpanded`, `isRowExpandable`. */
+import { DataTable, type DataTableColumn, DescriptionList } from "prime-ui-kit";
 
 type Order = {
   id: string;
@@ -9,8 +7,8 @@ type Order = {
   customer: string;
   date: string;
   total: number;
-  address: string;
-  items: string;
+  /** Delivery details; a cancelled order has none. */
+  delivery: { address: string; items: string } | null;
 };
 
 const ORDERS: Order[] = [
@@ -20,8 +18,10 @@ const ORDERS: Order[] = [
     customer: "Анна Соколова",
     date: "07.10.26",
     total: 12_480,
-    address: "Москва, ул. Тверская, 12, кв. 45",
-    items: "Кабель USB-C, 2 м × 2, док-станция × 1",
+    delivery: {
+      address: "Москва, ул. Тверская, 12, кв. 45",
+      items: "Кабель USB-C, 2 м × 2, док-станция × 1",
+    },
   },
   {
     id: "o2",
@@ -29,17 +29,23 @@ const ORDERS: Order[] = [
     customer: "Дмитрий Орлов",
     date: "06.10.26",
     total: 34_900,
-    address: "Санкт-Петербург, Невский пр., 28",
-    items: 'Монитор 27" × 1',
+    delivery: { address: "Санкт-Петербург, Невский пр., 28", items: 'Монитор 27" × 1' },
   },
   {
     id: "o3",
+    number: "№ 10 479",
+    customer: "Игорь Белов",
+    date: "06.10.26",
+    total: 2_990,
+    delivery: null,
+  },
+  {
+    id: "o4",
     number: "№ 10 477",
     customer: "Мария Ким",
     date: "05.10.26",
     total: 4_350,
-    address: "Казань, ул. Баумана, 7",
-    items: "Клавиатура × 1",
+    delivery: { address: "Казань, ул. Баумана, 7", items: "Клавиатура × 1" },
   },
 ];
 
@@ -51,7 +57,13 @@ const RUB = new Intl.NumberFormat("ru-RU", {
 
 const COLUMNS: DataTableColumn<Order>[] = [
   { id: "number", header: "Заказ", accessor: "number", minWidth: "8rem" },
-  { id: "customer", header: "Покупатель", accessor: "customer", sortable: true },
+  {
+    id: "customer",
+    header: "Покупатель",
+    accessor: "customer",
+    sortable: true,
+    cell: (row) => (row.delivery ? row.customer : `${row.customer} · отменён`),
+  },
   { id: "date", header: "Дата", accessor: "date", numeric: true },
   {
     id: "total",
@@ -70,30 +82,17 @@ export default function DataTableDetailPanelExample() {
       rows={ORDERS}
       getRowKey={(row) => row.id}
       getRowLabel={(row) => row.number}
-      renderExpanded={(row) => (
-        <dl className={styles.details}>
-          <dt>
-            <Typography as="span" variant="body-s" tone="muted">
-              Адрес доставки
-            </Typography>
-          </dt>
-          <dd>
-            <Typography as="span" variant="body-s">
-              {row.address}
-            </Typography>
-          </dd>
-          <dt>
-            <Typography as="span" variant="body-s" tone="muted">
-              Состав
-            </Typography>
-          </dt>
-          <dd>
-            <Typography as="span" variant="body-s">
-              {row.items}
-            </Typography>
-          </dd>
-        </dl>
-      )}
+      isRowExpandable={(row) => row.delivery !== null}
+      renderExpanded={(row) =>
+        row.delivery ? (
+          <DescriptionList.Root size="s">
+            <DescriptionList.Item label="Адрес доставки">
+              {row.delivery.address}
+            </DescriptionList.Item>
+            <DescriptionList.Item label="Состав">{row.delivery.items}</DescriptionList.Item>
+          </DescriptionList.Root>
+        ) : null
+      }
       defaultExpanded={["o1"]}
       paging="none"
     />

package/src/components/data-table/examples/examples.module.css

@@ -27,15 +27,7 @@
   max-width: calc(var(--prime-space-20) * 4);
 }
 
-/* sizes / appearance / states: a table with its caption under it; specimens kept apart. */
-.specimens {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-6);
-  width: 100%;
-  min-width: 0;
-}
-
+/* appearance / content-width: a table with its caption under it. */
 .specimen {
   display: flex;
   flex-direction: column;
@@ -57,18 +49,6 @@
   min-width: 0;
 }
 
-.details {
-  display: grid;
-  grid-template-columns: max-content minmax(0, 1fr);
-  gap: var(--prime-space-1) var(--prime-space-4);
-  margin: 0;
-}
-
-.details dd {
-  margin: 0;
-  min-width: 0;
-}
-
 /* fill-height: a panel of a fixed height (the rest of a page, a pane) the table fills. */
 .fillStage {
   display: flex;

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

@@ -21,7 +21,11 @@ const COLUMNS: DataTableColumn<Ticket>[] = [
     id: "priority",
     header: "Приоритет",
     cell: (row) =>
-      row.urgent ? <Badge.Root color="red">Высокий</Badge.Root> : <Badge.Root>Обычный</Badge.Root>,
+      row.urgent ? (
+        <Badge.Root tone="danger">Высокий</Badge.Root>
+      ) : (
+        <Badge.Root tone="neutral">Обычный</Badge.Root>
+      ),
   },
   { id: "waiting", header: "Ждёт, ч", accessor: "waiting", numeric: true },
 ];

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** An inventory report: number columns align to the end in tabular figures, a long name stays on one line with a title, formatted cells sort by their raw number and article numbers in natural order — `numeric`, `truncate`, `maxWidth`, `sortAccessor`, `sortComparator`. */
 import { DataTable, type DataTableColumn } from "prime-ui-kit";
 
 type Sku = {
@@ -22,18 +22,50 @@ const SKUS: Sku[] = [
   { sku: "MS-044", name: "Мышь оптическая", stock: 86, price: 1290, sold: 1204, margin: 0.312 },
   { sku: "MN-27Q", name: 'Монитор 27" QHD IPS', stock: 12, price: 32_900, sold: 41, margin: 0.118 },
   { sku: "HB-7P", name: "USB-хаб на 7 портов", stock: 530, price: 2190, sold: 97, margin: 0.402 },
+  {
+    sku: "HB-10P",
+    name: "USB-хаб на 10 портов",
+    stock: 210,
+    price: 3490,
+    sold: 64,
+    margin: 0.356,
+  },
 ];
 
 const INT = new Intl.NumberFormat("ru-RU");
 const PCT = new Intl.NumberFormat("ru-RU", { style: "percent", maximumFractionDigits: 1 });
 
+/** Article numbers in natural order: HB-7P before HB-10P. */
+const NATURAL = new Intl.Collator("ru-RU", { numeric: true });
+
 const COLUMNS: DataTableColumn<Sku>[] = [
-  { id: "sku", header: "Артикул", accessor: "sku", width: "6rem" },
+  {
+    id: "sku",
+    header: "Артикул",
+    accessor: "sku",
+    width: "6rem",
+    sortable: true,
+    sortComparator: (a, b) => NATURAL.compare(a.sku, b.sku),
+  },
   { id: "name", header: "Товар", accessor: "name", truncate: true, maxWidth: "14rem" },
-  { id: "stock", header: "Остаток, шт", numeric: true, cell: (row) => INT.format(row.stock) },
+  {
+    id: "stock",
+    header: "Остаток, шт",
+    numeric: true,
+    sortable: true,
+    sortAccessor: (row) => row.stock,
+    cell: (row) => INT.format(row.stock),
+  },
   { id: "price", header: "Цена, ₽", numeric: true, cell: (row) => INT.format(row.price) },
   { id: "sold", header: "Продано", numeric: true, cell: (row) => INT.format(row.sold) },
-  { id: "margin", header: "Маржа", numeric: true, cell: (row) => PCT.format(row.margin) },
+  {
+    id: "margin",
+    header: "Маржа",
+    numeric: true,
+    sortable: true,
+    sortAccessor: (row) => row.margin,
+    cell: (row) => PCT.format(row.margin),
+  },
 ];
 
 export default function DataTableNumericExample() {

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

@@ -34,6 +34,7 @@ const COLUMNS: DataTableColumn<Order>[] = [
     header: "Статус",
     accessor: "status",
     sortable: true,
+    sortAccessor: (row) => STATUS[row.status].label,
     cell: (row) => (
       <Badge.Root color={STATUS[row.status].color}>{STATUS[row.status].label}</Badge.Root>
     ),

package/src/components/data-table/examples/row-link.tsx

@@ -45,7 +45,8 @@ export default function DataTableRowLinkExample() {
     },
     {
       id: "actions",
-      header: "",
+      header: "Действия",
+      hideHeader: true,
       align: "end",
       cell: (row) =>
         row.total ? null : (

package/src/components/data-table/examples/row-open.tsx

@@ -1,9 +1,7 @@
 /** Deals that open in a side panel: a click, or Enter and Space on the focused row; the panel keeps the last deal while it slides away — `onRowClick`. */
-import { Badge, DataTable, type DataTableColumn, Drawer, Typography } from "prime-ui-kit";
+import { Badge, DataTable, type DataTableColumn, DescriptionList, Drawer } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
 type Stage = "new" | "talks" | "won";
 type Deal = { id: string; title: string; client: string; owner: string; stage: Stage; sum: number };
 
@@ -47,7 +45,7 @@ const RUB = new Intl.NumberFormat("ru-RU", {
 });
 
 const COLUMNS: DataTableColumn<Deal>[] = [
-  { id: "title", header: "Сделка", accessor: "title", hideable: false },
+  { id: "title", header: "Сделка", accessor: "title" },
   { id: "client", header: "Клиент", accessor: "client" },
   {
     id: "stage",
@@ -88,38 +86,11 @@ export default function DataTableRowOpenExample() {
           </Drawer.Header>
           <Drawer.Body>
             {deal ? (
-              <dl className={styles.details}>
-                <dt>
-                  <Typography as="span" variant="body-m" tone="muted">
-                    Клиент
-                  </Typography>
-                </dt>
-                <dd>
-                  <Typography as="span" variant="body-m">
-                    {deal.client}
-                  </Typography>
-                </dd>
-                <dt>
-                  <Typography as="span" variant="body-m" tone="muted">
-                    Ответственный
-                  </Typography>
-                </dt>
-                <dd>
-                  <Typography as="span" variant="body-m">
-                    {deal.owner}
-                  </Typography>
-                </dd>
-                <dt>
-                  <Typography as="span" variant="body-m" tone="muted">
-                    Сумма
-                  </Typography>
-                </dt>
-                <dd>
-                  <Typography as="span" variant="body-m">
-                    {RUB.format(deal.sum)}
-                  </Typography>
-                </dd>
-              </dl>
+              <DescriptionList.Root>
+                <DescriptionList.Item label="Клиент">{deal.client}</DescriptionList.Item>
+                <DescriptionList.Item label="Ответственный">{deal.owner}</DescriptionList.Item>
+                <DescriptionList.Item label="Сумма">{RUB.format(deal.sum)}</DescriptionList.Item>
+              </DescriptionList.Root>
             ) : null}
           </Drawer.Body>
         </Drawer.Content>

package/src/components/data-table/examples/screen.module.css

@@ -0,0 +1,13 @@
+/* List page: the header carries the title and the tools; this module lays out table cells only. */
+
+/* Client cell: avatar, then the name over the tax id (the column's `minWidth` keeps it on its
+   lines; on a phone the table scrolls sideways). */
+.client {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+.clientText {
+  display: grid;
+}