prime-ui-kit 0.7.11 → 0.9.0

package/src/components/command-menu/examples/keyboard-search.tsx

@@ -0,0 +1,94 @@
+/** App palette opened with ⌘K / Ctrl+K: groups, filtering by `value` and `keywords`, a description line, shortcuts, the empty state and a keyboard legend. Use as the global search of an app. */
+import {
+  ArrowDown,
+  ArrowUp,
+  CornerDownLeft,
+  FileText,
+  LayoutDashboard,
+  Receipt,
+  Settings,
+  Users,
+} from "lucide-react";
+import { Button, CommandMenu } from "prime-ui-kit";
+import * as React from "react";
+
+export default function CommandMenuKeyboardSearchExample() {
+  const [open, setOpen] = React.useState(false);
+  const close = () => setOpen(false);
+
+  React.useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((v) => !v);
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, []);
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Поиск по приложению · ⌘K
+      </Button.Root>
+
+      <CommandMenu.Dialog
+        open={open}
+        onOpenChange={setOpen}
+        aria-label="Поиск по приложению"
+        labels={{ emptyHint: "Проверьте раскладку или поищите по разделу" }}
+      >
+        <CommandMenu.InputRow>
+          <CommandMenu.Input
+            placeholder="Попробуйте «отчёт», «billing» или «xyz»"
+            aria-label="Поиск команд"
+          />
+        </CommandMenu.InputRow>
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group heading="Страницы">
+            <CommandMenu.Item value="дашборд" keywords="home main главная" onSelect={close}>
+              <CommandMenu.ItemIcon as={LayoutDashboard} />
+              Дашборд
+              <CommandMenu.ItemShortcut>G D</CommandMenu.ItemShortcut>
+            </CommandMenu.Item>
+            <CommandMenu.Item value="отчёты" keywords="analytics charts" onSelect={close}>
+              <CommandMenu.ItemIcon as={FileText} />
+              Аналитика и отчёты
+              <CommandMenu.ItemShortcut>G R</CommandMenu.ItemShortcut>
+            </CommandMenu.Item>
+            <CommandMenu.Item value="команда" keywords="people users" onSelect={close}>
+              <CommandMenu.ItemIcon as={Users} />
+              Команда
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group heading="Настройки">
+            <CommandMenu.Item value="счета" keywords="billing invoices" onSelect={close}>
+              <CommandMenu.ItemIcon as={Receipt} />
+              <CommandMenu.ItemText description="Настройки → Оплата">
+                Счета и оплата
+              </CommandMenu.ItemText>
+            </CommandMenu.Item>
+            <CommandMenu.Item value="профиль" keywords="account profile" onSelect={close}>
+              <CommandMenu.ItemIcon as={Settings} />
+              <CommandMenu.ItemText description="Имя, почта, пароль">Профиль</CommandMenu.ItemText>
+              <CommandMenu.ItemShortcut>⌘,</CommandMenu.ItemShortcut>
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+        <CommandMenu.Footer>
+          <CommandMenu.FooterHint
+            keys={[<ArrowUp key="up" aria-hidden />, <ArrowDown key="down" aria-hidden />]}
+          >
+            Навигация
+          </CommandMenu.FooterHint>
+          <CommandMenu.FooterHint keys={[<CornerDownLeft key="enter" aria-hidden />]}>
+            Выбрать
+          </CommandMenu.FooterHint>
+          <CommandMenu.FooterHint keys={["Esc"]}>Закрыть</CommandMenu.FooterHint>
+        </CommandMenu.Footer>
+      </CommandMenu.Dialog>
+    </>
+  );
+}

package/src/components/command-menu/examples/sizes.tsx

@@ -0,0 +1,74 @@
+/** CommandMenu.Dialog `size` xs → xl: rows, text, icons and the search row follow the tier. Match the density of the app. */
+import { File, Folder } from "lucide-react";
+import { Button, CommandMenu, type ControlSize } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SIZES: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+
+export default function CommandMenuSizesExample() {
+  const [open, setOpen] = React.useState(false);
+  const [size, setSize] = React.useState<ControlSize>("m");
+  const close = () => setOpen(false);
+
+  return (
+    <>
+      <div className={styles.row}>
+        {SIZES.map((s) => (
+          <Button.Root
+            key={s}
+            size={s}
+            variant="soft"
+            tone="neutral"
+            onClick={() => {
+              setSize(s);
+              setOpen(true);
+            }}
+          >
+            {s}
+          </Button.Root>
+        ))}
+      </div>
+
+      <CommandMenu.Dialog
+        open={open}
+        onOpenChange={setOpen}
+        size={size}
+        aria-label="Поиск файлов"
+        labels={{ search: "Найти файл" }}
+      >
+        <CommandMenu.InputRow>
+          <CommandMenu.Input />
+        </CommandMenu.InputRow>
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group heading="Файлы">
+            <CommandMenu.Item value="договор" onSelect={close}>
+              <CommandMenu.ItemIcon as={File} />
+              Договор поставки.pdf
+            </CommandMenu.Item>
+            <CommandMenu.Item value="счёт" onSelect={close}>
+              <CommandMenu.ItemIcon as={File} />
+              Счёт № 1042.pdf
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group heading="Папки">
+            <CommandMenu.Item value="бюджет" onSelect={close}>
+              <CommandMenu.ItemIcon as={Folder} />
+              <CommandMenu.ItemText description="Финансы / 2026 / Квартал 3">
+                Бюджет на квартал
+              </CommandMenu.ItemText>
+            </CommandMenu.Item>
+            <CommandMenu.Item value="презентация" onSelect={close}>
+              <CommandMenu.ItemIcon as={Folder} />
+              <CommandMenu.ItemText description="Маркетинг / Запуски">
+                Презентация продукта
+              </CommandMenu.ItemText>
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Dialog>
+    </>
+  );
+}

package/src/components/command-menu/examples/states.tsx

@@ -0,0 +1,58 @@
+/** A long list that scrolls under the fixed search row, a disabled item hidden from results and custom empty-state texts. Use for picking one entry from a long list by typing. */
+import { Button, CommandMenu } from "prime-ui-kit";
+import * as React from "react";
+
+const CITIES = [
+  "Москва",
+  "Санкт-Петербург",
+  "Новосибирск",
+  "Екатеринбург",
+  "Казань",
+  "Нижний Новгород",
+  "Челябинск",
+  "Красноярск",
+  "Самара",
+  "Уфа",
+  "Ростов-на-Дону",
+  "Омск",
+  "Краснодар",
+  "Воронеж",
+  "Пермь",
+];
+
+export default function CommandMenuStatesExample() {
+  const [open, setOpen] = React.useState(false);
+  const close = () => setOpen(false);
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Выбрать склад
+      </Button.Root>
+
+      <CommandMenu.Dialog
+        open={open}
+        onOpenChange={setOpen}
+        aria-label="Выбор склада"
+        labels={{ empty: "Склад не найден", emptyHint: "Склада в этом городе пока нет" }}
+      >
+        <CommandMenu.InputRow>
+          <CommandMenu.Input placeholder="Город склада" aria-label="Город склада" />
+        </CommandMenu.InputRow>
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group heading="Склады">
+            {CITIES.map((city) => (
+              <CommandMenu.Item key={city} value={city} onSelect={close}>
+                {city}
+              </CommandMenu.Item>
+            ))}
+            <CommandMenu.Item value="Калининград" disabled onSelect={close}>
+              Калининград — на ремонте
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Dialog>
+    </>
+  );
+}

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

@@ -1,140 +1,259 @@
 # DataTable
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** data-display
 
-## About
+> A data table with sorting, pagination 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 header 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`.
+## When not to use
+- One or two KPIs → use [Card](../card/COMPONENT.md) (`mini`, `stat-trend`).
+- A short list of events without columns → use `Card variant="list"` or [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 on its own (outside a table) → use [Pagination](../pagination/COMPONENT.md).
+- Picking values from a list → use [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md).
 
-## Composition
+## Import
+```tsx
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+```
+Exported types: `DataTableColumn<Row>`, `DataTableRootProps<Row>`, `DataTableSortState`, `DataTableOrder`, `DataTableLabels`.
 
-- **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.
+## Anatomy
+```
+DataTable.Root                      card-fill block, radius 12, clips its content
+├── toolbar                         optional slot above the table (search, filters, bulk actions)
+├── scroll viewport (ScrollContainer, both axes)
+│   └── table
+│       ├── thead                   head cells; sortable headers are buttons
+│       │   └── [select-all] [toggle] column headers…
+│       └── tbody                   rows · sub-rows · detail rows · skeleton / empty / error row
+└── footer                          range «Показано 1–5 из 23» · Pagination · infinite-scroll status
+```
+DataTable is a single configurable component: columns are data (`DataTableColumn<Row>[]`), not child parts.
 
-### Playground snippets
+## API
 
-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).
+### DataTable.Root
+Generic over `Row`. No ref forwarding, no `asChild`, no native prop spreading (only `className`). Sizes nested controls through the control-size context.
 
-| 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`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `DataTableColumn<Row>[]` | — (required) | Column definitions, see below. |
+| `rows` | `Row[]` | — (required) | Data; sorted in memory when a sort is set. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Density and control tier; passed to checkboxes, toggles, pagination and nested controls. |
+| `className` | `string` | — | Class on the root. |
+| `toolbar` | `ReactNode` | — | Slot above the table; wraps / stacks below 30rem table width. |
+| `showHeader` | `boolean` | `true` | Render `<thead>`. |
+| `stickyHeader` | `boolean` | `false` | Header sticks while the body scrolls. |
+| `stickyFirstColumn` | `boolean` | `false` | First column (with selection / toggle columns) sticks while scrolling horizontally. |
+| `getRowKey` | `(row: Row, index: number) => React.Key` | position | Stable row id; selection and expansion are keyed by it. Pass it whenever sorting, selection or expansion is used. |
+| `getRowLabel` | `(row: Row) => string` | — | Human row name for checkbox / toggle `aria-label`s. |
+| `onRowClick` | `(row: Row, index: number, event: React.MouseEvent<HTMLTableRowElement>) => void` | — | Row click; rows get a pointer cursor. |
+| `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 (text or EmptyPage). |
+| `error` | `ReactNode` | — | Replaces the body with a message in `role="alert"`. |
+| `labels` | `Partial<DataTableLabels>` | see Accessibility | Built-in strings. |
+| `dividerStyle` | `"standard" \| "dashed" \| "dotted" \| "none"` | `"standard"` | Row divider line. |
+| `columnDividers` | `boolean` | `false` | Vertical lines between columns. |
+| `striped` | `boolean` | `false` | Zebra rows. |
+| `highlightRowOnHover` | `boolean` | `true` | Row wash on hover (and pressed wash on clickable rows). |
+| `highlightColumnOnHover` | `boolean` | `false` | Column wash under the pointer (head + cells). |
+| `fillWidth` | `boolean` | `true` | Table spans the container; `false` sizes it by content. |
+| `sort` | `DataTableSortState` | — | Controlled sort `{ columnId, order: "asc" \| "desc" } \| null`. |
+| `defaultSort` | `DataTableSortState` | `null` | Initial sort (uncontrolled). |
+| `onSortChange` | `(sort: DataTableSortState) => void` | — | Header click cycles asc → desc → none; the page resets to 1. |
+| `page` | `number` | — | Controlled page (from 1). |
+| `defaultPage` | `number` | `1` | Initial page (uncontrolled). |
+| `onPageChange` | `(page: number) => void` | — | Page change. |
+| `pageSize` | `number` | `10` | Rows per page (also the first batch in infinite scroll). |
+| `showPagination` | `boolean` | `true` | Show Pagination in the footer when there is more than one page. |
+| `siblingCount` | `number` | `1` | Pagination siblings around the current page. |
+| `paginationSize` | `ControlSize` | `size` | Pagination size independent of the table. |
+| `infiniteScroll` | `boolean` | `false` | Reveal rows while scrolling instead of pages. |
+| `initialVisibleRows` | `number` | `pageSize` | Rows shown first in infinite scroll. |
+| `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 all loaded rows are shown and `hasMore`. |
+| `scrollHeight` | `number \| string` | `360` with `infiniteScroll`, else — | Max height of the scroll viewport (number = px). |
+| `selectable` | `boolean` | `false` | Leading checkbox column with select-all, Shift range, drag and Space. |
+| `selected` | `React.Key[]` | — | Controlled selected ids. |
+| `defaultSelected` | `React.Key[]` | `[]` | Initially selected ids (uncontrolled). |
+| `onSelectedChange` | `(selected: React.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` | has sub-rows or `renderExpanded` set | Which rows get an expand toggle. |
+| `expanded` | `React.Key[]` | — | Controlled expanded ids. |
+| `defaultExpanded` | `React.Key[]` | `[]` | Initially expanded ids (uncontrolled). |
+| `onExpandedChange` | `(expanded: React.Key[]) => void` | — | Expansion change. |
 
-### Extra recipes (`examples/`)
+### DataTableColumn&lt;Row&gt;
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | — (required) | Unique column id (sort state, `data-column-id`). |
+| `header` | `ReactNode` | — (required) | Header content. |
+| `accessor` | `keyof Row \| ((row: Row) => unknown)` | — | Cell value (rendered as text, `—` for null) and default sort value. |
+| `cell` | `(row: Row) => ReactNode` | — | Custom cell rendering. |
+| `sortable` | `boolean` | — | Header becomes a sort button with `aria-sort`. |
+| `sortAccessor` | `(row: Row) => unknown` | — | Value used for sorting instead of `accessor`. |
+| `sortComparator` | `(a: Row, b: Row, order: DataTableOrder) => number` | — | Custom comparison. |
+| `align` | `"start" \| "center" \| "end"` | `"start"` (`"end"` when `numeric`) | Cell and header alignment. |
+| `numeric` | `boolean` | — | `tabular-nums`, no wrapping, end alignment unless `align` is set. |
+| `truncate` | `boolean` | — | One line with ellipsis; width from `maxWidth` (or `width`); string values get a `title`. |
+| `width` | `string` | — | CSS width of the column. |
+| `minWidth` | `string` | — | CSS min width. |
+| `maxWidth` | `string` | — | CSS max width. |
+| `onHeaderClick` | `(event: React.MouseEvent<HTMLTableCellElement>) => void` | — | Header cell click (before sorting). |
+| `onCellClick` | `(row: Row, event: React.MouseEvent<HTMLTableCellElement> \| React.KeyboardEvent<HTMLTableCellElement>) => void` | — | Makes the cell a `role="button"` with `tabIndex=0`; Enter / Space trigger it. |
 
-| 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. |
+## Variants
 
-### Minimal example
+### size (density)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | Rows 36, head 28, text 12/16, cell padding 8 | Very dense admin grids | |
+| `s` | Rows 36, head 32, text 13/20 | Dense back-office lists, narrow containers | |
+| `m` | Rows 44, head 36 (13/20 head text), cells 14/20, padding 12 | Most tables | yes |
+| `l` | Rows 52, head 40, text 16/24 | Spacious lists with avatars and two-line cells | |
+| `xl` | Rows 52, head 48, text 16/24, padding 16 | Large touch-friendly tables | |
 
-```tsx
-import { DataTable, type DataTableColumn } from "prime-ui-kit";
+The head is the control height of the tier with text one step smaller (muted, weight 500). Checkboxes use the table tier; expand toggles are square ghost buttons one tier down (`xs` for xs–m, `s` for l–xl). Toolbar controls should use `s` in an `m` table.
 
-type Row = { id: string };
+### dividerStyle
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `standard` | 1px solid `border-subtle` between rows | Normal tables | yes |
+| `dashed` | Dashed hairline | Lighter separation in comparison tables | |
+| `dotted` | Dotted hairline | Very light separation, print-like reports | |
+| `none` | No row lines | Together with `striped`, or short tables | |
 
-const columns: DataTableColumn<Row>[] = [{ id: "id", header: "ID", accessor: "id" }];
-const rows: Row[] = [{ id: "1" }];
+### Column `align`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | Text at the start | Text columns | yes (non-numeric) |
+| `center` | Centered | Short symmetric values (icons, flags, hours) | |
+| `end` | At the end | Numbers, money (set automatically by `numeric`) | yes (`numeric`) |
 
-export function Example() {
-  return <DataTable.Root columns={columns} rows={rows} />;
-}
-```
+### Visual flags
+| Flag | Looks like when on | Use when | Default |
+|---|---|---|---|
+| `striped` | Every second row one opaque step off the table fill | Long numeric grids | `false` |
+| `columnDividers` | 1px vertical lines between columns | Many numeric columns | `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 | Turn off only for self-explanatory key/value tables | `true` |
+| `fillWidth` | Table 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, dates as numbers | — |
+| column `truncate` | Single line with ellipsis and `title` | Long names in narrow columns | — |
 
-## Rules
+**Combinations**
+- Recommended: `numeric` for every number column; `striped` + `dividerStyle="none"`; `selectable` + bulk actions in `toolbar`; `stickyHeader` + `scrollHeight` for long tables.
+- Allowed but rare: `highlightColumnOnHover` with `columnDividers`; `showHeader={false}` for key/value lists.
+- Avoid: `striped` with `columnDividers` and dashed lines at once (noise); `selectable` / expansion / sorting without `getRowKey` (ids shift when sorting); `infiniteScroll` together with pagination expectations (pagination is hidden in infinite mode).
 
-- 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.
+**Sizes**
+Default `m` (44px rows) lines up with `m` buttons and inputs on the page; toolbar controls inside use `s`. `size` also drives the pagination unless `paginationSize` is set.
 
-## API
+**Hierarchy**
+One primary action per toolbar (`soft` / `solid`), others `outline` or `ghost`; destructive bulk action `variant="soft" tone="danger"`.
 
-### DataTable.Root
+## 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 (with rows) / loading more | `loading`, `loadingMore` | `aria-busy`; footer `labels.loadingMore` |
+| empty | no rows and not loading | Centered muted body-s text (`empty` or `labels.empty`) |
+| error | `error` | Body replaced by `role="alert"` message in `danger-text`; range and infinite-scroll status hidden, Pagination still shows when `rows` exceed `pageSize` |
+| sorted | `sort` / `defaultSort` | `aria-sort` on the header, `data-sortable`, `data-sorted`; accent sort icon |
+| selected | `selected` / `defaultSelected` | `aria-selected` on rows, `accent-soft` fill; polite «Выбрано: N» |
+| expanded | `expanded` / `defaultExpanded` | `data-expanded` on the parent row (one step darker, first cell weight 500); toggle `aria-expanded` |
+| hover | pointer | Row / column wash per highlight flags |
 
-| 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`.
+Root data attributes: `data-size`, `data-divider`, `data-column-dividers`, `data-show-header`, `data-sticky-header`, `data-sticky-first-column`, `data-table-width="fill" | "auto"`, `data-highlight-row`, `data-highlight-column`, `data-striped`, `data-loading`, `data-selectable`, `data-expandable`, `data-dragging` (while drag-selecting).
+Cell / row attributes: `data-align`, `data-numeric`, `data-first-column`, `data-column-id`, `data-column-hovered`, `data-stripe="alt"`, `data-clickable`, `data-depth`, `data-animate` (rows mounted by the latest expand), `data-select-index`.
 
-## Related
+Controlled vs uncontrolled: `sort`, `page`, `selected`, `expanded` are controlled with their `on…Change`; `defaultSort`, `defaultPage`, `defaultSelected`, `defaultExpanded` are the uncontrolled starting values.
 
-- [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.
+## Layout & spacing
+- The root fills its container (`width: 100%`) on `--prime-color-card-bg`, radius 12, and clips full-bleed head and rows; on a card or modal it becomes a sunken block.
+- Toolbar padding `--prime-space-3` × cell padding; items `gap: var(--prime-space-2)`; below 30rem table width toolbar and footer stack.
+- The footer has a hairline on top, range text left, Pagination right (compact on narrow widths).
+- Columns scroll horizontally inside the table; use `stickyFirstColumn` for the identifying column. Works from 320px.
+- Column widths: pass `width` / `minWidth` / `maxWidth` strings (e.g. `"14rem"`); do not 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
+- Native `<table>` semantics; header cells are `scope="col"`. Sortable headers contain a `<button>` and expose `aria-sort`. The whole head cell shows the inset focus ring.
+- Selection: the header checkbox (`labels.selectAll`, indeterminate when partial), row checkboxes (`labels.selectRow(getRowLabel(row))`), Space toggles, Shift+click / Shift+Space selects a range, press-and-drag sets the same state on passed rows; a polite live region announces `labels.selectedCount(n)`.
+- Expansion: the toggle is a button with `aria-expanded`, `aria-controls` (detail row / sub-rows) and `labels.expand` / `labels.collapse`.
+- `onCellClick` cells are `role="button"`, focusable, Enter / Space; inset focus ring.
+- Pass `getRowLabel` so checkbox and toggle names are unique.
+- `labels` (`DataTableLabels`):
+  - `loading` — `"Загрузка данных…"`
+  - `empty` — `"Нет данных для отображения."`
+  - `range(from, to, total)` — `` `Показано ${from}–${to} из ${total}` ``
+  - `loadingMore` — `"Догружаем строки…"`
+  - `scrollForMore` — `"Прокрутите вниз для загрузки"`
+  - `selectAll` — `"Выбрать все строки"`
+  - `selectRow(label?)` — `` `Выбрать: ${label}` `` or `"Выбрать строку"`
+  - `selectedCount(count)` — `` `Выбрано: ${count}` ``
+  - `expand(label?)` — `` `Развернуть: ${label}` `` or `"Развернуть строку"`
+  - `collapse(label?)` — `` `Свернуть: ${label}` `` or `"Свернуть строку"`
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [dashboard.tsx](examples/dashboard.tsx) | KPI cards + recent orders with avatar, badge, `numeric` | Overview screens |
+| [sizes.tsx](examples/sizes.tsx) | Densities xs–xl | Choosing density |
+| [numeric.tsx](examples/numeric.tsx) | `numeric`, `truncate` + `maxWidth`, `columnDividers` | Inventories and reports |
+| [sorting-pagination.tsx](examples/sorting-pagination.tsx) | Controlled `sort` and `page` | Sorting / paging in URL or store |
+| [selection.tsx](examples/selection.tsx) | `selectable` with bulk actions in `toolbar` | Bulk operations |
+| [nested-rows.tsx](examples/nested-rows.tsx) | `getRowChildren`, controlled `expanded`, with selection | Hierarchical data |
+| [detail-panel.tsx](examples/detail-panel.tsx) | `renderExpanded` + `stickyFirstColumn` | Details without leaving the list |
+| [toolbar.tsx](examples/toolbar.tsx) | Search, SegmentedControl filter, export; `empty` on no match | Filterable lists |
+| [states.tsx](examples/states.tsx) | `loading` + `loadingRows`, `empty`, `error` with retry | Tables backed by requests |
+| [sticky.tsx](examples/sticky.tsx) | `stickyHeader` + `stickyFirstColumn` in a `scrollHeight` window (`infiniteScroll` with `initialVisibleRows={rows.length}`, so all rows render without pagination) | Wide reports |
+| [infinite-scroll.tsx](examples/infinite-scroll.tsx) | `infiniteScroll`, `hasMore`, `loadingMore`, `onLoadMore` | Logs and feeds |
+| [appearance.tsx](examples/appearance.tsx) | `striped`, `dividerStyle` none / dashed / dotted, `highlightColumnOnHover`, `columnDividers`, no header | Row styling |
+| [content-width.tsx](examples/content-width.tsx) | `fillWidth` vs `fillWidth={false}`, `align="center"` | Short lookup tables |
+| [narrow.tsx](examples/narrow.tsx) | 320px container, `size="s"`, sticky first column, compact pagination | Mobile layouts |
+
+```tsx
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+
+type Invoice = { id: string; client: string; amount: number };
+
+const columns: DataTableColumn<Invoice>[] = [
+  { id: "id", header: "Счёт", accessor: "id" },
+  { id: "client", header: "Клиент", accessor: "client", sortable: true },
+  { id: "amount", header: "Сумма, ₽", accessor: "amount", numeric: true, sortable: true },
+];
+
+export function InvoiceTable({ rows }: { rows: Invoice[] }) {
+  return <DataTable.Root columns={columns} rows={rows} getRowKey={(row) => row.id} />;
+}
+```
+
+## Mistakes
+- No `getRowKey` with `selectable` or sorting → selection follows positions, not records; always pass it.
+- Numbers in a plain column → set `numeric` (alignment and tabular figures).
+- A custom «Ничего не найдено» row inside `rows` → use `empty`.
+- Rendering a spinner instead of rows → use `loading` (skeleton keeps the header and layout).
+- Wrapping the table in a Card for a border → the table is already a bounded block with its own fill.
+- Custom checkbox column → use `selectable` (range, drag, announcements built in).
+- `scrollHeight` without `stickyHeader` on long tables → the header scrolls away.
+
+## Related
+- [Pagination](../pagination/COMPONENT.md) — used in the footer.
+- [Checkbox](../checkbox/COMPONENT.md) — selection column.
+- [ScrollContainer](../scroll-container/COMPONENT.md) — the scroll viewport.
+- [EmptyPage](../empty-page/COMPONENT.md) — rich empty state via `empty`.
+- [Badge](../badge/COMPONENT.md), [Avatar](../avatar/COMPONENT.md) — typical cell content.
+- [Card](../card/COMPONENT.md) — KPIs above a table.