prime-ui-kit 0.11.0 → 0.12.0

package/src/components/file-upload/COMPONENT.md

@@ -33,9 +33,11 @@
 
 ## Import
 ```tsx
-import { FileUpload, type FileUploadFile, useUploadQueue } from "prime-ui-kit";
+import { FileUpload, type FileUploadFile, formatFileSize, useUploadQueue } from "prime-ui-kit";
 ```
 
+`formatFileSize(bytes)` writes a size the way the rows do («820 КБ», «1,2 МБ»): use it wherever a file size appears beside the kit's.
+
 ## Anatomy
 ```
 FileUpload.Root                 field frame: label → trigger → files → hint | error

package/src/components/list/COMPONENT.md

@@ -0,0 +1,180 @@
+# 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`).
+
+## 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)
+└─ List.Item                <li> with a full-width <button> | <a href> | asChild element; current, disabled
+   ├─ 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. |
+| `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 |
+|---|---|---|---|
+| `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 |
+
+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).
+
+## 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. |
+
+### 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.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## 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`. |
+
+## 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.
+
+## Related
+- **Built from:** [Badge](../badge/COMPONENT.md) (`List.ItemCount`)
+- **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/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/page-content/COMPONENT.md

@@ -170,7 +170,7 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 - Header is a wrapping row: actions stay to the right of the title while the heading keeps half a reading measure, otherwise they wrap below it — no breakpoint needed, works from 320px.
 - Title and Description wrap long words (`overflow-wrap: anywhere`).
 - `fill` needs a main with a height: `AppShell.Root fillViewport` (main scrolls inside the panel). The body passes its free height on to a filling child — DataTable `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`.
-- Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately.
+- Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately. The records of the list pane are a [List](../list/COMPONENT.md).
 - The detail pane is on screen all the time on a wide split: while nothing is chosen it shows a short hint («Выберите диалог»), never an empty card.
 
 ## Accessibility
@@ -212,4 +212,4 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 
 ## Related
 - **Built from:** [Button](../button/COMPONENT.md) (`PageContent.BackButton`), Icon (`nav.chevronLeft`)
-- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [List](../list/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)

package/src/components/page-content/examples/examples.module.css

@@ -46,24 +46,17 @@
   min-height: 0;
 }
 
-.dialogs,
-.messages {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-1);
-  margin: 0;
+.dialogs {
   padding: var(--prime-space-2);
-  list-style: none;
 }
 
 .messages {
+  display: flex;
+  flex-direction: column;
   gap: var(--prime-space-3);
+  margin: 0;
   padding: var(--prime-space-2) var(--prime-space-4) var(--prime-space-4);
-}
-
-/* A dialog row: the name at the start, the unread count at the end. */
-.dialog {
-  justify-content: space-between;
+  list-style: none;
 }
 
 .hint {

package/src/components/page-content/examples/list-detail.tsx

@@ -1,5 +1,5 @@
 /** A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. */
-import { Badge, Button, Card, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
+import { Card, List, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -58,25 +58,20 @@ export default function PageContentListDetailExample() {
             <PageContent.List aria-label="Диалоги">
               <Card.Root className={styles.paneCard}>
                 <ScrollContainer className={styles.pane}>
-                  <ul className={styles.dialogs}>
+                  <List.Root className={styles.dialogs}>
                     {DIALOGS.map((dialog) => (
-                      <li key={dialog.id}>
-                        <Button.Root
-                          variant={dialog.id === dialogId ? "soft" : "ghost"}
-                          tone="neutral"
-                          fullWidth
-                          aria-current={dialog.id === dialogId ? "true" : undefined}
-                          className={styles.dialog}
-                          onClick={() => open(dialog)}
-                        >
-                          {dialog.client}
-                          {dialog.unread > 0 ? (
-                            <Badge.Root color="blue">{dialog.unread}</Badge.Root>
-                          ) : null}
-                        </Button.Root>
-                      </li>
+                      <List.Item
+                        key={dialog.id}
+                        current={dialog.id === dialogId}
+                        onClick={() => open(dialog)}
+                      >
+                        <List.ItemText>{dialog.client}</List.ItemText>
+                        {dialog.unread > 0 ? (
+                          <List.ItemCount color="blue">{dialog.unread}</List.ItemCount>
+                        ) : null}
+                      </List.Item>
                     ))}
-                  </ul>
+                  </List.Root>
                 </ScrollContainer>
               </Card.Root>
             </PageContent.List>

package/src/components/visually-hidden/COMPONENT.md

@@ -36,7 +36,8 @@ VisuallyHidden    <span>: out of sight (1px, clipped), pinned to its containing
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — | The text to read. |
-| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `id` (to point `aria-describedby` at it), `role="status"` with `aria-live` for an announcement, `className` and the other span attributes. |
+| `live` | `"polite" \| "assertive"` | — | An announcement region, read as a whole on every change: `polite` — `role="status"`, `assertive` — `role="alert"` (urgent only). |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `id` (to point `aria-describedby` at it), `className` and the other span attributes. |
 
 ## Variants
 One look: none. It renders no pixels and takes no room.
@@ -45,7 +46,7 @@ One look: none. It renders no pixels and takes no room.
 | State | Driven by | DOM |
 |---|---|---|
 | hidden text | children | a clipped `<span>` |
-| live region | `role="status"` + `aria-live="polite"` | read when its text changes; mount it empty first, then set the message |
+| live region | `live="polite"` (`"assertive"` for an urgent one) | `role="status"` (`"alert"`), `aria-live`, `aria-atomic`: read as a whole when its text changes; mount it empty first, then set the message |
 
 ## Layout & spacing
 - Takes no room and never scrolls its column: it is pinned to the start of the nearest positioned ancestor.
@@ -58,7 +59,7 @@ No keyboard interaction.
 
 ### ARIA
 - The text stays in the accessibility tree: it joins the accessible name of the element around it.
-- With `role="status"` it is a polite live region; keep it mounted and change its text — a region mounted together with its message is often not read.
+- With `live="polite"` it is a polite live region (`role="status"`), with `live="assertive"` an alert (`role="alert"`) for what cannot wait; keep it mounted and change its text — a region mounted together with its message is often not read.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -73,6 +74,8 @@ No `labels`.
 ## Mistakes
 - `display: none` or `hidden` for screen-reader text → both remove it from the accessibility tree.
 - A live region mounted with its first message → mount it empty, then set the text.
+- `role="status"` and `aria-live` written by hand → `live="polite"` sets them together, atomic.
+- `live="assertive"` for a routine result («Сохранено») → it interrupts the reader; keep it for errors that block.
 - VisuallyHidden as the only name of a button that has `aria-label` → the `aria-label` wins; use one of them.
 - Hidden text that repeats the visible label → screen readers read it twice.
 

package/src/components/visually-hidden/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** A count that sighted users read from the layout, said in words to screen readers, and a polite announcement after an action — `VisuallyHidden`. */
+/** A count that sighted users read from the layout, said in words to screen readers, and a polite announcement after an action — `VisuallyHidden`, `live`. */
 import { Badge, Button, Typography, VisuallyHidden } from "prime-ui-kit";
 import * as React from "react";
 
@@ -14,7 +14,7 @@ export default function VisuallyHiddenOverviewExample() {
       <Button.Root variant="soft" tone="neutral" onClick={() => setArchived((count) => count + 1)}>
         В архив
       </Button.Root>
-      <VisuallyHidden role="status" aria-live="polite">
+      <VisuallyHidden live="polite">
         {archived > 0 ? `Счетов в архиве: ${archived}` : ""}
       </VisuallyHidden>
     </>