prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/{patterns/list-page.tsx → reference/components/data-table/examples/screen.tsx}

@@ -1,5 +1,6 @@
-/** A list page: header with one primary action, SmartFilter in the table toolbar, DataTable with statuses, row actions, pages and a filtered empty state. */
+/** A list page: the title, a line of figures, search, filters and the one primary action in the app header, a DataTable of invoices with statuses, row actions, pages and a filtered empty state — `empty`, `pageSize`, `stickyFirstColumn`. */
 import {
+  AppHeader,
   Avatar,
   Badge,
   Button,
@@ -10,7 +11,7 @@ import {
   Icon,
   matchesSmartFilter,
   PageContent,
-  type PaletteColor,
+  PageToolbar,
   SmartFilter,
   type SmartFilterField,
   type SmartFilterValue,
@@ -18,7 +19,7 @@ import {
 } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./list-page.module.css";
+import styles from "./screen.module.css";
 
 type Status = "draft" | "sent" | "paid" | "overdue";
 
@@ -32,13 +33,13 @@ type Invoice = {
   status: Status;
 };
 
-/** One hue per status across the product: the text carries the meaning, the color repeats it. */
-const STATUS: Record<Status, { label: string; color: PaletteColor }> = {
-  draft: { label: "Черновик", color: "gray" },
-  sent: { label: "Отправлен", color: "blue" },
-  paid: { label: "Оплачен", color: "green" },
-  overdue: { label: "Просрочен", color: "red" },
-};
+/** One tone per status across the product: the text carries the meaning, the tone repeats it. */
+const STATUS = {
+  draft: { label: "Черновик", tone: "neutral" },
+  sent: { label: "Отправлен", tone: "info" },
+  paid: { label: "Оплачен", tone: "success" },
+  overdue: { label: "Просрочен", tone: "danger" },
+} as const satisfies Record<Status, { label: string; tone: string }>;
 
 const INVOICES: Invoice[] = [
   {
@@ -140,6 +141,13 @@ const MONEY = new Intl.NumberFormat("ru-RU", {
 });
 const DAY = new Intl.DateTimeFormat("ru-RU", { day: "numeric", month: "short" });
 
+const OVERDUE = INVOICES.filter((row) => row.status === "overdue");
+
+/** The header's line of context carries data: how many invoices and what is overdue. */
+const SUMMARY = `${INVOICES.length} счетов · просрочено ${OVERDUE.length} на ${MONEY.format(
+  OVERDUE.reduce((sum, row) => sum + row.amount, 0),
+)}`;
+
 const asOptions = (values: string[]) => values.map((value) => ({ value, label: value }));
 
 const FIELDS: SmartFilterField[] = [
@@ -177,6 +185,7 @@ const COLUMNS: DataTableColumn<Invoice>[] = [
     header: "Клиент",
     accessor: "client",
     sortable: true,
+    minWidth: "16rem",
     cell: (row) => (
       <span className={styles.client}>
         <Avatar.Root size="s" color="gray">
@@ -198,7 +207,7 @@ const COLUMNS: DataTableColumn<Invoice>[] = [
     header: "Статус",
     accessor: "status",
     cell: (row) => (
-      <Badge.Root color={STATUS[row.status].color}>{STATUS[row.status].label}</Badge.Root>
+      <Badge.Root tone={STATUS[row.status].tone}>{STATUS[row.status].label}</Badge.Root>
     ),
   },
   {
@@ -221,7 +230,8 @@ const COLUMNS: DataTableColumn<Invoice>[] = [
   },
   {
     id: "actions",
-    header: "",
+    header: "Действия",
+    hideHeader: true,
     width: "3.5rem",
     align: "end",
     cell: (row) => (
@@ -250,7 +260,7 @@ const COLUMNS: DataTableColumn<Invoice>[] = [
   },
 ];
 
-export default function ListPagePattern() {
+export default function DataTableScreenExample() {
   const [filter, setFilter] = React.useState<SmartFilterValue>({});
   const [search, setSearch] = React.useState("");
 
@@ -268,67 +278,78 @@ export default function ListPagePattern() {
   };
 
   return (
-    <PageContent.Page aria-labelledby="invoices-title">
-      <PageContent.Header>
-        <PageContent.Title id="invoices-title">Счета</PageContent.Title>
-        <PageContent.Description>
-          Выставленные клиентам счета и статус их оплаты.
-        </PageContent.Description>
-        <PageContent.Actions>
-          <Button.Root variant="soft" tone="neutral">
-            <Button.Icon>
-              <Icon name="action.download" />
-            </Button.Icon>
-            Экспорт
-          </Button.Root>
-          <Button.Root>
-            <Button.Icon>
-              <Icon name="action.add" />
-            </Button.Icon>
-            Новый счёт
-          </Button.Root>
-        </PageContent.Actions>
-      </PageContent.Header>
-      <PageContent.Body>
-        <DataTable
-          columns={COLUMNS}
-          rows={rows}
-          getRowKey={(row) => row.id}
-          getRowLabel={(row) => `Счёт ${row.id}`}
-          pageSize={6}
-          stickyFirstColumn
-          defaultSort={{ columnId: "due", order: "desc" }}
-          toolbar={
-            <SmartFilter.Root
-              fields={FIELDS}
-              value={filter}
-              onValueChange={setFilter}
-              search={search}
-              onSearchChange={setSearch}
-              className={styles.filter}
-            >
-              <SmartFilter.Toolbar />
-              <SmartFilter.Chips />
-            </SmartFilter.Root>
-          }
-          empty={
-            <EmptyPage.Root size="s" role="status" aria-labelledby="invoices-empty">
-              <EmptyPage.Icon>
-                <Icon name="action.search" />
-              </EmptyPage.Icon>
-              <EmptyPage.Title as="p" id="invoices-empty">
-                Счетов не найдено
-              </EmptyPage.Title>
-              <EmptyPage.Description>Измените запрос или сбросьте фильтры.</EmptyPage.Description>
-              <EmptyPage.Actions>
-                <Button.Root variant="soft" tone="neutral" onClick={resetFilters}>
-                  Сбросить фильтры
+    <>
+      {/* The page lives in the app header: the only h1, a line of figures under it, and the page's
+          tools — search, filters, export, the one primary action; main has no PageContent.Header. */}
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            Счета
+            <AppHeader.Description>{SUMMARY}</AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Tools>
+          <SmartFilter.Root
+            fields={FIELDS}
+            value={filter}
+            onValueChange={setFilter}
+            search={search}
+            onSearchChange={setSearch}
+          >
+            <PageToolbar.Root aria-label="Счета">
+              <PageToolbar.Tools>
+                <SmartFilter.Toolbar />
+              </PageToolbar.Tools>
+              <PageToolbar.Actions>
+                <Button.Root variant="soft" tone="neutral" aria-label="Экспорт в Excel">
+                  <Button.Icon>
+                    <Icon name="action.download" />
+                  </Button.Icon>
+                </Button.Root>
+                <Button.Root>
+                  <Button.Icon>
+                    <Icon name="action.add" />
+                  </Button.Icon>
+                  Новый счёт
                 </Button.Root>
-              </EmptyPage.Actions>
-            </EmptyPage.Root>
-          }
-        />
-      </PageContent.Body>
-    </PageContent.Page>
+              </PageToolbar.Actions>
+              <PageToolbar.Chips>
+                <SmartFilter.Chips />
+              </PageToolbar.Chips>
+            </PageToolbar.Root>
+          </SmartFilter.Root>
+        </AppHeader.Tools>
+      </AppHeader.Root>
+
+      <PageContent.Root>
+        <PageContent.Body>
+          <DataTable
+            columns={COLUMNS}
+            rows={rows}
+            getRowKey={(row) => row.id}
+            getRowLabel={(row) => `Счёт ${row.id}`}
+            pageSize={6}
+            stickyFirstColumn
+            defaultSort={{ columnId: "due", order: "desc" }}
+            empty={
+              <EmptyPage.Root size="s" role="status" aria-labelledby="invoices-empty">
+                <EmptyPage.Icon>
+                  <Icon name="action.search" />
+                </EmptyPage.Icon>
+                <EmptyPage.Title as="p" id="invoices-empty">
+                  Счетов не найдено
+                </EmptyPage.Title>
+                <EmptyPage.Description>Измените запрос или сбросьте фильтры.</EmptyPage.Description>
+                <EmptyPage.Actions>
+                  <Button.Root variant="soft" tone="neutral" onClick={resetFilters}>
+                    Сбросить фильтры
+                  </Button.Root>
+                </EmptyPage.Actions>
+              </EmptyPage.Root>
+            }
+          />
+        </PageContent.Body>
+      </PageContent.Root>
+    </>
   );
 }

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,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/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,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);
 }