prime-ui-kit 0.14.0 → 0.16.0

package/src/components/description-list/examples/screen.module.css

@@ -0,0 +1,46 @@
+/* Detail page: the header carries the title; two columns that wrap into one on narrow screens, no
+   breakpoints. */
+
+/* Main column grows; the side column keeps ~18rem and drops below once main would get < 30rem. */
+.columns {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: var(--prime-space-8) var(--prime-space-6);
+}
+
+.main {
+  flex: 999 1 calc(var(--prime-space-24) * 5);
+}
+
+.aside {
+  display: grid;
+  flex: 1 1 calc(var(--prime-space-24) * 3);
+  gap: var(--prime-space-4);
+  min-width: 0;
+}
+
+/* Totals under the table: the amounts end where the «Сумма» column ends (the table's cell padding). */
+.totals {
+  justify-self: end;
+  width: min(100%, calc(var(--prime-space-24) * 3));
+  padding-inline: var(--prime-table-cell-padding-x);
+}
+
+/* Client card: who it is, then the facts as label → value pairs. */
+.client {
+  display: grid;
+  gap: var(--prime-space-5);
+}
+
+.person {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+  min-width: 0;
+}
+
+.personText {
+  display: grid;
+  min-width: 0;
+}

package/src/components/description-list/examples/screen.tsx

@@ -0,0 +1,206 @@
+/** A nested record: the path, the title with its status and due date and the record's actions by weight in the app header, a main column with the line items and their totals and a side column with the client's details and the history — `align`, `orientation`. */
+import {
+  AppHeader,
+  Avatar,
+  Breadcrumb,
+  Button,
+  Card,
+  DataTable,
+  type DataTableColumn,
+  DescriptionList,
+  Dropdown,
+  Icon,
+  LinkButton,
+  PageContent,
+  PageToolbar,
+  Timeline,
+  Typography,
+} from "prime-ui-kit";
+
+import styles from "./screen.module.css";
+
+type Line = { id: string; name: string; quantity: number; unit: string; price: number };
+
+const LINES: Line[] = [
+  { id: "l1", name: "Лицензия CRM, тариф «Бизнес»", quantity: 25, unit: "мест", price: 12_000 },
+  { id: "l2", name: "Внедрение и настройка", quantity: 40, unit: "ч", price: 3_500 },
+  { id: "l3", name: "Обучение менеджеров", quantity: 2, unit: "дня", price: 18_000 },
+];
+
+const HISTORY = [
+  { id: "h1", title: "Счёт открыт клиентом", date: "2 окт., 11:40" },
+  { id: "h2", title: "Отправлен на billing@veter.ru", date: "30 сент., 16:05" },
+  { id: "h3", title: "Создан · Анна Климова", date: "30 сент., 15:52" },
+];
+
+const MONEY = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+const COUNT = new Intl.NumberFormat("ru-RU");
+
+const NET = LINES.reduce((sum, line) => sum + line.quantity * line.price, 0);
+const VAT = Math.round(NET * 0.2);
+
+const TOTALS = [
+  { label: "Без НДС", value: MONEY.format(NET) },
+  { label: "НДС 20%", value: MONEY.format(VAT) },
+];
+
+const COLUMNS: DataTableColumn<Line>[] = [
+  { id: "name", header: "Позиция", accessor: "name" },
+  {
+    id: "quantity",
+    header: "Кол-во",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => `${COUNT.format(row.quantity)} ${row.unit}`,
+  },
+  {
+    id: "price",
+    header: "Цена",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => MONEY.format(row.price),
+  },
+  {
+    id: "sum",
+    header: "Сумма",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => MONEY.format(row.quantity * row.price),
+  },
+];
+
+export default function DescriptionListScreenExample() {
+  return (
+    <>
+      {/* A nested record titles itself in the app header: the path up to the list, the record as the
+          only h1 with its status and due date under it, the record's actions in the tools row. */}
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#invoices">Счета</Breadcrumb.Item>
+          </Breadcrumb.Root>
+          <AppHeader.Separator />
+          <AppHeader.Title>
+            Счёт № 2026-0418
+            <AppHeader.Description>Отправлен · оплатить до 14 октября</AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Tools>
+          <PageToolbar.Root aria-label="Счёт № 2026-0418">
+            <PageToolbar.Actions>
+              <Dropdown.Root>
+                <Dropdown.Trigger>
+                  <Button.Root variant="soft" tone="neutral" aria-label="Другие действия">
+                    <Button.Icon>
+                      <Icon name="action.more" />
+                    </Button.Icon>
+                  </Button.Root>
+                </Dropdown.Trigger>
+                <Dropdown.Content>
+                  <Dropdown.Item>Дублировать</Dropdown.Item>
+                  <Dropdown.Item>Скачать PDF</Dropdown.Item>
+                  <Dropdown.Separator />
+                  <Dropdown.Item tone="danger">Аннулировать счёт</Dropdown.Item>
+                </Dropdown.Content>
+              </Dropdown.Root>
+              <Button.Root variant="soft" tone="neutral" aria-label="Напомнить клиенту">
+                <Button.Icon>
+                  <Icon name="action.send" />
+                </Button.Icon>
+              </Button.Root>
+              <Button.Root>Отметить оплату</Button.Root>
+            </PageToolbar.Actions>
+          </PageToolbar.Root>
+        </AppHeader.Tools>
+      </AppHeader.Root>
+
+      <PageContent.Root>
+        <PageContent.Body>
+          <div className={styles.columns}>
+            <PageContent.Section label="Позиции" className={styles.main}>
+              <DataTable
+                columns={COLUMNS}
+                rows={LINES}
+                getRowKey={(row) => row.id}
+                paging="none"
+                highlightRowOnHover={false}
+              />
+              {/* The totals end where the «Сумма» column of the table above ends. */}
+              <DescriptionList.Root align="end" className={styles.totals}>
+                {TOTALS.map((row) => (
+                  <DescriptionList.Item key={row.label} label={row.label}>
+                    {row.value}
+                  </DescriptionList.Item>
+                ))}
+                <DescriptionList.Item
+                  label={
+                    <Typography as="span" variant="title-m">
+                      К оплате
+                    </Typography>
+                  }
+                >
+                  <Typography as="span" variant="title-m" numeric="tabular">
+                    {MONEY.format(NET + VAT)}
+                  </Typography>
+                </DescriptionList.Item>
+              </DescriptionList.Root>
+            </PageContent.Section>
+            <aside className={styles.aside} aria-label="Клиент и история">
+              <Card.Root variant="panel">
+                <Card.Header>
+                  <Card.Title as="h2">Клиент</Card.Title>
+                </Card.Header>
+                <Card.Body>
+                  <div className={styles.client}>
+                    <span className={styles.person}>
+                      <Avatar.Root color="teal">
+                        <Avatar.Fallback>СВ</Avatar.Fallback>
+                      </Avatar.Root>
+                      <span className={styles.personText}>
+                        <Typography as="span" variant="title-s">
+                          ООО «Северный ветер»
+                        </Typography>
+                        <Typography as="span" variant="caption" tone="muted">
+                          ИНН 7704 512 908
+                        </Typography>
+                      </span>
+                    </span>
+                    <DescriptionList.Root orientation="vertical">
+                      <DescriptionList.Item label="Контакт">
+                        Ольга Мартынова, финансовый директор
+                      </DescriptionList.Item>
+                      <DescriptionList.Item label="Почта для счетов">
+                        <LinkButton href="mailto:billing@veter.ru">billing@veter.ru</LinkButton>
+                      </DescriptionList.Item>
+                    </DescriptionList.Root>
+                  </div>
+                </Card.Body>
+              </Card.Root>
+              <Card.Root variant="panel">
+                <Card.Header>
+                  <Card.Title as="h2">История</Card.Title>
+                </Card.Header>
+                <Card.Body>
+                  <Timeline.Root>
+                    <Timeline.Group>
+                      {HISTORY.map((event) => (
+                        <Timeline.Item key={event.id}>
+                          <Timeline.ItemTitle>{event.title}</Timeline.ItemTitle>
+                          <Timeline.ItemMeta>{event.date}</Timeline.ItemMeta>
+                        </Timeline.Item>
+                      ))}
+                    </Timeline.Group>
+                  </Timeline.Root>
+                </Card.Body>
+              </Card.Root>
+            </aside>
+          </div>
+        </PageContent.Body>
+      </PageContent.Root>
+    </>
+  );
+}

package/src/components/description-list/examples/sizes.tsx

@@ -1,15 +1,13 @@
 /** Every tier changes the label and value type and the gap between pairs — `size`. */
 import { DescriptionList, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DescriptionListSizesExample() {
   return (
-    <div className={styles.sizes}>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.size}>
+        <div key={size}>
           <DescriptionList.Root size={size}>
             <DescriptionList.Item label="Счёт">№ 4821 от 3 октября</DescriptionList.Item>
             <DescriptionList.Item label="Сумма">94 750 ₽</DescriptionList.Item>

package/src/components/description-list/examples/structure.tsx

@@ -1,4 +1,4 @@
-/** Optional pieces of a pair: a Badge or a link as the value, a row action and an empty value with its own mark — `DescriptionList.ItemAction`, `labels`. */
+/** Optional pieces of a pair: a Badge or a link as the value, a row action that is a link and an empty value with its own mark — `DescriptionList.ItemAction`, `asChild`, `labels`. */
 import { Badge, DescriptionList, Icon, LinkButton } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -8,18 +8,17 @@ export default function DescriptionListStructureExample() {
     <div className={styles.column}>
       <DescriptionList.Root labels={{ empty: "Нет", emptyText: "Нет данных" }}>
         <DescriptionList.Item label="Статус">
-          <Badge.Root color="green">Оплачен</Badge.Root>
+          <Badge.Root tone="success">Оплачен</Badge.Root>
         </DescriptionList.Item>
         <DescriptionList.Item label="Договор">
           <LinkButton href="#contract-118">Договор № 118 от 12 марта</LinkButton>
         </DescriptionList.Item>
-        <DescriptionList.Item label="Email">
+        <DescriptionList.Item label="Почта">
           finance@severny-veter.ru
-          <DescriptionList.ItemAction
-            label="Написать"
-            onClick={() => window.open("mailto:finance@severny-veter.ru")}
-          >
-            <Icon name="action.send" />
+          <DescriptionList.ItemAction label="Написать" asChild>
+            <a href="mailto:finance@severny-veter.ru">
+              <Icon name="action.send" />
+            </a>
           </DescriptionList.ItemAction>
         </DescriptionList.Item>
         <DescriptionList.Item label="Скидка">{null}</DescriptionList.Item>

package/src/components/description-list/examples/totals.tsx

@@ -0,0 +1,40 @@
+/** The totals of an invoice: every amount at the end of its row in tabular figures, the amount due a step larger — `align`. */
+import { Card, DescriptionList, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TOTALS = [
+  { label: "Без НДС", value: "400 000 ₽" },
+  { label: "Скидка 5%", value: "−20 000 ₽" },
+  { label: "НДС 20%", value: "76 000 ₽" },
+];
+
+export default function DescriptionListTotalsExample() {
+  return (
+    <Card.Root variant="panel" className={styles.column}>
+      <Card.Header>
+        <Card.Title>Итого по счёту № 2026-0418</Card.Title>
+      </Card.Header>
+      <Card.Body>
+        <DescriptionList.Root align="end">
+          {TOTALS.map((row) => (
+            <DescriptionList.Item key={row.label} label={row.label}>
+              {row.value}
+            </DescriptionList.Item>
+          ))}
+          <DescriptionList.Item
+            label={
+              <Typography as="span" variant="title-m">
+                К оплате
+              </Typography>
+            }
+          >
+            <Typography as="span" variant="title-m" numeric="tabular">
+              456 000 ₽
+            </Typography>
+          </DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/digit-input/COMPONENT.md

@@ -37,7 +37,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `length` | `number` | `4` | Number of cells. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier: the cell is a square on its own scale, two steps above the control heights (36 · 40 · 48 · 56 · 64); label and hint follow the field tier. Without it the tier of its host (LoginForm, a panel), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier: the cell is a square on its own scale, two steps above the control heights (36 · 40 · 48 · 56 · 64); label and hint follow the field tier. Without it the tier of its host (LoginForm, a panel), else `m`. |
 | `label` | `ReactNode` | — | Label above the cells; names the group (`aria-labelledby`) and focuses the first cell on click. Without it the group is named by `labels.group`. |
 | `required` | `boolean` | — | Red `*` after the label and native `required` on every cell. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
@@ -82,7 +82,8 @@ No `variant` or `tone`.
 | `groupSize` | an extra gap before every group (`3` → 123 456) | codes of six digits and longer | — |
 | `mask` | dots instead of digits | PIN codes | `false` |
 | `required` / `optional` | red `*` / muted «необязательно» after the label | mark the minority of the form | — |
-| `focusRing={false}` | no focus ring; the focus fill and the caret remain | a single code on a screen where focus is obvious | `true` |
+| `focusRing` | `false`: no focus ring; the focus fill and the caret remain | a single code on a screen where focus is obvious | `true` |
+| `autoFocus` | the entry cell takes focus on mount | the code is the one task of its step (a verification screen) | `false` |
 
 **Combinations**
 - Recommended: `onComplete` returning the check's promise — the field waits, shows success or clears and shows the reason; or, checking by hand, `error` set after a rejected code and cleared in `onValueChange`.
@@ -94,7 +95,7 @@ No `variant` or `tone`.
 | State | Driven by | DOM |
 |---|---|---|
 | hover | — | cell fill darkens (not on focused or disabled cells) |
-| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own; the code has no gaps, so focusing a cell past the first empty one moves focus to that entry cell |
+| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own; the code has no gaps, so focusing a cell past the first empty one moves focus to that entry cell; the code is one tab stop (the focused cell, else the entry cell) |
 | filled cell | a digit in the cell | `data-filled="true"` on the cell; the digit fades in as it lands |
 | checking | `onComplete` returned a pending promise | `aria-busy` and `data-pending="true"` on the fieldset, cells `readonly` and quiet to 0.6 (`fast`, both ways); typing waits for the answer |
 | refused | that promise rejected | the code clears and focus goes to the first cell; the reason (the rejection's message, else `labels.failed`) becomes the error (unless you pass `error`) and shakes in, a polite live region speaks it; typing again takes it away |
@@ -109,21 +110,27 @@ No `variant` or `tone`.
 
 ## Layout & spacing
 - The field hugs its cells (label left-aligned above them); with `fullWidth` it fills the container.
+- The code is always one row: in a container narrower than the row the cells narrow and keep the tier height, so no digit or group wraps to a second line.
+- On a coarse pointer an `xs` or `s` cell grows to the 44 px touch target itself (an input takes no taps through a hit area drawn around it).
 - Label → cells: tier `label-gap`; cells → hint: tier `hint-gap` — the same rhythm as every field.
 - Put the submit button below or next to the code; with the same `size` it lines up with the cells.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `0`–`9` | Types into the first empty cell and moves to the next one. |
+| `0–9` | Types into the first empty cell and moves to the next one. |
 | `Backspace` | Clears the cell; on an empty cell moves to the previous one. |
 | `ArrowLeft` · `ArrowRight` | Moves between filled cells and the entry cell. |
 | `Home` · `End` | Jumps to the first cell / the entry cell. |
-| `Tab` | Leaves the code. |
+| `Tab` | Enters the code at the entry cell; from any cell, leaves it. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The cells sit in a `<fieldset>` (`role="group"`) named by the `label` (`aria-labelledby`) or `labels.group`; clicking the label focuses the first cell.
 - Each cell is named by `labels.cell` («Цифра 1 из 6») and has `autocomplete="one-time-code"` and `inputmode="numeric"`, so SMS codes are suggested on phones.
 - The hint or the error is linked to the group through `aria-describedby`; invalid cells carry `aria-invalid`.
@@ -145,11 +152,12 @@ No `variant` or `tone`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A six-digit code from SMS with its label and a hint — `label`, `hint`, `length`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the cell is a square on its own scale, two steps above the control heights — `size`. |
-| [states.tsx](examples/states.tsx) | A default code next to a disabled one — `disabled`. |
+| [states.tsx](examples/states.tsx) | A default code next to a disabled one, an invalid one with no message and an accepted one — `disabled`, `invalid`, `success`. |
 | [validation.tsx](examples/validation.tsx) | A confirmation code checked once it is complete: a wrong code shakes in with one message and leaves as soon as you type again; a hint and an optional code — `required`, `optional`, `hint`, `error`. |
 | [grouped.tsx](examples/grouped.tsx) | A long code read in chunks with a wider gap between groups — `groupSize`. |
 | [full-width.tsx](examples/full-width.tsx) | Cells that share the container width and keep the tier height, above a full-width button — `fullWidth`. |
 | [on-complete.tsx](examples/on-complete.tsx) | The code is checked on the server as soon as the last cell is filled: the cells wait, a right one turns them success, a wrong one clears them and shakes in the reason — `onComplete`, `hint`. |
+| [without-focus-ring.tsx](examples/without-focus-ring.tsx) | The one code on a pickup point screen, where the caret and the lighter fill of the entry cell show focus — `focusRing`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the code and clears it with a button — `value`, `onValueChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A masked card PIN submitted with a form; a short or wrong PIN shakes in an error that leaves when you type again — `name`, `mask`, `required`, `error`. |
 
@@ -161,5 +169,5 @@ No `variant` or `tone`.
 - A hand-made «checking…» state, a disabled field and a manual reset after a wrong code → return the check's promise from `onComplete`.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Input](../input/COMPONENT.md), [LoginForm](../login-form/COMPONENT.md)

package/src/components/digit-input/examples/examples.module.css

@@ -1,11 +1,11 @@
 /* Layout of the DigitInput scenarios: semantic tokens only. */
 
-/* full-width.tsx, in-form.tsx: a phone-width column, code above the action (group → action 24). */
+/* full-width.tsx: a phone-width column, code above the action (group → action 24). */
 .panel {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-6);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* in-form.tsx: the form hugs the cells; as a grid item the button stretches to the code's width. */

package/src/components/digit-input/examples/in-form.tsx

@@ -32,7 +32,7 @@ export default function DigitInputInFormExample() {
         length={PIN_LENGTH}
         mask
         required
-        hint={`Для примера — ${PIN}`}
+        hint="Четыре цифры, которые вы задали при выпуске карты"
         error={error}
         onValueChange={() => {
           setError(undefined);

package/src/components/digit-input/examples/sizes.tsx

@@ -5,10 +5,12 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DigitInputSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <DigitInput key={size} size={size} label={size} defaultValue="2048" />
+        <div key={size}>
+          <DigitInput size={size} label={size} defaultValue="2048" />
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/digit-input/examples/states.tsx

@@ -1,11 +1,21 @@
-/** A default code next to a disabled one — `disabled`. */
+/** A default code next to a disabled one, an invalid one with no message and an accepted one — `disabled`, `invalid`, `success`. */
 import { DigitInput } from "prime-ui-kit";
 
 export default function DigitInputStatesExample() {
   return (
-    <>
-      <DigitInput label="default" defaultValue="42" />
-      <DigitInput label="disabled" defaultValue="42" disabled />
-    </>
+    <div>
+      <div>
+        <DigitInput label="default" defaultValue="42" />
+      </div>
+      <div>
+        <DigitInput label="disabled" defaultValue="42" disabled />
+      </div>
+      <div>
+        <DigitInput label="invalid" defaultValue="4271" invalid />
+      </div>
+      <div>
+        <DigitInput label="success" defaultValue="4821" success hint="Код подтверждён" />
+      </div>
+    </div>
   );
 }

package/src/components/digit-input/examples/without-focus-ring.tsx

@@ -0,0 +1,13 @@
+/** The one code on a pickup point screen, where the caret and the lighter fill of the entry cell show focus — `focusRing`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputWithoutFocusRingExample() {
+  return (
+    <DigitInput
+      label="Код выдачи заказа"
+      hint="Покупатель называет его на кассе"
+      length={6}
+      focusRing={false}
+    />
+  );
+}

package/src/components/divider/COMPONENT.md

@@ -9,7 +9,7 @@
 - Separate rows of a list or groups inside one panel, menu or card.
 - An «или» between two alternative actions (sign in / get a link by email).
 - A section heading drawn on a line (`align="start"`).
-- A vertical break between groups of buttons in a toolbar row.
+- A vertical break between groups of buttons in a toolbar row; `inset` makes it one text line tall (a header).
 
 ## When not to use
 - To separate cards or panels from each other → use fill and spacing ([Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md) sections), never a line.
@@ -38,7 +38,8 @@ Divider          <div role="separator">; the line is drawn by ::before / ::after
 |---|---|---|---|
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` stretches to the height of its flex row and sets `aria-orientation`. |
 | `align` | `"start" \| "center" \| "end"` | `"center"` | Position of the label on the line; `start` reads as a section heading. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the label: type, gap and icon size. Match the content around the divider. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the label: type, gap and icon size. Without it the tier of the content around (a menu, a panel with a size), else `m`. |
+| `inset` | `boolean` | `false` | The line stands off its neighbours by the tier gap; a vertical one is one text line tall, centred in its row (a header, a toolbar). |
 | `children` | `ReactNode` | — | Label: text, an `Icon`, or both. Omit for a plain line. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`"presentation"` for a purely visual line), `aria-label` and the other div attributes. |
 
@@ -65,27 +66,39 @@ No `variant`, `tone` or `color`: one hairline in `border-subtle`, label in `text
 | `m` | label 13/20, icon 16 | regular content | yes |
 | `l` · `xl` | label 14/20 · 16/24, icon 20 | large panels | |
 
+Without `size` the divider takes the tier of the content around it (a menu, a panel with a size), else `m`. The label type is a text role: caption for xs and s, body-s for m, body-m for l, body-l for xl.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `inset` | the tier gap on both sides of the line; vertical: one text line tall, centred in the row | a break between groups in a header or a toolbar | off |
+
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | plain line | no children | `:empty`, one line |
-| labelled | children | two line halves, each at least `--prime-space-6` long |
-| orientation / align / size | props | `data-orientation`, `data-align`, `data-size`, `aria-orientation` when vertical |
+| labelled | children that draw something (`false`, `null` and `""` do not) | two line halves, each at least `--prime-space-6` long; the separator is named by its label (`aria-labelledby`) |
+| orientation / align / size / inset | props | `data-orientation`, `data-align`, `data-size`, `data-inset`, `aria-orientation` when vertical |
 
 ## Layout & spacing
-- No margins: the parent's `gap` sets the rhythm around the line.
+- No margins: the parent's `gap` sets the rhythm around the line (`inset` adds the tier gap).
 - Horizontal: `width: 100%` in its flex column. Vertical: `align-self: stretch` in a flex row.
-- Label gap and icon size follow the tier (`--prime-control-<size>-gap`, `-icon`).
+- Label gap and icon size follow the tier (the shared tier table, `internal/fieldTier`).
+- Bleed: a host whose padding the line should cross (a menu panel) sets `--divider-bleed` to that padding; the line reaches past it on both sides, inline for a horizontal line, block for a vertical one.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `role="separator"`; vertical sets `aria-orientation="vertical"`.
 - A purely visual line between rows that are separate anyway → `role="presentation"`.
-- The label is read as the separator's text; an icon-only divider needs `aria-label`.
+- A labelled separator is named by its label (`aria-labelledby`); an icon-only divider needs `aria-label`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -95,19 +108,20 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Hairlines between the rows of a settings list. |
+| [overview.tsx](examples/overview.tsx) | Hairlines between the rows of a settings card — `Divider`. |
 | [sizes.tsx](examples/sizes.tsx) | The label at every tier, matching the content around it — `size`. |
-| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and an icon alone on the line; the divider sizes it. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and an icon alone on the line named by `aria-label`; the divider sizes the icon — `Icon`, `aria-label`. |
 | [align.tsx](examples/align.tsx) | The label at the start, the center or the end of the line; `start` heads a section — `align`. |
-| [vertical.tsx](examples/vertical.tsx) | A vertical line between groups of toolbar buttons — `orientation`. |
-| [or-separator.tsx](examples/or-separator.tsx) | An "or" line between two ways to sign in. |
+| [vertical.tsx](examples/vertical.tsx) | Vertical lines between groups of toolbar buttons: one as tall as the row, one inset to a text line — `orientation`, `inset`. |
+| [or-separator.tsx](examples/or-separator.tsx) | An "or" line between two ways to sign in, its label naming the separator — `Divider`. |
 
 ## Mistakes
 - Margins on the divider → spacing via the parent `gap`.
 - Lines between cards → separate cards by fill and spacing.
 - `<Icon size="l" />` inside the label → leave the size to the divider.
 - A vertical divider in a block container (no height) → place it in a flex row.
+- A host class that shortens a vertical divider or pulls it across padding → `inset`, or `--divider-bleed`.
 
 ## Related
-- **Built from:** —
+- **Built from:** `internal/fieldClasses` (the tier table), `internal/textRole` (the label type), `internal/hasContent`
 - **See also:** [Dropdown](../dropdown/COMPONENT.md) (`Dropdown.Separator`), [Select](../select/COMPONENT.md) (`Select.Separator`), [Accordion](../accordion/COMPONENT.md), [Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)

package/src/components/divider/examples/align.tsx

@@ -1,14 +1,12 @@
 /** The label at the start, the center or the end of the line; `start` heads a section — `align`. */
 import { Divider } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 export default function DividerAlignExample() {
   return (
-    <div className={styles.column}>
+    <>
       <Divider align="start">Уведомления</Divider>
       <Divider>Сегодня</Divider>
       <Divider align="end">Конец истории</Divider>
-    </div>
+    </>
   );
 }