prime-ui-kit 0.11.1 → 0.13.0

package/dist/skill/reference/components/kanban/examples/item-link.tsx

@@ -0,0 +1,92 @@
+/** Tickets that open: each card is a link to its page, so ⌘-click or a middle click opens a new tab, a plain click, Enter or Space opens it in place, and a drag only moves it — `getItemHref`, `onItemClick`. */
+import { Badge, Kanban, type KanbanValue, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Ticket = {
+  id: string;
+  title: string;
+  client: string;
+  priority: { text: string; color: "red" | "orange" | "gray" };
+};
+
+const COLUMNS = [
+  { id: "new", title: "Новые" },
+  { id: "progress", title: "В работе" },
+  { id: "waiting", title: "Ждут клиента" },
+];
+
+const TICKETS: Ticket[] = [
+  {
+    id: "SUP-482",
+    title: "Не выгружаются счета в 1С",
+    client: "ООО «Север»",
+    priority: { text: "Высокий", color: "red" },
+  },
+  {
+    id: "SUP-479",
+    title: "Сбросить пароль менеджеру склада",
+    client: "АО «Гранит»",
+    priority: { text: "Обычный", color: "gray" },
+  },
+  {
+    id: "SUP-475",
+    title: "Дубли заказов после импорта",
+    client: "ООО «Вектор»",
+    priority: { text: "Средний", color: "orange" },
+  },
+  {
+    id: "SUP-470",
+    title: "Акт сверки за третий квартал",
+    client: "ИП Лебедев",
+    priority: { text: "Обычный", color: "gray" },
+  },
+];
+
+const PLACEMENT: KanbanValue = {
+  new: ["SUP-482", "SUP-479"],
+  progress: ["SUP-475"],
+  waiting: ["SUP-470"],
+};
+
+export default function KanbanItemLinkExample() {
+  const [opened, setOpened] = React.useState<Ticket | null>(null);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.toolbar}>
+        <Typography as="span" variant="body-s" tone="muted" aria-live="polite">
+          {opened
+            ? `Открыт ${opened.id} · ${opened.client}`
+            : "Откройте обращение кликом или Enter"}
+        </Typography>
+      </div>
+      <Kanban.Root
+        aria-label="Обращения в поддержку"
+        className={styles.board}
+        columns={COLUMNS}
+        items={TICKETS}
+        getId={(ticket) => ticket.id}
+        getLabel={(ticket) => `${ticket.id}: ${ticket.title}`}
+        defaultValue={PLACEMENT}
+        getItemHref={(ticket) => `/support/${ticket.id}`}
+        onItemClick={(ticket, event) => {
+          // A client-side router goes here (navigate(href)); the page itself never reloads.
+          event.preventDefault();
+          setOpened(ticket);
+        }}
+        renderItem={(ticket) => (
+          <Kanban.Item>
+            <Kanban.ItemHeader>
+              <span>{ticket.id}</span>
+              <Badge.Root color={ticket.priority.color}>{ticket.priority.text}</Badge.Root>
+            </Kanban.ItemHeader>
+            <Kanban.ItemTitle>{ticket.title}</Kanban.ItemTitle>
+            <Kanban.ItemDescription>{ticket.client}</Kanban.ItemDescription>
+          </Kanban.Item>
+        )}
+      />
+    </div>
+  );
+}

package/dist/skill/reference/components/list/COMPONENT.md

@@ -0,0 +1,195 @@
+# List
+
+**Category:** navigation
+**Kind:** navigation
+
+> A selectable navigation list of rows: the master half of a list + detail screen (conversations, tickets, mail, records).
+
+## When to use
+- The list side of a list + detail screen (`PageContent.Split` → `PageContent.List`): dialogs, tickets, letters, invoices worked through one by one; the open one is `current`.
+- A short column of records that each open something — a page (`href`, `asChild` with a router link) or a detail pane (`onClick`).
+- A short list the team puts in order (funnel stages, queues, priorities) — `onReorder`, a `value` per item.
+
+## When not to use
+- App sections → use [Sidebar](../../layout/sidebar/COMPONENT.md) (wide) and [BottomNav](../../layout/bottom-nav/COMPONENT.md) (phone).
+- Panels of one screen → use [Tabs](../tabs/COMPONENT.md).
+- Many records compared by columns, sorted, filtered or selected in bulk → use [DataTable](../data-table/COMPONENT.md).
+- A static list of facts inside a card (no selection, nothing opens) → use `Card.List` of [Card](../card/COMPONENT.md) `variant="list"`.
+- Picking a value from options → use [Select](../select/COMPONENT.md) or [Radio](../radio/COMPONENT.md); a menu of commands → [Dropdown](../dropdown/COMPONENT.md).
+
+## Import
+```tsx
+import { List } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+List.Root                   <ul aria-label>; size → row tier (ControlSizeProvider); onReorder → Dnd.Sortable <ul>
+└─ List.Item                <li> with a full-width <button> | <a href> | asChild element; current, disabled
+   │                         value; with onReorder: Dnd.Handle (or a Spinner while saving) before the row element
+   ├─ List.ItemIcon         leading Avatar.Root / Icon (aria-hidden); after the text — a trailing glyph
+   ├─ List.ItemText         primary line, truncates
+   ├─ List.ItemDescription  second line, muted, truncates
+   ├─ List.ItemMeta         trailing small text (time, date, amount)
+   └─ List.ItemCount        trailing Badge, one tier down
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### List.Root
+`ref` → `HTMLUListElement`. `<ul>` of selectable rows: the master half of a list + detail screen; sets the row tier for its items and their parts.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Row tier: height, text, icon and avatar size; counts take one tier down. |
+| `onReorder` | `(id: string, beforeId: string \| null) => void \| Promise<void>` | — | Rows reorder by a leading handle (drag, touch hold, Alt + ↑ / ↓): item `value` `id` goes before `beforeId` (`null` = last). Apply with `moveBefore`; a returned promise keeps the row busy, a rejection moves it back. |
+| `labels` | `Partial<ListLabels>` | — | Built-in strings, see Labels. |
+| `aria-label` | `string` | — | Name of the list for screen readers («Диалоги»), when no visible heading names it. |
+| `children` | `ReactNode` | — | `List.Item`s. |
+| `…rest` | `HTMLAttributes<HTMLUListElement>` | — | `className` and the other `ul` attributes. |
+
+### List.Item
+`ref` → `HTMLElement` (the `<button>`, `<a>` or `asChild` element, not the `<li>`). `<li>` holding a full-width row: a button, a link (`href`) or your router link (`asChild`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Stable id of the row; required in a reorderable list (`onReorder` reports it). |
+| `current` | `boolean` | `false` | The open record: the selected fill and `aria-current` — `"true"` on a button, `"page"` on a link. |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | Opens the record; not called while `disabled`. |
+| `href` | `string` | — | Renders an `<a>` instead of a `<button>`; dropped while `disabled`. |
+| `asChild` | `boolean` | `false` | Renders the single child (a router link) as the row; its children are the content. |
+| `disabled` | `boolean` | `false` | Muted and out of the Tab order: a disabled button, or `aria-disabled` and no navigation on a link. |
+| `children` | `ReactNode` | — | `List.ItemIcon`, `List.ItemText`, `List.ItemDescription`, `List.ItemMeta`, `List.ItemCount`; loose text becomes the text line. |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and native attributes of the row element (`target`, `rel` on a link). |
+
+### List.ItemIcon
+`ref` → `HTMLSpanElement`. Leading `aria-hidden` slot: an `Avatar.Root` sized to the tier, or an `Icon`. After the text it is a trailing glyph.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | An `Avatar.Root` or an `Icon`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other `span` attributes. |
+
+### List.ItemText
+`ref` → `HTMLSpanElement`. The primary line: medium weight, one line, truncated with an ellipsis.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className`, `title` (full text when truncated) and the other `span` attributes. |
+
+### List.ItemDescription
+`ref` → `HTMLSpanElement`. The second line (a preview, a status): muted, smaller, truncated.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other `span` attributes. |
+
+### List.ItemMeta
+`ref` → `HTMLSpanElement`. Small muted text at the end of the row (a time, a date, an amount); on top beside two lines.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other `span` attributes. |
+
+### List.ItemCount
+`ref` → `HTMLSpanElement` (the Badge). A soft `Badge` one tier below the rows at the end of the row; below the meta beside two lines.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Badge hue; a hue for what needs attention (unread). |
+| `children` | `ReactNode` | — (required) | The number or a short status. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | — | `className` and the other `span` attributes. |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 one-line row, 12 text, caption description, 20 avatar | dense side panels | |
+| `s` | 32 row, 13 text, caption description, 24 avatar | compact panes | |
+| `m` | 36 row, 14 text, body-s description, 32 avatar | default | yes |
+| `l` | 40 row, 16 text, 40 avatar | roomy panes, touch-first screens | |
+| `xl` | 48 row, 16 text, 48 avatar | hero lists | |
+
+A second line or an avatar makes a row taller than the one-line height; the vertical padding stays the tier's.
+
+### Item kind
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| button | the row opens a record in place (`onClick`) | a detail pane on the same screen | yes |
+| link (`href`) | the same row as an `<a>` | each record has its own URL | |
+| router link (`asChild`) | the same row as your `<Link>` | client routing | |
+
+### List.ItemCount color
+`gray` (default) for a plain number; a hue for what needs attention (`blue` for unread). Any palette hue.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| rest | — | transparent row, secondary text |
+| hover | pointer (`@media (hover: hover)`) | `fill-subtle` wash, primary text |
+| pressed | `:active` | `fill-subtle-active` |
+| current | `current` | `aria-current="true"` (button) or `"page"` (link); `fill-muted-hover` fill, primary text |
+| focus-visible | keyboard | the focus ring inside the row edge |
+| disabled | `disabled` | `disabled` on a button; `aria-disabled="true"`, no `href` on a link, `tabindex="-1"` on an `asChild` element; `data-disabled="true"`; disabled text; in a reorderable list the handle is disabled and the row holds its place |
+| reorderable | `onReorder` | `data-reorderable="true"` on the root (a `Dnd.Sortable` `<ul>`); each `<li>` is a sortable item (`data-dnd-item` = `value`) with a leading `Dnd.Handle`; drag by the handle (a touch hold on touch), Alt + ↑ / ↓ from the handle or the row; a lifted row leaves a dashed gap, its neighbours glide, the copy follows the pointer and sets down in its new place |
+| saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy="true"`, a `Spinner` stands in for the handle, the row content dims to 0.6 (`--prime-motion-duration-fast` both ways); a rejection glides the row back |
+
+Root attribute: `data-size`. The fill changes on `background-color` with `--prime-motion-duration-xfast` both ways (0 under reduced motion).
+
+## Layout & spacing
+- The root fills its container (`width: 100%`); rows are 4px apart, each row a full-width button with the tier radius and field padding.
+- Put the list on a surface: a `Card.Root` pane in `PageContent.List`, with a `ScrollContainer` around it when it is long — the list never scrolls by itself.
+- Row: leading icon · body (text over description) · trail. Beside two lines the trail stacks — meta on top, count below; beside one line they sit in a row.
+- Text and description truncate with an ellipsis; give a long `List.ItemText` a `title` with the full text.
+- On a coarse pointer a row is at least the touch target (44px).
+- Reorderable (`onReorder`): an `xs` handle box sits before each row, 4px from it; the row keeps its own padding and fill.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus between rows; a disabled row is skipped. |
+| `Enter` · `Space` | Opens the record; a link row takes Enter only. |
+| `Alt + ↑` · `Alt + ↓` | With `onReorder`, moves the row one place up or down (from its handle or the row). |
+
+### ARIA
+- `<ul>` named by `aria-label` (or `aria-labelledby` to a visible heading); each row is an `<li>` with a button or link.
+- The open record: `aria-current="true"` on a button (a selection inside the screen), `aria-current="page"` on a link (`href`, `asChild`) — the link points at the current URL. A router link may set it itself.
+- The row's name is its text, description, meta and count, in that order; the leading icon or avatar is `aria-hidden` — the text names the row.
+- Arrow keys do not move between rows: rows are ordinary Tab stops, as in the Sidebar.
+- With `onReorder` each row gets a handle named «Переместить {label}» (`labels.reorderItem`, `{label}` is the row's text line) and `aria-keyshortcuts`; the new place is announced politely («Новый лид: позиция 2 из 5»), a row being saved is `aria-busy`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `reorderItem` | `"Переместить {label}"` | `aria-label` of a row's drag handle (`onReorder`); `{label}` is the row's text line. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Support dialogs with a preview, the time and the unread count; a click opens a dialog and makes it the current row — `current`, `onClick`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: row height, text, icon and count follow the tier — `size`. |
+| [states.tsx](examples/states.tsx) | The open record, a regular row and an unavailable one — `current`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | Leading avatars of clients and icons of queues; the slot sizes the avatar to the row tier — `List.ItemIcon`. |
+| [overflow.tsx](examples/overflow.tsx) | A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate. |
+| [as-link.tsx](examples/as-link.tsx) | Rows as links to the invoice pages: a plain link, or your router link through the slot — `href`, `asChild`. |
+| [reorder.tsx](examples/reorder.tsx) | Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server — `onReorder`, `value`. |
+
+## Mistakes
+- Rows hand-drawn from `Button.Root variant="ghost"` with a `soft` current → `List.Item current`.
+- An `Avatar.Root size="s"` in `List.ItemIcon` to fit the row → leave `size` out; the slot sizes the avatar to the tier.
+- A list as app navigation → Sidebar; as tabs of a screen → Tabs.
+- Several rows `current` at once → one open record; bulk selection belongs to DataTable.
+- A long list without a scroller → wrap it in `ScrollContainer` inside the pane.
+- Up / down buttons on rows or a hand-made `Dnd.Sortable` of rows to order them → `List.Root onReorder` with a `value` on every item.
+- `onReorder` that rolls the order back itself on an error → return the promise; a rejection moves the row back.
+
+## Related
+- **Built from:** [Badge](../badge/COMPONENT.md) (`List.ItemCount`), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable`, `Dnd.Handle`), [Spinner](../spinner/COMPONENT.md) (a move being saved)
+- **See also:** [PageContent](../page-content/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Tabs](../tabs/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md), [Avatar](../avatar/COMPONENT.md)

package/dist/skill/reference/components/list/examples/as-link.tsx

@@ -0,0 +1,37 @@
+/** Rows as links to the invoice pages: a plain link, or your router link through the slot — `href`, `asChild`. */
+import { Card, List } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const INVOICES = [
+  { id: "4830", client: "ООО «Гранит»", amount: "184 200 ₽", status: "Оплачен" },
+  { id: "4829", client: "ООО «Лето»", amount: "56 900 ₽", status: "Ждёт оплаты" },
+  { id: "4828", client: "ИП Козлов", amount: "12 400 ₽", status: "Просрочен" },
+];
+
+export default function ListAsLinkExample() {
+  return (
+    <Card.Root className={styles.pane}>
+      <Card.Body>
+        <List.Root aria-label="Счета">
+          {INVOICES.map((invoice, index) => (
+            <List.Item key={invoice.id} href={`#invoice-${invoice.id}`} current={index === 0}>
+              <List.ItemText>Счёт № {invoice.id}</List.ItemText>
+              <List.ItemDescription>
+                {invoice.client} · {invoice.status}
+              </List.ItemDescription>
+              <List.ItemMeta>{invoice.amount}</List.ItemMeta>
+            </List.Item>
+          ))}
+          {/* A router link (`<Link to>`) goes in the same way; the row keeps its `href`. */}
+          <List.Item asChild>
+            <a href="#invoices-archive">
+              <List.ItemText>Архив счетов</List.ItemText>
+              <List.ItemDescription>Все счета за 2025 год</List.ItemDescription>
+            </a>
+          </List.Item>
+        </List.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/list/examples/examples.module.css

@@ -0,0 +1,18 @@
+/* Layout of the List scenarios: the list stands in a pane as wide as the master side of a split. */
+
+.pane {
+  width: min(100%, calc(var(--prime-space-24) * 4));
+}
+
+/* overflow: a pane of a fixed height whose list scrolls. */
+.scroll {
+  height: calc(var(--prime-space-24) * 3);
+}
+
+/* sizes: a caption above each tier's list. */
+.tier {
+  display: flex;
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  flex-direction: column;
+  gap: var(--prime-space-2);
+}

package/dist/skill/reference/components/list/examples/overflow.tsx

@@ -0,0 +1,46 @@
+/** A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate. */
+import { Card, List, ScrollContainer } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TICKETS = [
+  { id: "1207", subject: "Возврат оплаты по счёту № 4821 за сентябрь", client: "ООО «Гранит»" },
+  { id: "1206", subject: "Смена тарифа", client: "ООО «Лето»" },
+  { id: "1205", subject: "Подключение ЭДО через Диадок", client: "ИП Козлов" },
+  {
+    id: "1204",
+    subject: "Акт сверки",
+    client: "АО «Северо-Западная транспортная компания»",
+  },
+  { id: "1203", subject: "Доступ к API для интеграции со складом", client: "ООО «Логистик Про»" },
+  { id: "1202", subject: "Перенос поставки", client: "ООО «Альфа-Трейд»" },
+  { id: "1201", subject: "Новый пользователь в команде", client: "ООО «Вектор»" },
+  { id: "1200", subject: "Ошибка в реквизитах", client: "ИП Смирнова" },
+];
+
+export default function ListOverflowExample() {
+  const [ticketId, setTicketId] = React.useState("1207");
+
+  return (
+    <Card.Root className={styles.pane}>
+      <ScrollContainer className={styles.scroll}>
+        <Card.Body>
+          <List.Root aria-label="Обращения">
+            {TICKETS.map((ticket) => (
+              <List.Item
+                key={ticket.id}
+                current={ticket.id === ticketId}
+                onClick={() => setTicketId(ticket.id)}
+              >
+                <List.ItemText>{ticket.subject}</List.ItemText>
+                <List.ItemDescription>{ticket.client}</List.ItemDescription>
+                <List.ItemMeta>№ {ticket.id}</List.ItemMeta>
+              </List.Item>
+            ))}
+          </List.Root>
+        </Card.Body>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/list/examples/overview.tsx

@@ -0,0 +1,63 @@
+/** Support dialogs with a preview, the time and the unread count; a click opens a dialog and makes it the current row — `current`, `onClick`. */
+import { Card, List } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const DIALOGS = [
+  {
+    id: "granit",
+    client: "ООО «Гранит»",
+    preview: "Счёт № 4821 пришёл без НДС",
+    time: "15:02",
+    unread: 2,
+  },
+  {
+    id: "leto",
+    client: "ООО «Лето»",
+    preview: "Можно перенести доставку на среду?",
+    time: "13:40",
+    unread: 0,
+  },
+  {
+    id: "kozlov",
+    client: "ИП Козлов",
+    preview: "Подключите, пожалуйста, ЭДО",
+    time: "вчера",
+    unread: 1,
+  },
+  {
+    id: "sever",
+    client: "АО «Северсталь-Сервис»",
+    preview: "Акт сверки за сентябрь подписан",
+    time: "6 окт",
+    unread: 0,
+  },
+];
+
+export default function ListOverviewExample() {
+  const [dialogId, setDialogId] = React.useState("granit");
+
+  return (
+    <Card.Root className={styles.pane}>
+      <Card.Body>
+        <List.Root aria-label="Диалоги">
+          {DIALOGS.map((dialog) => (
+            <List.Item
+              key={dialog.id}
+              current={dialog.id === dialogId}
+              onClick={() => setDialogId(dialog.id)}
+            >
+              <List.ItemText>{dialog.client}</List.ItemText>
+              <List.ItemDescription>{dialog.preview}</List.ItemDescription>
+              <List.ItemMeta>{dialog.time}</List.ItemMeta>
+              {dialog.unread > 0 ? (
+                <List.ItemCount color="blue">{dialog.unread}</List.ItemCount>
+              ) : null}
+            </List.Item>
+          ))}
+        </List.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/list/examples/reorder.tsx

@@ -0,0 +1,48 @@
+/** Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server — `onReorder`, `value`. */
+import { Card, List, moveBefore } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const STAGES = [
+  { id: "lead", name: "Новый лид", description: "Заявка с сайта или от партнёра", deals: 42 },
+  { id: "qualified", name: "Квалификация", description: "Бюджет и сроки подтверждены", deals: 18 },
+  { id: "proposal", name: "Коммерческое предложение", description: "КП отправлено", deals: 11 },
+  { id: "contract", name: "Договор", description: "Согласование с юристами", deals: 6 },
+  { id: "won", name: "Оплата", description: "Счёт выставлен", deals: 3 },
+];
+
+const SAVE_DELAY_MS = 600;
+
+/** A stand-in for the request that stores the new order. */
+function saveOrder(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, SAVE_DELAY_MS);
+  });
+}
+
+export default function ListReorderExample() {
+  const [stages, setStages] = React.useState(STAGES);
+
+  return (
+    <Card.Root className={styles.pane}>
+      <Card.Body>
+        <List.Root
+          aria-label="Этапы воронки"
+          onReorder={async (id, beforeId) => {
+            await saveOrder();
+            setStages((current) => moveBefore(current, id, beforeId, (stage) => stage.id));
+          }}
+        >
+          {stages.map((stage) => (
+            <List.Item key={stage.id} value={stage.id}>
+              <List.ItemText>{stage.name}</List.ItemText>
+              <List.ItemDescription>{stage.description}</List.ItemDescription>
+              <List.ItemCount>{stage.deals}</List.ItemCount>
+            </List.Item>
+          ))}
+        </List.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/list/examples/sizes.tsx

@@ -0,0 +1,35 @@
+/** Every size tier: row height, text, icon and count follow the tier — `size`. */
+import { Icon, List, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ListSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.tier}>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+          <List.Root size={size} aria-label={`Очереди, ${size}`}>
+            <List.Item current>
+              <List.ItemIcon>
+                <Icon name="object.inbox" />
+              </List.ItemIcon>
+              <List.ItemText>Входящие</List.ItemText>
+              <List.ItemCount color="blue">12</List.ItemCount>
+            </List.Item>
+            <List.Item>
+              <List.ItemIcon>
+                <Icon name="status.sent" />
+              </List.ItemIcon>
+              <List.ItemText>Отправленные</List.ItemText>
+            </List.Item>
+          </List.Root>
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/list/examples/states.tsx

@@ -0,0 +1,27 @@
+/** The open record, a regular row and an unavailable one — `current`, `disabled`. */
+import { Card, List } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ListStatesExample() {
+  return (
+    <Card.Root className={styles.pane}>
+      <Card.Body>
+        <List.Root aria-label="Заявки">
+          <List.Item current>
+            <List.ItemText>Заявка № 1207 · Возврат оплаты</List.ItemText>
+            <List.ItemDescription>Открыта сейчас</List.ItemDescription>
+          </List.Item>
+          <List.Item>
+            <List.ItemText>Заявка № 1206 · Смена тарифа</List.ItemText>
+            <List.ItemDescription>Ждёт ответа клиента</List.ItemDescription>
+          </List.Item>
+          <List.Item disabled>
+            <List.ItemText>Заявка № 1198 · Доступ к API</List.ItemText>
+            <List.ItemDescription>В архиве, недоступна</List.ItemDescription>
+          </List.Item>
+        </List.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/list/examples/with-icon.tsx

@@ -0,0 +1,60 @@
+/** Leading avatars of clients and icons of queues; the slot sizes the avatar to the row tier — `List.ItemIcon`. */
+import { Avatar, Card, Icon, List } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const CLIENTS = [
+  { id: "belova", name: "Ирина Белова", company: "ООО «Гранит»", initials: "ИБ", color: "blue" },
+  { id: "orlov", name: "Павел Орлов", company: "ООО «Лето»", initials: "ПО", color: "green" },
+  { id: "kozlov", name: "Сергей Козлов", company: "ИП Козлов", initials: "СК", color: "orange" },
+] as const;
+
+export default function ListWithIconExample() {
+  return (
+    <>
+      <Card.Root className={styles.pane}>
+        <Card.Body>
+          <List.Root aria-label="Клиенты">
+            {CLIENTS.map((client, index) => (
+              <List.Item key={client.id} current={index === 0}>
+                <List.ItemIcon>
+                  <Avatar.Root color={client.color}>
+                    <Avatar.Fallback>{client.initials}</Avatar.Fallback>
+                  </Avatar.Root>
+                </List.ItemIcon>
+                <List.ItemText>{client.name}</List.ItemText>
+                <List.ItemDescription>{client.company}</List.ItemDescription>
+              </List.Item>
+            ))}
+          </List.Root>
+        </Card.Body>
+      </Card.Root>
+      <Card.Root className={styles.pane}>
+        <Card.Body>
+          <List.Root aria-label="Очереди">
+            <List.Item current>
+              <List.ItemIcon>
+                <Icon name="object.headset" />
+              </List.ItemIcon>
+              <List.ItemText>Поддержка</List.ItemText>
+              <List.ItemCount color="blue">8</List.ItemCount>
+            </List.Item>
+            <List.Item>
+              <List.ItemIcon>
+                <Icon name="object.receipt" />
+              </List.ItemIcon>
+              <List.ItemText>Биллинг</List.ItemText>
+              <List.ItemCount>3</List.ItemCount>
+            </List.Item>
+            <List.Item>
+              <List.ItemIcon>
+                <Icon name="object.truck" />
+              </List.ItemIcon>
+              <List.ItemText>Доставка</List.ItemText>
+            </List.Item>
+          </List.Root>
+        </Card.Body>
+      </Card.Root>
+    </>
+  );
+}