prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/components/data-table/examples/sizes.tsx

@@ -1,8 +1,6 @@
 /** Every density: rows from 36 to 52 px, the head at the control height of the tier — `size`. */
 import { Badge, DataTable, type DataTableColumn, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 type Invoice = { id: string; client: string; paid: boolean; amount: number };
 
 const INVOICES: Invoice[] = [
@@ -24,9 +22,9 @@ const COLUMNS: DataTableColumn<Invoice>[] = [
     header: "Статус",
     cell: (row) =>
       row.paid ? (
-        <Badge.Root color="green">Оплачен</Badge.Root>
+        <Badge.Root tone="success">Оплачен</Badge.Root>
       ) : (
-        <Badge.Root color="orange">Ожидает</Badge.Root>
+        <Badge.Root tone="warning">Ожидает</Badge.Root>
       ),
   },
   { id: "amount", header: "Сумма", numeric: true, cell: (row) => RUB.format(row.amount) },
@@ -36,21 +34,23 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DataTableSizesExample() {
   return (
-    <div className={styles.specimens}>
+    <>
       {SIZES.map((size) => (
-        <div key={size} className={styles.specimen}>
-          <DataTable
-            size={size}
-            columns={COLUMNS}
-            rows={INVOICES}
-            getRowKey={(row) => row.id}
-            paging="none"
-          />
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
+        <div key={size}>
+          <div>
+            <DataTable
+              size={size}
+              columns={COLUMNS}
+              rows={INVOICES}
+              getRowKey={(row) => row.id}
+              paging="none"
+            />
+            <Typography as="span" variant="caption" tone="muted">
+              {size}
+            </Typography>
+          </div>
         </div>
       ))}
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/data-table/examples/states.tsx

@@ -1,8 +1,6 @@
-/** Loading skeleton, an empty period and a load error with a retry: the head stays, only the body changes — `loading`, `loadingRows`, `empty`, `error`. */
+/** Loading skeleton, an empty period and a load error with a retry: the head stays, only the body changes — `loading`, `loadingRows`, `empty`, `loadError`. */
 import { Button, DataTable, type DataTableColumn, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 type Payment = { id: string; payer: string; amount: number };
 
 const COLUMNS: DataTableColumn<Payment>[] = [
@@ -16,34 +14,44 @@ const NO_PAYMENTS: Payment[] = [];
 export default function DataTableStatesExample() {
   return (
     <>
-      <div className={styles.specimen}>
-        <DataTable columns={COLUMNS} rows={NO_PAYMENTS} loading loadingRows={3} />
-        <Typography as="span" variant="caption" tone="muted">
-          loading · loadingRows=&#123;3&#125;
-        </Typography>
+      <div>
+        <div>
+          <DataTable columns={COLUMNS} rows={NO_PAYMENTS} loading loadingRows={3} />
+          <Typography as="span" variant="caption" tone="muted">
+            loading · loadingRows=&#123;3&#125;
+          </Typography>
+        </div>
       </div>
-      <div className={styles.specimen}>
-        <DataTable columns={COLUMNS} rows={NO_PAYMENTS} empty="Платежей за выбранный период нет" />
-        <Typography as="span" variant="caption" tone="muted">
-          empty
-        </Typography>
+      <div>
+        <div>
+          <DataTable
+            columns={COLUMNS}
+            rows={NO_PAYMENTS}
+            empty="Платежей за выбранный период нет"
+          />
+          <Typography as="span" variant="caption" tone="muted">
+            empty
+          </Typography>
+        </div>
       </div>
-      <div className={styles.specimen}>
-        <DataTable
-          columns={COLUMNS}
-          rows={NO_PAYMENTS}
-          error={
-            <>
-              Не удалось загрузить платежи
-              <Button.Root variant="outline" tone="neutral" size="s">
-                Повторить
-              </Button.Root>
-            </>
-          }
-        />
-        <Typography as="span" variant="caption" tone="muted">
-          error
-        </Typography>
+      <div>
+        <div>
+          <DataTable
+            columns={COLUMNS}
+            rows={NO_PAYMENTS}
+            loadError={
+              <>
+                Не удалось загрузить платежи
+                <Button.Root variant="outline" tone="neutral" size="s">
+                  Повторить
+                </Button.Root>
+              </>
+            }
+          />
+          <Typography as="span" variant="caption" tone="muted">
+            loadError
+          </Typography>
+        </div>
       </div>
     </>
   );

package/dist/skill/reference/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,18 +155,21 @@ 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-hover` 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 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.
@@ -153,15 +178,17 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 
 ## 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,6 +228,7 @@ 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 |
@@ -211,6 +241,7 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 | [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`. |
@@ -226,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/dist/skill/reference/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/dist/skill/reference/components/datepicker/examples/examples.module.css

@@ -1,16 +1,17 @@
 /* Layout of the Datepicker scenarios: semantic tokens only. */
 
-/* in-form.tsx: field → field 20. */
+/* in-form.tsx: the fields (a label-less Fieldset) → actions 32 (foundation §1). */
 .form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-space-5);
+  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/dist/skill/reference/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, 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";
@@ -23,31 +23,39 @@ export default function DatepickerInFormExample() {
         setSent(complete);
       }}
     >
-      <Datepicker.Root
-        mode="range"
-        name="vacation"
-        label="Период отпуска"
-        required
-        hint="Не больше 28 дней подряд"
-        error={error}
-        value={period}
-        onValueChange={(next) => {
-          setPeriod(next);
-          setError(undefined);
-          setSent(false);
-        }}
-        months={2}
-        footer
-        placeholder="Выбрать период"
-        fullWidth
-      />
-      <Datepicker.Root mode="single" name="returnDate" label="Выход на работу" optional fullWidth />
-      {sent ? (
-        <Typography as="p" variant="body-s" tone="secondary" role="status">
-          Заявка отправлена на согласование.
-        </Typography>
-      ) : null}
+      <Fieldset>
+        <Datepicker.Root
+          mode="range"
+          name="vacation"
+          label="Период отпуска"
+          required
+          hint="Не больше 28 дней подряд"
+          error={error}
+          value={period}
+          onValueChange={(next) => {
+            setPeriod(next);
+            setError(undefined);
+            setSent(false);
+          }}
+          months={2}
+          footer
+          placeholder="Выбрать период"
+          fullWidth
+        />
+        <Datepicker.Root
+          mode="single"
+          name="returnDate"
+          label="Выход на работу"
+          optional
+          fullWidth
+        />
+      </Fieldset>
       <div className={styles.actions}>
+        {sent ? (
+          <Typography as="p" variant="body-s" tone="secondary" role="status">
+            Заявка отправлена на согласование.
+          </Typography>
+        ) : null}
         <Button.Root
           variant="ghost"
           tone="neutral"

package/dist/skill/reference/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/dist/skill/reference/components/datepicker/examples/states.tsx

@@ -5,7 +5,7 @@ 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
@@ -23,6 +23,6 @@ export default function DatepickerStatesExample() {
         focusRing={false}
         fullWidth
       />
-    </>
+    </div>
   );
 }

package/dist/skill/reference/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/dist/skill/reference/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,17 +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. |
-| [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 a side column with the client's details and the history — `orientation`. |
+| [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/dist/skill/reference/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/dist/skill/reference/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";