prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/reference/components/page-toolbar/examples/save-changes.tsx

@@ -13,28 +13,31 @@ const CHANGES = 3;
 export default function PageToolbarSaveChangesExample() {
   const [section, setSection] = React.useState("profile");
 
+  // The toolbar heads the settings form: its save action submits the page's form.
   return (
-    <PageToolbar.Root aria-label="Настройки">
-      <PageToolbar.Sections>
-        <SegmentedControl.Root
-          fullWidth
-          value={section}
-          onValueChange={setSection}
-          aria-label="Раздел настроек"
-        >
-          {SECTIONS.map((item) => (
-            <SegmentedControl.Item key={item.value} value={item.value}>
-              {item.label}
-            </SegmentedControl.Item>
-          ))}
-        </SegmentedControl.Root>
-      </PageToolbar.Sections>
-      <PageToolbar.Actions>
-        <Button.Root variant="ghost" tone="neutral">
-          Отменить
-        </Button.Root>
-        <Button.Root>Сохранить {CHANGES} изменения</Button.Root>
-      </PageToolbar.Actions>
-    </PageToolbar.Root>
+    <form onSubmit={(event) => event.preventDefault()}>
+      <PageToolbar.Root aria-label="Настройки">
+        <PageToolbar.Sections>
+          <SegmentedControl.Root
+            fullWidth
+            value={section}
+            onValueChange={setSection}
+            aria-label="Раздел настроек"
+          >
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </PageToolbar.Sections>
+        <PageToolbar.Actions>
+          <Button.Root variant="ghost" tone="neutral">
+            Отменить
+          </Button.Root>
+          <Button.Root type="submit">Сохранить {CHANGES} изменения</Button.Root>
+        </PageToolbar.Actions>
+      </PageToolbar.Root>
+    </form>
   );
 }

package/dist/skill/reference/components/pagination/COMPONENT.md

@@ -7,7 +7,7 @@
 
 ## When to use
 - Lists and tables split into pages, usually in their footer.
-- Narrow places (cards, mobile footers) — `compact` or `compact="auto"`.
+- Narrow places (cards, mobile footers): it turns compact by itself below 22rem of its width; `compact` forces that view.
 
 ## When not to use
 - Steps of a process with names and statuses → use [Stepper](../stepper/COMPONENT.md).
@@ -23,8 +23,8 @@ import { Pagination } from "prime-ui-kit";
 ```
 Pagination              <nav aria-label={labels.nav}>; size and compact mode
 ├─ previous             ghost icon-only Button (nav.chevronLeft)
-├─ pages                ghost Buttons with numbers; «…» for skipped ranges (aria-hidden)
-├─ summary              «3 / 12» in the compact view
+├─ pages                ghost `tight` Buttons with numbers, the current one in the Button `current` state; «…» for skipped ranges (aria-hidden)
+├─ summary              «3 / 12» in the compact view (below 22rem, or `compact`)
 └─ next                 ghost icon-only Button (nav.chevronRight)
 ```
 
@@ -33,7 +33,7 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Pagination
-`ref` → `HTMLElement`. A `<nav>` named by `labels.nav` with ghost `Button`s: previous, page numbers with ellipses, next.
+`ref` → `HTMLElement`. A `<nav>` named by `labels.nav` with `Button`s: ghost previous and next, ghost page numbers with ellipses, the current page in the Button `current` state.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -41,9 +41,9 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 | `value` | `number` | — | Current page (1-based), controlled; clamped to `1…totalPages`. |
 | `defaultValue` | `number` | `1` | Initial page, uncontrolled. |
 | `onValueChange` | `(page: number) => void` | — | Called when a page button or an arrow picks another page. |
-| `siblingCount` | `number` | `1` | Pages on each side of the current one before an ellipsis (when `totalPages > 7`). |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier of the buttons: height 28 · 32 · 36 · 40 · 48. |
-| `compact` | `boolean \| "auto"` | `false` | `true` — arrows + «current / total» instead of numbers; `"auto"` — fills the parent and turns compact below 22rem of its width. |
+| `siblingCount` | `number` | `1` | Pages on each side of the current one before an ellipsis (when `totalPages > 2·siblingCount+5`). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier of the buttons: height 28 · 32 · 36 · 40 · 48. Without it the tier of its host, else `m`. |
+| `compact` | `boolean` | `false` | Always arrows + «current / total» instead of numbers. Without it the nav fills its parent and shows that view only below 22rem of its width. |
 | `labels` | `Partial<PaginationLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "defaultValue" \| "onChange">` | — | `className`, `data-*` and the other `<nav>` attributes; `aria-label` comes from `labels.nav`. |
 
@@ -52,9 +52,8 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 ### compact
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `false` | arrows around page numbers; «…» for skipped ranges | desktop list and table footers | yes |
-| `true` | arrows around «3 / 12» (current in primary medium, total muted, tabular figures) | cards, mobile footers, tight toolbars | |
-| `"auto"` | fills the parent; the full row right-aligned, below 22rem of container width the compact view with arrows at the edges | responsive footers (DataTable uses it) | |
+| `false` | fills the parent: arrows around page numbers right-aligned, «…» for skipped ranges; below 22rem of its width the compact view with arrows at the edges | list and table footers, anywhere the width varies | yes |
+| `true` | arrows around «3 / 12» (current in primary medium, total muted, tabular figures) at any width | tight toolbars, a pager that must never show numbers | |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -75,26 +74,30 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| current page | `value` / `defaultValue` | `aria-current="page"` on a soft accent Button: `accent-soft` fill, `accent-text` |
+| current page | `value` / `defaultValue` | the Button `current` state: `aria-current="page"`, `data-current`, the selected fill |
 | hover / active | pointer | `fill-subtle` / `fill-subtle-active`, primary text, press scale |
 | focus-visible | keyboard | outer focus ring of the Button |
 | disabled arrow | first / last page | native `disabled`, `text-disabled` |
-| size / compact | `size`, `compact` | `data-size`, `data-compact` (`"true"` · `"false"` · `"auto"`) |
+| size / compact | `size` (else the host tier), `compact` | `data-size`, `data-compact` (`"auto"` · `"compact"`) |
 
 ## Layout & spacing
 - In a list footer: the range text on the left, rows-per-page Select and Pagination on the right (`justify-content: space-between`), the row wraps.
-- `compact="auto"` needs a parent with a width — it is a size container.
-- Page numbers keep a square footprint up to two digits; wider numbers grow the button.
+- By default the nav fills its parent and is a size container: it needs a parent with a width.
+- Page numbers use the Button `tight` density: tabular figures, a square footprint up to two digits; wider numbers grow the button.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves between the arrows and the page numbers. |
 | `Enter` · `Space` | Opens the focused page. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A `<nav>` landmark named by `labels.nav`.
 - The current page has `aria-current="page"`; every page button is named by `labels.page` («Страница 3»).
 - The edge arrows are `disabled`; the ellipsis is `aria-hidden`.
@@ -118,15 +121,15 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; buttons are as high as Button and Input of the same tier, 28 to 48 px — `size`. |
 | [overflow.tsx](examples/overflow.tsx) | Up to 7 pages without an ellipsis, then a window around the current page; a wider window — `siblingCount`. |
 | [controlled.tsx](examples/controlled.tsx) | A list footer owns the page: changing rows per page returns it to page 1 — `value`, `onValueChange`. |
-| [narrow.tsx](examples/narrow.tsx) | A 320 px card footer: `compact` always shows «current / total», `compact="auto"` switches by the container width — `compact`. |
+| [narrow.tsx](examples/narrow.tsx) | A 320 px card footer: by default the numbers give way to «current / total» on a narrow width, `compact` always shows it — `compact`. |
 
 ## Mistakes
 - `page` / `onPageChange` → use `value` / `onValueChange`.
 - A 0-based page index → pages start at `1`.
 - Passing `aria-label` to rename the landmark → use `labels={{ nav: "…" }}`.
-- `compact="auto"` inside a shrink-wrapped flex item → give the parent a width.
+- Pagination inside a shrink-wrapped flex item → give the parent a width; it measures its own container.
 - A pager under a DataTable → the table renders its own.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md), Icon (`nav.chevronLeft`, `nav.chevronRight`)
+- **Built from:** [Button](../button/COMPONENT.md), Icon (`nav.chevronLeft`, `nav.chevronRight`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)

package/dist/skill/reference/components/pagination/examples/controlled.tsx

@@ -16,36 +16,36 @@ export default function PaginationControlledExample() {
 
   return (
     <Card.Root>
-      <div className={styles.footer}>
-        <Typography as="span" variant="body-s" tone="secondary">
-          Счета {from}–{to} из {TOTAL_INVOICES}
-        </Typography>
-        <div className={styles.controls}>
-          <Select.Root
-            size="s"
-            value={perPage}
-            onValueChange={(next) => {
-              setPerPage(next);
-              setPage(1);
-            }}
-          >
-            <Select.Trigger aria-label="Строк на странице">
-              <Select.Value />
-            </Select.Trigger>
-            <Select.Content>
-              <Select.Item value="10">10 строк</Select.Item>
-              <Select.Item value="25">25 строк</Select.Item>
-              <Select.Item value="50">50 строк</Select.Item>
-            </Select.Content>
-          </Select.Root>
-          <Pagination
-            size="s"
-            value={page}
-            onValueChange={setPage}
-            totalPages={Math.ceil(TOTAL_INVOICES / pageSize)}
-          />
+      <Card.Body>
+        <div className={styles.footer}>
+          <Typography as="span" variant="body-s" tone="secondary">
+            Счета {from}–{to} из {TOTAL_INVOICES}
+          </Typography>
+          <div className={styles.controls}>
+            <Select.Root
+              value={perPage}
+              onValueChange={(next) => {
+                setPerPage(next);
+                setPage(1);
+              }}
+            >
+              <Select.Trigger aria-label="Строк на странице">
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                <Select.Item value="10">10 строк</Select.Item>
+                <Select.Item value="25">25 строк</Select.Item>
+                <Select.Item value="50">50 строк</Select.Item>
+              </Select.Content>
+            </Select.Root>
+            <Pagination
+              value={page}
+              onValueChange={setPage}
+              totalPages={Math.ceil(TOTAL_INVOICES / pageSize)}
+            />
+          </div>
         </div>
-      </div>
+      </Card.Body>
     </Card.Root>
   );
 }

package/dist/skill/reference/components/pagination/examples/examples.module.css

@@ -2,13 +2,11 @@
 
 /* A list footer in a Card: the range on the left, rows per page and pages on the right; wraps when narrow. */
 .footer {
-  box-sizing: border-box;
   display: flex;
   flex-wrap: wrap;
   align-items: center;
   justify-content: space-between;
   gap: var(--prime-space-3);
-  padding: var(--prime-space-3) var(--prime-space-4);
 }
 
 .controls {

package/dist/skill/reference/components/pagination/examples/narrow.tsx

@@ -1,4 +1,4 @@
-/** A 320 px card footer: `compact` always shows «current / total», `compact="auto"` switches by the container width — `compact`. */
+/** A 320 px card footer: by default the numbers give way to «current / total» on a narrow width, `compact` always shows it — `compact`. */
 import { Card, Pagination, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -8,15 +8,15 @@ export default function PaginationNarrowExample() {
     <Card.Root className={styles.narrow}>
       <Card.Body>
         <div>
-          <Pagination compact totalPages={12} defaultValue={3} />
+          <Pagination totalPages={12} defaultValue={3} />
           <Typography as="span" variant="caption" tone="muted">
-            compact
+            по умолчанию
           </Typography>
         </div>
         <div>
-          <Pagination compact="auto" totalPages={12} defaultValue={3} />
+          <Pagination compact totalPages={12} defaultValue={3} />
           <Typography as="span" variant="caption" tone="muted">
-            compact="auto"
+            compact
           </Typography>
         </div>
       </Card.Body>

package/dist/skill/reference/components/popover/COMPONENT.md

@@ -8,7 +8,7 @@
 ## When to use
 - Filters or quick settings tied to one button.
 - A short form (invite, rename) that does not need a full dialog.
-- A lightweight confirm next to a destructive action.
+- A must-finish step tied to a button (a note, a reason) that closes only from its own buttons.
 - An explanation with more than one sentence, or with a link, next to a term.
 
 ## When not to use
@@ -16,6 +16,7 @@
 - A list of actions or menu items → use [Dropdown](../dropdown/COMPONENT.md).
 - Choosing a value from options → use [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md).
 - A task that blocks the page or a long form → use [Modal](../modal/COMPONENT.md) or [Drawer](../drawer/COMPONENT.md).
+- Confirming a destructive action → use [ConfirmDialog](../confirm-dialog/COMPONENT.md).
 - A date picker → use [Datepicker](../datepicker/COMPONENT.md) (built on Popover).
 
 ## Import
@@ -27,7 +28,7 @@ import { Popover } from "prime-ui-kit";
 ```
 Popover.Root                 state and dismiss policy (no DOM)
 ├── Popover.Trigger          clones its child; toggles the panel
-├── Popover.Anchor           instead of Trigger: positions the panel, no click / ARIA
+├── Popover.Anchor           instead of Trigger: positions the panel, no click / ARIA; its control names a panel without a Title
 └── Popover.Content          portaled role="dialog" on the floating surface, scrolls
     ├── Popover.Header       title + description, 4 apart
     │   ├── Popover.Title        <h2>, names the dialog
@@ -51,31 +52,36 @@ No DOM, no ref. Open state and dismiss policy.
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, `Popover.Close`, Escape, outside press, code. |
 | `closeOnOutsideClick` | `boolean` | `true` | A pointerdown outside the panel and its trigger closes it; focus follows the pointer. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the panel and returns focus to the trigger. |
+| `openOnArrow` | `boolean` | `false` | ArrowDown and ArrowUp on the trigger open the panel, as on a picker whose trigger reads as a field (a colour, a period); Enter and Space open it either way. |
 | `children` | `ReactNode` | — (required) | Trigger (or Anchor) and Content. |
 
 ### Popover.Trigger · Popover.Anchor · Popover.Close
-No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles the panel and sets its ARIA; Anchor only positions the panel (open state comes from `open`); Close closes the panel.
+No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles the panel and sets its ARIA; Anchor only positions the panel (open state comes from `open`), and its control names a panel without a Title; Close closes the panel.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactElement` | — (required) | One element, usually a Button (Anchor: any element, e.g. a toolbar). |
 
 ### Popover.Content
-`ref` → `HTMLDivElement`. Portal + `role="dialog"` floating panel that scrolls inside, named by `Popover.Title`. Below 640px of viewport, opened from a Trigger, it is a bottom sheet.
+`ref` → `HTMLDivElement`. Portal + `role="dialog"` floating panel that scrolls inside, named by `Popover.Title` (else by the control it opened from). Below 640px of viewport, opened from a Trigger, it is a bottom sheet (`data-sheet`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side; flips to the opposite side when there is no room. |
 | `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Alignment along the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix the edge. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the text, padding and gap; also the size context of the controls inside. |
-| `matchTriggerWidth` | `boolean` | `false` | The panel is exactly as wide as the trigger and its text wraps. |
+| `width` | `"auto" \| "trigger" \| "content"` | `"auto"` | `auto`: by content, from the panel minimum to twice that. `trigger`: exactly the trigger's width, below the minimum too. `content`: what the content needs, within the viewport. A sheet is full width. |
 | `trapFocus` | `boolean` | `false` | Tab cycles inside the panel (forms). Without it Tab past the last (Shift+Tab before the first) stop closes the panel and returns focus to the trigger. |
-| `initialFocus` | `boolean` | `true with Trigger, false with Anchor` | Focus moves into the panel on open (`[data-autofocus]`, else the first tab stop, else the panel). Turn it on for an anchored panel opened by a command, such as a Dropdown item, so focus does not stay on the menu trigger. |
+| `initialFocus` | `boolean` | `true` with `Popover.Trigger`, `false` with `Popover.Anchor` | Focus moves into the panel on open (`[data-autofocus]`, else the first tab stop, else the panel). Turn it on for an anchored panel opened by a command, such as a Dropdown item, so focus does not stay on the menu trigger. |
 | `flush` | `boolean` | `false` | No inner padding and no gap: rows and dividers reach the panel edges; the content lays out its own spacing. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `className` and the other attributes of the panel. |
 
 ### Popover.Header · Popover.Title · Popover.Description · Popover.Actions
-`ref` → the element. `<div>` (title + description with a 4 px step) / `<h2>` (names the dialog) / `<p>` (describes it) / `<div>` (buttons at the end, stacked full width on phones, below 640 px). + native props.
+`ref` → `HTMLDivElement` / `HTMLHeadingElement` / `HTMLParagraphElement` / `HTMLDivElement`. `<div>` (title + description) / `<h2>` (names the dialog) / `<p>` (describes it) / `<div>` (buttons at the end; stacked in a sheet).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement \| HTMLHeadingElement \| HTMLParagraphElement>` | — | `className`, `children` and the other attributes; an own `id` on Title or Description is the one the panel points at. |
 
 ## Variants
 The panel has one look: the floating layer of the ladder (`data-depth="floating"`), `--prime-panel-radius`, `shadow-overlay`, no border. Fields inside take that layer's fill; a card inside is the next layer, a flat tile.
@@ -105,13 +111,22 @@ Title uses the tier text size with title weight; Description uses the tier label
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `matchTriggerWidth` | Panel exactly as wide as the trigger, text wraps | Full-width triggers in narrow columns | `false` |
 | `trapFocus` | Tab cycles inside the panel | Forms inside the panel | `false` |
 | `flush` | No padding, no gap; dividers run edge to edge | Panels of full-width rows ([SmartFilter](../smart-filter/COMPONENT.md)) | `false` |
-| `closeOnOutsideClick={false}` | Stays open on an outside press | Destructive confirms | |
+| `closeOnOutsideClick={false}` | Stays open on an outside press | A must-finish step whose typed input a stray click must not lose | |
 | `closeOnEscape={false}` | Escape does nothing | While a request of the panel runs | |
+| `openOnArrow` (Root) | ArrowDown / ArrowUp on the trigger open the panel | A picker whose trigger reads as a field (a colour, a period) | `false` |
+
+### width (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `auto` | As wide as the content, between `--prime-panel-min-width` and twice that | Most panels | yes |
+| `trigger` | Exactly as wide as the trigger, below the minimum too; text wraps | Full-width triggers in narrow columns | |
+| `content` | What the content needs, within the viewport | A wide calendar, a table of limits | |
 
-**Combinations** — panel `size` = trigger `size` = sizes of the buttons in Actions. Forms: `trapFocus` + Header + Actions. Destructive confirm: `closeOnOutsideClick={false}`, ghost neutral «Отмена» in `Popover.Close` and a solid `tone="danger"` action.
+A bottom sheet is always full width, whatever `width` says.
+
+**Combinations** — panel `size` = trigger `size` = sizes of the buttons in Actions. Forms: `trapFocus` + Header + Actions inside a `<form>`. A must-finish step: `closeOnOutsideClick={false}`, ghost neutral «Отмена» in `Popover.Close` and the primary action; a destructive confirm is a [ConfirmDialog](../confirm-dialog/COMPONENT.md).
 
 **Hierarchy** — one primary button in Actions (last), the rest `ghost` neutral.
 
@@ -119,34 +134,40 @@ Title uses the tier text size with title weight; Description uses the tier label
 | State | Driven by | DOM |
 |---|---|---|
 | open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state="open" \| "closed"` on the panel (closed while the exit animation plays) and on the trigger, `aria-expanded` on the trigger |
+| dismiss | `closeOnEscape`, `closeOnOutsideClick` (both default `true`) | Escape and a press outside close the panel; `false` turns that way off |
 | side | `side` and the room next to the trigger | `data-side` (resolved) |
 | size | `size` on Content | `data-size` |
-| width | `matchTriggerWidth` | `data-match-trigger-width="true"` |
+| width | `width` on Content | `data-width` on the anchored panel |
 | flush | `flush` | `data-flush="true"` |
-| sheet | viewport below 640px, opened from a Trigger (an Anchor keeps the panel next to its field) | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it (with `closeOnOutsideClick`) |
+| sheet | a phone viewport, opened from a Trigger (an Anchor keeps the panel next to its field) | a scrim and a full-width bottom sheet around the panel; the sheet carries `data-state`, the panel `data-sheet` and keeps its role and ref; page scroll locked; with `closeOnOutsideClick` an `aria-hidden` grab handle, and a swipe down from it closes the sheet |
 
 There is no `disabled` on Popover: a disabled trigger never opens it.
 
 Motion (`overlayMotion`): the panel grows out of the side that faces its trigger and fades, in and out over `fast`; as a sheet it slides up over `slow` and down over `base`. Content stays mounted until the exit ends; under `prefers-reduced-motion` it unmounts at once.
 
 ## Layout & spacing
-- Width is `max-content` between `--prime-panel-min-width` and twice that, never wider than the viewport; give forms an explicit width with `className`.
+- Width follows `width`: by default the content's width between `--prime-panel-min-width` and twice that, never wider than the viewport; give forms an explicit width with `className`.
 - Max height follows the free space on the resolved side; the panel scrolls inside.
 - Kept `--prime-space-2` from viewport edges; follows the trigger on scroll and resize.
-- Actions: at the end, `--prime-space-2` gap; on phones (below 640px) they stack full width.
+- Actions: at the end, `--prime-space-2` gap; in a bottom sheet they stack full width.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` | On the trigger: opens the panel (focus moves into it) and closes it. |
+| `ArrowDown` · `ArrowUp` | On the trigger with `openOnArrow`: opens the panel. |
 | `Escape` | Closes the panel (`closeOnEscape`); focus returns to the trigger. |
 | `Tab` | Moves through the panel content; with `trapFocus` it cycles inside the panel, without it Tab past the last stop closes the panel and goes on from the trigger. |
 
 ### ARIA
-- The panel is `role="dialog"` without `aria-modal`, named by `Popover.Title` (else by the trigger) and described by `Popover.Description`.
-- The trigger gets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` and `data-state`; the child's own `id` wins. Other props given to `Popover.Trigger` (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- The panel is `role="dialog"` without `aria-modal`, named by `Popover.Title` (its own `id` included), else by the control it opened from — the trigger, or the control inside `Popover.Anchor` — read from the page, and described by `Popover.Description`.
+- The trigger gets `aria-haspopup="dialog"`, `aria-expanded`, `data-state` and, while open, `aria-controls`; the child's own `id` wins. Other props given to `Popover.Trigger` (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
 - Opened from a Trigger, focus moves into the panel: `[data-autofocus]`, else the first tab stop, else the panel. Opened at a `Popover.Anchor`, focus stays in the anchor (`initialFocus` moves it in), and presses on the anchor do not dismiss the panel.
 - `Popover.Close` closes the panel and returns focus to the trigger, unless the child's own `onClick` calls `preventDefault()`.
 - An outside press closes the panel without moving focus back to the trigger: focus follows the pointer (foundation §8).
@@ -162,13 +183,13 @@ No `labels`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A button opens a filter panel with a header and actions; buttons in `Popover.Close` close it — `Popover.Trigger`, `Popover.Close`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: a panel with plain text only, and a panel with a title, a description and actions — `Popover.Header`, `Popover.Actions`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size tier with a header and actions; the panel takes the tier of its trigger — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier with a header and actions; the tier is the panel's own, set on `Popover.Content`, not taken from its trigger — `size`. |
 | [placement.tsx](examples/placement.tsx) | Every side and alignment relative to the trigger; near the viewport edge the panel flips and shifts — `side`, `align`. |
-| [match-trigger-width.tsx](examples/match-trigger-width.tsx) | In a narrow column the panel takes the exact width of a full-width trigger and its text wraps — `matchTriggerWidth`. |
+| [width.tsx](examples/width.tsx) | In a narrow column the panel takes the exact width of a full-width trigger and its text wraps; a table of limits takes the width it needs — `width`. |
 | [flush.tsx](examples/flush.tsx) | A notification list whose rows and dividers reach the panel edges; each row brings its own padding — `flush`. |
 | [from-menu.tsx](examples/from-menu.tsx) | A menu command opens a panel at the same button: the rename item shows a form anchored to the menu button and focus lands in its field, not back on that button — `Popover.Anchor`, `initialFocus`. |
-| [dismiss.tsx](examples/dismiss.tsx) | A destructive confirm that closes only from its buttons, and not at all while the request runs — `closeOnOutsideClick`, `closeOnEscape`. |
-| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: another button opens the panel from code and its own button closes it — `open`, `onOpenChange`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A note being typed is not lost to a stray click: the panel closes only from its buttons, and not at all while the note is saved — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: another button opens the panel from code, and the panel's own button in `Popover.Close` closes it — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | An invite form in a panel: Tab stays inside, the role list does not count as an outside click, an invalid email shakes the field and keeps the panel open until it is fixed — `trapFocus`, `error`. |
 
 ## Mistakes
@@ -177,6 +198,8 @@ No `labels`.
 - A form without `trapFocus` → add it so Tab stays in the panel.
 - Closing from inside through your own `open` state only → wrap the button in `Popover.Close`.
 - A menu of actions built from buttons in a Popover → use Dropdown (roving focus, menu roles).
+- A destructive confirm in a Popover → use ConfirmDialog (the request, its pending state and its failure are inside).
+- `width="trigger"` on a panel whose content cannot wrap (a table, a calendar) → `width="content"`.
 
 ## Related
 - **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the panel)

package/dist/skill/reference/components/popover/examples/controlled-open.tsx

@@ -1,4 +1,4 @@
-/** The parent owns the open state: another button opens the panel from code and its own button closes it — `open`, `onOpenChange`. */
+/** The parent owns the open state: another button opens the panel from code, and the panel's own button in `Popover.Close` closes it — `open`, `onOpenChange`. */
 import { Button, Popover, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -21,9 +21,11 @@ export default function PopoverControlledOpenExample() {
             Отчёт выгрузится в CSV с текущими фильтрами.
           </Typography>
           <Popover.Actions>
-            <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(false)}>
-              Понятно
-            </Button.Root>
+            <Popover.Close>
+              <Button.Root variant="soft" tone="neutral">
+                Понятно
+              </Button.Root>
+            </Popover.Close>
           </Popover.Actions>
         </Popover.Content>
       </Popover.Root>

package/dist/skill/reference/components/popover/examples/dismiss.tsx

@@ -1,48 +1,57 @@
-/** A destructive confirm that closes only from its buttons, and not at all while the request runs — `closeOnOutsideClick`, `closeOnEscape`. */
-import { Button, Popover } from "prime-ui-kit";
+/** A note being typed is not lost to a stray click: the panel closes only from its buttons, and not at all while the note is saved — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, Input, Popover } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function PopoverDismissExample() {
   const [open, setOpen] = React.useState(false);
-  const [deleting, setDeleting] = React.useState(false);
-
-  const remove = () => {
-    setDeleting(true);
-    window.setTimeout(() => {
-      setDeleting(false);
-      setOpen(false);
-    }, 1200);
-  };
+  const [saving, setSaving] = React.useState(false);
 
   return (
     <Popover.Root
       open={open}
       onOpenChange={setOpen}
       closeOnOutsideClick={false}
-      closeOnEscape={!deleting}
+      closeOnEscape={!saving}
     >
       <Popover.Trigger>
-        <Button.Root variant="soft" tone="danger">
-          Удалить комментарий
+        <Button.Root variant="soft" tone="neutral">
+          Заметка к заказу
         </Button.Root>
       </Popover.Trigger>
-      <Popover.Content className={styles.panel}>
-        <Popover.Header>
-          <Popover.Title>Удалить комментарий?</Popover.Title>
-          <Popover.Description>Его нельзя будет восстановить.</Popover.Description>
-        </Popover.Header>
-        <Popover.Actions>
-          <Popover.Close>
-            <Button.Root variant="ghost" tone="neutral" disabled={deleting}>
-              Отмена
+      <Popover.Content className={styles.panel} trapFocus>
+        <form
+          className={styles.stack}
+          onSubmit={(event) => {
+            event.preventDefault();
+            setSaving(true);
+            window.setTimeout(() => {
+              setSaving(false);
+              setOpen(false);
+            }, 1200);
+          }}
+        >
+          <Popover.Header>
+            <Popover.Title>Заметка к заказу №4821</Popover.Title>
+            <Popover.Description>Её увидят все, кто работает с заказом.</Popover.Description>
+          </Popover.Header>
+          <Input.Root label="Текст заметки">
+            <Input.Wrapper>
+              <Input.Field name="note" placeholder="Клиент просит доставку после 18:00" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Popover.Actions>
+            <Popover.Close>
+              <Button.Root variant="ghost" tone="neutral" disabled={saving}>
+                Отмена
+              </Button.Root>
+            </Popover.Close>
+            <Button.Root type="submit" loading={saving}>
+              Сохранить
             </Button.Root>
-          </Popover.Close>
-          <Button.Root tone="danger" loading={deleting} onClick={remove}>
-            Удалить
-          </Button.Root>
-        </Popover.Actions>
+          </Popover.Actions>
+        </form>
       </Popover.Content>
     </Popover.Root>
   );

package/dist/skill/reference/components/popover/examples/examples.module.css

@@ -12,7 +12,7 @@
   gap: var(--prime-space-3);
 }
 
-/* match-trigger-width.tsx: a narrow sidebar column. */
+/* width.tsx: a narrow sidebar column. */
 .narrowColumn {
   display: flex;
   flex-direction: column;
@@ -22,7 +22,7 @@
 
 /* flush.tsx: the panel has no padding; every row brings its own. */
 .flushPanel {
-  width: calc(var(--prime-panel-min-width) * 1.5);
+  width: var(--prime-layout-min-width);
 }
 
 .flushHead {