prime-ui-kit 0.10.0 → 0.11.0

package/src/components/data-table/examples/heatmap.tsx

@@ -0,0 +1,44 @@
+/** Deals closed per manager and month as a heatmap: each count shades its cell on the chart scale and stays readable in it — `scale`, `numeric`. */
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+
+type Row = { manager: string; jul: number; aug: number; sep: number; oct: number };
+
+const MONTHS = [
+  { id: "jul", header: "Июль" },
+  { id: "aug", header: "Август" },
+  { id: "sep", header: "Сентябрь" },
+  { id: "oct", header: "Октябрь" },
+] as const;
+
+const ROWS: Row[] = [
+  { manager: "Ольга Смирнова", jul: 14, aug: 18, sep: 22, oct: 25 },
+  { manager: "Игорь Волков", jul: 9, aug: 7, sep: 12, oct: 10 },
+  { manager: "Мария Орлова", jul: 4, aug: 11, sep: 16, oct: 21 },
+  { manager: "Глеб Котов", jul: 2, aug: 3, sep: 5, oct: 8 },
+];
+
+const COLUMNS: DataTableColumn<Row>[] = [
+  { id: "manager", header: "Менеджер", accessor: "manager" },
+  // One fixed range for every month, so the same count has the same shade in each column.
+  ...MONTHS.map(
+    ({ id, header }): DataTableColumn<Row> => ({
+      id,
+      header,
+      accessor: id,
+      numeric: true,
+      scale: { min: 0, max: 25 },
+    }),
+  ),
+];
+
+export default function DataTableHeatmapExample() {
+  return (
+    <DataTable
+      columns={COLUMNS}
+      rows={ROWS}
+      getRowKey={(row) => row.manager}
+      paging="none"
+      highlightRowOnHover={false}
+    />
+  );
+}

package/src/components/data-table/examples/reorder.tsx

@@ -0,0 +1,61 @@
+/** Pipeline stages put in order by the handle or Alt + ↑ / ↓; each move is saved with a spinner in its handle, and sorting by a column turns the handles off — `onReorder`, `getRowLabel`. */
+import { Badge, DataTable, type DataTableColumn, moveBefore } from "prime-ui-kit";
+import * as React from "react";
+
+type Stage = { id: string; name: string; owner: string; deals: number; probability: number };
+
+const STAGES: Stage[] = [
+  { id: "lead", name: "Новый лид", owner: "Отдел продаж", deals: 48, probability: 10 },
+  { id: "call", name: "Первый звонок", owner: "Отдел продаж", deals: 31, probability: 20 },
+  { id: "demo", name: "Демонстрация", owner: "Пресейл", deals: 17, probability: 40 },
+  {
+    id: "offer",
+    name: "Коммерческое предложение",
+    owner: "Отдел продаж",
+    deals: 12,
+    probability: 60,
+  },
+  { id: "contract", name: "Договор", owner: "Юристы", deals: 6, probability: 80 },
+  { id: "payment", name: "Оплата", owner: "Бухгалтерия", deals: 4, probability: 95 },
+];
+
+const COLUMNS: DataTableColumn<Stage>[] = [
+  { id: "name", header: "Этап", accessor: "name", hideable: false },
+  { id: "owner", header: "Ответственный", accessor: "owner" },
+  { id: "deals", header: "Сделки", accessor: "deals", numeric: true, sortable: true },
+  {
+    id: "probability",
+    header: "Вероятность",
+    accessor: "probability",
+    sortable: true,
+    align: "end",
+    cell: (row) => <Badge.Root>{row.probability}%</Badge.Root>,
+  },
+];
+
+/** Stands in for the request that saves the new order. */
+const saveOrder = () => new Promise<void>((resolve) => setTimeout(resolve, 700));
+
+export default function DataTableReorderExample() {
+  const [stages, setStages] = React.useState(STAGES);
+  return (
+    <DataTable
+      columns={COLUMNS}
+      rows={stages}
+      paging="none"
+      getRowKey={(row) => row.id}
+      getRowLabel={(row) => row.name}
+      onReorder={async (id, beforeId) => {
+        await saveOrder();
+        setStages((current) =>
+          moveBefore(
+            current,
+            String(id),
+            beforeId === null ? null : String(beforeId),
+            (row) => row.id,
+          ),
+        );
+      }}
+    />
+  );
+}

package/src/components/data-table/examples/row-link.tsx

@@ -0,0 +1,100 @@
+/** Invoices whose rows are links: ⌘-click or a middle click opens a new tab, a plain click routes inside the app, the totals row and the ⋯ menu never open a row — `getRowHref`, `onRowClick`, `isRowClickable`. */
+import { Button, DataTable, type DataTableColumn, Dropdown, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Invoice = { id: string; client: string; due: string; amount: number; total?: boolean };
+
+const INVOICES: Invoice[] = [
+  { id: "INV-1042", client: "ООО «Северный ветер»", due: "12.10.2026", amount: 184_500 },
+  { id: "INV-1043", client: "ИП Козлов", due: "14.10.2026", amount: 27_900 },
+  { id: "INV-1044", client: "АО «Технопарк»", due: "20.10.2026", amount: 612_000 },
+];
+
+const ROWS: Invoice[] = [
+  ...INVOICES,
+  {
+    id: "total",
+    client: "Итого к оплате",
+    due: "",
+    amount: INVOICES.reduce((sum, invoice) => sum + invoice.amount, 0),
+    total: true,
+  },
+];
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+export default function DataTableRowLinkExample() {
+  const [status, setStatus] = React.useState("Откройте счёт из списка");
+
+  const columns: DataTableColumn<Invoice>[] = [
+    { id: "client", header: "Клиент", accessor: "client", hideable: false },
+    { id: "id", header: "Счёт", cell: (row) => (row.total ? "" : row.id) },
+    { id: "due", header: "Оплатить до", accessor: "due", numeric: true },
+    {
+      id: "amount",
+      header: "Сумма",
+      accessor: "amount",
+      numeric: true,
+      cell: (row) => RUB.format(row.amount),
+    },
+    {
+      id: "actions",
+      header: "",
+      align: "end",
+      cell: (row) =>
+        row.total ? null : (
+          <Dropdown.Root>
+            <Dropdown.Trigger>
+              <Button.Root
+                variant="ghost"
+                tone="neutral"
+                size="s"
+                aria-label={`Действия со счётом ${row.id}`}
+              >
+                <Button.Icon>
+                  <Icon name="action.more" />
+                </Button.Icon>
+              </Button.Root>
+            </Dropdown.Trigger>
+            <Dropdown.Content>
+              <Dropdown.Item onSelect={() => setStatus(`${row.id} отправлен клиенту повторно`)}>
+                Отправить повторно
+              </Dropdown.Item>
+              <Dropdown.Item onSelect={() => setStatus(`${row.id} скачан в PDF`)}>
+                Скачать PDF
+              </Dropdown.Item>
+            </Dropdown.Content>
+          </Dropdown.Root>
+        ),
+    },
+  ];
+
+  return (
+    <DataTable
+      columns={columns}
+      rows={ROWS}
+      getRowKey={(row) => row.id}
+      paging="none"
+      getRowHref={(row) => `/invoices/${row.id}`}
+      isRowClickable={(row) => !row.total}
+      onRowClick={(row, _index, event) => {
+        // A client-side router goes here (navigate(href)); the page itself never reloads.
+        event.preventDefault();
+        setStatus(`Открыт ${row.id} · ${row.client}`);
+      }}
+      toolbar={
+        <div className={styles.toolbar}>
+          <Typography as="span" variant="body-s" tone="secondary" aria-live="polite">
+            {status}
+          </Typography>
+        </div>
+      }
+    />
+  );
+}

package/src/components/data-table/examples/row-open.tsx

@@ -0,0 +1,129 @@
+/** Deals that open in a side panel: a click, or Enter and Space on the focused row; the panel keeps the last deal while it slides away — `onRowClick`. */
+import { Badge, DataTable, type DataTableColumn, Drawer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Stage = "new" | "talks" | "won";
+type Deal = { id: string; title: string; client: string; owner: string; stage: Stage; sum: number };
+
+const STAGE: Record<Stage, { label: string; color: "blue" | "orange" | "green" }> = {
+  new: { label: "Новая", color: "blue" },
+  talks: { label: "Переговоры", color: "orange" },
+  won: { label: "Выиграна", color: "green" },
+};
+
+const DEALS: Deal[] = [
+  {
+    id: "D-311",
+    title: "Поставка серверов",
+    client: "АО «Технопарк»",
+    owner: "Ольга Смирнова",
+    stage: "talks",
+    sum: 1_240_000,
+  },
+  {
+    id: "D-312",
+    title: "Годовая лицензия",
+    client: "ООО «Лето»",
+    owner: "Игорь Волков",
+    stage: "new",
+    sum: 360_000,
+  },
+  {
+    id: "D-313",
+    title: "Внедрение CRM",
+    client: "ООО «Гранит»",
+    owner: "Мария Орлова",
+    stage: "won",
+    sum: 890_000,
+  },
+];
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const COLUMNS: DataTableColumn<Deal>[] = [
+  { id: "title", header: "Сделка", accessor: "title", hideable: false },
+  { id: "client", header: "Клиент", accessor: "client" },
+  {
+    id: "stage",
+    header: "Этап",
+    cell: (row) => <Badge.Root color={STAGE[row.stage].color}>{STAGE[row.stage].label}</Badge.Root>,
+  },
+  {
+    id: "sum",
+    header: "Сумма",
+    accessor: "sum",
+    numeric: true,
+    cell: (row) => RUB.format(row.sum),
+  },
+];
+
+export default function DataTableRowOpenExample() {
+  const [open, setOpen] = React.useState(false);
+  // The last opened deal stays while the panel slides away, so it never empties mid-motion.
+  const [deal, setDeal] = React.useState<Deal | null>(null);
+
+  return (
+    <>
+      <DataTable
+        columns={COLUMNS}
+        rows={DEALS}
+        getRowKey={(row) => row.id}
+        paging="none"
+        onRowClick={(row) => {
+          setDeal(row);
+          setOpen(true);
+        }}
+      />
+      <Drawer.Root open={open} onOpenChange={setOpen}>
+        <Drawer.Content size="s">
+          <Drawer.Header>
+            <Drawer.Title>{deal?.title}</Drawer.Title>
+            <Drawer.Description>{deal?.id}</Drawer.Description>
+          </Drawer.Header>
+          <Drawer.Body>
+            {deal ? (
+              <dl className={styles.details}>
+                <dt>
+                  <Typography as="span" variant="body-m" tone="muted">
+                    Клиент
+                  </Typography>
+                </dt>
+                <dd>
+                  <Typography as="span" variant="body-m">
+                    {deal.client}
+                  </Typography>
+                </dd>
+                <dt>
+                  <Typography as="span" variant="body-m" tone="muted">
+                    Ответственный
+                  </Typography>
+                </dt>
+                <dd>
+                  <Typography as="span" variant="body-m">
+                    {deal.owner}
+                  </Typography>
+                </dd>
+                <dt>
+                  <Typography as="span" variant="body-m" tone="muted">
+                    Сумма
+                  </Typography>
+                </dt>
+                <dd>
+                  <Typography as="span" variant="body-m">
+                    {RUB.format(deal.sum)}
+                  </Typography>
+                </dd>
+              </dl>
+            ) : null}
+          </Drawer.Body>
+        </Drawer.Content>
+      </Drawer.Root>
+    </>
+  );
+}

package/src/components/data-table/examples/server.tsx

@@ -0,0 +1,181 @@
+/** A CRM deal list the server sorts, pages and searches; a new search returns to page 1 — `source`, `rowCount`, `sort`, `page`, `loading`. */
+import {
+  Badge,
+  DataTable,
+  type DataTableColumn,
+  type DataTableSortState,
+  matchesSmartFilter,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+} from "prime-ui-kit";
+import * as React from "react";
+
+type Stage = "new" | "talks" | "won" | "lost";
+type Deal = { id: number; client: string; manager: string; stage: Stage; amount: number };
+type DealsRequest = {
+  page: number;
+  sort: DataTableSortState;
+  search: string;
+  filter: SmartFilterValue;
+};
+type DealsPage = { rows: Deal[]; total: number };
+
+const PAGE_SIZE = 8;
+/** The fake server answers after this delay, like a real request. */
+const LATENCY_MS = 600;
+
+const STAGE: Record<Stage, { label: string; color: "blue" | "orange" | "green" | "gray" }> = {
+  new: { label: "Новая", color: "blue" },
+  talks: { label: "Переговоры", color: "orange" },
+  won: { label: "Выиграна", color: "green" },
+  lost: { label: "Проиграна", color: "gray" },
+};
+const STAGES = Object.keys(STAGE) as Stage[];
+
+const CLIENTS = [
+  "ООО «Вектор»",
+  "АО «Северсталь-Логистик»",
+  "ИП Смирнова",
+  "ООО «Альфа-Трейд»",
+  "ЗАО «Меридиан»",
+  "ООО «Гринлайн»",
+  "АО «Техносфера»",
+  "ООО «Купол»",
+  "ООО «Ространс»",
+  "АО «Нордик Фудс»",
+  "ООО «Пиксель Медиа»",
+];
+const MANAGERS = ["Анна Климова", "Илья Петров", "Марат Хасанов", "Ольга Тарасова"];
+
+/** The server's table: 137 deals. */
+const DEALS: Deal[] = Array.from({ length: 137 }, (_, i) => ({
+  id: 2401 + i,
+  client: CLIENTS[(i * 7) % CLIENTS.length],
+  manager: MANAGERS[(i * 3) % MANAGERS.length],
+  stage: STAGES[(i * 5) % STAGES.length],
+  amount: 40_000 + ((i * 7919) % 97) * 12_500,
+}));
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "stage",
+    label: "Этап",
+    options: STAGES.map((value) => ({ value, label: STAGE[value].label })),
+  },
+  {
+    key: "manager",
+    label: "Менеджер",
+    options: MANAGERS.map((value) => ({ value, label: value })),
+  },
+];
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const COLUMNS: DataTableColumn<Deal>[] = [
+  { id: "id", header: "Сделка", accessor: "id", sortable: true, numeric: true, align: "start" },
+  { id: "client", header: "Клиент", accessor: "client", sortable: true },
+  { id: "manager", header: "Менеджер", accessor: "manager", sortable: true },
+  {
+    id: "stage",
+    header: "Этап",
+    accessor: "stage",
+    cell: (row) => <Badge.Root color={STAGE[row.stage].color}>{STAGE[row.stage].label}</Badge.Root>,
+  },
+  {
+    id: "amount",
+    header: "Сумма",
+    accessor: "amount",
+    sortable: true,
+    numeric: true,
+    cell: (row) => RUB.format(row.amount),
+  },
+];
+
+const compare = (a: string | number, b: string | number) =>
+  typeof a === "number" && typeof b === "number" ? a - b : String(a).localeCompare(String(b), "ru");
+
+/** Fake API: searches, filters, sorts and cuts one page on the «server», then answers late. */
+function fetchDeals({ page, sort, search, filter }: DealsRequest): Promise<DealsPage> {
+  const query = search.trim().toLowerCase();
+  const found = DEALS.filter(
+    (row) =>
+      matchesSmartFilter(filter.stage, row.stage) &&
+      matchesSmartFilter(filter.manager, row.manager) &&
+      (String(row.id).includes(query) || row.client.toLowerCase().includes(query)),
+  );
+  if (sort) {
+    const key = sort.columnId as keyof Deal;
+    const direction = sort.order === "asc" ? 1 : -1;
+    found.sort((a, b) => compare(a[key], b[key]) * direction);
+  }
+  const start = (page - 1) * PAGE_SIZE;
+  const answer = { rows: found.slice(start, start + PAGE_SIZE), total: found.length };
+  return new Promise((resolve) => window.setTimeout(() => resolve(answer), LATENCY_MS));
+}
+
+export default function DataTableServerExample() {
+  const [filter, setFilter] = React.useState<SmartFilterValue>({});
+  const [search, setSearch] = React.useState("");
+  const [sort, setSort] = React.useState<DataTableSortState>({ columnId: "amount", order: "desc" });
+  const [page, setPage] = React.useState(1);
+  const [result, setResult] = React.useState<DealsPage>({ rows: [], total: 0 });
+  const [loading, setLoading] = React.useState(true);
+
+  React.useEffect(() => {
+    let latest = true;
+    setLoading(true);
+    fetchDeals({ page, sort, search, filter }).then((answer) => {
+      // A newer request replaced this one: its answer is dropped.
+      if (!latest) return;
+      setResult(answer);
+      setLoading(false);
+    });
+    return () => {
+      latest = false;
+    };
+  }, [page, sort, search, filter]);
+
+  // A new search or filter is another result set: back to its first page.
+  const changeSearch = (next: string) => {
+    setSearch(next);
+    setPage(1);
+  };
+  const changeFilter = (next: SmartFilterValue) => {
+    setFilter(next);
+    setPage(1);
+  };
+
+  return (
+    <DataTable
+      source="server"
+      columns={COLUMNS}
+      rows={result.rows}
+      rowCount={result.total}
+      getRowKey={(row) => row.id}
+      pageSize={PAGE_SIZE}
+      page={page}
+      onPageChange={setPage}
+      sort={sort}
+      onSortChange={setSort}
+      loading={loading}
+      empty="Сделок не найдено — измените запрос или фильтры"
+      toolbar={
+        <SmartFilter.Root
+          fields={FIELDS}
+          value={filter}
+          onValueChange={changeFilter}
+          search={search}
+          onSearchChange={changeSearch}
+        >
+          <SmartFilter.Toolbar />
+          <SmartFilter.Chips />
+        </SmartFilter.Root>
+      }
+    />
+  );
+}

package/src/components/datepicker/COMPONENT.md

@@ -33,7 +33,7 @@ import {
 ```
 Datepicker.Root             field frame: label · field button (calendar icon, value, chevron) · hint / error
 └─ Popover                  the calendar panel
-Datepicker.Panel            the same panel without a field, styled as a card
+Datepicker.Panel            the same calendar without a field, the host's own content (no card)
 
 panel                       presets column (range) · 1–2 month grids · prompt · footer
 ├─ month header             ghost icon-only Buttons (previous / next) around the month title
@@ -66,20 +66,21 @@ panel                       presets column (range) · 1–2 month grids · promp
 | `invalid` | `boolean` | — | Danger ring and `aria-invalid` without a message. |
 | `disabled` | `boolean` | `false` | The field cannot be opened. |
 | `fullWidth` | `boolean` | `false` | The field stretches to its container; otherwise it fits the text. |
-| `align` | `"start" \| "center" \| "end"` | `"start"` | Popover alignment to the field. |
+| `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Popover alignment to the field. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring (`data-focus-ring="false"`). |
 | `placeholder` | `string` | `labels.placeholder` | Field text without a value for this field. |
 | `valuePrefix` | `string` | — | Text before the value, e.g. «С». |
 | `id` | `string` | — | Id of the field button; generated when omitted. |
+| `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. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
 
 ### Datepicker.Panel
-`ref` → `HTMLDivElement`. The calendar without a field, inline in a page: its own card, 1–2 months by the parent's width. Takes `mode`, `value` / `defaultValue` / `onValueChange` like Root and every calendar option below.
+`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 card. |
+| `…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`.
@@ -128,7 +129,7 @@ Shared by `Datepicker.Root` and `Datepicker.Panel`.
 |---|---|---|---|
 | `presets` | «Период» column on the left (a scrolling row above when narrow); the active preset is pressed | analytics periods | `false` |
 | `prompt` | muted step line under the grid | infrequent use of ranges | `false` |
-| `footer` | dates (dd.MM.yyyy) and «Сбросить» / «Применить» | the user confirms, or with time | `false` |
+| `footer` | dates (dd.MM.yyyy, dd.MM with `yearless`) and «Сбросить» / «Применить» | the user confirms, or with time | `false` |
 | `withTime` | HH:mm inputs in the footer | timestamps (with `footer`) | `false` |
 | `yearless` | month title without a year, value «15 октября» | annual dates | `false` |
 | `fullWidth` | the field fills its container | form columns | `false` |
@@ -146,12 +147,15 @@ Shared by `Datepicker.Root` and `Datepicker.Panel`.
 | selected / band | value | day `aria-pressed`, `data-edge`; cell `data-band="selected" \| "preview"`, `data-band-start` / `-end` |
 | day disabled | `isDayDisabled`, `disableFuture` | native `disabled`, muted |
 
-Panel DOM: `data-size`, `data-embedded`, `data-compact`, `data-layout` (`aside` · `stacked`). The popover follows the overlay contract: an outside press or Escape closes it, focus is trapped while open, the wheel over the panel does not scroll the page.
+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.
+
+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`.
-- Months gap `--prime-space-6`. An embedded panel measures its parent; narrower than one month → compact cells and footer fields above the buttons. Works from 320 px.
+- `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.
 - Values are wall-clock local dates; convert time zones in the app.
 
 ## Accessibility
@@ -203,11 +207,11 @@ Panel DOM: `data-size`, `data-embedded`, `data-compact`, `data-layout` (`aside`
 | [states.tsx](examples/states.tsx) | An empty field with the default placeholder, a filled one and a disabled one — `disabled`. |
 | [validation.tsx](examples/validation.tsx) | A 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`. |
-| [inline-panel.tsx](examples/inline-panel.tsx) | A booking calendar embedded in the page: its own card, two months when the parent has room, the range applies at once — `Datepicker.Panel`, `months`, `prompt`. |
+| [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`. |
 | [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 checks the required period, the error shakes in and leaves once the period is fixed; an optional return date — `required`, `error`, `optional`. |
+| [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`. |
 | [narrow.tsx](examples/narrow.tsx) | An embedded panel in a 320 px column: one compact month instead of two, the footer fields wrap above the buttons — `months`, `footer`. |
 
 ## Mistakes
@@ -220,5 +224,5 @@ Panel DOM: `data-size`, `data-embedded`, `data-compact`, `data-layout` (`aside`
 - 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), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md)
+- **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)
 - **See also:** [Input](../input/COMPONENT.md), [Select](../select/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -1,4 +1,4 @@
-/** A leave request form: submit checks the required period, the error shakes in and leaves once the period is fixed; an optional return date — `required`, `error`, `optional`. */
+/** 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 * as React from "react";
 
@@ -17,13 +17,16 @@ export default function DatepickerInFormExample() {
         className={styles.form}
         onSubmit={(event) => {
           event.preventDefault();
-          const complete = Boolean(period.from && period.to);
+          // 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);
         }}
       >
         <Datepicker.Root
           mode="range"
+          name="vacation"
           label="Период отпуска"
           required
           hint="Не больше 28 дней подряд"
@@ -39,7 +42,13 @@ export default function DatepickerInFormExample() {
           placeholder="Выбрать период"
           fullWidth
         />
-        <Datepicker.Root mode="single" label="Выход на работу" optional fullWidth />
+        <Datepicker.Root
+          mode="single"
+          name="returnDate"
+          label="Выход на работу"
+          optional
+          fullWidth
+        />
         {sent ? (
           <Typography as="p" variant="body-s" tone="secondary" role="status">
             Заявка отправлена на согласование.

package/src/components/datepicker/examples/inline-panel.tsx

@@ -1,8 +1,14 @@
-/** A booking calendar embedded in the page: its own card, two months when the parent has room, the range applies at once — `Datepicker.Panel`, `months`, `prompt`. */
-import { Datepicker, type DatepickerRange } from "prime-ui-kit";
+/** 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`. */
+import { Card, Datepicker, type DatepickerRange } from "prime-ui-kit";
 import * as React from "react";
 
 export default function DatepickerInlinePanelExample() {
   const [stay, setStay] = React.useState<DatepickerRange>({ from: null, to: null });
-  return <Datepicker.Panel mode="range" value={stay} onValueChange={setStay} months={2} prompt />;
+  return (
+    <Card.Root>
+      <Card.Body>
+        <Datepicker.Panel mode="range" value={stay} onValueChange={setStay} months={2} prompt />
+      </Card.Body>
+    </Card.Root>
+  );
 }