prime-ui-kit 0.9.0 → 0.9.1

package/src/components/popover/COMPONENT.md

@@ -1,6 +1,7 @@
 # Popover
 
 **Category:** overlays
+**Kind:** overlay
 
 > A non-modal floating panel anchored to a trigger: short forms, filters, confirmations, explanations.
 
@@ -15,7 +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).
-- A date picker → use [Datepicker](../datepicker/COMPONENT.md) (built on the same panel).
+- A date picker → use [Datepicker](../datepicker/COMPONENT.md) (built on Popover).
 
 ## Import
 ```tsx
@@ -24,60 +25,56 @@ import { Popover } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Popover.Root               state (no DOM)
-├── Popover.Trigger        clones its single child (usually a Button)
-└── Popover.Content        portaled panel, role="dialog", scrolls (ScrollContainer)
-    ├── Popover.Header     title + description, 4 apart
+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.Content          portaled role="dialog" on the floating surface, scrolls
+    ├── Popover.Header       title + description, 4 apart
     │   ├── Popover.Title        <h2>, names the dialog
     │   └── Popover.Description  <p>, describes the dialog
     ├── …content
-    └── Popover.Actions    buttons at the end, right-aligned
+    └── Popover.Actions      buttons at the end
+        └── Popover.Close    clones its child; closes on click
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Popover.Root
-No DOM, no ref.
+No DOM, no ref. Open state and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `open` | `boolean` | — | Controlled visibility. |
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on trigger click, Escape and outside press. |
-| `closeOnOutsideClick` | `boolean` | `true` | A pointerdown outside the panel and its trigger closes it. |
-| `children` | `ReactNode` | — (required) | Trigger and Content. |
+| `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. |
+| `children` | `ReactNode` | — (required) | Trigger (or Anchor) and Content. |
 
-### Popover.Trigger
-No DOM of its own: clones the child (`cloneElement`), like `asChild`. Merges the child's `ref`, sets `id`, `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`, `data-state`, and chains `onClick` (toggles).
+### Popover.Trigger · Popover.Anchor · Popover.Close
+No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles the panel and adds `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, `data-state` (the child's own `id` wins); Anchor only positions the panel and keeps presses on it from dismissing (open state comes from `open`; focus stays in the anchor on open); Close closes the panel (focus back on the trigger) unless the child's handler calls `preventDefault()`. Other props given to Trigger (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactElement` | — (required) | Exactly one element (Button, a `<button>` styled as a link). |
+| `children` | `ReactElement` | — (required) | One element, usually a Button (Anchor: any element, e.g. a toolbar). |
 
 ### Popover.Content
-No ref. Rendered in a portal while open and during its exit animation.
+`ref` → `HTMLDivElement`. Portal + `role="dialog"` on the floating surface (a ScrollContainer); renders while open and during its exit animation. Named by `Popover.Title`, else by the trigger. Opened from a Trigger, focus moves into the panel (`[data-autofocus]`, else the first tab stop, else the panel).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `side` | `"bottom" \| "top"` | `"bottom"` | Preferred side; flips when it does not fit. |
-| `align` | `"start" \| "center" \| "end"` | `"start"` | Horizontal alignment to the trigger. |
-| `sameMinWidthAsTrigger` | `boolean` | `false` | The panel takes the trigger width (not wider than the panel max width and viewport). |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Padding, gap and text tier; size context for controls inside. |
-| `trapFocus` | `boolean` | `false` | Moves focus into the panel and keeps Tab inside; focus returns to the trigger on close. |
-| `insetPadding` | `"none" \| "x1" \| "x2" \| "x3"` | `"none"` | Extra padding on top of the tier padding: +4 · +8 · +12. |
-| `insetGap` | `"none" \| "pad" \| "x2" \| "x3" \| "x4"` | `"pad"` | Gap between direct children: tier gap, or 0 · 8 · 12 · 16. |
-| `stackAboveDropdown` | `boolean` | `false` | Raise the panel above a dropdown / listbox of the same layer (trigger inside a Select, TagSelect or Dropdown panel). |
-| `className` | `string` | — | Extra class on the panel (e.g. a fixed width). |
-| `children` | `ReactNode` | — (required) | Panel content. |
-
-### Popover.Header · Popover.Actions
-No ref. + native `<div>` props.
-
-### Popover.Title
-No ref. Renders `<h2>`; without an own `id` it becomes the dialog name (`aria-labelledby`). + native heading props.
-
-### Popover.Description
-No ref. Renders `<p>`; without an own `id` it becomes the dialog description (`aria-describedby`). + native `<p>` props.
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side; flips to the opposite side when there is no room. |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment along the trigger; shifts inside the viewport. |
+| `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. |
+| `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. |
+| `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 below 480 px). + native props.
 
 ## Variants
 The panel has one look: `bg-raised` fill, `--prime-panel-radius`, `shadow-overlay`, no border. Fields inside get the surface field fill; cards inside become sunken tiles.
@@ -96,90 +93,82 @@ Title uses the tier text size with title weight; Description uses the tier label
 ### side / align (Content)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `side="bottom"` | Below the trigger, `--prime-space-1` away | Default | yes |
+| `side="bottom"` | Below the trigger, `--prime-panel-offset` away | Default | yes |
 | `side="top"` | Above the trigger | Triggers near the bottom of the screen | |
-| `align="start"` | Start edges aligned | Default, LTR reading | yes |
-| `align="center"` | Centred under the trigger | Small icon triggers | |
-| `align="end"` | End edges aligned | Triggers at the right edge | |
-
-### insetPadding / insetGap
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `insetPadding="none"` | Tier padding only | Default | yes |
-| `insetPadding="x1"` · `"x2"` · `"x3"` | +4 · +8 · +12 padding | Airy marketing/explainer panels | |
-| `insetGap="pad"` | Tier gap (8 / 12 / 16) | Default | yes |
-| `insetGap="none"` | No gap between children | Own layout inside | |
-| `insetGap="x2"` · `"x3"` · `"x4"` | 8 · 12 · 16 gap | Fixed rhythm independent of size | |
+| `side="left"` / `"right"` | Beside the trigger, aligned along its height | Triggers in a side rail or a narrow column | |
+| `align="start"` | Start edges aligned | Default | yes |
+| `align="center"` | Centred on the trigger | Small icon triggers | |
+| `align="end"` | End edges aligned | Triggers at the end of a toolbar | |
 
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `sameMinWidthAsTrigger` | Panel as wide as the trigger | Full-width triggers in narrow columns | `false` |
-| `trapFocus` | Focus moves into the panel | Forms inside the panel | `false` |
-| `stackAboveDropdown` | Higher z-index on the same layer | Popover opened from inside a listbox | `false` |
+| `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 | |
+| `closeOnEscape={false}` | Escape does nothing | While a request of the panel runs | |
 
-**Combinations** — panel `size` = trigger `size` = sizes of the buttons in Actions. Forms: `trapFocus` + Header + Actions. Destructive confirm: Actions with ghost neutral «Отмена» and solid `tone="danger"` primary.
+**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.
 
 **Hierarchy** — one primary button in Actions (last), the rest `ghost` neutral.
 
 ## States
-- Closed / open: uncontrolled by default; `open` + `onOpenChange` for controlled. There is no `disabled` on Popover: a disabled trigger simply never opens it.
-- Panel DOM: `data-state="open" | "closed"`, `data-side` (resolved), `data-size`, `data-inset-padding`, `data-inset-gap`, `data-overlay-portal-layer`, `data-overlay-stack="above-dropdown"` (with `stackAboveDropdown`).
-- Trigger DOM: `data-state="open" | "closed"`, `aria-expanded`.
+| 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 |
+| 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"` |
+| flush | `flush` | `data-flush="true"` |
+
+There is no `disabled` on Popover: a disabled trigger never opens it.
 
 ## Layout & spacing
-- Width is `max-content` between `--prime-panel-min-width` and twice that, never wider than the viewport; set an explicit width with `className` for forms.
+- Width is `max-content` 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; repositions on scroll / resize.
-- Actions: right-aligned, `--prime-space-2` gap; below 480px they stack full width.
+- Kept `--prime-space-2` from viewport edges; follows the trigger on scroll and resize.
+- Actions: at the end, `--prime-space-2` gap; below 480px they stack full width.
 
 ## Accessibility
-- Panel: `role="dialog"`, `aria-modal="false"`, named by Popover.Title (or by the trigger when there is no Title), described by Popover.Description.
-- Trigger: `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`.
-- Dismiss (foundation §8): Escape closes and returns focus to the trigger; an outside press closes without moving focus back (focus follows the pointer). Clicks inside nested layers (a Select list inside the panel) do not close it. Only the topmost layer reacts.
-- Use `trapFocus` for forms so keyboard users land inside the panel.
-- No `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | `size` xs → xl with header and actions | Matching the panel to the trigger |
-| [inset-variants.tsx](examples/inset-variants.tsx) | `insetPadding` / `insetGap` | Custom density |
-| [states.tsx](examples/states.tsx) | Destructive confirm, disabled trigger | Confirming next to the action |
-| [placement.tsx](examples/placement.tsx) | `side` × `align` | Placing near edges |
-| [controlled.tsx](examples/controlled.tsx) | `open` + `onOpenChange` from the parent | Opening from other UI |
-| [composition.tsx](examples/composition.tsx) | Report filters with SegmentedControl and checkboxes | Filters / quick settings |
-| [full-width.tsx](examples/full-width.tsx) | `sameMinWidthAsTrigger` | Narrow columns |
-| [as-child.tsx](examples/as-child.tsx) | Text-link button as the trigger | Inline explanations |
-| [features.tsx](examples/features.tsx) | Invite form with `trapFocus` and a nested Select | Short forms |
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | On the trigger: opens the panel (focus moves into it) and closes it. |
+| `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. |
 
-```tsx
-import { Button, Popover } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Popover.Root>
-      <Popover.Trigger>
-        <Button.Root variant="soft" tone="neutral">
-          Условия тарифа
-        </Button.Root>
-      </Popover.Trigger>
-      <Popover.Content>
-        <Popover.Header>
-          <Popover.Title>Тариф «Бизнес»</Popover.Title>
-          <Popover.Description>До 10 пользователей и 50 ГБ хранилища.</Popover.Description>
-        </Popover.Header>
-      </Popover.Content>
-    </Popover.Root>
-  );
-}
-```
+### 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` and `aria-controls`.
+- An outside press closes the panel without moving focus back to the trigger: focus follows the pointer (foundation §8).
+- Only the topmost layer reacts: a Select open inside the panel closes first.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [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`. |
+| [flush.tsx](examples/flush.tsx) | A notification list whose rows and dividers reach the panel edges; each row brings its own padding — `flush`. |
+| [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`. |
+| [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, and submit closes the panel — `trapFocus`. |
 
 ## Mistakes
-- `side="left"` / `"right"` → Popover supports only `top` and `bottom`.
+- A hint of a few words in a Popover → use Tooltip (hover / focus, no interactive content).
 - A form without `trapFocus` → add it so Tab stays in the panel.
-- A popover opened from inside a Select/Dropdown panel hides behind it → `stackAboveDropdown`.
-- Menu of actions built from buttons in a Popover → use Dropdown (roving focus, menu roles).
+- 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).
 
 ## Related
-[Tooltip](../tooltip/COMPONENT.md) · [Dropdown](../dropdown/COMPONENT.md) · [Modal](../modal/COMPONENT.md) · [Datepicker](../datepicker/COMPONENT.md) · [ColorPicker](../color-picker/COMPONENT.md)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the panel)
+- **See also:** [Tooltip](../tooltip/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Modal](../modal/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md)

package/src/components/popover/examples/controlled-open.tsx

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

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

@@ -0,0 +1,49 @@
+/** 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";
+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);
+  };
+
+  return (
+    <Popover.Root
+      open={open}
+      onOpenChange={setOpen}
+      closeOnOutsideClick={false}
+      closeOnEscape={!deleting}
+    >
+      <Popover.Trigger>
+        <Button.Root variant="soft" tone="danger">
+          Удалить комментарий
+        </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}>
+              Отмена
+            </Button.Root>
+          </Popover.Close>
+          <Button.Root tone="danger" loading={deleting} onClick={remove}>
+            Удалить
+          </Button.Root>
+        </Popover.Actions>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/examples.module.css

@@ -1,20 +1,18 @@
-/* Layout for the Popover examples: layout only, text goes through Typography. */
+/* Layout of the Popover scenarios: semantic tokens only. */
 
-.row {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: var(--prime-space-3);
+/* A panel with a fixed measure for a header, text or a short form. */
+.panel {
+  width: calc(var(--prime-space-24) * 3.5);
+  max-width: 100%;
 }
 
-.column {
+.stack {
   display: flex;
   flex-direction: column;
-  align-items: center;
   gap: var(--prime-space-3);
 }
 
+/* match-trigger-width.tsx: a narrow sidebar column. */
 .narrowColumn {
   display: flex;
   flex-direction: column;
@@ -22,43 +20,25 @@
   max-width: calc(var(--prime-space-24) * 2.5);
 }
 
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-3);
-}
-
-.panelWidth {
-  width: calc(var(--prime-space-24) * 3.5);
-  max-width: 100%;
-}
-
-/* Measure of plain text inside a panel. */
-.text {
-  max-width: calc(var(--prime-space-24) * 3.5);
+/* flush.tsx: the panel has no padding; every row brings its own. */
+.flushPanel {
+  width: calc(var(--prime-panel-min-width) * 1.5);
 }
 
-/* Unstyled button around a Typography label that reads as a text link. */
-.textLinkTrigger {
-  padding: 0;
-  border: 0;
-  background: none;
-  cursor: pointer;
+.flushHead {
+  padding: var(--prime-space-3) var(--prime-space-4);
 }
 
-.underline {
-  text-decoration: underline;
-  text-underline-offset: var(--prime-space-1);
-}
-
-.textLinkTrigger:focus-visible {
-  outline: var(--prime-focus-width) solid var(--prime-color-focus-ring);
-  outline-offset: var(--prime-focus-offset);
-  border-radius: var(--prime-radius-xs);
+.flushRow {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-3) var(--prime-space-4);
 }
 
-.field {
+.flushFooter {
   display: flex;
-  flex-direction: column;
-  gap: var(--prime-control-m-label-gap);
+  justify-content: flex-end;
+  padding: var(--prime-space-1);
 }

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

@@ -0,0 +1,47 @@
+/** A notification list whose rows and dividers reach the panel edges; each row brings its own padding — `flush`. */
+import { Button, Divider, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  { id: "paid", title: "Счёт № 4821 оплачен", time: "12:04" },
+  { id: "review", title: "Новый отзыв на «Планшет Pro»", time: "11:47" },
+  { id: "sync", title: "Синхронизация складов завершена", time: "10:30" },
+];
+
+export default function PopoverFlushExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Уведомления
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content flush className={styles.flushPanel}>
+        <Popover.Title className={styles.flushHead}>Уведомления</Popover.Title>
+        {EVENTS.map((event) => (
+          <React.Fragment key={event.id}>
+            <Divider role="presentation" />
+            <div className={styles.flushRow}>
+              <Typography as="span" variant="body-m">
+                {event.title}
+              </Typography>
+              <Typography as="span" variant="caption" tone="muted">
+                {event.time}
+              </Typography>
+            </div>
+          </React.Fragment>
+        ))}
+        <Divider role="presentation" />
+        <div className={styles.flushFooter}>
+          <Popover.Close>
+            <Button.Root variant="ghost" tone="neutral" size="s">
+              Прочитать все
+            </Button.Root>
+          </Popover.Close>
+        </div>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

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

@@ -0,0 +1,54 @@
+/** An invite form in a panel: Tab stays inside, the role list does not count as an outside click, and submit closes the panel — `trapFocus`. */
+import { Button, Input, Popover, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function PopoverInFormExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger>
+        <Button.Root>Пригласить</Button.Root>
+      </Popover.Trigger>
+      <Popover.Content className={styles.panel} trapFocus>
+        <Popover.Header>
+          <Popover.Title>Пригласить в проект</Popover.Title>
+          <Popover.Description>Приглашение придёт на почту.</Popover.Description>
+        </Popover.Header>
+        <form
+          className={styles.stack}
+          onSubmit={(event) => {
+            event.preventDefault();
+            setOpen(false);
+          }}
+        >
+          <Input.Root label="Почта" required>
+            <Input.Wrapper>
+              <Input.Field type="email" name="email" placeholder="name@company.ru" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Select.Root label="Роль" defaultValue="editor">
+            <Select.Trigger>
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              <Select.Item value="viewer">Наблюдатель</Select.Item>
+              <Select.Item value="editor">Редактор</Select.Item>
+              <Select.Item value="admin">Администратор</Select.Item>
+            </Select.Content>
+          </Select.Root>
+          <Popover.Actions>
+            <Popover.Close>
+              <Button.Root variant="ghost" tone="neutral">
+                Отмена
+              </Button.Root>
+            </Popover.Close>
+            <Button.Root type="submit">Отправить</Button.Root>
+          </Popover.Actions>
+        </form>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/{full-width.tsx → match-trigger-width.tsx}

@@ -1,21 +1,21 @@
-/** `sameMinWidthAsTrigger`: the panel takes the width of a full-width trigger and the text wraps. Use in narrow columns and sidebars. */
+/** In a narrow column the panel takes the exact width of a full-width trigger and its text wraps — `matchTriggerWidth`. */
 import { Button, Popover, Typography } from "prime-ui-kit";
 
-import preview from "./examples.module.css";
+import styles from "./examples.module.css";
 
-export default function PopoverFullWidthExample() {
+export default function PopoverMatchTriggerWidthExample() {
   return (
-    <div className={preview.narrowColumn}>
+    <div className={styles.narrowColumn}>
       <Popover.Root>
         <Popover.Trigger>
           <Button.Root variant="soft" tone="neutral" fullWidth>
             Условия тарифа
           </Button.Root>
         </Popover.Trigger>
-        <Popover.Content sameMinWidthAsTrigger>
-          <Typography.Root variant="body-s" tone="secondary" className={preview.text}>
+        <Popover.Content matchTriggerWidth>
+          <Typography variant="body-s" tone="secondary">
             До 10 пользователей, 50 ГБ хранилища и приоритетная поддержка.
-          </Typography.Root>
+          </Typography>
         </Popover.Content>
       </Popover.Root>
     </div>

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

@@ -0,0 +1,43 @@
+/** A button opens a filter panel with a header and actions; buttons in `Popover.Close` close it — `Popover.Trigger`, `Popover.Close`. */
+import { Button, Checkbox, Icon, Popover } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PopoverOverviewExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="action.filter" />
+          </Button.Icon>
+          Фильтры
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content className={styles.panel}>
+        <Popover.Header>
+          <Popover.Title>Фильтры отчёта</Popover.Title>
+          <Popover.Description>Применяются ко всем графикам на странице.</Popover.Description>
+        </Popover.Header>
+        <div className={styles.stack}>
+          <Checkbox.Root defaultChecked>
+            <Checkbox.Label>Только активные клиенты</Checkbox.Label>
+          </Checkbox.Root>
+          <Checkbox.Root>
+            <Checkbox.Label>Скрыть нулевые строки</Checkbox.Label>
+          </Checkbox.Root>
+        </div>
+        <Popover.Actions>
+          <Popover.Close>
+            <Button.Root variant="ghost" tone="neutral">
+              Сбросить
+            </Button.Root>
+          </Popover.Close>
+          <Popover.Close>
+            <Button.Root>Применить</Button.Root>
+          </Popover.Close>
+        </Popover.Actions>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}