prime-ui-kit 0.7.13 → 0.9.1

package/src/components/popover/COMPONENT.md

@@ -1,146 +1,174 @@
 # Popover
 
-**Default sizing:** when designing screens and examples, start with **`m`** for `size` (where a size axis exists) unless the scenario explicitly needs another value.
+**Category:** overlays
+**Kind:** overlay
 
-## About
+> A non-modal floating panel anchored to a trigger: short forms, filters, confirmations, explanations.
 
-A composite “anchor + portaled panel”: clicking the trigger toggles a non-modal dialog next to the anchor, positioned toward the viewport edge and dismissible with Escape or an outside click.
+## 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.
+- An explanation with more than one sentence, or with a link, next to a term.
 
-- **Use** for short contextual panels—help text, compact filters, a few fields or actions—without leaving the page or blocking the whole UI.
-- **Use** when content should stay visually tied to a specific control (metrics, footnotes, inline configuration).
-- **Do not use** for full-screen or blocking flows; prefer [Modal](../modal/COMPONENT.md).
-- **Do not use** for hover-only hints; prefer [Tooltip](../tooltip/COMPONENT.md).
-- **Do not use** expecting left/right placement relative to the anchor; only **top** and **bottom** sides are supported.
-- **Do not use** with multiple or fragment children under `Popover.Trigger`; exactly **one** element is supported.
-
-## Composition
-
-- **`Popover.Root`** — holds open state (controlled or uncontrolled), stable ids for trigger and content, and the trigger element ref used for positioning.
-- **`Popover.Trigger`** — must wrap **exactly one** `React` element; ref, `aria-*`, and click-to-toggle are merged onto that child (`cloneElement`).
-- **`Popover.Content`** — rendered in a **portal** only when open; root is a scroll container with `role="dialog"`, positioned from the trigger via `side` / `align`, wraps children in `ControlSizeProvider` when `size` is set, and applies optional **`insetPadding`** / **`insetGap`** on the same node (`data-inset-padding`, `data-inset-gap`).
-
-### Minimal example
+## When not to use
+- A one-line hint on hover → use [Tooltip](../tooltip/COMPONENT.md).
+- 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 Popover).
 
+## Import
 ```tsx
-import { Button, Popover } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Popover.Root>
-      <Popover.Trigger asChild>
-        <Button.Root type="button">Open</Button.Root>
-      </Popover.Trigger>
-      <Popover.Content>
-        Panel
-      </Popover.Content>
-    </Popover.Root>
-  );
-}
+import { Popover } from "prime-ui-kit";
 ```
 
-### Canonical panel (reference)
-
-Short English recipe (stroke trigger, **`insetPadding` / `insetGap`**, body copy): **`examples/canonical-panel.tsx`**.
-
-### Playground-aligned examples
-
-**`playground/sections/PopoverSection.tsx`** and **`playground/snippets/popover/`** define the demo order and code shown in the playground (Russian UI copy). Matching runnable package examples (imports from **`"prime-ui-kit"`**) live next to this file:
-
-| Playground block | Snippet | Example file |
-|------------------|---------|--------------|
-| Sizes | `sizes.tsx` | `sizes.tsx` |
-| Inset variants | `inset-variants.tsx` | `inset-variants.tsx` |
-| States | `states.tsx` | `states.tsx` |
-| Placement | `placement.tsx` | `placement.tsx` |
-| Controlled | `controlled.tsx` | `controlled.tsx` |
-| Composition | `composition.tsx` | `composition.tsx` |
-| Full width (trigger) | `full-width.tsx` | `full-width.tsx` |
-| Custom trigger | `as-child.tsx` | `as-child.tsx` |
-| Focus + nested Select | `features.tsx` | `features.tsx` |
-
-Shared layout for these examples: **`examples/popover-examples.module.css`**.
-
-### Additional examples in `examples/`
-
-| File | Intent |
-|------|--------|
-| `canonical-panel.tsx` | Default English composition: stroke trigger, inset spacing, short copy |
-| `date-trigger.tsx` | Date-style trigger label; native **`type="date"`** field; **`trapFocus`** |
-| `rich-content.tsx` | Badges, **`Divider`**, **`Hint`** — denser non-modal panel |
-| `form-in-popover.tsx` | Controlled root, small form, **`trapFocus`**, submit closes |
-
-### Extended usage
-
-- **Controlled popovers:** pass **`open`** and **`onOpenChange`** on **`Popover.Root`**; keep **`Popover.Trigger`** and **`Popover.Content`** as siblings. Close from inside the panel by calling the same setter or relying on outside click / Escape.
-- **Forms and focus:** set **`trapFocus={true}`** on **`Popover.Content`** when several controls should keep Tab cycles inside the panel (see **`examples/form-in-popover.tsx`**, **`examples/date-trigger.tsx`**, and **`examples/features.tsx`**).
-- **Match trigger width:** use **`sameMinWidthAsTrigger`** when the panel should match the trigger’s **`width`** and **`minWidth`** (`border-box`, text wraps; still bounded by panel max width and viewport). See **`examples/full-width.tsx`**.
-- **Nested Select:** portaled Select listbox clicks owned by the panel are not treated as outside closes (see `isPortaledSelectListboxOwnedByContainer` in implementation; **`examples/features.tsx`**).
-- **Density:** tune **`size`** on **`Popover.Content`** for nested controls and **`insetPadding` / `insetGap`** for internal vertical rhythm; optional **`className`** on **`Content`** for scoped layout hooks.
-
-### Note for LLMs
-
-When generating **Popover** markup for this library: (1) **`Popover.Trigger`** accepts **exactly one** child element—no fragments or multiple nodes. (2) Prefer **`Button.Root`**, **`LinkButton.Root`**, or another kit control as the trigger so sizing and focus styles stay on the design-system tier. (3) Only **`side="top"`** and **`side="bottom"`** are valid; do not assume left/right anchoring. (4) Align scenarios with **`playground/snippets/popover/`** and the matching **`examples/*.tsx`** files in the table above; add **`canonical-panel.tsx`**, **`date-trigger.tsx`**, **`rich-content.tsx`**, or **`form-in-popover.tsx`** when you need those extra recipes. (5) Do not wrap kit components to restyle them; use **`size`**, **`variant`**, **`mode`**, **`insetPadding`**, **`insetGap`**, and documented props only.
-
-## Rules
-
-- **Uncontrolled:** use `defaultOpen` on `Popover.Root` for the initial open state after mount.
-- **Controlled:** pass `open` and `onOpenChange` together; parent can open or close from outside logic.
-- When closed, **`Popover.Content`** returns `null` (nothing is mounted in the portal).
-- **`trapFocus`** on `Popover.Content` keeps Tab cycling inside the panel while open and restores focus on close when enabled.
-- **Escape** and **outside click** call close; clicks on a portaled **Select** listbox that belongs to the panel are ignored as outside (see `isPortaledSelectListboxOwnedByContainer`).
-- **Non-modal:** `aria-modal={false}`—focus can leave the page; this is intentional for a lightweight overlay.
-- Trigger receives **`aria-expanded`**, **`aria-haspopup="dialog"`**, and **`aria-controls`** pointing at the content id; **`aria-labelledby`** on the panel references the trigger id—give the anchor a visible name or **`aria-label`** when there is no text.
-- There is no popover-level **`disabled`**; if the anchor (e.g. [Button](../button/COMPONENT.md)) is disabled, it will not open.
-- **`asChild`** exists for slot API compatibility; merging always applies to the single child—**`asChild={false}`** does not render an internal button.
-- Density: tune **`Popover.Content` `size`** for the control tier and **`insetPadding` / `insetGap`** for inner spacing; optional **`className`** on `Content` for further styling.
+## Anatomy
+```
+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
+        └── 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. Open state and dismiss policy.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| open | `boolean` | — | No | Controlled open state; use with `onOpenChange`. |
-| defaultOpen | `boolean` | `false` | No | Initial state in uncontrolled mode. |
-| onOpenChange | `(open: boolean) => void` | — | No | Fires when opening or closing (trigger, Escape, outside click). |
-| children | `React.ReactNode` | — | Yes | Typically `Popover.Trigger` and `Popover.Content`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
+| `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
+| `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
+### 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 | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactElement` | — | Yes | Single anchor element; ref, ARIA, and click handler are merged in. |
-| asChild | `boolean` | `true` | No | Reserved for slot API compatibility; behavior always merges with the single child. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element, usually a Button (Anchor: any element, e.g. a toolbar). |
 
 ### Popover.Content
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| align | `"start" \| "center" \| "end"` | `"start"` | No | Horizontal alignment of the panel relative to the trigger. |
-| side | `"bottom" \| "top"` | `"bottom"` | No | Preferred side; layout may flip at the viewport edge. |
-| sameMinWidthAsTrigger | `boolean` | `false` | No | When `true`, panel `width` and `minWidth` match the trigger (`border-box`); text wraps; still subject to panel max width and viewport. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control density tier for nested controls via `ControlSizeProvider`. |
-| trapFocus | `boolean` | `false` | No | Trap focus inside the panel while open. |
-| insetPadding | `"none" \| "x1" \| "x2" \| "x3"` | `"none"` | No | Extra inset padding relative to the panel tier (`data-inset-padding`). |
-| insetGap | `"none" \| "x2" \| "x3" \| "x4"` | `"none"` | No | Vertical gap between direct children (`data-inset-gap`). |
-| className | `string` | — | No | Extra class on the panel root. |
-| children | `React.ReactNode` | — | Yes | Panel body. |
+`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` | `"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.
+
+### size (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | padding 12, gap 8, text 12/16 | Next to xs triggers | |
+| `s` | padding 12, gap 8, text 13/20 | Dense toolbars | |
+| `m` | padding 16, gap 12, text 14/20 | Most panels | yes |
+| `l` | padding 16, gap 16, text 16/24 | l triggers, roomier forms | |
+| `xl` | padding 20, gap 16, text 16/24 | xl triggers | |
+
+Title uses the tier text size with title weight; Description uses the tier label size (m: 13/20) in `text-secondary`.
+
+### side / align (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `side="bottom"` | Below the trigger, `--prime-panel-offset` away | Default | yes |
+| `side="top"` | Above the trigger | Triggers near the bottom of the screen | |
+| `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 |
+|---|---|---|---|
+| `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: `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
+| 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; 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; below 480px they stack full width.
+
+## Accessibility
+
+### 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. |
+
+### 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
+- 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.
+- 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
-
-- [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md) — typical triggers.
-- [Select](../select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md) — nested overlays; Select listbox clicks are treated as inside the popover when owned by the panel.
-- [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md) — fields inside the panel.
-- [Typography](../typography/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — text and labels in the panel.
-- [Badge](../badge/COMPONENT.md), [Divider](../divider/COMPONENT.md) — structured panel chrome.
-- [Modal](../modal/COMPONENT.md) — blocking modal flow.
-- [Tooltip](../tooltip/COMPONENT.md) — short hover/focus hint without an action panel.
-
-</think>
-<think>
-I made a mistake in Related - Switch should link to COMPONENT.md not Switch.tsx
-</think>
-
-
-<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
-Glob
+- **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

@@ -0,0 +1,44 @@
+/* Layout of the Popover scenarios: semantic tokens only. */
+
+/* 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%;
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+}
+
+/* match-trigger-width.tsx: a narrow sidebar column. */
+.narrowColumn {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 2.5);
+}
+
+/* flush.tsx: the panel has no padding; every row brings its own. */
+.flushPanel {
+  width: calc(var(--prime-panel-min-width) * 1.5);
+}
+
+.flushHead {
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.flushRow {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.flushFooter {
+  display: flex;
+  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/match-trigger-width.tsx

@@ -0,0 +1,23 @@
+/** 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 styles from "./examples.module.css";
+
+export default function PopoverMatchTriggerWidthExample() {
+  return (
+    <div className={styles.narrowColumn}>
+      <Popover.Root>
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral" fullWidth>
+            Условия тарифа
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content matchTriggerWidth>
+          <Typography variant="body-s" tone="secondary">
+            До 10 пользователей, 50 ГБ хранилища и приоритетная поддержка.
+          </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>
+  );
+}