prime-ui-kit 0.7.13 → 0.9.1

package/src/components/datepicker/COMPONENT.md

@@ -1,192 +1,224 @@
 # Datepicker
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** selection
+**Kind:** field
 
-## About
+> A calendar for picking a date or a date range: a field with a popover (`Datepicker.Root`) or an embedded panel (`Datepicker.Panel`).
 
-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
+- One date in a form or a filter (`mode="single"`): due date, shipping date, birthday.
+- A period for reports and analytics (`mode="range"`), with presets, time and an explicit Apply.
+- A calendar shown right on the page — booking, scheduling (`Datepicker.Panel`).
+- An annual day and month without a year (`yearless`).
 
-- **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
+## When not to use
+- Time of day only → use [Input](../input/COMPONENT.md) with a time mask.
+- A choice between a few fixed periods («7 дней», «30 дней») → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Select](../select/COMPONENT.md).
+- A free-text date the user types → use [Input](../input/COMPONENT.md).
 
+## Import
 ```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>
-  );
-}
+import {
+  DEFAULT_DATEPICKER_PRESETS,
+  Datepicker,
+  type DatepickerPreset,
+  type DatepickerRange,
+  datepickerPresets,
+  formatDatepickerValue,
+  YEARLESS_YEAR,
+} from "prime-ui-kit";
 ```
 
-## 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.
+## Anatomy
+```
+Datepicker.Root             field frame: label · field button (calendar icon, value, chevron) · hint / error
+└─ Popover                  the calendar panel
+Datepicker.Panel            the same panel without a field, styled as a card
+
+panel                       presets column (range) · 1–2 month grids · prompt · footer
+├─ month header             ghost icon-only Buttons (previous / next) around the month title
+├─ presets                  Buttons with aria-pressed; a scrolling row above the months when narrow
+└─ footer                   date (+ time) pairs · Сбросить / Применить Buttons
+```
 
 ## 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.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Datepicker.Root
+`ref` → `HTMLDivElement` (the field frame). A field (label, hint / error, the field button with a calendar icon, the value and a chevron) that opens the calendar panel in a Popover. Takes every calendar option below.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"single" \| "range"` | — (required) | One date or a period; sets the value type. |
+| `value` | `Date \| null  ·  DatepickerRange` | — | Controlled value: a date (`single`) or `{ from, to }` in wall-clock time (`range`); `null` — not set. |
+| `defaultValue` | `Date \| null  ·  DatepickerRange` | `null · { from: null, to: null }` | Initial value, uncontrolled. |
+| `onValueChange` | `(value) => void` | — | Called when a pick, a preset, Apply or Reset changes the value. |
+| `open` | `boolean` | — | Controlled visibility of the panel. |
+| `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | Field click, Escape, an outside press or an applied value. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier (height 28 · 32 · 36 · 40 · 48) and panel tier (day cell 24 · 28 · 32 · 36 · 40). |
+| `label` | `ReactNode` | — | Field label; part of the button's accessible name together with the value. |
+| `hint` | `ReactNode` | — | Support text under the field (`aria-describedby`). |
+| `error` | `ReactNode` | — | Error message in place of the hint; implies `invalid`. |
+| `required` | `boolean` | `false` | Red `*` after the label. |
+| `optional` | `boolean` | — | Muted `labels.optional` after the label. |
+| `invalid` | `boolean` | — | Danger ring and `aria-invalid` without a message. |
+| `disabled` | `boolean` | `false` | The field cannot be opened. |
+| `fullWidth` | `boolean` | `false` | The field stretches to its container; otherwise it fits the text. |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Popover alignment to the field. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring (`data-focus-ring="false"`). |
+| `placeholder` | `string` | `labels.placeholder` | Field text without a value for this field. |
+| `valuePrefix` | `string` | — | Text before the value, e.g. «С». |
+| `id` | `string` | — | Id of the field button; generated when omitted. |
+| `aria-label · aria-labelledby · aria-describedby` | `string` | — | Name without a `label` (the value is appended) and extra description ids. |
+| `…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). |
+
+### Datepicker.Panel
+`ref` → `HTMLDivElement`. The calendar without a field, inline in a page: its own card, 1–2 months by the parent's width. Takes `mode`, `value` / `defaultValue` / `onValueChange` like Root and every calendar option below.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className` and the other attributes of the panel card. |
+
+### Calendar options (Root · Panel)
+Shared by `Datepicker.Root` and `Datepicker.Panel`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `months` | `1 \| 2` | `1` | Months side by side; one when there is no room. |
+| `presets` | `DatepickerPreset[] \| false` | `false` | Preset column (`range` only): `DEFAULT_DATEPICKER_PRESETS` or picks from `datepickerPresets`; a row above the calendar when narrow. |
+| `prompt` | `boolean` | `false` | Step prompt under the calendar (`labels.pickStart` / `pickEnd` / `pickDate`). |
+| `footer` | `boolean` | `false` | Footer with date fields and Reset / Apply; without it a pick applies at once. |
+| `withTime` | `boolean` | `false` | Time fields in the footer (00:00 — 23:59 by default). |
+| `isDayDisabled` | `(day: Date) => boolean` | — | Days that cannot be picked. |
+| `disableFuture` | `boolean` | `false` | Future days are muted and cannot be picked. |
+| `yearless` | `boolean` | `false` | An annual day + month: no year, months wrap around inside `YEARLESS_YEAR`. |
+| `resetValue` | `Date \| null  ·  DatepickerRange` | `null · { from: null, to: null }` | Value applied by Reset. |
+| `today` | `Date` | `new Date()` | «Today» for highlighting, presets and `disableFuture`. |
+| `locale` | `Locale` | `ru` | date-fns locale of titles, weekdays and day names. |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First day of the week (1 — Monday). |
+| `labels` | `Partial<DatepickerLabels>` | — | Built-in strings, see Labels. |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 px field, 24 px day cell | dense filters | |
+| `s` | 32 px field, 28 px cell | compact toolbars | |
+| `m` | 36 px field, 32 px cell, panel buttons `s` | regular forms | yes |
+| `l` | 40 px field, 36 px cell | spacious forms | |
+| `xl` | 48 px field, 40 px cell | touch-first screens | |
+
+### mode
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `single` | one picked day with an accent fill | one date | |
+| `range` | accent edges and a soft band between them, a preview band while picking the end | periods | |
+
+### months
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `1` | one month; neighbouring days shown muted | single dates, short ranges | yes |
+| `2` | two months; one when the viewport (popover) or the parent (panel) is too narrow | ranges across months | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `presets` | «Период» column on the left (a scrolling row above when narrow); the active preset is pressed | analytics periods | `false` |
+| `prompt` | muted step line under the grid | infrequent use of ranges | `false` |
+| `footer` | dates (dd.MM.yyyy) and «Сбросить» / «Применить» | the user confirms, or with time | `false` |
+| `withTime` | HH:mm inputs in the footer | timestamps (with `footer`) | `false` |
+| `yearless` | month title without a year, value «15 октября» | annual dates | `false` |
+| `fullWidth` | the field fills its container | form columns | `false` |
+| `align` | popover at the field's start / center / end | a field near the right edge → `end` | `start` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| empty | no value | `data-empty="true"`, `labels.placeholder` (or `placeholder`) in placeholder color |
+| open | click, `open` | `data-state="open"`, `field-bg-focus` fill, the chevron turns |
+| focus-visible | keyboard | inset focus ring; none with `focusRing={false}` (`data-focus-ring="false"`) |
+| invalid | `invalid`, `error` | `data-invalid`, `aria-invalid`, inset `danger-border` ring |
+| disabled | `disabled` | native `disabled`, `data-disabled`, `field-bg-disabled`, cannot open |
+| today | the current day | `data-today`, `aria-current="date"`, accent text |
+| selected / band | value | day `aria-pressed`, `data-edge`; cell `data-band="selected" \| "preview"`, `data-band-start` / `-end` |
+| day disabled | `isDayDisabled`, `disableFuture` | native `disabled`, muted |
+
+Panel DOM: `data-size`, `data-embedded`, `data-compact`, `data-layout` (`aside` · `stacked`). The popover follows the overlay contract: an outside press or Escape closes it, focus is trapped while open, the wheel over the panel does not scroll the page.
+
+## Layout & spacing
+- The field fits its text by default (`width: fit-content`, max 100%); in forms use `fullWidth`.
+- Label → field: the tier `label-gap`; field → field in a form: `--prime-space-5`.
+- Months gap `--prime-space-6`. An embedded panel measures its parent; narrower than one month → compact cells and footer fields above the buttons. Works from 320 px.
+- Values are wall-clock local dates; convert time zones in the app.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | On the field opens the calendar; on a day picks it. |
+| `←` · `→` | The neighbouring day. |
+| `↑` · `↓` | The same day of the neighbouring week. |
+| `Home` · `End` | Start and end of the week. |
+| `PageUp` · `PageDown` | The same day of the neighbouring month; with Shift — of the year. |
+| `Escape` | Closes the calendar and returns focus to the field. |
+
+### ARIA
+- The field is a `<button>` named by the label and the value (or `aria-label` + value); hint and error in `aria-describedby`, an error sets `aria-invalid`.
+- The popover is a `role="dialog"` with a focus trap; focus lands on the picked or today's day.
+- Every month is a table named by the month; days are buttons with the full date as name, picked ones `aria-pressed`, today `aria-current="date"`.
+- One polite live region announces the visible months («Сентябрь 2026 — Октябрь 2026») when they change; the step prompt is a polite live region too; on open the popover focuses the picked (or today's) day (`data-autofocus`); presets are a named group of buttons with `aria-pressed`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `placeholder` | `"Выбрать дату"` | Field text without a value. |
+| `pickStart` | `"Выберите начальную дату"` | Step prompt before the start of a range. |
+| `pickEnd` | `"Выберите конечную дату"` | Step prompt before the end of a range. |
+| `pickDate` | `"Выберите дату"` | Step prompt of a single date. |
+| `reset` | `"Сбросить"` | Footer reset button. |
+| `apply` | `"Применить"` | Footer apply button. |
+| `prevMonth` | `"Предыдущий месяц"` | Name of the previous-month arrow. |
+| `nextMonth` | `"Следующий месяц"` | Name of the next-month arrow. |
+| `rangeStart` | `"Начало периода"` | Name of the footer start field. |
+| `rangeEnd` | `"Конец периода"` | Name of the footer end field. |
+| `date` | `"Дата"` | Name of the footer field of a single date. |
+| `timeStart` | `"Время начала"` | Name of the start time input. |
+| `timeEnd` | `"Время конца"` | Name of the end time input. |
+| `time` | `"Время"` | Name of the time input of a single date. |
+| `until` | `"до"` | Prefix of a range without a start: «до 6 окт». |
+| `presetsTitle` | `"Период"` | Heading and group name of the presets column. |
+| `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A shipping date field: a click opens one month, a picked day applies at once — `mode`, `label`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: the field is 28 to 48 px high, the day cell of the panel 24 to 40 px — `size`. |
+| [states.tsx](examples/states.tsx) | An empty field with the default placeholder, a filled one and a disabled one — `disabled`. |
+| [validation.tsx](examples/validation.tsx) | A required leave period with a hint, the same field with an error and an optional return date — `required`, `hint`, `error`, `optional`. |
+| [range-presets.tsx](examples/range-presets.tsx) | A report period: presets aside, two months, a step prompt, time fields with Reset / Apply, no future days — `presets`, `months`, `prompt`, `footer`, `withTime`, `disableFuture`. |
+| [inline-panel.tsx](examples/inline-panel.tsx) | 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`. |
+| [yearless.tsx](examples/yearless.tsx) | An annual price change date: day and month without a year, a value prefix and taken days disabled — `yearless`, `valuePrefix`, `isDayDisabled`. |
+| [controlled.tsx](examples/controlled.tsx) | A report filter owns the period: quick buttons set it from outside, the field shows it — `value`, `onValueChange`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the panel: a reminder button opens the calendar from code, a picked day closes it — `open`, `onOpenChange`. |
+| [in-form.tsx](examples/in-form.tsx) | A leave request form: a required period that turns into an error after submit and an optional return date — `required`, `error`, `optional`. |
+| [narrow.tsx](examples/narrow.tsx) | An embedded panel in a 320 px column: one compact month instead of two, the footer fields wrap above the buttons — `months`, `footer`. |
+
+## Mistakes
+- Omitting `mode` → it is required (`"single"` or `"range"`).
+- `value={new Date()}` with `mode="range"` → pass `{ from, to }`.
+- `withTime` without `footer` → add `footer`.
+- `presets` on `mode="single"` → presets work only for ranges.
+- `hint` for the calendar step line → `hint` is the field hint; the step line is `prompt`.
+- A status badge inside the field → put a Badge next to the field or use `hint`.
+- Converting values to UTC inside the component → values are wall-clock dates; convert in the app.
 
 ## 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)
+- **Built from:** [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md)
+- **See also:** [Input](../input/COMPONENT.md), [Select](../select/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -0,0 +1,32 @@
+/** The parent owns the panel: a reminder button opens the calendar from code, a picked day closes it — `open`, `onOpenChange`. */
+import { Button, Datepicker } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TODAY = new Date(2026, 9, 7);
+
+export default function DatepickerControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+  const [date, setDate] = React.useState<Date | null>(null);
+
+  return (
+    <>
+      <Datepicker.Root
+        mode="single"
+        label="Дата отгрузки"
+        value={date}
+        onValueChange={setDate}
+        open={open}
+        onOpenChange={setOpen}
+        today={TODAY}
+        fullWidth
+      />
+      <div className={styles.actions}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+          Указать дату отгрузки
+        </Button.Root>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,26 @@
+/* Layout of the Datepicker scenarios: semantic tokens only. */
+
+/* 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 {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}
+
+/* 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

@@ -0,0 +1,44 @@
+/** 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 [period, setPeriod] = React.useState<DatepickerRange>({ from: null, to: null });
+  const [submitted, setSubmitted] = React.useState(false);
+  const missing = submitted && (!period.from || !period.to);
+
+  return (
+    <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

@@ -0,0 +1,8 @@
+/** 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 [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

@@ -0,0 +1,14 @@
+/** 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";
+
+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/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

@@ -0,0 +1,22 @@
+/** 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 [period, setPeriod] = React.useState<DatepickerRange>({ from: null, to: null });
+  return (
+    <Datepicker.Root
+      mode="range"
+      label="Период отчёта"
+      value={period}
+      onValueChange={setPeriod}
+      months={2}
+      presets={DEFAULT_DATEPICKER_PRESETS}
+      prompt
+      footer
+      withTime
+      disableFuture
+      placeholder="Выбрать период"
+    />
+  );
+}