prime-ui-kit 0.14.0 → 0.16.0

package/src/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/src/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/src/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/src/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 {

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

@@ -1,36 +1,41 @@
-/** Every size tier with a header and actions; the panel takes the tier of its trigger — `size`. */
-import { Button, Popover } from "prime-ui-kit";
+/** 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`. */
+import { Button, Popover, Typography } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function PopoverSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <Popover.Root key={size}>
-          <Popover.Trigger>
-            <Button.Root variant="soft" tone="neutral" size={size}>
-              {size}
-            </Button.Root>
-          </Popover.Trigger>
-          <Popover.Content size={size}>
-            <Popover.Header>
-              <Popover.Title>Сохранить фильтр?</Popover.Title>
-              <Popover.Description>Он появится в списке слева.</Popover.Description>
-            </Popover.Header>
-            <Popover.Actions>
-              <Popover.Close>
-                <Button.Root variant="ghost" tone="neutral" size={size}>
-                  Отмена
-                </Button.Root>
-              </Popover.Close>
-              <Popover.Close>
-                <Button.Root size={size}>Сохранить</Button.Root>
-              </Popover.Close>
-            </Popover.Actions>
-          </Popover.Content>
-        </Popover.Root>
+        <div key={size}>
+          <Popover.Root>
+            <Popover.Trigger>
+              <Button.Root variant="soft" tone="neutral" size={size}>
+                Сохранить фильтр
+              </Button.Root>
+            </Popover.Trigger>
+            <Popover.Content size={size}>
+              <Popover.Header>
+                <Popover.Title>Сохранить фильтр?</Popover.Title>
+                <Popover.Description>Он появится в списке слева.</Popover.Description>
+              </Popover.Header>
+              <Popover.Actions>
+                <Popover.Close>
+                  <Button.Root variant="ghost" tone="neutral" size={size}>
+                    Отмена
+                  </Button.Root>
+                </Popover.Close>
+                <Popover.Close>
+                  <Button.Root size={size}>Сохранить</Button.Root>
+                </Popover.Close>
+              </Popover.Actions>
+            </Popover.Content>
+          </Popover.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/popover/examples/width.tsx

@@ -0,0 +1,45 @@
+/** 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`. */
+import { Button, DescriptionList, Popover, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LIMITS = [
+  { term: "Пользователи", value: "до 10 на рабочее пространство" },
+  { term: "Хранилище", value: "50 ГБ на команду, файлы до 2 ГБ" },
+  { term: "Поддержка", value: "приоритетная, ответ в течение 4 часов" },
+];
+
+export default function PopoverWidthExample() {
+  return (
+    <div className={styles.narrowColumn}>
+      <Popover.Root>
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral" fullWidth>
+            Условия тарифа
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content width="trigger">
+          <Typography variant="body-s" tone="secondary">
+            До 10 пользователей, 50 ГБ хранилища и приоритетная поддержка.
+          </Typography>
+        </Popover.Content>
+      </Popover.Root>
+      <Popover.Root>
+        <Popover.Trigger>
+          <Button.Root variant="ghost" tone="neutral" fullWidth>
+            Все лимиты
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content width="content">
+          <DescriptionList.Root>
+            {LIMITS.map((limit) => (
+              <DescriptionList.Item key={limit.term} label={limit.term}>
+                {limit.value}
+              </DescriptionList.Item>
+            ))}
+          </DescriptionList.Root>
+        </Popover.Content>
+      </Popover.Root>
+    </div>
+  );
+}

package/src/components/progress-bar/COMPONENT.md

@@ -39,40 +39,27 @@ ProgressBar              <div>; size, tone (value mode), aria-busy while loading
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### ProgressBar
-`ref` → `HTMLDivElement` (the root). Props of both modes; pass either `value` (value mode) or `segments` (segments mode), never both.
+`ref` → `HTMLDivElement` (the root). Pass `value` (value mode: a native `<progress>`, transparent, under the drawn line) or `segments` (segments mode: a `role="group"` bar of parts described by the legend or the distribution text; `layout="rows"` — an `<ol>`), never both.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Line thickness 4 → 8 px (`--prime-control-<tier>-track`, shared with Slider) and label type. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Line thickness 4 → 8 px (`--prime-control-<tier>-track`, shared with Slider) and label type. Without it the tier of its host, else `m`. |
 | `label` | `string` | — | Visible label above the line and its accessible name; a value bar without it needs `aria-label`. |
 | `showValue` | `boolean` | `false` | Shows the rounded filled percentage at the end of the label row (`aria-hidden`); `bar` layout only. |
 | `loading` | `boolean` | `false` | The data is on its way: a Skeleton in the bar's geometry cross-fades into the data; the label stays. Pass the last known `value` or `segments` (or `0` / `[]`). |
+| `value` | `number` | — | Value mode: the current value, clamped to `0…max`. |
+| `max` | `number` | `100` (value mode), the sum of the parts (segments mode) | Value mode: top of the scale. Segments mode: total capacity; a `max` above the sum of the parts leaves the rest as track. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Value mode: fill color, telling the outcome. |
+| `steps` | `boolean` | `false` | Value mode: draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. For a level out of a few: password strength, onboarding steps. |
+| `segments` | `ProgressSegment[]` | — | Segments mode: parts in order, `{ value, label?, tone? \| color? }`: `tone` names a meaning (default `accent`), `color` a category, as in its charts. Each part's width is its share of `max`. |
+| `segmentGap` | `"none" \| "hairline"` | `"none"` | Segments mode: `none` — one continuous pill; `hairline` — every part and the rest are separate pills. `bar` layout. |
+| `legend` | `boolean` | `false` | Segments mode: a legend under the bar, one row per part: color · name · value · share; it becomes the group's description. `bar` layout. |
+| `formatValue` | `(value: number) => string` | Russian digit groups | Segments mode: display of a part's value in the legend and the rows («1 840 000 ₽»). |
+| `layout` | `"bar" \| "rows"` | `"bar"` | Segments mode: `bar` — every part in one bar; `rows` — a ranking: an `<ol>`, one row per part with label · value · share over its own bar. |
+| `scale` | `"sum" \| "max" \| "first"` | `"sum"` | Segments mode: `rows` only: what 100% is. `sum` — bars and shares of the total (`max` raises it); `max` — the leader is a full bar, shares stay of the total; `first` — bars and shares against the first row (a funnel). |
+| `labels` | `Partial<ProgressBarLabels>` | — | Segments mode: built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root; `aria-label` names the bar when there is no `label`. |
 
-### ProgressBar · value mode
-A native `<progress>` (transparent, for assistive tech) under the drawn line.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `value` | `number` | — (required) | The current value, clamped to `0…max`. |
-| `max` | `number` | `100` | Top of the scale. |
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Fill color, telling the outcome. |
-| `steps` | `boolean` | `false` | Draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. For a level out of a few: password strength, onboarding steps. |
-
-### ProgressBar · segments mode
-A `role="group"` bar of parts, named by `label` and described by the legend or the distribution text; with `layout="rows"` an `<ol>` named by `label`.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? \| color? }`: `tone` names a meaning (default `accent`), `color` a category, as in its charts. Each part's width is its share of `max`. |
-| `max` | `number` | — | Total capacity. Default: the sum of the parts; a larger `max` leaves the rest as track. |
-| `segmentGap` | `"none" \| "hairline"` | `"none"` | `none` — one continuous pill; `hairline` — every part and the rest are separate pills. `bar` layout. |
-| `legend` | `boolean` | `false` | A legend under the bar, one row per part: color · name · value · share; it becomes the group's description. `bar` layout. |
-| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a part's value in the legend and the rows («1 840 000 ₽»). |
-| `layout` | `"bar" \| "rows"` | `"bar"` | `bar` — every part in one bar; `rows` — a ranking: an `<ol>`, one row per part with label · value · share over its own bar. |
-| `scale` | `"sum" \| "max" \| "first"` | `"sum"` | `rows` only: what 100% is. `sum` — bars and shares of the total (`max` raises it); `max` — the leader is a full bar, shares stay of the total; `first` — bars and shares against the first row (a funnel). |
-| `labels` | `Partial<ProgressBarLabels>` | — | Built-in strings, see Labels. |
-
 ## Variants
 
 ### tone (value mode or each segment)
@@ -126,6 +113,7 @@ A `role="group"` bar of parts, named by `label` and described by the legend or t
 | `showValue` | secondary `NN%` at the end of the header | uploads, quotas — the user tracks the number | `false` |
 | `legend` | rows of swatch · name · value · share under the bar | a distribution the reader compares in numbers | `false` |
 | `loading` | a Skeleton bar (and legend or row lines) in the same geometry | the data is on its way | `false` |
+| `steps` | `max` equal cells (2–12), each filled whole | a level out of a few: password strength, an onboarding step | `false` |
 
 ## States
 | State | Driven by | DOM |
@@ -134,7 +122,7 @@ A `role="group"` bar of parts, named by `label` and described by the legend or t
 | value | `value`, `max` | native `value` / `max`; the drawn pill slides by `translate` over `slow` + `standard`, RTL aware |
 | segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the group, `data-tone` or `data-color` per part; widths animate by `flex-grow` over `slow` |
 | rows | `layout="rows"`, `scale` | `data-layout="rows"` on the root, an `<ol>`; each bar slides like the value pill |
-| loading | `loading` | `aria-busy` on the root; Skeletons in place of the bar, the legend or the rows; the data cross-fades in (`swapMotion`) |
+| loading | `loading` | `aria-busy` on the root; Skeletons in place of the bar, the legend or the rows; the data cross-fades in and the height glides (`RegionSwap`) |
 | steps | `steps` (value mode) | `data-steps="true"` on the bar; `max` cells (2–12), filled ones `data-filled`; a cell fills from its start edge (`base` · emphasized), cells of one change go half a stagger step apart — from the start when filling, from the end when emptying |
 | empty segments | `segments` empty or all `0` | only the track; accessible text `labels.empty` / `labels.allEmpty` |
 | reduced motion | `prefers-reduced-motion` | fill, widths and cells change instantly |
@@ -146,14 +134,18 @@ Always controlled: pass the current `value` or `segments` on every render.
 - Label → line: the tier `label-gap` (`--prime-space-1` xs/s, `--prime-space-2` m–xl). The label is primary, medium weight; the percentage secondary, tabular numbers.
 - Bar → legend `--prime-space-3` (12). Rows (`layout="rows"`) are 12 apart, each header 4 above its bar: the label (secondary, truncates) takes the free width, the value (primary, medium) and the share (muted, at least 4ch) line up at the end in tabular numbers.
 - `hairline` gaps and `steps` cells are ¾ of the line thickness apart.
-- Stack several bars with `--prime-space-4`–`--prime-space-5`.
+- Stack several bars 16–20 apart (a gap on their parent).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Value mode: native `<progress>` — role `progressbar` with value and max.
 - Segments mode: `role="group"`; its text lists the shares of `max` («Видео: 38%, Документы: 21%»). With `label` (or `aria-label`) the group is named by it and described by the distribution — or by the legend when `legend` is on; without a name the distribution is the name.
 - Rows: an `<ol>` named by `label`; each row reads as text («Москва 1 284 52%»), the bars are `aria-hidden`.
@@ -177,7 +169,7 @@ No keyboard interaction.
 | [sizes.tsx](examples/sizes.tsx) | Every tier: the line grows from 4 to 8 px like the Slider track — `size`. |
 | [states.tsx](examples/states.tsx) | Loading takes the bar's own geometry, so the data lands without a jump — `loading`. |
 | [custom-max.tsx](examples/custom-max.tsx) | A scale of steps instead of percent: 3 of 5 profile steps — `max`. |
-| [segments.tsx](examples/segments.tsx) | Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list — `segments`, `segmentGap`, `max`. |
+| [segments.tsx](examples/segments.tsx) | Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list with its own spoken text — `segments`, `segmentGap`, `max`, `labels`. |
 | [legend.tsx](examples/legend.tsx) | Shares of categories in their chart colors with a legend of color · name · value · share — `color`, `legend`, `formatValue`. |
 | [ranking.tsx](examples/ranking.tsx) | Rankings as rows of label · value · share over a bar: top cities against the leader and a funnel against its first step — `layout`, `scale`. |
 | [steps.tsx](examples/steps.tsx) | The scale as whole cells that fill one after another: 2 of 5 onboarding steps, forward and back — `steps`, `max`. |
@@ -195,5 +187,5 @@ No keyboard interaction.
 - A grey box while the data loads → `loading` draws the Skeleton in the bar's geometry.
 
 ## Related
-- **Built from:** [Skeleton](../skeleton/COMPONENT.md)
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ProgressCircle](../progress-circle/COMPONENT.md), [Slider](../slider/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md), [Spinner](../spinner/COMPONENT.md)

package/src/components/progress-bar/examples/examples.module.css

@@ -5,7 +5,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-5);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
   min-width: 0;
 }
 

package/src/components/progress-bar/examples/segments.tsx

@@ -1,4 +1,4 @@
-/** Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list — `segments`, `segmentGap`, `max`. */
+/** Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list with its own spoken text — `segments`, `segmentGap`, `max`, `labels`. */
 import { ProgressBar, type ProgressSegment } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -26,7 +26,7 @@ export default function ProgressBarSegmentsExample() {
         label="Хранилище: 71 из 100 ГБ"
         showValue
       />
-      <ProgressBar segments={[]} label="Нет данных за период" />
+      <ProgressBar segments={[]} label="Заявки за ноябрь" labels={{ empty: "Заявок пока нет" }} />
     </div>
   );
 }