prime-ui-kit 0.2.5 → 0.3.2

package/src/components/command-menu/examples/app-palette.tsx

@@ -0,0 +1,129 @@
+import { ArrowDown, ArrowUp, CornerDownLeft, Search } from "lucide-react";
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { CommandMenu } from "@/components/command-menu/CommandMenu";
+
+const inputIconStyle: React.CSSProperties = {
+  width: "var(--prime-sys-size-control-m-icon)",
+  height: "var(--prime-sys-size-control-m-icon)",
+  color: "var(--prime-sys-color-content-muted)",
+  flexShrink: 0,
+};
+
+const footerRowStyle: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x3)",
+};
+
+const footerHintStyle: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: "var(--prime-sys-spacing-x2)",
+};
+
+const footerTextStyle: React.CSSProperties = {
+  fontSize: "var(--prime-sys-size-control-s-supportText)",
+  lineHeight: "var(--prime-sys-typography-body-lineHeight)",
+  color: "var(--prime-sys-color-content-secondary)",
+};
+
+/**
+ * App-wide command palette: routes and settings, keyboard legend in the footer.
+ */
+export default function CommandMenuExampleAppPalette() {
+  const [open, setOpen] = React.useState(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 size="m" variant="primary" onClick={() => setOpen(true)}>
+        Open palette (⌘K / Ctrl+K)
+      </Button.Root>
+
+      <CommandMenu.Dialog open={open} onOpenChange={setOpen} aria-labelledby="palette-title">
+        <CommandMenu.DialogTitle id="palette-title">Go to</CommandMenu.DialogTitle>
+        <CommandMenu.DialogDescription>
+          Type to filter pages and settings.
+        </CommandMenu.DialogDescription>
+
+        <CommandMenu.InputRow
+          leading={<Search style={inputIconStyle} strokeWidth={2} aria-hidden />}
+        >
+          <CommandMenu.Input placeholder="Where to…" aria-label="Search commands" />
+        </CommandMenu.InputRow>
+
+        <CommandMenu.List>
+          <CommandMenu.Group heading="Pages">
+            <CommandMenu.Item
+              value="dashboard"
+              keywords="home overview"
+              onSelect={() => setOpen(false)}
+            >
+              Dashboard
+            </CommandMenu.Item>
+            <CommandMenu.Item
+              value="reports"
+              keywords="analytics charts metrics"
+              onSelect={() => setOpen(false)}
+            >
+              Reports
+            </CommandMenu.Item>
+            <CommandMenu.Item
+              value="team"
+              keywords="people members"
+              onSelect={() => setOpen(false)}
+            >
+              Team
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group heading="Settings">
+            <CommandMenu.Item
+              value="account"
+              keywords="profile billing plan"
+              onSelect={() => setOpen(false)}
+            >
+              Account
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+
+        <CommandMenu.Footer>
+          <div style={footerRowStyle}>
+            <div style={footerHintStyle}>
+              <CommandMenu.FooterKeyBox>
+                <ArrowUp size={14} strokeWidth={2} aria-hidden />
+              </CommandMenu.FooterKeyBox>
+              <CommandMenu.FooterKeyBox>
+                <ArrowDown size={14} strokeWidth={2} aria-hidden />
+              </CommandMenu.FooterKeyBox>
+              <span style={footerTextStyle}>Navigate</span>
+            </div>
+            <div style={footerHintStyle}>
+              <CommandMenu.FooterKeyBox>
+                <CornerDownLeft size={14} strokeWidth={2} aria-hidden />
+              </CommandMenu.FooterKeyBox>
+              <span style={footerTextStyle}>Select</span>
+            </div>
+            <div style={footerHintStyle}>
+              <CommandMenu.FooterKeyBox tone="muted">Esc</CommandMenu.FooterKeyBox>
+              <span style={footerTextStyle}>Close</span>
+            </div>
+          </div>
+        </CommandMenu.Footer>
+      </CommandMenu.Dialog>
+    </>
+  );
+}

package/src/components/command-menu/examples/disabled-items.tsx

@@ -0,0 +1,73 @@
+import { Search } from "lucide-react";
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { CommandMenu } from "@/components/command-menu/CommandMenu";
+import { Typography } from "@/components/typography/Typography";
+
+const inputIconStyle: React.CSSProperties = {
+  width: "var(--prime-sys-size-control-m-icon)",
+  height: "var(--prime-sys-size-control-m-icon)",
+  color: "var(--prime-sys-color-content-muted)",
+  flexShrink: 0,
+};
+
+const footerStyle: React.CSSProperties = {
+  background: "var(--prime-sys-color-surface-default)",
+};
+
+/**
+ * Items with `disabled` are omitted from the filtered list and keyboard order (not shown as gray rows).
+ * Use conditional rendering instead if you need a visible “locked” row.
+ */
+export default function CommandMenuExampleDisabledItems() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root size="m" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Disabled items behavior
+      </Button.Root>
+
+      <CommandMenu.Dialog open={open} onOpenChange={setOpen} aria-labelledby="disabled-demo-title">
+        <CommandMenu.DialogTitle id="disabled-demo-title">Commands</CommandMenu.DialogTitle>
+        <CommandMenu.InputRow
+          leading={<Search style={inputIconStyle} strokeWidth={2} aria-hidden />}
+        >
+          <CommandMenu.Input placeholder="Try “delete”…" aria-label="Filter commands" />
+        </CommandMenu.InputRow>
+        <CommandMenu.List>
+          <CommandMenu.Group heading="Available">
+            <CommandMenu.Item value="save draft" keywords="write" onSelect={() => setOpen(false)}>
+              Save draft
+            </CommandMenu.Item>
+            <CommandMenu.Item
+              value="publish"
+              keywords="release ship"
+              onSelect={() => setOpen(false)}
+            >
+              Publish
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          {/* `disabled` items are excluded from visible options — this row never appears in the listbox */}
+          <CommandMenu.Group heading="Hidden when disabled">
+            <CommandMenu.Item
+              value="delete production database"
+              keywords="delete destroy danger"
+              disabled
+              onSelect={() => setOpen(false)}
+            >
+              Delete production (disabled in code)
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+        <CommandMenu.Footer style={footerStyle}>
+          <Typography.Root variant="body-compact" tone="muted">
+            Searching “delete” finds no option: the dangerous action is disabled and removed from
+            the palette, not listed as inactive.
+          </Typography.Root>
+        </CommandMenu.Footer>
+      </CommandMenu.Dialog>
+    </>
+  );
+}

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

@@ -0,0 +1,98 @@
+import { File, FileCode, Search } from "lucide-react";
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { CommandMenu } from "@/components/command-menu/CommandMenu";
+
+const inputIconStyle: React.CSSProperties = {
+  width: "var(--prime-sys-size-control-m-icon)",
+  height: "var(--prime-sys-size-control-m-icon)",
+  color: "var(--prime-sys-color-content-muted)",
+  flexShrink: 0,
+};
+
+type FileRow = { id: string; label: string; value: string; keywords: string };
+
+const FILES: FileRow[] = [
+  {
+    id: "1",
+    label: "README.md",
+    value: "readme",
+    keywords: "markdown docs root getting started",
+  },
+  {
+    id: "2",
+    label: "src/components/Button.tsx",
+    value: "button tsx",
+    keywords: "src components button react",
+  },
+  {
+    id: "3",
+    label: "playground/vite.config.ts",
+    value: "vite config",
+    keywords: "playground vite build",
+  },
+  {
+    id: "4",
+    label: "tokens/semantic.ts",
+    value: "semantic tokens",
+    keywords: "tokens theme design system",
+  },
+];
+
+/**
+ * File picker-style palette: match on file name, path segments, and extra keywords.
+ */
+export default function CommandMenuExampleFileSearch() {
+  const [open, setOpen] = React.useState(false);
+  const [activeId, setActiveId] = React.useState<string | null>(null);
+
+  return (
+    <>
+      <Button.Root size="m" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Search files
+      </Button.Root>
+
+      <CommandMenu.Dialog open={open} onOpenChange={setOpen} aria-labelledby="files-title">
+        <CommandMenu.DialogTitle id="files-title">Open file</CommandMenu.DialogTitle>
+        <CommandMenu.InputRow
+          leading={<Search style={inputIconStyle} strokeWidth={2} aria-hidden />}
+        >
+          <CommandMenu.Input placeholder="Filter by name or path…" aria-label="Filter files" />
+        </CommandMenu.InputRow>
+        <CommandMenu.List>
+          <CommandMenu.Group heading="Repository">
+            {FILES.map((f) => {
+              const Icon = f.label.endsWith(".tsx") || f.label.endsWith(".ts") ? FileCode : File;
+              return (
+                <CommandMenu.Item
+                  key={f.id}
+                  value={f.value}
+                  keywords={f.keywords}
+                  onSelect={() => {
+                    setActiveId(f.id);
+                    setOpen(false);
+                  }}
+                >
+                  <CommandMenu.ItemIcon as={Icon} strokeWidth={2} />
+                  {f.label}
+                </CommandMenu.Item>
+              );
+            })}
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Dialog>
+
+      {activeId ? (
+        <p
+          style={{
+            marginTop: "var(--prime-sys-spacing-x3)",
+            color: "var(--prime-sys-color-content-muted)",
+          }}
+        >
+          Last opened id: {activeId}
+        </p>
+      ) : null}
+    </>
+  );
+}

package/src/components/command-menu/examples/quick-actions.tsx

@@ -0,0 +1,74 @@
+import { Copy, Link2, Mail, Search, UserPlus } from "lucide-react";
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { CommandMenu } from "@/components/command-menu/CommandMenu";
+
+const inputIconStyle: React.CSSProperties = {
+  width: "var(--prime-sys-size-control-m-icon)",
+  height: "var(--prime-sys-size-control-m-icon)",
+  color: "var(--prime-sys-color-content-muted)",
+  flexShrink: 0,
+};
+
+/**
+ * Quick actions on the current context: copy, share, invite — grouped under one palette.
+ */
+export default function CommandMenuExampleQuickActions() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root size="m" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Quick actions
+      </Button.Root>
+
+      <CommandMenu.Dialog open={open} onOpenChange={setOpen} aria-labelledby="actions-title">
+        <CommandMenu.DialogTitle id="actions-title">Actions</CommandMenu.DialogTitle>
+        <CommandMenu.InputRow
+          leading={<Search style={inputIconStyle} strokeWidth={2} aria-hidden />}
+        >
+          <CommandMenu.Input placeholder="Run an action…" aria-label="Filter actions" />
+        </CommandMenu.InputRow>
+        <CommandMenu.List>
+          <CommandMenu.Group heading="Clipboard">
+            <CommandMenu.Item
+              value="copy link"
+              keywords="url clipboard"
+              onSelect={() => setOpen(false)}
+            >
+              <CommandMenu.ItemIcon as={Link2} strokeWidth={2} />
+              Copy link
+            </CommandMenu.Item>
+            <CommandMenu.Item
+              value="copy page as markdown"
+              keywords="clipboard md export"
+              onSelect={() => setOpen(false)}
+            >
+              <CommandMenu.ItemIcon as={Copy} strokeWidth={2} />
+              Copy page as Markdown
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group heading="People">
+            <CommandMenu.Item
+              value="invite teammate"
+              keywords="email share member"
+              onSelect={() => setOpen(false)}
+            >
+              <CommandMenu.ItemIcon as={UserPlus} strokeWidth={2} />
+              Invite teammate
+            </CommandMenu.Item>
+            <CommandMenu.Item
+              value="message owner"
+              keywords="dm mail contact"
+              onSelect={() => setOpen(false)}
+            >
+              <CommandMenu.ItemIcon as={Mail} strokeWidth={2} />
+              Message owner
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Dialog>
+    </>
+  );
+}

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

@@ -0,0 +1,114 @@
+# DataTable
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+`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).
+
+- **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.
+
+## 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.
+- **Reference examples** — longer patterns (full column set, controlled sort/page, row selection with `Checkbox`, infinite `onLoadMore`, sticky header and first column) live under [`examples/`](./examples/) as copy-ready `tsx` modules that import from `"prime-ui-kit"`.
+
+### Minimal example
+
+```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} />;
+}
+```
+
+## 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.
+
+## 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`.
+
+## Related
+
+- [Pagination](../pagination/COMPONENT.md) — used under the table for page navigation.
+- [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.

package/src/components/data-table/examples/canonical-orders.tsx

@@ -0,0 +1,107 @@
+import { Badge, DataTable, type DataTableColumn, Tag } from "prime-ui-kit";
+import * as React from "react";
+
+type OrderRow = {
+  id: string;
+  customer: string;
+  amount: number;
+  region: string;
+  status: "Оплачен" | "В работе" | "Просрочен";
+};
+
+const rows: OrderRow[] = [
+  { id: "ORD-104", customer: "ООО «Север»", amount: 128_400, region: "СЗФО", status: "Оплачен" },
+  { id: "ORD-105", customer: "ИП Ким", amount: 42_100, region: "ДВФО", status: "В работе" },
+  { id: "ORD-106", customer: "АО «Транзит»", amount: 901_000, region: "ЦФО", status: "Оплачен" },
+  { id: "ORD-107", customer: "ООО «Логистик»", amount: 15_750, region: "ЮФО", status: "Просрочен" },
+  {
+    id: "ORD-108",
+    customer: "Самозанятый Орлов",
+    amount: 6_200,
+    region: "ПФО",
+    status: "В работе",
+  },
+  { id: "ORD-109", customer: "ООО «Полюс»", amount: 333_000, region: "УФО", status: "Оплачен" },
+  { id: "ORD-110", customer: "КФХ «Рядок»", amount: 88_500, region: "ЮФО", status: "В работе" },
+  { id: "ORD-111", customer: "АНО «Школа»", amount: 12_000, region: "СКФО", status: "Просрочен" },
+];
+
+function statusColor(status: OrderRow["status"]) {
+  if (status === "Оплачен") return "green";
+  if (status === "Просрочен") return "red";
+  return "yellow";
+}
+
+const columns: DataTableColumn<OrderRow>[] = [
+  {
+    id: "id",
+    header: "Заказ",
+    accessor: "id",
+    sortable: true,
+    minWidth: "8.5rem",
+  },
+  {
+    id: "customer",
+    header: "Клиент",
+    accessor: "customer",
+    sortable: true,
+    minWidth: "12rem",
+  },
+  {
+    id: "amount",
+    header: "Сумма, ₽",
+    accessor: "amount",
+    sortable: true,
+    align: "end",
+    minWidth: "9rem",
+    cell: (row) => row.amount.toLocaleString("ru-RU"),
+  },
+  {
+    id: "region",
+    header: "Округ",
+    accessor: "region",
+    sortable: true,
+    minWidth: "6rem",
+    cell: (row) => <Tag.Root>{row.region}</Tag.Root>,
+  },
+  {
+    id: "status",
+    header: "Статус",
+    accessor: "status",
+    sortable: true,
+    minWidth: "9rem",
+    cell: (row) => (
+      <Badge.Root color={statusColor(row.status)} variant="light">
+        {row.status}
+      </Badge.Root>
+    ),
+  },
+];
+
+/**
+ * Полноценная таблица: сортировка по умолчанию, пагинация (`pageSize` меньше числа строк),
+ * стабильные ключи строк и типичное оформление ячеек через `Tag` / `Badge`.
+ */
+export default function DataTableCanonicalOrdersExample() {
+  const [lastOpened, setLastOpened] = React.useState<string | null>(null);
+
+  return (
+    <div>
+      {lastOpened ? (
+        <p style={{ marginBottom: "0.75rem" }}>Открыт заказ: {lastOpened}</p>
+      ) : (
+        <p style={{ marginBottom: "0.75rem" }}>
+          Клик по строке выбирает заказ для сценария «открыть».
+        </p>
+      )}
+      <DataTable.Root
+        columns={columns}
+        rows={rows}
+        getRowKey={(row) => row.id}
+        defaultSort={{ columnId: "amount", order: "desc" }}
+        pageSize={4}
+        onRowClick={(row) => setLastOpened(row.id)}
+      />
+    </div>
+  );
+}

package/src/components/data-table/examples/controlled-sort-and-page.tsx

@@ -0,0 +1,66 @@
+import { DataTable, type DataTableColumn, type DataTableSortState } from "prime-ui-kit";
+import * as React from "react";
+
+type TaskRow = {
+  id: string;
+  title: string;
+  assignee: string;
+  priority: number;
+};
+
+const rows: TaskRow[] = [
+  { id: "T-01", title: "Сверстать отчёт", assignee: "Аня", priority: 2 },
+  { id: "T-02", title: "Починить билд", assignee: "Борис", priority: 1 },
+  { id: "T-03", title: "Обновить зависимости", assignee: "Вика", priority: 3 },
+  { id: "T-04", title: "Ревью API", assignee: "Гриша", priority: 2 },
+  { id: "T-05", title: "Документация полей", assignee: "Даша", priority: 4 },
+  { id: "T-06", title: "E2E флейки", assignee: "Егор", priority: 1 },
+];
+
+const columns: DataTableColumn<TaskRow>[] = [
+  { id: "id", header: "ID", accessor: "id", sortable: true, minWidth: "5rem" },
+  { id: "title", header: "Задача", accessor: "title", sortable: true, minWidth: "14rem" },
+  {
+    id: "assignee",
+    header: "Исполнитель",
+    accessor: "assignee",
+    sortable: true,
+    minWidth: "10rem",
+  },
+  {
+    id: "priority",
+    header: "Приоритет",
+    accessor: "priority",
+    sortable: true,
+    align: "end",
+    minWidth: "8rem",
+  },
+];
+
+/**
+ * Управляемые `sort` и `page`: родитель синхронизирует состояние с URL, стором или формой фильтров.
+ */
+export default function DataTableControlledSortAndPageExample() {
+  const [sort, setSort] = React.useState<DataTableSortState>({
+    columnId: "priority",
+    order: "asc",
+  });
+  const [page, setPage] = React.useState(1);
+
+  return (
+    <DataTable.Root
+      columns={columns}
+      rows={rows}
+      getRowKey={(row) => row.id}
+      sort={sort}
+      onSortChange={(next) => {
+        setSort(next);
+        setPage(1);
+      }}
+      page={page}
+      onPageChange={setPage}
+      pageSize={3}
+      siblingCount={1}
+    />
+  );
+}