prime-ui-kit 0.9.0 → 0.9.2

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

@@ -0,0 +1,39 @@
+/** A report filter owns the period: quick buttons set it from outside, the field shows it — `value`, `onValueChange`. */
+import { Button, Datepicker, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TODAY = new Date(2026, 9, 7);
+const LAST_WEEK: DatepickerRange = {
+  from: new Date(2026, 8, 30),
+  to: new Date(2026, 9, 6, 23, 59, 59, 999),
+};
+const NO_PERIOD: DatepickerRange = { from: null, to: null };
+
+export default function DatepickerControlledExample() {
+  const [period, setPeriod] = React.useState<DatepickerRange>(LAST_WEEK);
+
+  return (
+    <>
+      <Datepicker.Root
+        mode="range"
+        label="Период отчёта"
+        value={period}
+        onValueChange={setPeriod}
+        today={TODAY}
+        months={2}
+        placeholder="Выбрать период"
+        fullWidth
+      />
+      <div className={styles.actions}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setPeriod(LAST_WEEK)}>
+          Прошлая неделя
+        </Button.Root>
+        <Button.Root variant="ghost" tone="neutral" onClick={() => setPeriod(NO_PERIOD)}>
+          Сбросить
+        </Button.Root>
+      </div>
+    </>
+  );
+}

package/src/components/datepicker/examples/examples.module.css

@@ -1,30 +1,15 @@
-/* Example layout: semantic tokens only. */
+/* Layout of the Datepicker scenarios: semantic tokens only. */
 
-.row {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: var(--prime-space-3);
-}
-
-.grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(calc(var(--prime-space-24) * 2.5), 1fr));
-  gap: var(--prime-space-5) var(--prime-space-4);
-  width: 100%;
-}
-
-/* A 320px phone-width column: the panel measures the column and shows one compact month. */
-.phone {
-  width: calc(var(--prime-space-20) * 4);
-  max-width: 100%;
+/* A form in a Card. */
+.formCard {
+  width: min(100%, calc(var(--prime-space-24) * 5));
 }
 
 .form {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-5);
+  padding: var(--prime-card-padding-m);
 }
 
 .actions {
@@ -34,7 +19,8 @@
   gap: var(--prime-space-2);
 }
 
-.card {
-  width: 100%;
-  max-width: calc(var(--prime-space-24) * 5);
+/* A 320 px phone column: the panel measures it and shows one compact month. */
+.phone {
+  width: calc(var(--prime-space-20) * 4);
+  max-width: 100%;
 }

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

@@ -1,57 +1,44 @@
-/** 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. */
+/** A leave request form: a required period that turns into an error after submit and an optional return date — `required`, `error`, `optional`. */
 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 [period, setPeriod] = React.useState<DatepickerRange>({ from: null, to: null });
   const [submitted, setSubmitted] = React.useState(false);
-  const missing = submitted && (!range.from || !range.to);
+  const missing = submitted && (!period.from || !period.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 className={styles.formCard}>
+      <form
+        className={styles.form}
+        onSubmit={(event) => {
+          event.preventDefault();
+          setSubmitted(true);
+        }}
+      >
+        <Datepicker.Root
+          mode="range"
+          label="Период отпуска"
+          required
+          hint="Не больше 28 дней подряд"
+          error={missing ? "Укажите начало и конец отпуска" : undefined}
+          value={period}
+          onValueChange={setPeriod}
+          months={2}
+          footer
+          placeholder="Выбрать период"
+          fullWidth
+        />
+        <Datepicker.Root mode="single" label="Выход на работу" optional fullWidth />
+        <div className={styles.actions}>
+          <Button.Root variant="ghost" tone="neutral">
+            Отмена
+          </Button.Root>
+          <Button.Root type="submit">Отправить заявку</Button.Root>
+        </div>
+      </form>
     </Card.Root>
   );
 }

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

@@ -1,8 +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. */
+/** A booking calendar embedded in the page: its own card, two months when the parent has room, the range applies at once — `Datepicker.Panel`, `months`, `prompt`. */
 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 />;
+  const [stay, setStay] = React.useState<DatepickerRange>({ from: null, to: null });
+  return <Datepicker.Panel mode="range" value={stay} onValueChange={setStay} months={2} prompt />;
 }

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

@@ -1,4 +1,4 @@
-/** 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. */
+/** An embedded panel in a 320 px column: one compact month instead of two, the footer fields wrap above the buttons — `months`, `footer`. */
 import { Datepicker, type DatepickerRange } from "prime-ui-kit";
 import * as React from "react";
 

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

@@ -0,0 +1,6 @@
+/** A shipping date field: a click opens one month, a picked day applies at once — `mode`, `label`. */
+import { Datepicker } from "prime-ui-kit";
+
+export default function DatepickerOverviewExample() {
+  return <Datepicker.Root mode="single" label="Дата отгрузки" />;
+}

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

@@ -1,21 +1,22 @@
-/** A report period: presets aside, two months, step prompt, time fields and Reset / Apply, future days disabled. Use it for analytics and report filters. */
+/** A report period: presets aside, two months, a step prompt, time fields with Reset / Apply, no future days — `presets`, `months`, `prompt`, `footer`, `withTime`, `disableFuture`. */
 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 });
+  const [period, setPeriod] = React.useState<DatepickerRange>({ from: null, to: null });
   return (
     <Datepicker.Root
       mode="range"
-      value={range}
-      onValueChange={setRange}
+      label="Период отчёта"
+      value={period}
+      onValueChange={setPeriod}
       months={2}
       presets={DEFAULT_DATEPICKER_PRESETS}
       prompt
       footer
       withTime
       disableFuture
-      aria-label="Период"
+      placeholder="Выбрать период"
     />
   );
 }

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

@@ -1,25 +1,22 @@
-/** 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. */
+/** 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";
-import * as React from "react";
-
-import styles from "./examples.module.css";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+const INVOICE_DATE = new Date(2026, 9, 7);
 
 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}`}
+          label={size}
+          defaultValue={INVOICE_DATE}
+          fullWidth
         />
       ))}
-    </div>
+    </>
   );
 }

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

@@ -1,41 +1,20 @@
-/** 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";
+/** An empty field with the default placeholder, a filled one and a disabled one — `disabled`. */
+import { Datepicker } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
+const CONTRACT_DATE = new Date(2026, 8, 15);
 
 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="empty" fullWidth />
+      <Datepicker.Root mode="single" label="default" defaultValue={CONTRACT_DATE} fullWidth />
       <Datepicker.Root
         mode="single"
-        label="Отключено"
-        value={filled}
-        onValueChange={setFilled}
+        label="disabled"
+        defaultValue={CONTRACT_DATE}
         disabled
         fullWidth
       />
-    </div>
+    </>
   );
 }

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

@@ -1,19 +1,20 @@
-/** 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. */
+/** 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";
-import * as React from "react";
+
+const TAKEN_DAYS = [
+  new Date(YEARLESS_YEAR, 9, 1).getTime(),
+  new Date(YEARLESS_YEAR, 9, 31).getTime(),
+];
 
 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"
+      label="Ежегодное изменение цены"
       yearless
-      value={date}
-      onValueChange={setDate}
+      defaultValue={new Date(YEARLESS_YEAR, 9, 15)}
       valuePrefix="С"
-      isDayDisabled={(day) => taken.includes(day.getTime())}
-      aria-label="Дата изменения цены"
+      isDayDisabled={(day) => TAKEN_DAYS.includes(day.getTime())}
     />
   );
 }

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

@@ -1,15 +1,16 @@
 # DigitInput
 
 **Category:** inputs
+**Kind:** field
 
-> A row of square single-digit cells for a fixed-length code (OTP from SMS, PIN, pickup code).
+> 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`.
+- 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"`.
 
@@ -18,25 +19,46 @@
 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
 
-### 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`.
+<!-- 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"` | `"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. |
+| `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. |
 | `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>`. |
+| `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 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`.
@@ -44,23 +66,26 @@ 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 | |
+| `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 | |
 
-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.
+**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.
 
-### invalid
+### Flags
 | 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 | |
+| `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: `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.
+- 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
@@ -69,51 +94,64 @@ Digits are semibold and tabular; on `s`–`xl` they are one type step larger tha
 | 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 |
+| 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 fieldset and every cell. Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (+ `onValueChange` to observe).
+`data-size` is set on the frame, 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).
+- 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
-- 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 |
+### 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 fieldset |
-| `cell` | `"Цифра {index} из {length}"` | Accessible name of each cell; `{index}` (1-based) and `{length}` are replaced |
+| `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
-| 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 |
-
-```tsx
-import { DigitInput } from "prime-ui-kit";
-
-export function SmsCode() {
-  return <DigitInput.Root length={6} labels={{ group: "Код из SMS" }} onComplete={console.log} />;
-}
-```
+| 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) | 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 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.
+- `<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
-- [Input](../input/COMPONENT.md) — free-form single-line values.
-- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — label and message around 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)