prime-ui-kit 0.9.3 → 0.11.0

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

@@ -0,0 +1,132 @@
+# DescriptionList
+
+**Category:** data-display
+**Kind:** composite
+
+> Read-only properties of a record: «label — value» pairs on a `<dl>` that stack by themselves where the room is narrow, with a muted dash for an empty value.
+
+## When to use
+- The details of a record in a card, a drawer or a page section: requisites, contacts, deal terms.
+- A summary before a confirm («Сумма», «Получатель», «Срок»).
+- Properties next to a value-specific action: copy an ИНН, call a number, write an email (`DescriptionList.ItemAction`).
+
+## When not to use
+- Values the user edits → fields ([Input](../input/COMPONENT.md), [Select](../select/COMPONENT.md)) in a form.
+- Many records with the same properties → [DataTable](../data-table/COMPONENT.md).
+- One headline number → [Card](../card/COMPONENT.md) `mini` / `stat-trend`.
+- A history of events → [Timeline](../timeline/COMPONENT.md).
+
+## Import
+```tsx
+import { DescriptionList } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+DescriptionList.Root                 <dl>; size (host tier), orientation; a size container
+└─ DescriptionList.Item              <div> per pair; label
+   ├─ <dt>                           the label
+   └─ <dd>                           the value (or labels.empty) · DescriptionList.ItemAction?
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### DescriptionList.Root
+`ref` → `HTMLDListElement`. A `<dl>` of «label — value» pairs and a size container: horizontal pairs stack once the list is narrower than 24rem. Gives its tier to the controls inside.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else `"m"`` | Label and value type and the gap between pairs; without it the list takes the tier of its host (a Card, a Drawer, a form). |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` — the label in a column beside its value (one third of the width), stacking below 24rem of the list's own width; `vertical` — the label above its value at any width. |
+| `labels` | `Partial<DescriptionListLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDListElement>` | — | `className`, `id`, `data-*` and the other attributes of the element. |
+
+### DescriptionList.Item
+`ref` → `HTMLDivElement`. One pair: a `<div>` holding the `<dt>` and the `<dd>`. The value wraps anywhere; no value (`null`, `""`, `false`) shows a muted `labels.empty` and speaks `labels.emptyText`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | The visible name of the value (`<dt>`). |
+| `children` | `ReactNode` | — | The value (`<dd>`): text, a Badge, a link; plus an optional `DescriptionList.ItemAction`, which goes to the end of the value. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `id`, `data-*` and the other attributes of the element. |
+
+### DescriptionList.ItemAction
+`ref` → `HTMLButtonElement`. A row action at the end of the value («Копировать», «Позвонить»): a ghost icon Button one tier below the list, with `label` as its name and tooltip.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — (required) | Accessible name and tooltip of the action. |
+| `children` | `ReactNode` | — (required) | The icon (`<Icon name="…" />`). |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">` | — | `onClick`, `disabled`, `className` and the other button attributes. |
+
+## Variants
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | the label in a column (one third of the width) beside the value; stacked below 24rem of the list's width | record details in a card or a page | yes |
+| `vertical` | the label above its value at any width | a narrow side panel, a summary of a few long values | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` | label 12/16, value 12–13, pairs 8 apart | dense side panels, table expansions | |
+| `m` | label 13/20, value 14/20, pairs 12 apart | most cards and drawers | the host tier, else `m` |
+| `l` · `xl` | label 14/20, value 16/24, pairs 16 apart | a record page with room | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| size / orientation | props, the host tier | `data-size`, `data-orientation` on the `<dl>` |
+| narrow | the list narrower than 24rem (container query) | each pair stacks: the label above its value |
+| empty value | `children` is `null`, `""` or `false` | `data-empty` on the `<dd>`; muted `labels.empty`, spoken `labels.emptyText` |
+
+No motion: the list is static text; a row action has the Button's own press and hover.
+
+## Layout & spacing
+- The list fills its container; pairs are separated by air (8 · 12 · 16 by tier), not lines.
+- A horizontal pair: label column one third, value two thirds, 16 apart; values wrap anywhere, labels wrap too.
+- A row action sits at the end of the value, centred on its first line; it does not make the row taller.
+- Inside a `Card.Body` or a `Drawer` the list takes the host tier; do not pass `size` there.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves to the row actions (`DescriptionList.ItemAction`); the pairs themselves are not focusable. |
+| `Enter` · `Space` | Runs the row action. |
+
+### ARIA
+- The list is a `<dl>`: the label is a `<dt>`, the value a `<dd>`; screen readers read each pair as a term and its definition.
+- An empty value shows a muted `labels.empty` (hidden from assistive tech) and is read as `labels.emptyText`.
+- A row action is named by its `label`, which is also its tooltip; the icon is decorative.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `empty` | `"—"` | Visible mark of an empty value (muted, hidden from assistive tech). |
+| `emptyText` | `"Не указано"` | What assistive tech reads for an empty value. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A client's details in a card: labels beside values, a long address that wraps, an empty manager and a copy action — `DescriptionList.Item`, `label`, `DescriptionList.ItemAction`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier changes the label and value type and the gap between pairs — `size`. |
+| [structure.tsx](examples/structure.tsx) | 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`. |
+| [vertical.tsx](examples/vertical.tsx) | Labels above their values at any width, for a side panel of a record — `orientation`. |
+| [narrow.tsx](examples/narrow.tsx) | In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap. |
+
+## Mistakes
+- A grid of `Typography` pairs or a two-column table for record details → `DescriptionList`: the `<dl>` semantics and the stacking come with it.
+- `""` or «—» typed by hand for a missing value → pass nothing; the list shows `labels.empty` and speaks `labels.emptyText`.
+- A copy button placed after the list or inside the label → `DescriptionList.ItemAction` inside the item, at the end of its value.
+- A viewport media query to stack the pairs → the list adapts to its own width already.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md) (`ItemAction`), [Tooltip](../tooltip/COMPONENT.md) (the action's `label`)
+- **See also:** [Card](../card/COMPONENT.md) (the surface the list usually sits in), [Drawer](../drawer/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Timeline](../timeline/COMPONENT.md)

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

@@ -0,0 +1,41 @@
+/* Layout of the DescriptionList scenarios: semantic tokens only. */
+
+/* overview.tsx: a record card as wide as a dialog of size m. */
+.card {
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+/* structure.tsx: a column as wide as a short form. */
+.column {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* sizes.tsx: one tier per block, its caption right under it, blocks apart. */
+.sizes {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.size {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}
+
+.size > :first-child {
+  align-self: stretch;
+}
+
+/* vertical.tsx: a record side panel. */
+.side {
+  width: min(100%, var(--prime-drawer-width-s));
+}
+
+/* narrow.tsx: 320 px, the smallest supported viewport. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+}

package/dist/skill/reference/components/description-list/examples/narrow.tsx

@@ -0,0 +1,20 @@
+/** In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap. */
+import { Card, DescriptionList } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DescriptionListNarrowExample() {
+  return (
+    <Card.Root className={styles.narrow}>
+      <Card.Body>
+        <DescriptionList.Root>
+          <DescriptionList.Item label="Компания">ООО «Северный ветер»</DescriptionList.Item>
+          <DescriptionList.Item label="Электронная почта">
+            finance.department@severny-veter-logistics.ru
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Менеджер">{null}</DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,35 @@
+/** A client's details in a card: labels beside values, a long address that wraps, an empty manager and a copy action — `DescriptionList.Item`, `label`, `DescriptionList.ItemAction`. */
+import { Card, DescriptionList, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const INN = "7704512398";
+
+export default function DescriptionListOverviewExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Header>
+        <Card.Title>Реквизиты клиента</Card.Title>
+      </Card.Header>
+      <Card.Body>
+        <DescriptionList.Root>
+          <DescriptionList.Item label="Компания">ООО «Северный ветер»</DescriptionList.Item>
+          <DescriptionList.Item label="ИНН">
+            {INN}
+            <DescriptionList.ItemAction
+              label="Копировать ИНН"
+              onClick={() => navigator.clipboard?.writeText(INN)}
+            >
+              <Icon name="action.copy" />
+            </DescriptionList.ItemAction>
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Телефон">+7 495 120-44-18</DescriptionList.Item>
+          <DescriptionList.Item label="Юридический адрес">
+            125167, г. Москва, Ленинградский проспект, д. 37, корп. 9, этаж 4, помещение XII
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Менеджер">{null}</DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,24 @@
+/** 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}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.size}>
+          <DescriptionList.Root size={size}>
+            <DescriptionList.Item label="Счёт">№ 4821 от 3 октября</DescriptionList.Item>
+            <DescriptionList.Item label="Сумма">94 750 ₽</DescriptionList.Item>
+          </DescriptionList.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/description-list/examples/structure.tsx

@@ -0,0 +1,29 @@
+/** 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`. */
+import { Badge, DescriptionList, Icon, LinkButton } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DescriptionListStructureExample() {
+  return (
+    <div className={styles.column}>
+      <DescriptionList.Root labels={{ empty: "Нет", emptyText: "Нет данных" }}>
+        <DescriptionList.Item label="Статус">
+          <Badge.Root color="green">Оплачен</Badge.Root>
+        </DescriptionList.Item>
+        <DescriptionList.Item label="Договор">
+          <LinkButton href="#contract-118">Договор № 118 от 12 марта</LinkButton>
+        </DescriptionList.Item>
+        <DescriptionList.Item label="Email">
+          finance@severny-veter.ru
+          <DescriptionList.ItemAction
+            label="Написать"
+            onClick={() => window.open("mailto:finance@severny-veter.ru")}
+          >
+            <Icon name="action.send" />
+          </DescriptionList.ItemAction>
+        </DescriptionList.Item>
+        <DescriptionList.Item label="Скидка">{null}</DescriptionList.Item>
+      </DescriptionList.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/description-list/examples/vertical.tsx

@@ -0,0 +1,21 @@
+/** Labels above their values at any width, for a side panel of a record — `orientation`. */
+import { Card, DescriptionList } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DescriptionListVerticalExample() {
+  return (
+    <Card.Root className={styles.side}>
+      <Card.Body>
+        <DescriptionList.Root orientation="vertical">
+          <DescriptionList.Item label="Сделка">
+            Поставка оборудования, 2-й этап
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Сумма">1 250 000 ₽</DescriptionList.Item>
+          <DescriptionList.Item label="Ответственный">Анна Ким</DescriptionList.Item>
+          <DescriptionList.Item label="Срок">15 ноября 2026</DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/digit-input/COMPONENT.md

@@ -0,0 +1,165 @@
+# DigitInput
+
+**Category:** inputs
+**Kind:** field
+
+> A row of square single-digit cells for a fixed-length code (OTP from SMS, PIN, pickup code), with the field label, hint and error.
+
+## When to use
+- One-time codes from SMS or e-mail, PIN codes, short numeric confirmation codes of a known length.
+- When the user benefits from seeing how many digits are left and from pasting the whole code at once.
+
+## When not to use
+- Codes with letters or a variable length → use [Input](../input/COMPONENT.md) with `inputMode` / `autoComplete`.
+- Numbers with meaning (amounts, quantities) → use [Input](../input/COMPONENT.md) with an inline affix, or [Slider](../slider/COMPONENT.md).
+- Passwords → use [Input](../input/COMPONENT.md) with `type="password"`.
+
+## Import
+```tsx
+import { DigitInput } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+DigitInput            field frame: label row → cells → support row (hint | error)
+└─ <fieldset>         role="group", named by the label (or labels.group)
+   ├─ <input>…        one cell per digit (the first one carries `id`)
+   └─ <input hidden>  the joined code when `name` is set
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### DigitInput
+`ref` → `HTMLDivElement` (the field frame). The field frame (label → cells → hint | error) around a `<fieldset>` of one-character inputs; the value has no gaps, typing always goes to the first empty cell.
+
+| 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`. |
+| `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`). |
+| `hint` | `ReactNode` | — | Help text under the cells. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | — | Danger ring and danger digits on every cell, `aria-invalid`. A non-empty `error` implies it. |
+| `success` | `boolean` | `false` | The code was accepted (after the server checked it): the cells turn success one after another. Ignored while invalid. Say it in words too (`hint`). |
+| `disabled` | `boolean` | — | Disables the fieldset and every cell. |
+| `value` | `string` | — | Controlled code; non-digits are dropped, extra digits cut to `length`. |
+| `defaultValue` | `string` | `""` | Initial code when uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Called with the joined digits on every change. |
+| `onComplete` | `(value: string) => void \| Promise<void>` | — | Called once when the last empty cell is filled (typing, paste or autofill). Return the check's promise: the cells wait read-only; resolve — the `success` look; reject — the code clears and the reason shows as the error. |
+| `fullWidth` | `boolean` | `false` | Cells share the container width up to 1.5 × their side (the row centres beyond that) and keep the tier height; otherwise square cells and the field hugs them. |
+| `groupSize` | `number` | — | Splits the cells into groups of this size with a wider gap (`3` → 123 456). |
+| `mask` | `boolean` | `false` | Hides the digits (PIN): cells are `type="password"`. |
+| `name` | `string` | — | Name of a hidden input that carries the joined code in a native form submit. |
+| `autoFocus` | `boolean` | `false` | Focuses the first empty cell on mount. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on the cells (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
+| `id` | `string` | — | Id of the first cell (the label points at it); hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids on the group. |
+| `labels` | `Partial<DigitInputLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+## Variants
+No `variant` or `tone`.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 36 × 36 cells, radius 8, digits 16/24, gap 8 | A code inside a popover or a dense panel | |
+| `s` | 40 × 40 cells, radius 10, digits 18/24, gap 8 | Compact dialogs | |
+| `m` | 48 × 48 cells, radius 12, digits 20/28, gap 12 | Regular forms, modals, LoginForm | yes |
+| `l` | 56 × 56 cells, radius 12, digits 24/32, gap 12 | Standalone verification screens | |
+| `xl` | 64 × 64 cells, radius 16, digits 30/36, gap 16 | Full-page sign-in, mobile-first screens | |
+
+**Sizes:** cells have their own scale, two steps above the control heights: a code is the one thing on its screen and a small cell is hard to hit and to read (cell `xs` = control `m`, `s` = control `l`, `m` = control `xl`). Digits are semibold and tabular and grow with the cell; the label and the hint keep the field tier.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | one row, cells share the width up to 1.5 × their side, then the row centres; tier height | narrow phone columns where a full-width button follows | `false` |
+| `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` |
+
+**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`.
+- `error` and `success` you pass win over the `onComplete` check.
+- Pointless: `invalid` together with `error`; `length` larger than the real code.
+- Forbidden: `focusRing={false}` without another focus indicator (WCAG 2.4.7).
+
+## States
+| 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 |
+| 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 |
+| success | `success`, or a resolved `onComplete` promise (not while invalid) | `data-success="true"` on the fieldset (say it in words in `hint`); the cells turn `success-soft` one after another, half a stagger step apart |
+| full width | `fullWidth` | `data-full-width="true"` on the fieldset |
+| group start | `groupSize` | `data-group-start="true"` on the first cell of every group |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the fieldset and the frame, `aria-invalid="true"` on cells; the digits turn `danger-text` and the focus ring `danger-border`; the control shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | `disabled` | `data-disabled="true"` and native `disabled` on the fieldset, every cell disabled, label and hint dimmed |
+| no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the fieldset |
+
+`data-size` is set on the frame, the fieldset and every cell. Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (+ `onValueChange` to observe).
+
+## Layout & spacing
+- The field hugs its cells (label left-aligned above them); with `fullWidth` it fills the container.
+- 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
+| Key | Action |
+|---|---|
+| `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. |
+
+### ARIA
+- 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`.
+- While a code is checked the group has `aria-busy`; the reason of a refused code is spoken by a polite live region.
+- Paste and autofill of the whole code into any cell fill all cells.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `group` | `"Код"` | Accessible name of the group when there is no visible `label`. |
+| `cell` | `"Цифра {index} из {length}"` | Accessible name of each cell; `{index}` (1-based) and `{length}` are replaced. |
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+| `failed` | `"Неверный код"` | The error of a code whose `onComplete` promise rejected without a reason. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [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`. |
+| [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`. |
+
+## Mistakes
+- `<DigitInput.Root>` → the component is a single export: `<DigitInput />`.
+- A `Label` and a `Hint` placed next to the code by hand → pass `label`, `hint`, `error`.
+- Letters in the code → use `Input`; DigitInput accepts digits only.
+- Keeping `error` after the user edits the code → clear it in `onValueChange`.
+- 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`)
+- **See also:** [Input](../input/COMPONENT.md), [LoginForm](../login-form/COMPONENT.md)

package/dist/skill/reference/components/digit-input/examples/controlled.tsx

@@ -0,0 +1,23 @@
+/** The parent owns the code and clears it with a button — `value`, `onValueChange`. */
+import { Button, DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DigitInputControlledExample() {
+  const [code, setCode] = React.useState("73");
+
+  return (
+    <div className={styles.row}>
+      <DigitInput label="PIN-код терминала" value={code} onValueChange={setCode} />
+      <Button.Root
+        variant="soft"
+        tone="neutral"
+        disabled={code.length === 0}
+        onClick={() => setCode("")}
+      >
+        Очистить
+      </Button.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/digit-input/examples/examples.module.css

@@ -0,0 +1,25 @@
+/* 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). */
+.panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-6);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* in-form.tsx: the form hugs the cells; as a grid item the button stretches to the code's width. */
+.form {
+  display: grid;
+  gap: var(--prime-space-6);
+  width: fit-content;
+  max-width: 100%;
+}
+
+/* controlled.tsx: the code and its action on one line, bottoms aligned. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: var(--prime-space-3);
+}

package/dist/skill/reference/components/digit-input/examples/full-width.tsx

@@ -0,0 +1,13 @@
+/** Cells that share the container width and keep the tier height, above a full-width button — `fullWidth`. */
+import { Button, DigitInput } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DigitInputFullWidthExample() {
+  return (
+    <div className={styles.panel}>
+      <DigitInput label="Код из SMS" length={6} fullWidth />
+      <Button.Root fullWidth>Подтвердить</Button.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/digit-input/examples/grouped.tsx

@@ -0,0 +1,11 @@
+/** A long code read in chunks with a wider gap between groups — `groupSize`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputGroupedExample() {
+  return (
+    <>
+      <DigitInput label="Код из приложения" length={6} groupSize={3} defaultValue="482915" />
+      <DigitInput label="Резервный код" length={8} groupSize={4} />
+    </>
+  );
+}

package/dist/skill/reference/components/digit-input/examples/in-form.tsx

@@ -0,0 +1,50 @@
+/** 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`. */
+import { Button, DigitInput, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PIN_LENGTH = 4;
+const PIN = "4821";
+
+export default function DigitInputInFormExample() {
+  const [error, setError] = React.useState<string>();
+  const [linked, setLinked] = React.useState(false);
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const pin = String(new FormData(event.currentTarget).get("pin") ?? "");
+    const next =
+      pin.length !== PIN_LENGTH
+        ? "Введите все четыре цифры"
+        : pin === PIN
+          ? undefined
+          : "Неверный PIN-код";
+    setError(next);
+    setLinked(next === undefined);
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <DigitInput
+        label="PIN-код карты"
+        name="pin"
+        length={PIN_LENGTH}
+        mask
+        required
+        hint={`Для примера — ${PIN}`}
+        error={error}
+        onValueChange={() => {
+          setError(undefined);
+          setLinked(false);
+        }}
+      />
+      {linked ? (
+        <Typography as="p" variant="body-s" tone="secondary" role="status">
+          Карта привязана.
+        </Typography>
+      ) : null}
+      <Button.Root type="submit">Привязать карту</Button.Root>
+    </form>
+  );
+}

package/dist/skill/reference/components/digit-input/examples/on-complete.tsx

@@ -0,0 +1,33 @@
+/** 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`. */
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+const VALID_CODE = "123456";
+
+/** The server checking the code a beat later. */
+function verifyCode(code: string) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (code === VALID_CODE) resolve();
+      else reject(new Error("Неверный код — попробуйте ещё раз"));
+    }, 900);
+  });
+}
+
+export default function DigitInputOnCompleteExample() {
+  const [verified, setVerified] = React.useState(false);
+
+  return (
+    <DigitInput
+      label="Код подтверждения входа"
+      length={6}
+      // The success look is color: the hint says it in words.
+      hint={verified ? "Код подтверждён" : `Для проверки подходит ${VALID_CODE}`}
+      onValueChange={() => setVerified(false)}
+      onComplete={async (code) => {
+        await verifyCode(code);
+        setVerified(true);
+      }}
+    />
+  );
+}

package/dist/skill/reference/components/digit-input/examples/overview.tsx

@@ -0,0 +1,6 @@
+/** A six-digit code from SMS with its label and a hint — `label`, `hint`, `length`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputOverviewExample() {
+  return <DigitInput label="Код из SMS" hint="Код действует 5 минут" length={6} />;
+}