prime-ui-kit 0.14.0 → 0.16.0

package/src/components/datepicker/COMPONENT.md

@@ -25,6 +25,7 @@ import {
   type DatepickerRange,
   datepickerPresets,
   formatDatepickerValue,
+  formatDateValue,
   YEARLESS_YEAR,
 } from "prime-ui-kit";
 ```
@@ -46,22 +47,24 @@ panel                       presets column (range) · 1–2 month grids · promp
 <!-- 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.
+`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.
 
 | 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. |
+| `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). |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the calendar and returns focus to the field. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press outside the calendar and the field closes it; focus follows the pointer. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Field tier (height 28 · 32 · 36 · 40 · 48) and panel tier (day cell 24 · 28 · 32 · 36 · 40). Without it the tier of its host, else `m`. |
 | `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. |
+| `required` | `boolean` | `false` | Red `*` after the label; the field button is described by `labels.required` (a button takes no `aria-required`). |
 | `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. |
@@ -73,20 +76,31 @@ panel                       presets column (range) · 1–2 month grids · promp
 | `id` | `string` | — | Id of the field button; generated when omitted. |
 | `name` | `string` | — | Submits the value with a form through hidden inputs: `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` with `withTime`); a range submits two values under the name, `from` then `to` (empty for an open bound). |
 | `aria-label · aria-labelledby · aria-describedby` | `string` | — | Name without a `label` (the value is appended) and extra description ids. |
+| `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` | today | «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. |
 | `…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, as the host's own content (a Drawer sheet, a Card); 1–2 months by the host's width. Takes `mode`, the value triad 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. |
-
-### Calendar options (Root · Panel)
-Shared by `Datepicker.Root` and `Datepicker.Panel`.
+`ref` → `HTMLDivElement`. The calendar without a field, as the host's own content (a Drawer sheet, a Card); 1–2 months by the host's width. Takes `mode`, the value triad and every calendar option.
 
 | 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. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Panel tier (day cell 24 · 28 · 32 · 36 · 40). Without it the tier of its host, else `m`. |
 | `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`). |
@@ -95,11 +109,19 @@ Shared by `Datepicker.Root` and `Datepicker.Panel`.
 | `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`. |
+| `resetValue` | `Date \| null  ·  DatepickerRange` | `null` · `{ from: null, to: null }` | Value applied by Reset. |
+| `today` | `Date` | today | «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. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className` and the other attributes of the panel. |
+
+### Functions
+
+#### `formatDateValue(date, { withTime })`
+`(date: Date, options?: { withTime?: boolean }) => string`
+
+A date as a form submits it, in local time: `yyyy-MM-dd`, with `withTime` `yyyy-MM-ddTHH:mm` (the value of a `name`d field) — never `toISOString()`, which shifts the day to UTC.
 
 ## Variants
 
@@ -133,35 +155,40 @@ Shared by `Datepicker.Root` and `Datepicker.Panel`.
 | `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` |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | Mark the minority of the form | `false` / — |
+| `align` | popover at the field's start / center / end; `auto` takes the edge with more room | a field near the right edge → `end` | `auto` |
+| `closeOnOutsideClick` | `false`: a press beside the calendar keeps it open with its draft | a `footer` draft the person must apply or reset | `true` |
+| `closeOnEscape` | `false`: Escape leaves the calendar open | the calendar must close only by Apply or Reset | `true` |
 
 ## 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"`) |
+| open | click, `open` / `defaultOpen` | `data-state="open"`, `field-bg-hover` fill, the chevron turns |
+| focus-visible | keyboard | inset focus ring; none with `focusRing` off (`data-focus-ring="false"`) |
 | invalid | `invalid`, `error` | `data-invalid`, `aria-invalid`, inset `danger-border` ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | 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` |
+| today | the current day | `aria-current="date"`, accent text |
+| selected / band | value | day `aria-pressed` (accent text), `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. The panel of `Datepicker.Root` mounts only while the popover is open, so every opening starts from the current value; nothing is rendered for it while closed.
+Panel DOM: `data-size`, `data-embedded`, `data-compact`, `data-layout` (`aside` · `stacked`). The footer row carries `data-time` with `withTime`; a footer field never shrinks below its whole date and time — the fields wrap above the actions, and in a footer narrower than 22rem with time they stand one under the other. 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. The panel of `Datepicker.Root` mounts only while the popover is open, so every opening starts from the current value; nothing is rendered for it while closed.
 
 Committing: without `footer` a picked day (or the second day of a range) applies at once and closes the popover; with `footer` the pick stays a draft until «Применить», and «Сбросить» sets `resetValue` (else empty) and closes. A preset applies its period at once, with or without `footer`. With `name`, hidden inputs submit `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` with `withTime`); a range submits `from`, then `to`.
 
 ## 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`.
+- Label → field: the tier `label-gap`; field → field in a form: the gap of a label-less `Fieldset`.
 - `align="auto"`: a field near the end of the screen lines up the popover's end edge and the panel grows toward the start, and the other way near the start; a fixed `align` still flips at the screen edge.
-- Months gap `--prime-space-6`. `Datepicker.Panel` has no fill, padding or radius — the host is its container; it shows 1–2 months by the host's width with day columns spread across it. An embedded panel measures its parent; narrower than one month → compact cells and footer fields above the buttons. Works from 320 px.
+- Months gap `--prime-space-6`. `Datepicker.Panel` has no fill, padding or radius — the host is its container; it shows 1–2 months by the host's width with day columns spread across it. An embedded panel measures its parent; narrower than one month → compact cells and footer fields above the buttons. Works in a 320 px column.
 - On a coarse pointer the day cells grow to the 44 px touch target (a dense grid cannot grow an invisible hit area past its neighbours); narrower than seven of them, the columns shrink.
 - Values are wall-clock local dates; convert time zones in the app.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` | On the field opens the calendar; on a day picks it. |
@@ -172,6 +199,8 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 | `Escape` | Closes the calendar and returns focus to the field. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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"`.
@@ -199,17 +228,20 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 | `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`. |
+| `required` | `"обязательное поле"` | Read after the field name of a `required` field: its trigger is a button, which takes no `aria-required`. |
 
 ## 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`. |
+| [states.tsx](examples/states.tsx) | An empty field with the default placeholder, a filled, a disabled and an invalid one, and one whose focus shows without the ring — `disabled`, `invalid`, `focusRing`. |
 | [validation.tsx](examples/validation.tsx) | A leave period checked live: the error shakes in, names the broken rule and leaves once the period fits; 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`. |
+| [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; Reset returns the current month and the panel lines up with the field's end — `presets`, `months`, `prompt`, `footer`, `withTime`, `disableFuture`, `resetValue`, `align`. |
 | [inline-panel.tsx](examples/inline-panel.tsx) | A booking calendar embedded in a card: the card is its container, 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`. |
+| [locale.tsx](examples/locale.tsx) | A delivery window on a partner portal in English: month and weekday names from the date-fns locale, the week from Sunday and the system texts translated — `locale`, `weekStartsOn`, `labels`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A shift period with a footer: the calendar keeps the draft on a press beside it and closes by Escape, Reset or Apply — `closeOnOutsideClick`, `closeOnEscape`. |
 | [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: submit reads the period from the form data and checks it, the error shakes in and leaves once the period is fixed; an optional return date — `name`, `required`, `error`, `optional`. |
@@ -225,5 +257,5 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 - Converting values to UTC inside the component → values are wall-clock dates; convert in the app.
 
 ## Related
-- **Built from:** [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md) (month arrows, presets, Reset / Apply), [VisuallyHidden](../visually-hidden/COMPONENT.md) (month announcement), `Icon` (calendar, chevron), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md)
+- **Built from:** [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md) (month arrows, presets, Reset / Apply), [ScrollContainer](../scroll-container/COMPONENT.md) (the presets row when narrow), [VisuallyHidden](../visually-hidden/COMPONENT.md) (month announcement), `Icon` (calendar, chevron), [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/dismiss.tsx

@@ -0,0 +1,15 @@
+/** A shift period with a footer: the calendar keeps the draft on a press beside it and closes by Escape, Reset or Apply — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Datepicker } from "prime-ui-kit";
+
+export default function DatepickerDismissExample() {
+  return (
+    <Datepicker.Root
+      mode="range"
+      label="Смена склада"
+      footer
+      withTime
+      closeOnOutsideClick={false}
+      closeOnEscape
+    />
+  );
+}

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

@@ -1,20 +1,17 @@
 /* Layout of the Datepicker scenarios: semantic tokens only. */
 
-/* A form in a Card. */
-.formCard {
-  width: min(100%, calc(var(--prime-space-24) * 5));
-}
-
+/* in-form.tsx: the fields (a label-less Fieldset) → actions 32 (foundation §1). */
 .form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-space-5);
-  padding: var(--prime-card-padding-m);
+  gap: var(--prime-space-8);
+  width: min(100%, calc(var(--prime-space-24) * 5));
 }
 
 .actions {
   display: flex;
   flex-wrap: wrap;
+  align-items: center;
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }

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

@@ -1,5 +1,5 @@
 /** A leave request form: submit reads the period from the form data and checks it, the error shakes in and leaves once the period is fixed; an optional return date — `name`, `required`, `error`, `optional`. */
-import { Button, Card, Datepicker, type DatepickerRange, Typography } from "prime-ui-kit";
+import { Button, Datepicker, type DatepickerRange, Fieldset, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -12,18 +12,18 @@ export default function DatepickerInFormExample() {
   const [sent, setSent] = React.useState(false);
 
   return (
-    <Card.Root className={styles.formCard}>
-      <form
-        className={styles.form}
-        onSubmit={(event) => {
-          event.preventDefault();
-          // The range submits `from`, then `to` under its name ("2026-07-06").
-          const [from, to] = new FormData(event.currentTarget).getAll("vacation");
-          const complete = Boolean(from && to);
-          setError(complete ? undefined : "Укажите начало и конец отпуска");
-          setSent(complete);
-        }}
-      >
+    <form
+      className={styles.form}
+      onSubmit={(event) => {
+        event.preventDefault();
+        // The range submits `from`, then `to` under its name ("2026-07-06").
+        const [from, to] = new FormData(event.currentTarget).getAll("vacation");
+        const complete = Boolean(from && to);
+        setError(complete ? undefined : "Укажите начало и конец отпуска");
+        setSent(complete);
+      }}
+    >
+      <Fieldset>
         <Datepicker.Root
           mode="range"
           name="vacation"
@@ -49,26 +49,26 @@ export default function DatepickerInFormExample() {
           optional
           fullWidth
         />
+      </Fieldset>
+      <div className={styles.actions}>
         {sent ? (
           <Typography as="p" variant="body-s" tone="secondary" role="status">
             Заявка отправлена на согласование.
           </Typography>
         ) : null}
-        <div className={styles.actions}>
-          <Button.Root
-            variant="ghost"
-            tone="neutral"
-            onClick={() => {
-              setPeriod(EMPTY_PERIOD);
-              setError(undefined);
-              setSent(false);
-            }}
-          >
-            Отмена
-          </Button.Root>
-          <Button.Root type="submit">Отправить заявку</Button.Root>
-        </div>
-      </form>
-    </Card.Root>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          onClick={() => {
+            setPeriod(EMPTY_PERIOD);
+            setError(undefined);
+            setSent(false);
+          }}
+        >
+          Отмена
+        </Button.Root>
+        <Button.Root type="submit">Отправить заявку</Button.Root>
+      </div>
+    </form>
   );
 }

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

@@ -0,0 +1,35 @@
+/** A delivery window on a partner portal in English: month and weekday names from the date-fns locale, the week from Sunday and the system texts translated — `locale`, `weekStartsOn`, `labels`. */
+import { enUS } from "date-fns/locale";
+import { Datepicker, type DatepickerLabels, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+const LABELS: Partial<DatepickerLabels> = {
+  placeholder: "Pick dates",
+  pickStart: "Pick the first day",
+  pickEnd: "Pick the last day",
+  reset: "Reset",
+  apply: "Apply",
+  prevMonth: "Previous month",
+  nextMonth: "Next month",
+  rangeStart: "From",
+  rangeEnd: "To",
+  until: "until",
+};
+
+export default function DatepickerLocaleExample() {
+  const [delivery, setDelivery] = React.useState<DatepickerRange>({ from: null, to: null });
+
+  return (
+    <Datepicker.Root
+      mode="range"
+      label="Delivery window"
+      value={delivery}
+      onValueChange={setDelivery}
+      locale={enUS}
+      weekStartsOn={0}
+      labels={LABELS}
+      prompt
+      footer
+    />
+  );
+}

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

@@ -1,21 +1,30 @@
-/** A report period: presets aside, two months, a step prompt, time fields with Reset / Apply, no future days — `presets`, `months`, `prompt`, `footer`, `withTime`, `disableFuture`. */
+/** A report period: presets aside, two months, a step prompt, time fields with Reset / Apply, no future days; Reset returns the current month and the panel lines up with the field's end — `presets`, `months`, `prompt`, `footer`, `withTime`, `disableFuture`, `resetValue`, `align`. */
 import { Datepicker, type DatepickerRange, DEFAULT_DATEPICKER_PRESETS } from "prime-ui-kit";
 import * as React from "react";
 
+const NOW = new Date();
+/** The current month up to the end of today: the report's default period. */
+const THIS_MONTH: DatepickerRange = {
+  from: new Date(NOW.getFullYear(), NOW.getMonth(), 1),
+  to: new Date(NOW.getFullYear(), NOW.getMonth(), NOW.getDate(), 23, 59, 59, 999),
+};
+
 export default function DatepickerRangePresetsExample() {
-  const [period, setPeriod] = React.useState<DatepickerRange>({ from: null, to: null });
+  const [period, setPeriod] = React.useState<DatepickerRange>(THIS_MONTH);
   return (
     <Datepicker.Root
       mode="range"
       label="Период отчёта"
       value={period}
       onValueChange={setPeriod}
+      resetValue={THIS_MONTH}
       months={2}
       presets={DEFAULT_DATEPICKER_PRESETS}
       prompt
       footer
       withTime
       disableFuture
+      align="end"
       placeholder="Выбрать период"
     />
   );

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

@@ -6,7 +6,7 @@ const INVOICE_DATE = new Date(2026, 9, 7);
 
 export default function DatepickerSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
         <Datepicker.Root
           key={size}
@@ -17,6 +17,6 @@ export default function DatepickerSizesExample() {
           fullWidth
         />
       ))}
-    </>
+    </div>
   );
 }

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

@@ -1,11 +1,11 @@
-/** An empty field with the default placeholder, a filled one and a disabled one — `disabled`. */
+/** An empty field with the default placeholder, a filled, a disabled and an invalid one, and one whose focus shows without the ring — `disabled`, `invalid`, `focusRing`. */
 import { Datepicker } from "prime-ui-kit";
 
 const CONTRACT_DATE = new Date(2026, 8, 15);
 
 export default function DatepickerStatesExample() {
   return (
-    <>
+    <div>
       <Datepicker.Root mode="single" label="empty" fullWidth />
       <Datepicker.Root mode="single" label="default" defaultValue={CONTRACT_DATE} fullWidth />
       <Datepicker.Root
@@ -15,6 +15,14 @@ export default function DatepickerStatesExample() {
         disabled
         fullWidth
       />
-    </>
+      <Datepicker.Root mode="single" label="invalid" invalid fullWidth />
+      <Datepicker.Root
+        mode="single"
+        label="focusRing={false}"
+        defaultValue={CONTRACT_DATE}
+        focusRing={false}
+        fullWidth
+      />
+    </div>
   );
 }

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

@@ -1,16 +1,16 @@
 /** A leave period checked live: the error shakes in, names the broken rule and leaves once the period fits; an optional return date — `required`, `hint`, `error`, `optional`. */
+import { differenceInCalendarDays } from "date-fns";
 import { Datepicker, type DatepickerRange } from "prime-ui-kit";
 import * as React from "react";
 
 const MAX_DAYS = 28;
-const DAY_MS = 24 * 60 * 60 * 1000;
 const LONG_PERIOD: DatepickerRange = { from: new Date(2026, 6, 1), to: new Date(2026, 7, 4) };
 
 /** The period error, or nothing when both ends are set and the period fits the limit. */
 function periodError({ from, to }: DatepickerRange) {
   if (!from || !to) return "Укажите начало и конец отпуска";
-  if ((to.getTime() - from.getTime()) / DAY_MS + 1 > MAX_DAYS)
-    return "Больше 28 дней подряд нельзя";
+  // Calendar days, not hours: a period across a daylight-saving change counts right.
+  if (differenceInCalendarDays(to, from) + 1 > MAX_DAYS) return "Больше 28 дней подряд нельзя";
   return undefined;
 }
 

package/src/components/description-list/COMPONENT.md

@@ -38,8 +38,9 @@ DescriptionList.Root                 <dl>; size (host tier), orientation; a size
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else `"m"`` | Label and value type and the gap between pairs; without it the list takes the tier of its host (a Card, a Drawer, a form). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Label and value type and the gap between pairs; without it the list takes the tier of a sized host (a Drawer, a Modal). |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` — the label in a column beside its value (one third of the width), stacking below 24rem of the list's own width; `vertical` — the label above its value at any width. |
+| `align` | `"start" \| "end"` | `"start"` | `start` — values from the start of their column; `end` — each value at the end of its row in tabular figures, at any width: a summary of amounts (subtotal, tax, total). |
 | `labels` | `Partial<DescriptionListLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDListElement>` | — | `className`, `id`, `data-*` and the other attributes of the element. |
 
@@ -58,7 +59,8 @@ DescriptionList.Root                 <dl>; size (host tier), orientation; a size
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `string` | — (required) | Accessible name and tooltip of the action. |
-| `children` | `ReactNode` | — (required) | The icon (`<Icon name="…" />`). |
+| `children` | `ReactNode` | — (required) | The icon (`<Icon name="…" />`); with `asChild`, the one link whose children are the icon. |
+| `asChild` | `boolean` | `false` | The action is the child link (`mailto:`, another page) with the button look. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">` | — | `onClick`, `disabled`, `className` and the other button attributes. |
 
 ## Variants
@@ -69,6 +71,13 @@ DescriptionList.Root                 <dl>; size (host tier), orientation; a size
 | `horizontal` | the label in a column (one third of the width) beside the value; stacked below 24rem of the list's width | record details in a card or a page | yes |
 | `vertical` | the label above its value at any width | a narrow side panel, a summary of a few long values | |
 
+### align
+
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | each value from the start of its column | record details | yes |
+| `end` | the label at the start, the value at the end of the row in tabular figures, at any width | a summary of amounts: subtotal, tax, the amount due | |
+
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -79,8 +88,8 @@ DescriptionList.Root                 <dl>; size (host tier), orientation; a size
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| size / orientation | props, the host tier | `data-size`, `data-orientation` on the `<dl>` |
-| narrow | the list narrower than 24rem (container query) | each pair stacks: the label above its value |
+| size / orientation / align | props, the host tier | `data-size`, `data-orientation`, `data-align` (`end` only) on the `<dl>` |
+| narrow | the list narrower than 24rem (container query) | each pair stacks: the label above its value (not with `align="end"`) |
 | empty value | `children` is `null`, `""` or `false` | `data-empty` on the `<dd>`; muted `labels.empty`, spoken `labels.emptyText` |
 
 No motion: the list is static text; a row action has the Button's own press and hover.
@@ -89,17 +98,21 @@ No motion: the list is static text; a row action has the Button's own press and
 - The list fills its container; pairs are separated by air (8 · 12 · 16 by tier), not lines.
 - A horizontal pair: label column one third, value two thirds, 16 apart; values wrap anywhere, labels wrap too.
 - A row action sits at the end of the value, centred on its first line; it does not make the row taller.
-- Inside a `Card.Body` or a `Drawer` the list takes the host tier; do not pass `size` there.
+- Inside a `Drawer` or a `Modal` the list takes the host tier; do not pass `size` there. A `Card` gives no tier: the list is `m` unless `size` is set.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves to the row actions (`DescriptionList.ItemAction`); the pairs themselves are not focusable. |
 | `Enter` · `Space` | Runs the row action. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The list is a `<dl>`: the label is a `<dt>`, the value a `<dd>`; screen readers read each pair as a term and its definition.
 - An empty value shows a muted `labels.empty` (hidden from assistive tech) and is read as `labels.emptyText`.
 - A row action is named by its `label`, which is also its tooltip; the icon is decorative.
@@ -117,16 +130,19 @@ No motion: the list is static text; a row action has the Button's own press and
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A client's details in a card: labels beside values, a long address that wraps, an empty manager and a copy action — `DescriptionList.Item`, `label`, `DescriptionList.ItemAction`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier changes the label and value type and the gap between pairs — `size`. |
-| [structure.tsx](examples/structure.tsx) | Optional pieces of a pair: a Badge or a link as the value, a row action and an empty value with its own mark — `DescriptionList.ItemAction`, `labels`. |
+| [structure.tsx](examples/structure.tsx) | Optional pieces of a pair: a Badge or a link as the value, a row action that is a link and an empty value with its own mark — `DescriptionList.ItemAction`, `asChild`, `labels`. |
 | [vertical.tsx](examples/vertical.tsx) | Labels above their values at any width, for a side panel of a record — `orientation`. |
-| [narrow.tsx](examples/narrow.tsx) | In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap. |
+| [totals.tsx](examples/totals.tsx) | The totals of an invoice: every amount at the end of its row in tabular figures, the amount due a step larger — `align`. |
+| [narrow.tsx](examples/narrow.tsx) | In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap — `DescriptionList.Item`, `label`. |
+| [screen.tsx](examples/screen.tsx) | A nested record: the path, the title with its status and due date and the record's actions by weight in the app header, a main column with the line items and their totals and a side column with the client's details and the history — `align`, `orientation`. |
 
 ## Mistakes
 - A grid of `Typography` pairs or a two-column table for record details → `DescriptionList`: the `<dl>` semantics and the stacking come with it.
 - `""` or «—» typed by hand for a missing value → pass nothing; the list shows `labels.empty` and speaks `labels.emptyText`.
 - A copy button placed after the list or inside the label → `DescriptionList.ItemAction` inside the item, at the end of its value.
 - A viewport media query to stack the pairs → the list adapts to its own width already.
+- A hand-made `<dl>` with `justify-content: space-between` for invoice totals → `align="end"`.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md) (`ItemAction`), [Tooltip](../tooltip/COMPONENT.md) (the action's `label`)
+- **Built from:** [Button](../button/COMPONENT.md) (`ItemAction`), [Tooltip](../tooltip/COMPONENT.md) (the action's `label`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Card](../card/COMPONENT.md) (the surface the list usually sits in), [Drawer](../drawer/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Timeline](../timeline/COMPONENT.md)

package/src/components/description-list/examples/examples.module.css

@@ -2,37 +2,17 @@
 
 /* overview.tsx: a record card as wide as a dialog of size m. */
 .card {
-  width: min(100%, var(--prime-modal-width-m));
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
-/* structure.tsx: a column as wide as a short form. */
+/* structure.tsx, totals.tsx: a column as wide as a short form. */
 .column {
-  width: min(100%, var(--prime-modal-width-s));
-}
-
-/* sizes.tsx: one tier per block, its caption right under it, blocks apart. */
-.sizes {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-s));
-}
-
-.size {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-  min-width: 0;
-}
-
-.size > :first-child {
-  align-self: stretch;
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* vertical.tsx: a record side panel. */
 .side {
-  width: min(100%, var(--prime-drawer-width-s));
+  width: min(100%, var(--prime-layout-narrow-width));
 }
 
 /* narrow.tsx: 320 px, the smallest supported viewport. */

package/src/components/description-list/examples/narrow.tsx

@@ -1,4 +1,4 @@
-/** In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap. */
+/** In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap — `DescriptionList.Item`, `label`. */
 import { Card, DescriptionList } from "prime-ui-kit";
 
 import styles from "./examples.module.css";