prime-ui-kit 0.7.11 → 0.9.0

package/src/components/datepicker/examples/in-form.tsx

@@ -0,0 +1,57 @@
+/** A leave request in a card: a required range with a hint that turns into an error after submit, and an optional single date. Use it for date fields inside forms. */
+import { Button, Card, Datepicker, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DatepickerInFormExample() {
+  const [range, setRange] = React.useState<DatepickerRange>({ from: null, to: null });
+  const [returnDay, setReturnDay] = React.useState<Date | null>(null);
+  const [submitted, setSubmitted] = React.useState(false);
+  const missing = submitted && (!range.from || !range.to);
+
+  return (
+    <Card.Root variant="panel" className={styles.card}>
+      <Card.SectionHeader>
+        <Card.SectionTitle>Заявка на отпуск</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <form
+          className={styles.form}
+          onSubmit={(event) => {
+            event.preventDefault();
+            setSubmitted(true);
+          }}
+        >
+          <Datepicker.Root
+            mode="range"
+            label="Период"
+            required
+            hint="Не больше 28 дней подряд"
+            error={missing ? "Укажите начало и конец отпуска" : undefined}
+            value={range}
+            onValueChange={setRange}
+            months={2}
+            footer
+            placeholder="Выбрать период"
+            fullWidth
+          />
+          <Datepicker.Root
+            mode="single"
+            label="Выход на работу"
+            optional
+            value={returnDay}
+            onValueChange={setReturnDay}
+            fullWidth
+          />
+          <div className={styles.actions}>
+            <Button.Root variant="ghost" tone="neutral">
+              Отмена
+            </Button.Root>
+            <Button.Root type="submit">Отправить</Button.Root>
+          </div>
+        </form>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/datepicker/examples/inline-panel.tsx

@@ -0,0 +1,8 @@
+/** Datepicker.Panel embedded in the page: its own card, two months when the parent has room, the range applies at once. Use it on booking and scheduling pages. */
+import { Datepicker, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+export default function DatepickerInlinePanelExample() {
+  const [range, setRange] = React.useState<DatepickerRange>({ from: null, to: null });
+  return <Datepicker.Panel mode="range" value={range} onValueChange={setRange} months={2} prompt />;
+}

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

@@ -0,0 +1,14 @@
+/** An embedded panel in a 320px column: one compact month instead of two, footer fields wrap above the buttons. Use it to check mobile layouts. */
+import { Datepicker, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DatepickerNarrowExample() {
+  const [range, setRange] = React.useState<DatepickerRange>({ from: null, to: null });
+  return (
+    <div className={styles.phone}>
+      <Datepicker.Panel mode="range" value={range} onValueChange={setRange} months={2} footer />
+    </div>
+  );
+}

package/src/components/datepicker/examples/range-presets.tsx

@@ -0,0 +1,21 @@
+/** A report period: presets aside, two months, step prompt, time fields and Reset / Apply, future days disabled. Use it for analytics and report filters. */
+import { Datepicker, type DatepickerRange, DEFAULT_DATEPICKER_PRESETS } from "prime-ui-kit";
+import * as React from "react";
+
+export default function DatepickerRangePresetsExample() {
+  const [range, setRange] = React.useState<DatepickerRange>({ from: null, to: null });
+  return (
+    <Datepicker.Root
+      mode="range"
+      value={range}
+      onValueChange={setRange}
+      months={2}
+      presets={DEFAULT_DATEPICKER_PRESETS}
+      prompt
+      footer
+      withTime
+      disableFuture
+      aria-label="Период"
+    />
+  );
+}

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

@@ -0,0 +1,16 @@
+/** A single date without a footer: one month, a click on a day applies the value at once. Use it for one-off dates in filters and forms. */
+import { Datepicker } from "prime-ui-kit";
+import * as React from "react";
+
+export default function DatepickerSingleExample() {
+  const [date, setDate] = React.useState<Date | null>(null);
+  return (
+    <Datepicker.Root
+      mode="single"
+      value={date}
+      onValueChange={setDate}
+      placeholder="Дата продажи"
+      aria-label="Дата продажи"
+    />
+  );
+}

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

@@ -0,0 +1,25 @@
+/** All five size tiers sharing one value: field height 28–48, day cell 24–40. Use it to line the field up with Input, Select and Button of the same size. */
+import { Datepicker } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function DatepickerSizesExample() {
+  const [date, setDate] = React.useState<Date | null>(new Date());
+  return (
+    <div className={styles.row}>
+      {SIZES.map((size) => (
+        <Datepicker.Root
+          key={size}
+          size={size}
+          mode="single"
+          value={date}
+          onValueChange={setDate}
+          aria-label={`Дата, размер ${size}`}
+        />
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,41 @@
+/** Empty, filled, error and disabled fields with labels and hints. Use it as a reference for every field state. */
+import { Datepicker, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DatepickerStatesExample() {
+  const [filled, setFilled] = React.useState<Date | null>(new Date());
+  const [range, setRange] = React.useState<DatepickerRange>({ from: null, to: null });
+
+  return (
+    <div className={styles.grid}>
+      <Datepicker.Root mode="single" label="Пусто" hint="Плейсхолдер «Выбрать дату»" fullWidth />
+      <Datepicker.Root
+        mode="single"
+        label="Выбрано"
+        value={filled}
+        onValueChange={setFilled}
+        fullWidth
+      />
+      <Datepicker.Root
+        mode="range"
+        label="Ошибка"
+        required
+        error="Укажите период отпуска"
+        value={range}
+        onValueChange={setRange}
+        placeholder="Выбрать период"
+        fullWidth
+      />
+      <Datepicker.Root
+        mode="single"
+        label="Отключено"
+        value={filled}
+        onValueChange={setFilled}
+        disabled
+        fullWidth
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,19 @@
+/** An annual day-and-month date (yearless) with a value prefix and taken days disabled via isDayDisabled. Use it for birthdays, anniversaries and yearly schedules. */
+import { Datepicker, YEARLESS_YEAR } from "prime-ui-kit";
+import * as React from "react";
+
+export default function DatepickerYearlessExample() {
+  const [date, setDate] = React.useState<Date | null>(new Date(YEARLESS_YEAR, 9, 15));
+  const taken = [new Date(YEARLESS_YEAR, 9, 1).getTime(), new Date(YEARLESS_YEAR, 9, 31).getTime()];
+  return (
+    <Datepicker.Root
+      mode="single"
+      yearless
+      value={date}
+      onValueChange={setDate}
+      valuePrefix="С"
+      isDayDisabled={(day) => taken.includes(day.getTime())}
+      aria-label="Дата изменения цены"
+    />
+  );
+}

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

@@ -1,116 +1,119 @@
 # DigitInput
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** inputs
 
-## Canonical
+> A row of square single-digit cells for a fixed-length code (OTP from SMS, PIN, pickup code).
 
-- **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` на корне.
-
 ## API
 
 ### DigitInput.Root
+Leaf component. Renders a `<fieldset>` with one `<input>` per digit. No ref forwarding, no native props passthrough besides those listed. There is no `label`/`hint`/`error` prop: place [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) next to it and link the hint with `aria-describedby`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `length` | `number` | `4` | Number of cells. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Cell side = control height of the tier; gap = tier gap. |
+| `value` | `string` | — | Controlled value; non-digits are dropped, cut to `length`. |
+| `defaultValue` | `string` | `""` | Uncontrolled initial value (normalized the same way). |
+| `onValueChange` | `(value: string) => void` | — | Called with the joined digit string on every change. |
+| `onComplete` | `(value: string) => void` | — | Called once when the last empty cell gets filled. |
+| `disabled` | `boolean` | — | Disables the fieldset and every cell. |
+| `invalid` | `boolean` | — | Danger ring and danger digits on every cell, `aria-invalid` on cells. |
+| `focusRing` | `boolean` | `true` | `false` sets `data-focus-ring="false"` on the fieldset and hides only the visual ring of the focused cell; focus, keyboard, ARIA and the invalid ring stay. |
+| `aria-describedby` | `string` | — | Id(s) of the hint / error text describing the group. |
+| `labels` | `Partial<DigitInputLabels>` | see Accessibility | Accessible names of the group and the cells. |
+| `className` | `string` | — | Class on the `<fieldset>`. |
+
+## 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 | |
+
+Digits are semibold and tabular; on `s`–`xl` they are one type step larger than the tier text, on `xs` they use the `xs` tier text (12/16). **Sizes:** a cell of size T is as high as Input and Button of size T, so the code and its submit button line up in one row.
+
+### invalid
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` / unset | Field fill, primary digits | Normal entry | yes |
+| `true` | Danger inset ring on every cell, danger digits, danger focus ring | The code was rejected; pair with an error Hint | |
+
+**Combinations**
+- Recommended: `invalid` + `Hint.Root invalid` linked via `aria-describedby`; reset `invalid` in `onValueChange` when the user edits.
+- Pointless: `invalid` together with `disabled` (disabled look wins); `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 |
+| invalid | `invalid` | `data-invalid="true"` on the fieldset, `aria-invalid="true"` on cells |
+| disabled | `disabled` | `data-disabled="true"` and native `disabled` on the fieldset, every cell disabled |
+| no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the fieldset |
+
+`data-size` is set on the fieldset and every cell. Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (+ `onValueChange` to observe).
+
+## Layout & spacing
+- Cells are centered and wrap if the row does not fit.
+- Label → code: `--prime-space-2`; code → hint: `--prime-space-1`–`--prime-space-2` (foundation proximity).
+- Put the submit button below or next to the code; with the same `size` it lines up with the cells.
+
+## Accessibility
+- The fieldset is named by `labels.group`; set it to the visible label text (e.g. "Код из SMS").
+- Each cell has its own name from `labels.cell` and `inputMode="numeric"`, `autoComplete="one-time-code"`, `maxLength={1}`.
+- Keyboard: a digit moves focus to the next cell; Backspace in an empty cell moves back; ← / → move between cells without editing; paste fills consecutive cells from the current one and drops non-digits.
+
+| `labels` key | Default | Used for |
+|---|---|---|
+| `group` | `"Код"` | Accessible name of the fieldset |
+| `cell` | `"Цифра {index} из {length}"` | Accessible name of each cell; `{index}` (1-based) and `{length}` are replaced |
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` side by side | Picking a size |
+| [states.tsx](examples/states.tsx) | Empty, partial, filled, `invalid`, `disabled` | Checking all states |
+| [surfaces.tsx](examples/surfaces.tsx) | Cells following the surface fill | Code fields in cards and popovers |
+| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` with a reset button | Clearing or validating from outside |
+| [length-and-complete.tsx](examples/length-and-complete.tsx) | `length={6}`, `onComplete`, keyboard and paste | Auto-submit when complete |
+| [verification-step.tsx](examples/verification-step.tsx) | Sign-in confirmation card with Label, Hint/error, resend and submit | Full OTP screen |
 
-| 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`.                                          |
+```tsx
+import { DigitInput } from "prime-ui-kit";
 
-Exported composite: `DigitInput = { Root }`. Types: `DigitInputRootProps`, `DigitInputSize`.
+export function SmsCode() {
+  return <DigitInput.Root length={6} labels={{ group: "Код из SMS" }} onComplete={console.log} />;
+}
+```
 
-## Related
+## Mistakes
+- `<DigitInput.Root label="Код" />` → there is no `label` prop; render `Label.Root` next to it and set `labels.group`.
+- Showing the error only by color → add a `Hint.Root invalid` with text and link it via `aria-describedby`.
+- Keeping `invalid` after the user starts editing → clear it in `onValueChange`.
+- Expecting letters to be accepted → only digits are kept; use Input for alphanumeric codes.
 
-- [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.
+## Related
+- [Input](../input/COMPONENT.md) — free-form single-line values.
+- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — label and message around the code.

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

@@ -1,26 +1,32 @@
-import { DigitInput } from "prime-ui-kit";
+/** The parent owns the code (`value` + `onValueChange`), so a button can reset it. Use it when the code must be cleared or validated from outside. */
+import { Button, DigitInput, Typography } 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("");
 
   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.cell}>
+      <DigitInput.Root
+        length={4}
+        value={code}
+        onValueChange={setCode}
+        labels={{ group: "PIN-код" }}
+      />
+      <Typography.Root variant="caption" tone="muted">
+        Значение: {code.length > 0 ? code : "пусто"} ({code.length}/4)
+      </Typography.Root>
+      <Button.Root
+        variant="ghost"
+        tone="neutral"
+        size="s"
+        disabled={code.length === 0}
+        onClick={() => setCode("")}
+      >
+        Очистить
+      </Button.Root>
     </div>
   );
 }

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

@@ -0,0 +1,50 @@
+/* Layout helpers for the DigitInput examples. Semantic tokens only. */
+
+.sizesRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-6);
+}
+
+.cell {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+.statesGrid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
+  justify-items: center;
+  gap: var(--prime-space-6) var(--prime-space-5);
+  width: 100%;
+  max-width: var(--prime-modal-width-l);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--prime-space-2);
+}
+
+.card {
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-2);
+}

package/src/components/digit-input/examples/length-and-complete.tsx

@@ -0,0 +1,30 @@
+/** `length`, `onComplete` and keyboard navigation (typing, Backspace, arrow keys, paste). Use `onComplete` to submit the code as soon as the last cell is filled. */
+import { DigitInput, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DigitInputLengthAndCompleteExample() {
+  const [completed, setCompleted] = React.useState<string | null>(null);
+
+  return (
+    <div className={styles.statesGrid}>
+      <div className={styles.cell}>
+        <DigitInput.Root length={6} defaultValue="12" labels={{ group: "Код из шести цифр" }} />
+        <Typography.Root variant="caption" tone="muted">
+          length=6 · ← → ходят по ячейкам
+        </Typography.Root>
+      </div>
+      <div className={styles.cell}>
+        <DigitInput.Root
+          length={4}
+          onComplete={setCompleted}
+          labels={{ group: "Код подтверждения" }}
+        />
+        <Typography.Root variant="caption" tone="muted">
+          {completed ? `onComplete: ${completed}` : "Введите или вставьте 4 цифры"}
+        </Typography.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -1,23 +1,26 @@
-import { DigitInput } from "prime-ui-kit";
+/** Five tiers in a row: the cell is square with the side equal to the control height (28 · 32 · 36 · 40 · 48). Match the size of the surrounding buttons and inputs. */
+import { DigitInput, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-/**
- * Четыре размера ячеек: `size` s, m, l, xl — те же токены контролов, что у поля ввода.
- * Паритет с `playground/snippets/digit-input/sizes.tsx`.
- */
 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 className={styles.sizesRow}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.cell}>
+          <DigitInput.Root
+            size={size}
+            length={4}
+            defaultValue="2048"
+            labels={{ group: `Код, ${size}` }}
+          />
+          <Typography.Root variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
     </div>
   );
 }