prime-ui-kit 0.0.1

package/src/components/datepicker/COMPONENT.md

@@ -0,0 +1,192 @@
+# Datepicker
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Composite pieces for picking a calendar date or range: a size-aware shell, a day grid built on react-day-picker with kit styling, optional quick presets, optional time inputs, and a caption-sized text wrapper. Pass `locale` and formatting from **date-fns** (or compatible) so labels match your UI language.
+
+- **When to use** — booking, scheduling, or any task where users choose one day or a from–to range from a calendar grid.
+- **When to use** — filters and reports that pair the grid with quick presets and optional time fields in the same shell.
+- **When to use** — forms that need a short caption (`Datepicker.Value`) tied to picker scale and tone.
+- **When not to use** — free-text or partial dates (use a plain or masked [Input](../input/COMPONENT.md) instead).
+- **When not to use** — always-visible full calendars as default page chrome; open the shell from a trigger in [Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md), or [Drawer](../drawer/COMPONENT.md).
+- **When not to use** — month- or year-only picking without days (use a slimmer control or native inputs).
+
+## Canonical
+
+- **Exports** — `Datepicker` (`Shell`, `Calendar`, `Presets`, `Time`, `Value`), `formatTimeInputValue`, `mergeTimeIntoDate`, and types including **`DateRange`** (re-exported from react-day-picker).
+- **Hierarchy** — `Datepicker.Shell` is the panel root; **`Datepicker.Calendar` must be inside `Shell`** (directly or nested) so `size` context resolves.
+- **Selection** — `Calendar` forwards **react-day-picker** `DayPicker` props: `mode="single"` or `mode="range"`, `selected`, `onSelect`, `disabled`, `locale`, etc.
+- **Presets** — Pass `Datepicker.Presets` as **`Shell`’s `presets` prop**; `Presets` **`mode`** (`"single"` | `"range"`) must match the calendar **`mode`**.
+- **Layout** — `Calendar` supports **`responsiveMonths`** (ignores `numberOfMonths` when `true`) and **`responsiveBreakpoints.twoColumns`** (default **500** px). Default **`weekStartsOn`** is **1** (Monday).
+- **Popover** — Typical pattern: `Datepicker.Shell` inside **`Popover.Content`** with **`insetPadding="none"`**.
+- **Presets `title`** — Typed on `Datepicker.Presets` but **not rendered** in the UI.
+- **Time** — `Datepicker.Time` keeps `input type="time"` **disabled** until the anchor date exists (`value`, or `from` / `to` in range mode).
+
+## Extended
+
+### Playground snippets
+
+Demos match **`playground/sections/DatepickerSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/datepicker/`**:
+
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Sizes** | [`sizes.tsx`](../../../playground/snippets/datepicker/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/datepicker/sizes.module.css)) | Four **`Datepicker.Shell`** / **`Calendar`** **`size`** values (**`s`**–**`xl`**), each in its own **`Popover`**. |
+| **Variants and modes** | [`variants-modes.tsx`](../../../playground/snippets/datepicker/variants-modes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/datepicker/sizes.module.css)) | **`mode="single"`** vs **`mode="range"`** with separate triggers. |
+| **States** | [`states.tsx`](../../../playground/snippets/datepicker/states.tsx) | **`disabled`** by day of week; **`Calendar`** + **`Datepicker.Time`** (time inputs disabled until a date exists). |
+| **Responsive months** | [`responsive-months.tsx`](../../../playground/snippets/datepicker/responsive-months.tsx) | **`responsiveMonths`**, **`responsiveBreakpoints`**; preview uses **`examplePreviewBleed`** for container width. |
+| **Controlled value** | [`controlled-value.tsx`](../../../playground/snippets/datepicker/controlled-value.tsx) | Controlled **`selected`** / **`onSelect`**; **`Datepicker.Value`**; popover closes after a date is chosen. |
+| **Composition** | [`composition.tsx`](../../../playground/snippets/datepicker/composition.tsx) | **`Shell`** **`presets`**, **`Calendar`**, **`Time`**, **`Value`** in one panel; shared parent state. |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/datepicker/full-width.tsx) | Wide **`Popover.Content`** and **`Datepicker.Shell className="min-w-0"`** with **`responsiveMonths`**. |
+| **Trigger with icon** | [`popover.tsx`](../../../playground/snippets/datepicker/popover.tsx) | Calendar icon on **`Popover.Trigger`**; close after single-date select. |
+| **Range presets + time** | [`range-presets-time.tsx`](../../../playground/snippets/datepicker/range-presets-time.tsx) | **`mode="range"`** on **`Calendar`** and **`Presets`**; **`Datepicker.Time`** with **`mode="range"`**. |
+
+### Scenarios (recipes)
+
+Runnable **`prime-ui-kit`** examples under **`examples/`** (type-checked with the library build). Copy into your app and wire spacing/theme (see [Label](../label/COMPONENT.md) for the label primitive).
+
+| Scenario | File |
+|----------|------|
+| **Booking (stay + time)** — **`mode="range"`** on **`Calendar`** and **`Presets`**, **`Datepicker.Time`** **`mode="range"`**; presets for short stays and windows | [`booking.tsx`](./examples/booking.tsx) (`BookingDateRangeExample`) |
+| **Birthdate** — **`mode="single"`**, **`disabled`** for future days, **`Datepicker.Value`**, default month near a sensible year when empty | [`birthdate.tsx`](./examples/birthdate.tsx) (`BirthdateSingleExample`) |
+| **Range (reports / filters)** — **`numberOfMonths={2}`** or **`responsiveMonths`**; presets such as this month / last month / last N days | [`range-report.tsx`](./examples/range-report.tsx) (`ReportRangeExample`) |
+| **Full-width form field** — **`Button.Root fullWidth`** as **`Popover.Trigger`**; wide **`Popover.Content`** and **`Shell className="min-w-0"`** | [`full-width-form.tsx`](./examples/full-width-form.tsx) (`FullWidthFormDateExample`) |
+
+Snippet-level demos (internal **`@/`** imports) are listed in **Playground snippets** above.
+
+## LLM note
+
+- Playground order and copy mirror **`playground/sections/DatepickerSection.tsx`**; runnable snippet sources live in **`playground/snippets/datepicker/`**.
+- Always compose **`Datepicker.Shell` → `Datepicker.Calendar`** at minimum; never use **`Calendar` without `Shell`** in real UIs if you rely on **`size`** context (default **`m`** on `Shell`).
+- For overlays, default to **[Popover](../popover/COMPONENT.md)** with **`insetPadding="none"`** on content unless the design system specifies otherwise.
+- **Controlled state:** bind **`selected`** and **`onSelect`** from react-day-picker; for range, state type is **`DateRange | undefined`**.
+- **Do not** mix **`Presets` `mode="range"`** with **`Calendar` `mode="single"`** (or the reverse) in one shell.
+- **Do not** invent a **`title`** UI for **`Datepicker.Presets`** — it is not implemented.
+- Pass **`locale`** from **date-fns** (`import { ru } from "date-fns/locale"`) into **`Calendar`** for localized month/weekday labels.
+- Month navigation **`aria-label`** strings on the kit nav buttons are **English**; override via **`Calendar` `components`** if the product language must match.
+- **Utilities:** use **`formatTimeInputValue`** / **`mergeTimeIntoDate`** only when integrating custom time inputs; **`Datepicker.Time`** already uses them.
+
+## Composition
+
+- **`Datepicker.Shell`** — Root wrapper: sets `DatepickerSize` context, owns `requestedMonth` / `requestMonth` for syncing the grid month when presets fire. Optional **`presets`** renders a bottom row after **`children`**.
+- **`Datepicker.Calendar`** — Must live under `Shell` (directly or nested) so `size` context resolves. Forwards **react-day-picker** `DayPicker` props; kit adds `responsiveMonths`, `responsiveBreakpoints`, and `size`.
+- **`Datepicker.Presets`** — Optional; usually passed as `Shell`’s `presets` prop. Calls `requestMonth` when a preset is chosen so the visible month follows the selection.
+- **`Datepicker.Time`** — Optional; place as a child of `Shell` (e.g. under or beside `Calendar`). Single mode merges time into one `Date`; range mode uses `from` / `to` and separate change handlers.
+- **`Datepicker.Value`** — Optional caption: `Typography.Root` with picker-scale typography; default `tone` is `muted`.
+
+### Minimal example
+
+```tsx
+import { enUS } from "date-fns/locale";
+import { Datepicker } from "prime-ui-kit";
+
+export function DatepickerMinimal() {
+  return (
+    <Datepicker.Shell>
+      <Datepicker.Calendar locale={enUS} mode="single" />
+    </Datepicker.Shell>
+  );
+}
+```
+
+## Rules
+
+- Prefer **`Datepicker.Shell` inside [Popover](../popover/COMPONENT.md) `Content`** (often with `insetPadding="none"` on `Content`) opened from a trigger that shows the current value; the calendar is large and focus-heavy for inline page defaults.
+- **Controlled vs uncontrolled** — Drive selection with **`selected`** and **`onSelect`** from react-day-picker (and optional **`month`** / **`onMonthChange`**) when the parent must own state; otherwise rely on day-picker internal state where types allow.
+- **`responsiveMonths`** — When `true`, **`numberOfMonths` is ignored**; the kit measures the calendar viewport and switches between one and two columns using **`responsiveBreakpoints.twoColumns`** (default **500** px).
+- **Presets** — Use **`mode="single"`** or **`mode="range"`** per instance; do not mix range presets with single calendar mode in one `Presets`. The **`title`** prop exists on the type but **is not rendered** in the component.
+- **Time fields** — **`Datepicker.Time`** disables `input type="time"` until the anchor date exists (`value` in single mode; `from` / `to` in range mode). Default labels are Russian (**«Время»**, **«Начало»**, **«Конец»**); override via **`labels`**.
+- **Accessibility** — Day grid roles and keyboard navigation come from react-day-picker; month nav uses [Button](../button/COMPONENT.md) with English **`aria-label`** strings in the kit—replace via **`components`** / **`classNames`** on `Calendar` if your product language differs. Ensure the popover trigger has an accessible name. Time row uses **`useId`**-scoped labels on [Input](../input/COMPONENT.md).
+- **Styling and layout** — The module imports **`react-day-picker/style.css`**. **`responsiveMonths`** depends on container width; in tight flex layouts without **`min-width: 0`**, width can clip—check popover and grid CSS.
+- **Time zones** — Behavior follows local `Date` instances and how the browser shows **`type="time"`**; UTC shifts are the app’s responsibility.
+
+## API
+
+### Datepicker.Calendar
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | from `Shell` context, else `m` | No | Cell typography, nav buttons, and control scale. |
+| responsiveMonths | `boolean` | `false` | No | If `true`, `numberOfMonths` is ignored; column count follows viewport width. |
+| responsiveBreakpoints | `{ twoColumns: number }` | `{ twoColumns: 500 }` | No | Pixel width at which the layout uses two month columns. |
+| weekStartsOn | `0`–`6` | `1` | No | First weekday column (0 = Sunday). |
+| navLayout | `DayPicker` nav layout | `"after"` | No | Month navigation placement (react-day-picker). |
+| month | `Date` | — | No | Displayed month (controlled when set). |
+| onMonthChange | `(d: Date) => void` | — | No | Month changes; also notifies `Shell` month context. |
+| numberOfMonths | `number` | `1` | No | Fixed month count when `responsiveMonths` is not `true`. |
+| classNames, components, style | `DayPicker` props | — | No | Merged with kit defaults; custom `components` extend kit chevron and month caption. |
+| mode, selected, onSelect, disabled, locale, … | `DayPickerProps` | — | Varies | Other react-day-picker props are forwarded to `DayPicker`. |
+
+### Datepicker.Shell
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `m` | No | Size context for `Calendar`, `Presets`, `Time`, and `Value`. |
+| presets | `ReactNode` | — | No | Bottom bar (commonly `Datepicker.Presets`). |
+| children | `ReactNode` | — | Yes | Main panel content (`Calendar`, `Time`, `Value`, etc.). |
+| className | `string` | — | No | Root element class. |
+
+### Datepicker.Presets
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| mode | `"single" \| "range"` | — | Yes | Selects preset shape and `onSelect` signature. |
+| presets | `DatepickerPresetSingle[]` or `DatepickerPresetRange[]` | — | Yes | Quick actions; single items use `{ label, date }`, range items use `{ label, range }`. |
+| onSelect | `(date: Date \| undefined) => void` or `(range: DateRange \| undefined) => void` | — | Yes | Invoked when a preset button is pressed; updates shell month from the preset anchor. |
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | [ButtonGroup](../button-group/COMPONENT.md) segment size. |
+| className | `string` | — | No | Block wrapper class. |
+| title | `string` | — | No | Present in types only; not rendered. |
+
+### Datepicker.Time
+
+**Single** (default — `mode` omitted or `"single"`)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `Date \| undefined` | — | Yes | Anchor date; time field disabled when unset. |
+| onChange | `(next: Date) => void` | — | Yes | Called with date merged from `HH:mm` input. |
+| labels | `{ time?: string }` | — | No | Overrides default time label. |
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | Input size. |
+
+**Range** (`mode="range"`)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| mode | `"range"` | — | Yes | Enables two time fields. |
+| from | `Date \| undefined` | — | Yes | Start date; start time disabled when unset. |
+| to | `Date \| undefined` | — | Yes | End date; end time disabled when unset. |
+| onFromChange | `(next: Date) => void` | — | Yes | Merges time into `from`. |
+| onToChange | `(next: Date) => void` | — | Yes | Merges time into `to`. |
+| labels | `{ from?: string; to?: string }` | — | No | Overrides default range labels. |
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | Input size. |
+
+### Datepicker.Value
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | from context | No | Масштаб пикера; внутри маппится на [Typography](../typography/COMPONENT.md) `variant`. |
+| tone | `Typography` tone | `muted` | No | Передаётся в `Typography.Root`. |
+| as, weight, tracking, italic, children, className, … | `Omit<TypographyRootProps, "variant">` | — | No | Как у `Typography.Root`, но кегль задаётся через `size` пикера (см. выше). |
+
+### Utilities
+
+| Name | Signature | Description |
+|------|-----------|-------------|
+| `formatTimeInputValue` | `(date?: Date) => string` | `HH:mm` for `input type="time"` `value`. |
+| `mergeTimeIntoDate` | `(date: Date, timeHHmm: string) => Date` | New `Date` with hours and minutes from the string. |
+
+### Exported types
+
+`DatepickerCalendarProps`, `DatepickerShellProps`, `DatepickerPresetsProps`, `DatepickerTimeProps`, `DatepickerTimeSingleProps`, `DatepickerTimeRangeProps`, `DatepickerValueProps`, `DatepickerSize`, `DatepickerPresetSingle`, `DatepickerPresetRange`, and **`DateRange`** (re-exported from react-day-picker) are exported from the package alongside the component and utilities.
+
+## Related
+
+- [Popover](../popover/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [ButtonGroup](../button-group/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)
+- [Modal](../modal/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)

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

@@ -0,0 +1,43 @@
+import { format, startOfTomorrow } from "date-fns";
+import { ru } from "date-fns/locale";
+import { Button, Datepicker, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Дата рождения: один день, будущие даты отключены, подпись в масштабе пикера.
+ */
+export function BirthdateSingleExample() {
+  const [value, setValue] = React.useState<Date | undefined>();
+  const [open, setOpen] = React.useState(false);
+
+  const triggerLabel = value
+    ? format(value, "d MMMM yyyy", { locale: ru })
+    : "Укажите дату рождения";
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" variant="neutral">
+          {triggerLabel}
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom">
+        <Datepicker.Shell>
+          <Datepicker.Calendar
+            disabled={(date) => date >= startOfTomorrow()}
+            locale={ru}
+            mode="single"
+            month={value ?? new Date(2000, 0, 1)}
+            selected={value}
+            onSelect={(d) => {
+              setValue(d);
+            }}
+          />
+          <Datepicker.Value as="p">
+            {value ? format(value, "d MMMM yyyy", { locale: ru }) : "Выберите день в сетке."}
+          </Datepicker.Value>
+        </Datepicker.Shell>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

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

@@ -0,0 +1,71 @@
+import { addDays, endOfMonth, startOfMonth, subDays } from "date-fns";
+import { ru } from "date-fns/locale";
+import {
+  Button,
+  Datepicker,
+  type DatepickerPresetRange,
+  type DateRange,
+  Popover,
+} from "prime-ui-kit";
+import * as React from "react";
+
+function stayPresets(): DatepickerPresetRange[] {
+  const today = new Date();
+  const threeNightsTo = addDays(today, 3);
+  return [
+    { label: "Сегодня", range: { from: today, to: today } },
+    { label: "3 ночи", range: { from: today, to: threeNightsTo } },
+    { label: "Неделя", range: { from: today, to: addDays(today, 7) } },
+    {
+      label: "Этот месяц",
+      range: { from: startOfMonth(today), to: endOfMonth(today) },
+    },
+    {
+      label: "Прошлая неделя",
+      range: { from: subDays(today, 7), to: subDays(today, 1) },
+    },
+  ];
+}
+
+/**
+ * Бронирование: диапазон дат, быстрые пресеты и время заезда/выезда.
+ */
+export function BookingDateRangeExample() {
+  const [range, setRange] = React.useState<DateRange | undefined>();
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" variant="neutral">
+          Заезд и выезд
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom">
+        <Datepicker.Shell
+          presets={<Datepicker.Presets mode="range" presets={stayPresets()} onSelect={setRange} />}
+        >
+          <Datepicker.Calendar
+            locale={ru}
+            mode="range"
+            responsiveMonths
+            selected={range}
+            onSelect={setRange}
+          />
+          <Datepicker.Time
+            mode="range"
+            from={range?.from}
+            labels={{ from: "Заезд", to: "Выезд" }}
+            to={range?.to}
+            onFromChange={(next) => {
+              setRange((prev) => ({ from: next, to: prev?.to }));
+            }}
+            onToChange={(next) => {
+              setRange((prev) => ({ from: prev?.from, to: next }));
+            }}
+          />
+        </Datepicker.Shell>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/datepicker/examples/full-width-form.tsx

@@ -0,0 +1,52 @@
+import { format } from "date-fns";
+import { ru } from "date-fns/locale";
+import { Button, Datepicker, Label, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+const fieldStack: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--prime-sys-spacing-s)",
+  width: "100%",
+  maxWidth: "22rem",
+  minWidth: 0,
+};
+
+/**
+ * Полноширинное поле в колонке формы: триггер на всю ширину, широкая панель поповера.
+ */
+export function FullWidthFormDateExample() {
+  const [value, setValue] = React.useState<Date | undefined>();
+  const [open, setOpen] = React.useState(false);
+
+  const triggerText = value ? format(value, "d MMMM yyyy", { locale: ru }) : "Выберите дату";
+
+  return (
+    <div style={fieldStack}>
+      <Label.Root htmlFor="fw-date-trigger">Дата визита</Label.Root>
+      <Popover.Root open={open} onOpenChange={setOpen}>
+        <Popover.Trigger asChild>
+          <Button.Root fullWidth id="fw-date-trigger" mode="stroke" variant="neutral">
+            {triggerText}
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" className="min-w-[min(100vw-2rem,36rem)]" side="bottom">
+          <Datepicker.Shell className="min-w-0">
+            <Datepicker.Calendar
+              locale={ru}
+              mode="single"
+              responsiveMonths
+              selected={value}
+              onSelect={(d) => {
+                setValue(d);
+                if (d) {
+                  setOpen(false);
+                }
+              }}
+            />
+          </Datepicker.Shell>
+        </Popover.Content>
+      </Popover.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,54 @@
+import { endOfMonth, startOfMonth, subDays, subMonths } from "date-fns";
+import { enUS } from "date-fns/locale";
+import {
+  Button,
+  Datepicker,
+  type DatepickerPresetRange,
+  type DateRange,
+  Popover,
+} from "prime-ui-kit";
+import * as React from "react";
+
+function reportPresets(): DatepickerPresetRange[] {
+  const today = new Date();
+  const startPrev = startOfMonth(subMonths(today, 1));
+  const endPrev = endOfMonth(subMonths(today, 1));
+  return [
+    { label: "This month", range: { from: startOfMonth(today), to: endOfMonth(today) } },
+    { label: "Last month", range: { from: startPrev, to: endPrev } },
+    { label: "Last 30 days", range: { from: subDays(today, 29), to: today } },
+  ];
+}
+
+/**
+ * Отчётный диапазон: только календарь и пресеты (без времени).
+ */
+export function ReportRangeExample() {
+  const [range, setRange] = React.useState<DateRange | undefined>();
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" variant="neutral">
+          Report period
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" side="bottom">
+        <Datepicker.Shell
+          presets={
+            <Datepicker.Presets mode="range" presets={reportPresets()} onSelect={setRange} />
+          }
+        >
+          <Datepicker.Calendar
+            locale={enUS}
+            mode="range"
+            numberOfMonths={2}
+            selected={range}
+            onSelect={setRange}
+          />
+        </Datepicker.Shell>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

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

@@ -0,0 +1,116 @@
+# DigitInput
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+- **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`**.
+
+## 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
+
+```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
+
+| 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`.
+
+## 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.

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

@@ -0,0 +1,24 @@
+import { DigitInput, Hint, Label } from "prime-ui-kit";
+
+/**
+ * Подпись и подсказка рядом с группой ячеек — типичный блок ввода кода в форме.
+ * Паритет с `playground/snippets/digit-input/composition.tsx`.
+ */
+export default function DigitInputCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <Label.Root>Код из сообщения</Label.Root>
+      <DigitInput.Root length={4} />
+      <Hint.Root variant="default">
+        Вставьте код из буфера: цифры распределятся по ячейкам с текущей позиции.
+      </Hint.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,26 @@
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Значение держит родитель: `value` и `onChange`; подпись показывает прогресс заполнения.
+ * Паритет с `playground/snippets/digit-input/controlled.tsx`.
+ */
+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>
+  );
+}

package/src/components/digit-input/examples/error-state.tsx

@@ -0,0 +1,12 @@
+import { DigitInput, Hint, Label } from "prime-ui-kit";
+
+/** Отклонённый код: визуальная ошибка на группе и текст подсказки в тоне danger. */
+export default function ErrorStateExample() {
+  return (
+    <>
+      <Label.Root>Код подтверждения</Label.Root>
+      <DigitInput.Root defaultValue="1230" hasError length={4} />
+      <Hint.Root variant="error">Неверный код. Запросите новый или проверьте ввод.</Hint.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,30 @@
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Разная длина ряда, начальное значение, колбэк по завершении ввода.
+ * Паритет с `playground/snippets/digit-input/features.tsx`.
+ */
+export default function DigitInputFeaturesExample() {
+  const [completed, setCompleted] = React.useState<string | null>(null);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p style={{ margin: 0 }}>Пропы length и defaultValue без внешнего состояния</p>
+      <DigitInput.Root length={4} defaultValue="2184" />
+      <DigitInput.Root length={6} defaultValue="12" />
+      <p style={{ margin: 0 }}>onComplete — один раз при заполнении последней ячейки</p>
+      <DigitInput.Root length={4} onComplete={(v) => setCompleted(v)} />
+      <p style={{ margin: 0 }}>
+        {completed ? `Последний полный код: ${completed}` : "Введите четыре цифры подряд"}
+      </p>
+    </div>
+  );
+}