prime-ui-kit 0.11.1 → 0.13.0

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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>
+    </>
+  );
+}

package/src/components/message/COMPONENT.md

@@ -41,12 +41,14 @@ Message.Root                      role="article" row «{author}, {time}» (an op
 │  │                              (under a picture or a circle), the meta's spacer at its end
 │  └─ meta                        «изменено» · time · ticks, in the bottom-end corner (a dark pill
 │                                 over a picture or a circle)
+├─ Message.Actions                a row of a bot's inline keyboard under the bubble (Button.Root children);
+│                                 several make several rows
 ├─ Message.Menu                   Dropdown.Content opened at the pointer (+ «Выбрать» in a chat with a selection)
 └─ [reaction bar]                 floating toolbar above the bubble: long press, long hover, `R`
 
 Message.Typing                    «печатает…»: an incoming bubble of three dots, the last row of a list
 ```
-The part that ends a bubble closes its last line with the meta's spacer — an invisible copy of the meta that floats to the line's end — so the time sits on that line when it fits and on a line of its own when it does not; a picture or a circle carries the meta on a dark pill (`internal/mediaPill`). Every content part declares its kind once (`defineMessagePart` in `internal/messagePart`: its shell, how the meta stands with it, whether it is a picture, reaches the edges or sets the width, its off-screen estimate and the text a chat's search looks in), so the message decides the shell, the tail and the meta from what it holds, fragments opened and empty children ignored. Parts render in the order you write them, except three that the message places itself: `Message.Author` heads the bubble (on a pill over a picture or a circle), `Message.Avatar` goes to the gutter, `Message.Menu` to the menu. Nothing in a message is measured in JS but the hug of a bubble of text (see Layout) and the before / after boxes of a size change (`bubbleMorph`). The reaction bar is mounted only from its open to the end of its exit, one on the page at a time; the menu mounts on its first open.
+The part that ends a bubble closes its last line with the meta's spacer — an invisible copy of the meta that floats to the line's end — so the time sits on that line when it fits and on a line of its own when it does not; a picture or a circle carries the meta on a dark pill (`internal/mediaPill`). Every content part declares its kind once (`defineMessagePart` in `internal/messagePart`: its shell, how the meta stands with it, whether it is a picture, reaches the edges or sets the width, its off-screen estimate and the text a chat's search looks in), so the message decides the shell, the tail and the meta from what it holds, fragments opened and empty children ignored. Parts render in the order you write them, except four that the message places itself: `Message.Author` heads the bubble (on a pill over a picture or a circle), `Message.Avatar` goes to the gutter, `Message.Menu` to the menu, and `Message.Actions` rows go under the bubble (and its reactions), in their own order. Nothing in a message is measured in JS but the hug of a bubble of text (see Layout) and the before / after boxes of a size change (`bubbleMorph`). The reaction bar is mounted only from its open to the end of its exit, one on the page at a time; the menu mounts on its first open.
 
 In a list (`Chat.Messages`) a message reads the list through `internal/messageList`: its place in a run (`position`) and the chat's kind decide the author's header (first of a run in a group chat) and the avatar (last of a run); the list registers it for new-message entry and read receipts, selects it, jumps to it and holds its size changes still. On its own a message given an author or an avatar does the same by its `position`: the header on `single` / `first`, the avatar (and the gutter) on `single` / `last`.
 
@@ -211,6 +213,13 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `labels` | `Partial<MessageReactionsLabels>` | — | System strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes. |
 
+### Message.Actions
+`ref` → `HTMLDivElement`. A row of a bot's inline keyboard under the bubble: `Button.Root` children share it equally at the message's width (the bubble widens to it). Several make several rows; such a message has no tail.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` — the `Button.Root`s of the row (`variant="soft" tone="neutral"`, `asChild` for a link); `className`. |
+
 ### Message.Menu
 `ref` → `HTMLDivElement`. The context menu: a `Dropdown.Content` of the `Dropdown.Item`s you write; the kit adds «Выбрать» when the chat has a selection. Opens on right click, long press and from the keyboard.
 
@@ -298,6 +307,7 @@ The list-level settings a message reads — the group chat's author header and a
 | typing | `Message.Typing active` | an incoming bubble of three dots rising and fading in turn on the loading loop (reduced motion slows it); enters floating up while its height opens (`fast`), leaves closing its height (`fast`) — or at once when a reply arrives at the end of the list in the same update; its block axis clips, so a closed row leaves nothing under the list |
 | status change | `status` | the ticks cross-fade and scale (`base`, `emphasized`), interruptible |
 | retrying | `onRetry` returns a promise | `sending` ticks and a `loading` retry button until it settles |
+| inline keyboard | `Message.Actions` children | `data-actions` on the message column: the rows under the bubble, the bubble at least as wide as them, no tail |
 | failed | `status="failed"` | `data-failed` on the row; danger mark, retry button |
 | reaction toggled | a chip, a double tap, `L`, the reaction bar | the chip changes in place (never remounts) in the same frame: the fill is a color transition (`fast`); a reactor who joins fades and scales in from 0.9 while the stack widens (its width follows its circles), one who leaves the reverse; a count that only changes value rolls its digits and the chip does not move — its width follows the number of digits (tabular) and moves (`fast`) only when that changes; the reader (`Chat.Messages reader`) joins or leaves the avatar stack; while a returned promise runs `aria-busy`, `data-pending` — update `items` before it resolves; a rejection drops it back. Without `onReactionToggle` the chips are read-only and there is no reaction bar |
 | size change | a reaction row that opens or closes, a chip that comes or goes, a transcript, an edit, an upload state | one stroke (`bubbleMorph`, `--prime-message-morph-duration` 300 ms): the new layout is laid out at once, in the same frame, and the bubble's visible box glides from the old rectangle to the new one — width and height together, one `clip-path: inset(… round …)` animation on the compositor, the fill a layer under the content that reaches over both boxes. Every part that moved (the text, the meta, the cards, the chips, the tail, the retry) glides from where it was by a `transform` on the same clock; a part that came fades (a chip also scales from 0.9) in where it stands once the box has room for it; a part that went fades out where it stood, out of flow. A change mid-flight retargets from what is on screen; a commit that moves nothing touches nothing. The meta and the tail stay put on a reaction: the message grows upward, the chat scrolling by the change in the same frame while the rows above glide as one block on the same clock (the rows below never move). A disclosed block (a transcript) fades over the whole stroke while the box opens or closes over it. The text glides straight with the bubble's top-start corner, keeping its padding all the way. Nothing travels across text: a meta that stays while text passes through its place dips — it fades out at the same spot before the text reaches it and back once the text has left — and a meta that changes line (a transcript's last line ↔ the player row) cross-fades — out at its old place in the first 40 % of the stroke, in at its new place in the last 40 %. Easing `standard`. Reduced motion: instant (the scroll still keeps the view) |
@@ -330,6 +340,7 @@ The list-level settings a message reads — the group chat's author header and a
 - `Message.Text` wraps anywhere; the meta stands at the end of its last line.
 - Round controls (download, cancel, retry, play) are a Button `shape="circle"`: hover, press, focus ring and the touch area follow the circle. A file's action is its round tile (48): the transfer disk (`internal/transferDisk`, `xl`) with its ring, the retry or the download stand on it — never a separate button beside the name. Every transfer, either way (media, file, video note, voice), is that one disk.
 - `Message.Typing` is the last row of a list; a chat puts it there itself (`Chat.Root typing`).
+- **A bot's inline keyboard** (`Message.Actions`): each part is a row under the bubble, `--prime-space-1` below it and between rows and buttons, on the chat's own surface (outside the bubble's fill). The keyboard is as wide as the message: the column takes the wider of the bubble and the keyboard (up to the bubble's cap) and the bubble widens to it, so their edges line up. Buttons share a row equally (`flex: 1 1 0`); a row too narrow for its labels wraps them. The expected look is `Button.Root variant="soft" tone="neutral"` at the host tier; `asChild` turns one into a link. A message with a keyboard has no tail: the keyboard closes it.
 
 ## Accessibility
 
@@ -339,6 +350,7 @@ The list-level settings a message reads — the group chat's author header and a
 | `Enter` · `Shift+F10` · `ContextMenu` | Opens the menu of the focused message (`ContextMenu` is the menu key); in a chat's selection mode `Enter` / `Space` toggle it and Shift extends the range from the anchor |
 | `R` | Opens the reaction bar (with `onReactionToggle`); arrows move between reactions, `Home` / `End` to the ends, `Enter` / `Space` pick, `Tab` closes it |
 | `L` | Puts or takes back the quick reaction (as a double tap) |
+| `Tab` | Moves to the buttons and links of a message: the reply quote, a file, the `Message.Actions` buttons in row order |
 | `Escape` | Closes the menu or the reaction bar |
 
 ### ARIA
@@ -351,6 +363,7 @@ The list-level settings a message reads — the group chat's author header and a
 - Reactions are a group of buttons with `aria-pressed`; a chip is named «{emoji}: {count}», with `users` «{emoji} {count}: {users}» («❤️ 3: Анна, Пётр, Мария», «ещё N» when not everyone is listed); its avatars are `aria-hidden`; without `onReactionToggle` the chips are `disabled`. The reaction bar is a `toolbar` of toggle buttons named by the reaction («Нравится», «Огонь»…); its «⌄» is `aria-expanded`. The quick reaction is announced in the list's polite live region.
 - `VideoNote` and `VoicePlayer` carry their own ARIA (see their pages); inside a message their transcript is a plain paragraph, selectable and marked by the chat's search.
 - Media tiles are buttons «Открыть: {alt}» that open the album in MediaViewer, the focus returning to the tile on close; a transfer is the round cancel, retry or download button, the share its accessible description; a refused retry or cancel is announced politely; a done transfer's disk is `inert`.
+- `Message.Actions` are plain buttons and links (`Button.Root`, `asChild`) with visible labels, in row order; in a chat's selection mode they take no presses.
 - Color is never the only signal: the status is named, the own reaction is `aria-pressed`, a selected message is `aria-selected` with a check, the author is text.
 
 ### Labels
@@ -376,6 +389,7 @@ The list-level settings a message reads — the group chat's author header and a
 | `reactionRemoved` | `"Реакция {emoji} снята"` | Announced when the quick reaction is taken back. |
 | `reactionBar` | `"Реакции"` | The name of the reaction bar. |
 | `moreReactions` | `"Все реакции"` | The «⌄» of the reaction bar that shows every reaction. |
+| `spoiler` | `"Скрытый текст"` | `Message.Text`: the name of a `\|\|spoiler\|\|` while it is hidden. |
 | `typing` | `"Собеседник печатает"` | `Message.Typing`: the text read while the other side types. |
 | `reply` | `"Ответ на сообщение"` | `Message.Reply labels`: the hidden prefix read before the quote. |
 | `forwarded` | `"Переслано от {author}"` | `Message.Forwarded labels`: the header; `{author}` — the original author. |
@@ -416,6 +430,7 @@ The list-level settings a message reads — the group chat's author header and a
 | [location.tsx](examples/location.tsx) | A place on a map picture from your map service with a pin, the place and its address, and a live location of a courier on its way — `Message.Location`, `href`, `live`. |
 | [contact.tsx](examples/contact.tsx) | A shared contact: initials or a photo, name and phone, with the actions to write or save — `Message.Contact`, `phone`. |
 | [link-preview.tsx](examples/link-preview.tsx) | A message with a link and the card of the page under it: site, title, description and picture — `Message.LinkPreview`, `site`, `image`. |
+| [bot-actions.tsx](examples/bot-actions.tsx) | A bot's message with an inline keyboard: rows of buttons under the bubble at its width, sharing each row equally, one of them a link — `Message.Actions`, `asChild`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width bubbles take up to 85% of the chat, long words and links wrap inside, an album keeps its rows — `Message.Root`, `Message.Media`. |
 
 ## Mistakes
@@ -438,7 +453,8 @@ The list-level settings a message reads — the group chat's author header and a
 - Pausing other players by hand → one sound at a time is built into `VoicePlayer`, `VideoNote` and chat videos.
 - A transcript as a separate `Message.Text`, or a height animation of your own around it → `transcript` / `onTranscribe` on `VoicePlayer` and `VideoNote`: the text opens inside the same message, in one stroke with its height.
 - A list, dates, search or selection built around messages → [Chat](../chat/COMPONENT.md).
+- A bot's buttons placed inside `Message.Text`, or a row of buttons of your own under a message → `Message.Actions` with `Button.Root` children: one row per part, at the message's width.
 
 ## Related
-- **Built from:** [Dropdown](../dropdown/COMPONENT.md) (`Message.Menu`), [Gallery](../gallery/COMPONENT.md) (`Message.Media`), [Avatar](../avatar/COMPONENT.md) (`Avatar.Group` + `Avatar.Overflow` in reaction chips), [Badge](../badge/COMPONENT.md) (the «Трансляция» mark of a live location), [Thumbnail](../thumbnail/COMPONENT.md) (the map, the link preview picture, a file's preview), [Button](../button/COMPONENT.md) (retry, the transfer disk, `shape="circle"`), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in selection mode), [Spinner](../spinner/COMPONENT.md) (pending transfers and transcripts), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`); `internal/messagePart` (the contract of content parts), `internal/messageList` (the contract with a chat's list), `internal/palette` (`hueOf`), `internal/Disclosure` (the reactions row, transcripts), `bubbleMorph` (every size change as one stroke), `bubbleHug` (a bubble of text as wide as its widest line), `internal/transferDisk` (the transfer of a file), `internal/mediaPill` (the meta, the author's pill), `internal/HighlightMatch` (search marks), `internal/richText` (Markdown)
+- **Built from:** [Dropdown](../dropdown/COMPONENT.md) (`Message.Menu`), [Gallery](../gallery/COMPONENT.md) (`Message.Media`), [Avatar](../avatar/COMPONENT.md) (`Avatar.Group` + `Avatar.Overflow` in reaction chips), [Badge](../badge/COMPONENT.md) (the «Трансляция» mark of a live location), [Thumbnail](../thumbnail/COMPONENT.md) (the map, the link preview picture, a file's preview), [Button](../button/COMPONENT.md) (retry, the transfer disk, `shape="circle"`, the buttons of `Message.Actions`), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in selection mode), [Spinner](../spinner/COMPONENT.md) (pending transfers and transcripts), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`); `internal/messagePart` (the contract of content parts), `internal/messageList` (the contract with a chat's list), `internal/palette` (`hueOf`), `internal/Disclosure` (the reactions row, transcripts), `bubbleMorph` (every size change as one stroke), `bubbleHug` (a bubble of text as wide as its widest line), `internal/transferDisk` (the transfer of a file), `internal/mediaPill` (the meta, the author's pill), `internal/HighlightMatch` (search marks), `internal/richText` (Markdown)
 - **See also:** [Chat](../chat/COMPONENT.md) — the conversation the messages stand in; [Gallery](../gallery/COMPONENT.md) — the album of `Message.Media`; [VideoNote](../video-note/COMPONENT.md) — the round video message; [VoicePlayer](../voice-player/COMPONENT.md) — the content of a voice message; [Composer](../composer/COMPONENT.md) — the input under the list; [Timeline](../timeline/COMPONENT.md)