prime-ui-kit 0.7.13 → 0.9.1

package/src/components/datepicker/examples/sizes.tsx

@@ -0,0 +1,22 @@
+/** Every size tier: the field is 28 to 48 px high, the day cell of the panel 24 to 40 px — `size`. */
+import { Datepicker } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+const INVOICE_DATE = new Date(2026, 9, 7);
+
+export default function DatepickerSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <Datepicker.Root
+          key={size}
+          size={size}
+          mode="single"
+          label={size}
+          defaultValue={INVOICE_DATE}
+          fullWidth
+        />
+      ))}
+    </>
+  );
+}

package/src/components/datepicker/examples/states.tsx

@@ -0,0 +1,20 @@
+/** An empty field with the default placeholder, a filled one and a disabled one — `disabled`. */
+import { Datepicker } from "prime-ui-kit";
+
+const CONTRACT_DATE = new Date(2026, 8, 15);
+
+export default function DatepickerStatesExample() {
+  return (
+    <>
+      <Datepicker.Root mode="single" label="empty" fullWidth />
+      <Datepicker.Root mode="single" label="default" defaultValue={CONTRACT_DATE} fullWidth />
+      <Datepicker.Root
+        mode="single"
+        label="disabled"
+        defaultValue={CONTRACT_DATE}
+        disabled
+        fullWidth
+      />
+    </>
+  );
+}

package/src/components/datepicker/examples/validation.tsx

@@ -0,0 +1,26 @@
+/** A required leave period with a hint, the same field with an error and an optional return date — `required`, `hint`, `error`, `optional`. */
+import { Datepicker } from "prime-ui-kit";
+
+export default function DatepickerValidationExample() {
+  return (
+    <>
+      <Datepicker.Root
+        mode="range"
+        label="Период отпуска"
+        required
+        hint="Не больше 28 дней подряд"
+        placeholder="Выбрать период"
+        fullWidth
+      />
+      <Datepicker.Root
+        mode="range"
+        label="Период отпуска"
+        required
+        error="Укажите начало и конец отпуска"
+        placeholder="Выбрать период"
+        fullWidth
+      />
+      <Datepicker.Root mode="single" label="Выход на работу" optional fullWidth />
+    </>
+  );
+}

package/src/components/datepicker/examples/yearless.tsx

@@ -0,0 +1,20 @@
+/** An annual price change date: day and month without a year, a value prefix and taken days disabled — `yearless`, `valuePrefix`, `isDayDisabled`. */
+import { Datepicker, YEARLESS_YEAR } from "prime-ui-kit";
+
+const TAKEN_DAYS = [
+  new Date(YEARLESS_YEAR, 9, 1).getTime(),
+  new Date(YEARLESS_YEAR, 9, 31).getTime(),
+];
+
+export default function DatepickerYearlessExample() {
+  return (
+    <Datepicker.Root
+      mode="single"
+      label="Ежегодное изменение цены"
+      yearless
+      defaultValue={new Date(YEARLESS_YEAR, 9, 15)}
+      valuePrefix="С"
+      isDayDisabled={(day) => TAKEN_DAYS.includes(day.getTime())}
+    />
+  );
+}

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

@@ -1,116 +1,157 @@
 # DigitInput
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** inputs
+**Kind:** field
 
-## Canonical
+> 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.
 
-- **Import:** `import { DigitInput } from "prime-ui-kit"`.
-- **Surface:** только **`DigitInput.Root`** — горизонтальный ряд ячеек (`<fieldset>` + несколько `<input>`).
-- **Значение:** одна строка из цифр; длина задаётся **`length`** (по умолчанию **`4`**).
-- **Размер ячеек:** **`size`**: `"s"` \| `"m"` \| `"l"` \| `"xl"` (по умолчанию **`m`**).
-- **Режимы:** контролируемый (`value` + `onChange`) или неконтролируемый (`defaultValue`); опционально **`onComplete`**, **`disabled`**, **`hasError`**, **`className`**.
-- **Подписи и ошибки:** снаружи — [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md); встроенных слотов нет.
-- **Playground:** секция **`playground/sections/DigitInputSection.tsx`**; исходники демо — **`playground/snippets/digit-input/*.tsx`** (импорты **`@/`**). Сниппеты **`playground/snippets/slider-digit/`** относятся к **Slider** с режимом «цифры», а не к **DigitInput**.
-- **Примеры для копирования:** [`examples/`](./examples/) — продуктовые сценарии и зеркала сниппетов с импортом **`prime-ui-kit`**.
+## 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.
 
-## Extended
-
-### About
-
-`DigitInput` — один OTP-стиль контроль: горизонтальный ряд полей по одному символу, общая строка цифр, вставка из буфера и автоматический перенос фокуса между ячейками.
-
-- **Use** for short numeric codes (SMS/OTP, PIN, pickup codes) where one digit per box matches user expectations.
-- **Use** when you want `inputMode="numeric"`, `maxLength={1}` per cell, and `autoComplete="one-time-code"` without wiring it yourself.
-- **Use** with `onComplete` to react once the user fills all cells (for example, submit or advance a step).
-- **Do not use** for alphanumeric codes; non-digit characters are stripped on type and paste.
-- **Do not use** when a single full-width numeric field is enough — prefer [Input](../input/COMPONENT.md) or app-level masking.
-- **Do not use** for free-form numbers (amounts, phone as one field); this component is fixed-length, one digit per slot.
-- **Do not expect** arrow keys to move between cells; only typing, Backspace on an empty cell, and pointer focus apply.
-
-### Playground snippets
-
-Демо совпадают по порядку и смыслу с **`playground/sections/DigitInputSection.tsx`**. В сниппетах — импорты **`@/`**; зеркальные рецепты с **`prime-ui-kit`** — в **`examples/`** (та же разметка и пропы, раскладка через простой column flex и токены отступов).
-
-| Блок | Сниппет | Зеркало в `examples/` |
-| ---- | ------- | ---------------------- |
-| **Размеры** | [`sizes.tsx`](../../../playground/snippets/digit-input/sizes.tsx) | [`sizes.tsx`](./examples/sizes.tsx) — **`size`** **`s`**, **`m`**, **`l`**, **`xl`** при **`length={4}`** и одинаковом **`defaultValue`** для сравнения масштаба. |
-| **Состояния** | [`states.tsx`](../../../playground/snippets/digit-input/states.tsx) | [`states.tsx`](./examples/states.tsx) — без флагов, **`hasError`**, **`disabled`**. |
-| **Контролируемый режим** | [`controlled.tsx`](../../../playground/snippets/digit-input/controlled.tsx) | [`controlled.tsx`](./examples/controlled.tsx) — **`value`** + **`onChange`**, подпись со строкой и счётчиком **`(n/4)`**. |
-| **Композиция** | [`composition.tsx`](../../../playground/snippets/digit-input/composition.tsx) | [`composition.tsx`](./examples/composition.tsx) — **[Label](../label/COMPONENT.md)** + **DigitInput** + **[Hint](../hint/COMPONENT.md)** без слотов на корне. |
-| **Специфичные фичи** | [`features.tsx`](../../../playground/snippets/digit-input/features.tsx) | [`features.tsx`](./examples/features.tsx) — разные **`length`** / **`defaultValue`**, демо **`onComplete`** после последней цифры. |
-
-### Composition
-
-- Public API is **`DigitInput.Root` only** (`DigitInput = { Root }`). There are no inner slots (`Label`, `Icon`, etc.) on this component.
-- The root renders a native **`fieldset`** with `aria-label="Digit input"` and **`length`** separate `<input type="text">` cells (`inputMode="numeric"`, `maxLength={1}`, `autoComplete="one-time-code"`).
-- Pair captions and helper text with [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) **outside** the root; there is no built-in link from one label to a single control id.
-
-### Minimal example
+## 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";
-
-export function OneTimeCode() {
-  return <DigitInput.Root />;
-}
 ```
 
-### Scenarios (recipes)
-
-Продуктовые сценарии (импорт **`prime-ui-kit`**). Для построчного соответствия демо плейграунда см. **Playground snippets** выше.
-
-| Сценарий | Файл |
-| -------- | ---- |
-| Вход по SMS / OTP, `length={6}`, контролируемое значение, подсказка про вставку | [`examples/otp-login.tsx`](./examples/otp-login.tsx) |
-| PIN, крупные ячейки для тача (`size="l"`) | [`examples/pin.tsx`](./examples/pin.tsx) |
-| Шаг верификации: код + кнопка «Продолжить» до заполнения | [`examples/verification-step.tsx`](./examples/verification-step.tsx) |
-| Неверный код: `hasError` и `Hint` с `variant="error"` | [`examples/error-state.tsx`](./examples/error-state.tsx) |
-| Повторная отправка кода и сброс поля через родительское состояние | [`examples/resend-and-clear.tsx`](./examples/resend-and-clear.tsx) |
-
-### Rules
-
-- **Controlled:** pass `value` and `onChange`; the live string is always normalized to digits only and truncated to `length`.
-- **Uncontrolled:** use `defaultValue` (defaults to `""`); still pass `onChange` if you need to observe updates.
-- **`onChange`** receives the full normalized digit string after each edit (not only the last key).
-- **`onComplete`** fires **once** when the string length becomes `length` **after** having been shorter; editing digits while already full does not fire it again until the value is shortened below `length` and filled again.
-- **Paste** at any cell fills forward from that index; non-digits are dropped; focus moves to the last filled or last cell.
-- **Backspace** on an **empty** cell moves focus to the previous cell (it does not delete the previous digit by itself).
-- **After typing a digit** in a cell, focus moves to the next cell when one exists.
-- **`disabled`** disables every cell; **`hasError`** drives error styling on the root via `data-has-error`.
-- **No portal, no polymorphic root, no `variant`:** visual scale is only `size` (`s` | `m` | `l` | `xl`); width follows cell layout, not a `fullWidth` prop.
-
-## LLM note
-
-- Для разметки и комбинаций пропов сначала смотри **`playground/snippets/digit-input/*.tsx`** и зеркала **`examples/sizes.tsx`**, **`states.tsx`**, **`controlled.tsx`**, **`composition.tsx`**, **`features.tsx`**.
-- Нормализация: в **`value` / `onChange` / paste** нецифровые символы **удаляются**, строка **обрезается** до **`length`**. Алфавитно-цифровые коды **не поддерживаются**.
-- **`onComplete(value)`** вызывается **один раз**, когда длина строки **впервые** стала **`length`**, будучи до этого **меньше**; при редактировании уже полной строки без укорочения **не** вызывается снова.
-- **Backspace** на **пустой** ячейке только **переносит фокус** назад; **не** стирает предыдущую цифру автоматически.
-- После ввода цифры фокус **переходит вперёд** (если есть следующая ячейка). **Стрелки** между ячейками **не** обрабатываются.
-- **Paste** с любой ячейки: цифры подставляются **вперёд** от индекса; нецифры отбрасываются.
-- Каждая ячейка: **`inputMode="numeric"`**, **`maxLength={1}`**, **`autoComplete="one-time-code"`** (задано в реализации).
-- Нет **`fullWidth`**, **`variant`**, портала и полиморфного корня; ошибка только через **`hasError`** → `data-has-error` на корне.
+## 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
 
-### DigitInput.Root
-
-| Prop           | Type                        | Default | Required | Description                                                                 |
-| -------------- | --------------------------- | ------- | -------- | --------------------------------------------------------------------------- |
-| `length`       | `number`                    | `4`     | No       | Number of cells (one digit per cell).                                       |
-| `size`         | `"s" \| "m" \| "l" \| "xl"` | `"m"`   | No       | Visual size of cells (control tokens).                                      |
-| `value`        | `string`                    | —       | No       | Controlled value; non-digits stripped, truncated to `length`.               |
-| `defaultValue` | `string`                    | `""`    | No       | Initial value in uncontrolled mode (normalized the same way).               |
-| `onChange`     | `(value: string) => void`   | —       | No       | Called with the normalized digit string on every change.                    |
-| `disabled`     | `boolean`                   | —       | No       | Disables all cells.                                                         |
-| `hasError`     | `boolean`                   | —       | No       | Error styling for the group (`data-has-error` on the root).                |
-| `onComplete`   | `(value: string) => void`   | —       | No       | Called when the value first reaches full `length` from a shorter string.   |
-| `className`    | `string`                    | —       | No       | Class name on the root `fieldset`.                                          |
-
-Exported composite: `DigitInput = { Root }`. Types: `DigitInputRootProps`, `DigitInputSize`.
+<!-- 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 with the side of the control height (28 · 32 · 36 · 40 · 48); label and hint follow it. 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. |
+| `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` | — | Called once when the last empty cell is filled (typing, paste or autofill). |
+| `fullWidth` | `boolean` | `false` | Cells share the container width 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` | 28 × 28 cells, radius 6, digits 12/16, gap 4 | Inline confirmation inside dense tables or popovers | |
+| `s` | 32 × 32 cells, radius 8, digits 14/20, gap 8 | Compact dialogs | |
+| `m` | 36 × 36 cells, radius 8, digits 16/24, gap 8 | Regular forms and modals | yes |
+| `l` | 40 × 40 cells, radius 10, digits 18/24, gap 8 | Standalone verification screens | |
+| `xl` | 48 × 48 cells, radius 12, digits 20/28, gap 12 | Full-page sign-in, mobile-first screens | |
+
+**Sizes:** digits are semibold and tabular, one type step larger than the tier text (`xs` uses the tier text). A cell of size T is as high as Input and Button of size T; the label and the hint take the same tier.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | one row, cells share the width, tier height | cards, forms and 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: `error` set after a rejected code and cleared in `onValueChange`; `onComplete` to check the code as soon as it is filled.
+- 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 + inset focus ring; its content is selected so a new digit replaces it |
+| filled cell | a digit in the cell | `data-filled="true"` on the cell |
+| 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 |
+| 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`.
+- 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`. |
+
+## 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 with the side of the control height — `size`. |
+| [states.tsx](examples/states.tsx) | A default code next to a disabled one — `disabled`. |
+| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint and an error that replaces it — `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 as soon as the last cell is filled; a wrong code turns the hint into an error — `onComplete`, `error`. |
+| [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 PIN shows an error — `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`.
 
 ## Related
-
-- [Label](../label/COMPONENT.md) — caption for the code group (place beside or above the fieldset).
-- [Hint](../hint/COMPONENT.md) — validation or timing hints under the cells.
-- [Input](../input/COMPONENT.md) — single-line text or number entry without fixed cells.
-- [Button](../button/COMPONENT.md) — actions such as clear, resend, or continue next to the code.
+- **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/src/components/digit-input/examples/controlled.tsx

@@ -1,26 +1,23 @@
-import { DigitInput } from "prime-ui-kit";
+/** 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";
 
-/**
- * Значение держит родитель: `value` и `onChange`; подпись показывает прогресс заполнения.
- * Паритет с `playground/snippets/digit-input/controlled.tsx`.
- */
+import styles from "./examples.module.css";
+
 export default function DigitInputControlledExample() {
-  const [code, setCode] = React.useState("");
+  const [code, setCode] = React.useState("73");
 
   return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-s)",
-        alignItems: "flex-start",
-      }}
-    >
-      <DigitInput.Root length={4} value={code} onChange={setCode} />
-      <p style={{ margin: 0 }}>
-        Собранная строка: {code.length > 0 ? code : "пусто"} ({code.length}/4)
-      </p>
+    <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/src/components/digit-input/examples/examples.module.css

@@ -0,0 +1,17 @@
+/* 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));
+}
+
+/* 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/src/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/src/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/src/components/digit-input/examples/in-form.tsx

@@ -0,0 +1,35 @@
+/** A masked card PIN submitted with a form; a short PIN shows an error — `name`, `mask`, `required`, `error`. */
+import { Button, DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PIN_LENGTH = 4;
+
+export default function DigitInputInFormExample() {
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const pin = String(new FormData(event.currentTarget).get("pin") ?? "");
+    setError(pin.length === PIN_LENGTH ? undefined : "Введите все четыре цифры");
+  };
+
+  return (
+    <form className={styles.panel} noValidate onSubmit={submit}>
+      <DigitInput
+        label="PIN-код карты"
+        name="pin"
+        length={PIN_LENGTH}
+        mask
+        required
+        fullWidth
+        error={error}
+        onValueChange={() => setError(undefined)}
+      />
+      <Button.Root type="submit" fullWidth>
+        Привязать карту
+      </Button.Root>
+    </form>
+  );
+}

package/src/components/digit-input/examples/on-complete.tsx

@@ -0,0 +1,20 @@
+/** The code is checked as soon as the last cell is filled; a wrong code turns the hint into an error — `onComplete`, `error`. */
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+const VALID_CODE = "123456";
+
+export default function DigitInputOnCompleteExample() {
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <DigitInput
+      label="Код подтверждения входа"
+      length={6}
+      hint={`Для проверки подходит ${VALID_CODE}`}
+      error={error}
+      onValueChange={() => setError(undefined)}
+      onComplete={(code) => setError(code === VALID_CODE ? undefined : "Неверный код")}
+    />
+  );
+}

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

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

@@ -1,23 +1,14 @@
+/** Every size; the cell is a square with the side of the control height — `size`. */
 import { DigitInput } from "prime-ui-kit";
 
-/**
- * Четыре размера ячеек: `size` s, m, l, xl — те же токены контролов, что у поля ввода.
- * Паритет с `playground/snippets/digit-input/sizes.tsx`.
- */
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
 export default function DigitInputSizesExample() {
   return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-m)",
-        alignItems: "center",
-      }}
-    >
-      <DigitInput.Root size="s" length={4} defaultValue="1234" />
-      <DigitInput.Root size="m" length={4} defaultValue="1234" />
-      <DigitInput.Root size="l" length={4} defaultValue="1234" />
-      <DigitInput.Root size="xl" length={4} defaultValue="1234" />
-    </div>
+    <>
+      {SIZES.map((size) => (
+        <DigitInput key={size} size={size} label={size} defaultValue="2048" />
+      ))}
+    </>
   );
 }

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

@@ -1,22 +1,11 @@
+/** A default code next to a disabled one — `disabled`. */
 import { DigitInput } from "prime-ui-kit";
 
-/**
- * Обычное поле, визуальная ошибка (`hasError`) и отключённый ввод (`disabled`).
- * Паритет с `playground/snippets/digit-input/states.tsx`.
- */
 export default function DigitInputStatesExample() {
   return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-m)",
-        alignItems: "center",
-      }}
-    >
-      <DigitInput.Root length={4} defaultValue="42" />
-      <DigitInput.Root length={4} defaultValue="12" hasError />
-      <DigitInput.Root length={4} defaultValue="99" disabled />
-    </div>
+    <>
+      <DigitInput label="default" defaultValue="42" />
+      <DigitInput label="disabled" defaultValue="42" disabled />
+    </>
   );
 }

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

@@ -0,0 +1,17 @@
+/** Required and optional markers, a hint and an error that replaces it — `required`, `optional`, `hint`, `error`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputValidationExample() {
+  return (
+    <>
+      <DigitInput label="Код из письма" required hint="Проверьте папку «Спам»" length={6} />
+      <DigitInput
+        label="Код подтверждения"
+        required
+        defaultValue="1111"
+        error="Неверный код, осталось 2 попытки"
+      />
+      <DigitInput label="Код приглашения" optional />
+    </>
+  );
+}