prime-ui-kit 0.3.2 → 0.4.1

package/src/components/digit-input/examples/features.tsx

@@ -0,0 +1,30 @@
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Разная длина ряда, начальное значение, колбэк по завершении ввода.
+ * Паритет с `playground/snippets/digit-input/features.tsx`.
+ */
+export default function DigitInputFeaturesExample() {
+  const [completed, setCompleted] = React.useState<string | null>(null);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p style={{ margin: 0 }}>Пропы length и defaultValue без внешнего состояния</p>
+      <DigitInput.Root length={4} defaultValue="2184" />
+      <DigitInput.Root length={6} defaultValue="12" />
+      <p style={{ margin: 0 }}>onComplete — один раз при заполнении последней ячейки</p>
+      <DigitInput.Root length={4} onComplete={(v) => setCompleted(v)} />
+      <p style={{ margin: 0 }}>
+        {completed ? `Последний полный код: ${completed}` : "Введите четыре цифры подряд"}
+      </p>
+    </div>
+  );
+}

package/src/components/digit-input/examples/sizes.tsx

@@ -0,0 +1,23 @@
+import { DigitInput } from "prime-ui-kit";
+
+/**
+ * Четыре размера ячеек: `size` s, m, l, xl — те же токены контролов, что у поля ввода.
+ * Паритет с `playground/snippets/digit-input/sizes.tsx`.
+ */
+export default function DigitInputSizesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <DigitInput.Root size="s" length={4} defaultValue="1234" />
+      <DigitInput.Root size="m" length={4} defaultValue="1234" />
+      <DigitInput.Root size="l" length={4} defaultValue="1234" />
+      <DigitInput.Root size="xl" length={4} defaultValue="1234" />
+    </div>
+  );
+}

package/src/components/digit-input/examples/states.tsx

@@ -0,0 +1,22 @@
+import { DigitInput } from "prime-ui-kit";
+
+/**
+ * Обычное поле, визуальная ошибка (`hasError`) и отключённый ввод (`disabled`).
+ * Паритет с `playground/snippets/digit-input/states.tsx`.
+ */
+export default function DigitInputStatesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <DigitInput.Root length={4} defaultValue="42" />
+      <DigitInput.Root length={4} defaultValue="12" hasError />
+      <DigitInput.Root length={4} defaultValue="99" disabled />
+    </div>
+  );
+}

package/src/components/divider/COMPONENT.md

@@ -52,7 +52,11 @@ export function Example() {
 
 Shared layout tokens for the examples: [`examples/divider-examples.module.css`](examples/divider-examples.module.css).
 
-Playground snippets (broader overview): `playground/snippets/divider/` (`variants.tsx`, `sizes.tsx`, `composition.tsx`).
+Playground snippets (same demos as `playground/sections/DividerSection.tsx`):
+
+- **`variants.tsx`** — empty horizontal line; **`default`** with centered label; **`variant="text"`**; **`line-spacing`** between rows in a column; **`orientation="vertical"`** between toolbar-style buttons; full-width line between list rows (**`size="s"`**).
+- **`sizes.tsx`** — **`variant="text"`** at **`size`** **`s`**, **`m`**, and **`xl`** (three steps to compare label scale and spacing).
+- **`composition.tsx`** — **`Icon`** + label inside **`variant="text"`** **`size="m"`**; second divider at **`size="xl"`** with icon + label.
 
 ### Rules
 
@@ -95,4 +99,4 @@ Playground snippets (broader overview): `playground/snippets/divider/` (`variant
 - **Vertical:** requires ancestor **`align-items: stretch`** (or explicit height) so `::before`/`::after` flex segments fill the row.
 - **Children:** toggles inner **`span`** and **`ControlSizeProvider`**; **`Icon`** ignores its own **`size`** when inside divider content.
 - **a11y:** default **`separator`** is announced; for decorative list lines between items, mirror **`examples/list-separators.tsx`**: **`ul`/`li`**, separator **`li`** with **`aria-hidden`**, **`Divider.Root`** with **`role="presentation"`**.
-- **Playground alignment:** `playground/snippets/divider/variants.tsx` shows default vs `text` vs `line-spacing` vs vertical in one frame.
+- **Playground alignment:** `variants.tsx` is one frame (empty line, `default` label, `text`, `line-spacing` column, vertical toolbar, list-row separator); `sizes.tsx` is `text` at **s / m / xl**; `composition.tsx` is icon + text at **m** and **xl**.

package/src/components/drawer/COMPONENT.md

@@ -6,21 +6,21 @@
 
 A slide-over panel rendered in a portal with a backdrop: page scroll is locked, focus stays inside the dialog until it closes, and siblings of the portal root on `document.body` are marked inert and `aria-hidden` while open.
 
-- **When to use** — secondary detail, filters, forms, or actions tied to a screen edge (left/right/top/bottom) without leaving the current view.
-- **When to use** — bottom or top sheets when the main canvas (e.g. a map) should stay partly visible.
-- **When to use** — the same modal-style contract as a dialog (focus trap, blocked background) but with an edge-attached panel instead of a centered box.
-- **When not to use** — short confirmations or compact prompts; prefer a centered [Modal](../modal/COMPONENT.md).
-- **When not to use** — inline expandable regions; use disclosure or a non-modal sidebar if you should not block the whole page.
-- **When not to use** — full page changes driven only by the URL; the kit does not wire routing—control `open` / `onOpenChange` from the app.
+- **Use** for secondary detail, filters, forms, or actions tied to a screen edge (left/right/top/bottom) without leaving the current view.
+- **Use** for bottom or top sheets when the main canvas (for example a map) should stay partly visible.
+- **Use** for the same modal-style contract as a dialog (focus trap, blocked background) but with an edge-attached panel instead of a centered box.
+- **Do not use** for short confirmations or compact prompts; prefer a centered [Modal](../modal/COMPONENT.md).
+- **Do not use** for inline expandable regions; use disclosure or a non-modal sidebar if you should not block the whole page.
+- **Do not use** for full page changes driven only by the URL; the kit does not wire routing—control `open` / `onOpenChange` from the app.
 
 ## Composition
 
 - **`Drawer.Root`** — holds open state, `closeOnEscape`, and `closeOnOverlayClick`; wraps everything else.
 - **`Drawer.Trigger`** (optional) — exactly one child element; opens on click unless the child’s `onClick` calls `preventDefault`.
 - **`Drawer.Portal`** — renders nothing when closed; when open, portals children (default container `document.body` via the internal `Portal`).
-- **`Drawer.Overlay`** and **`Drawer.Content`** should be **siblings** inside **`Drawer.Portal`** (backdrop is not a wrapper around the panel). List **`Drawer.Overlay`** before **`Drawer.Content`** so the panel paints above the backdrop when stacking order ties on `z-index`.
-- **`Drawer.Content`** — `role="dialog"`, `aria-modal="true"`, focus trap, and chrome size context for header/footer controls.
-- **`Drawer.Header`** → **`Drawer.Title`**, **`Drawer.Body`**, **`Drawer.Footer`** — all **must** be nested inside **`Drawer.Content`** (runtime error otherwise). **`Drawer.Close`** wraps a single control that should close the drawer (often a button in the footer or custom actions).
+- **`Drawer.Overlay`** and the panel surface should be **siblings** inside **`Drawer.Portal`** (backdrop is not a wrapper around the panel). List **`Drawer.Overlay`** before the panel so it stacks under the dialog when `z-index` ties.
+- **Panel surface:** at the portal root, **`Drawer.Content`** renders the full dialog shell (`role="dialog"`, focus trap, scroll lock, inert siblings, chrome size for header/footer). For a split where only the middle scrolls, use **`Drawer.Panel`** as the shell and nest **`Drawer.Content`** for the body region — see **`examples/explicit-panel.tsx`**.
+- **`Drawer.Header`** → **`Drawer.Title`**, **`Drawer.Body`**, **`Drawer.Footer`** — all **must** be nested inside the panel surface (**`Drawer.Content`** at root or **`Drawer.Panel`**). **`Drawer.Close`** wraps a single control that should close the drawer (often a button in the footer or custom actions).
 
 ### Minimal example
 
@@ -51,14 +51,42 @@ export function DrawerMinimal() {
 }
 ```
 
+### Playground snippets (source of truth)
+
+Runnable demos and copy-paste references: `playground/snippets/drawer/*.tsx` (Russian copy in UI; workspace imports use `@/`).
+
+| File | Intent |
+|------|--------|
+| `sizes.tsx` | Ladder **`size`** `s`–`xl` on **`Drawer.Content`**; padding, title tier, header close button, and footer controls share one control tier. |
+| `variants-sides.tsx` | **`side`** `right` (default), `left`, `bottom`, `top`; top/bottom sheets use capped height (~**`80vh`** in styles) and scroll in **`Drawer.Body`**. |
+| `states.tsx` | **`closeOnEscape={false}`** and **`closeOnOverlayClick={false}`** for dismiss only via actions; **`showCloseButton={false}`** on **`Drawer.Header`**. |
+| `controlled.tsx` | **`open`** / **`onOpenChange`** on **`Drawer.Root`** without **`Drawer.Trigger`**. |
+| `composition.tsx` | Header, **`Input`** in **`Drawer.Body`**, footer with **`Drawer.Close`** on cancel. |
+| `full-width.tsx` | Vertical stack in **`Drawer.Footer`** with **`Button.Root`** **`fullWidth`**. |
+| `responsive.tsx` | Side width cap **`min(28rem, 90vw)`**; long copy scrolls in **`Drawer.Body`**. |
+| `trigger-link.tsx` | **`Drawer.Trigger`** with a single **`LinkButton`** child; opening merges with existing **`onClick`** (e.g. **`preventDefault`** on **`href`**). |
+| `features.tsx` | **`Drawer.Portal`** **`container`**, **`aria-label`** on **`Drawer.Content`** without a visible title row, long list scroll inside **`Drawer.Body`**. |
+
+### Examples (`examples/`)
+
+English scenario starters next to this file (workspace **`@/`**; published **`prime-ui-kit`**):
+
+| File | Intent |
+|------|--------|
+| `examples/filters-panel.tsx` | Leading-edge filters; scroll criteria, **Apply** / **Reset** in footer. |
+| `examples/cart-preview.tsx` | Trailing-edge cart preview; line items scroll; checkout in footer. |
+| `examples/settings-side.tsx` | Trailing-edge settings; form fields share drawer **`size`** with chrome. |
+| `examples/mobile-nav-sheet.tsx` | Bottom sheet nav; rows wrapped in **`Drawer.Close`**. |
+| `examples/explicit-panel.tsx` | **`Drawer.Panel`** shell with inner **`Drawer.Content`** as scroll body only. |
+
 ## Rules
 
 - **Controlled vs uncontrolled:** pass `open` and `onOpenChange` for controlled mode; otherwise use `defaultOpen` on `Drawer.Root`. Omit `Drawer.Trigger` when you open/close from parent state only.
-- **Closing:** Escape and backdrop click call `onClose` by default; disable with `closeOnEscape={false}` and/or `closeOnOverlayClick={false}` on `Drawer.Root` for explicit-dismiss-only flows. Backdrop close runs only when the click target is the overlay element itself (not bubbled from children).
+- **Closing:** Escape and overlay click update open state by default (and invoke **`onOpenChange`** when controlled). Disable with `closeOnEscape={false}` and/or `closeOnOverlayClick={false}` on `Drawer.Root` for explicit-dismiss-only flows. Escape is handled while the panel is open (same layer as the dialog focus trap). Backdrop close runs only when the click target is the overlay element itself (not bubbled from children).
 - **`Drawer.Trigger` / `Drawer.Close`:** each expects **exactly one** React child that accepts an `onClick` handler; the kit merges its handler with yours and respects `preventDefault`.
-- **Accessible name:** set `aria-labelledby` on `Drawer.Content` to the `id` of `Drawer.Title`, or `aria-label` when there is no visible title.
+- **Accessible name:** set `aria-labelledby` on the panel to the `id` of `Drawer.Title`, or `aria-label` when there is no visible title.
 - **Header close control:** `showCloseButton={false}` on `Drawer.Header` removes the built-in ghost button (`aria-label` is `"Close drawer"` in code when shown).
-- **Sizing:** `size` on `Drawer.Content` is `s` | `m` | `l` | `xl` (default `m`); it drives padding, title scale, and control sizing in chrome via `ControlSizeProvider`. Panel width/height caps come from the component styles, not separate width/height props.
+- **Sizing:** `size` on the panel (`Drawer.Content` at root or `Drawer.Panel`) is `s` | `m` | `l` | `xl` (default `m`); it drives padding, title scale, and control sizing in chrome via `ControlSizeProvider`. Side panels cap width in CSS (**`min(28rem, 90vw)`**); top/bottom sheets cap height (~**`80vh`**), not separate width/height props.
 - **Portal:** `Drawer.Portal` renders `null` while closed, so portal subtree is unmounted when not open.
 
 ## API
@@ -69,8 +97,8 @@ export function DrawerMinimal() {
 |------|------|---------|----------|-------------|
 | `open` | `boolean` | — | No | Controlled open state. |
 | `defaultOpen` | `boolean` | `false` | No | Initial open state when uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | No | Called when open state changes. |
-| `closeOnEscape` | `boolean` | `true` | No | Close when Escape is pressed while open. |
+| `onOpenChange` | `(open: boolean) => void` | — | No | Called when open state changes (trigger, dismiss, programmatic). |
+| `closeOnEscape` | `boolean` | `true` | No | Close on Escape while the panel is open. |
 | `closeOnOverlayClick` | `boolean` | `true` | No | Close when the overlay receives a direct click. |
 | `children` | `React.ReactNode` | — | Yes | Tree: trigger, portal, etc. |
 
@@ -84,39 +112,49 @@ export function DrawerMinimal() {
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `children` | `React.ReactElement<{ onClick?: React.MouseEventHandler; className?: string }>` | — | Yes | Single child; click closes unless default prevented. |
+| `children` | `React.ReactElement<{ onClick?: React.MouseEventHandler; className?: string }>` | — | Yes | Single child; click runs your `onClick` then closes unless default prevented. |
 
 ### Drawer.Portal
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `children` | `React.ReactNode` | — | Yes | Portaled subtree; not mounted when closed. |
+| `children` | `React.ReactNode` | — | No | Portaled subtree; not mounted when closed. |
 | `container` | `HTMLElement \| null` | `document.body` | No | DOM node for `createPortal` (falls back when `null`/omitted per `Portal` implementation). |
 
 ### Drawer.Overlay
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Spread onto the backdrop `div` (`role="presentation"` set in the component). |
+| `className` | `string` | — | No | Extra class on the backdrop. |
+| `onClick` | `React.MouseEventHandler<HTMLDivElement>` | — | No | Fires before overlay dismiss logic. |
+| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | `role="presentation"`; remaining attributes on the backdrop `div`. |
 
 ### Drawer.Content
 
+When used as the **direct** child of **`Drawer.Portal`** (after **`Drawer.Overlay`**), renders the dialog panel. When nested **inside** an existing panel, renders the scrollable body region only (see **`examples/explicit-panel.tsx`**).
+
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `side` | `"left" \| "right" \| "bottom" \| "top"` | `"right"` | No | Edge from which the panel enters. |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Chrome and spacing tier for header/footer controls. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Chrome and spacing tier for header/footer controls (`ControlSizeProvider`). |
 | `aria-label` | `string` | — | No | Accessible name when no visible title. |
 | `aria-labelledby` | `string` | — | No | `id` of the visible title element. |
 | `aria-describedby` | `string` | — | No | `id` of auxiliary description content. |
-| `className` | `string` | — | No | Class on the dialog root. |
-| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Additional attributes on the dialog `div` (`role="dialog"`, `aria-modal`, `tabIndex={-1}`, focus trap ref). |
+| `className` | `string` | — | No | Class on the panel or inner body root. |
+| `children` | `React.ReactNode` | — | No | Shell slots (header, body, footer) when panel root; scroll content when nested. |
+| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Panel: `role="dialog"`, `aria-modal`, `tabIndex={-1}`, focus trap, scroll lock, inert siblings. |
+
+### Drawer.Panel
+
+Same props as **`Drawer.Content`** when **`Drawer.Content`** is the portal-root panel. Use **`Drawer.Panel`** for explicit shell + inner **`Drawer.Content`** body scrolling — **`examples/explicit-panel.tsx`**.
 
 ### Drawer.Header
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `showCloseButton` | `boolean` | `true` | No | Renders the built-in icon close button. |
+| `showCloseButton` | `boolean` | `true` | No | Built-in ghost close control (neutral) on the right. |
 | `className` | `string` | — | No | Class on the `<header>`. |
+| `children` | `React.ReactNode` | — | No | Usually **`Drawer.Title`**; area left of the close control. |
 | … | `React.HTMLAttributes<HTMLElement>` | — | No | Native `<header>` attributes. |
 
 ### Drawer.Title
@@ -124,6 +162,7 @@ export function DrawerMinimal() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `className` | `string` | — | No | Class on the `<h2>`. |
+| `children` | `React.ReactNode` | — | No | Title text; set `id` for `aria-labelledby` on the panel. |
 | … | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Renders `<h2>`. |
 
 ### Drawer.Body
@@ -131,6 +170,7 @@ export function DrawerMinimal() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `className` | `string` | — | No | Class on the scroll container root. |
+| `children` | `React.ReactNode` | — | No | Main content; vertical scroll when overflowing. |
 | … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Scrollable body via `ScrollContainer`. |
 
 ### Drawer.Footer
@@ -138,7 +178,8 @@ export function DrawerMinimal() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `className` | `string` | — | No | Class on the `<footer>`. |
-| … | `React.HTMLAttributes<HTMLElement>` | — | No | Wraps actions; provides control size context. |
+| `children` | `React.ReactNode` | — | No | Action row; controls use **`ControlSizeProvider`** from panel **`size`**. |
+| … | `React.HTMLAttributes<HTMLElement>` | — | No | Renders `<footer>`. |
 
 ## Related
 

package/src/components/dropdown/COMPONENT.md

@@ -12,14 +12,40 @@
 
 **Position:** **`Content.align`**: `start` | `center` | `end`. **`Content.side`**: `bottom` | `top` (may flip). **`sameMinWidthAsTrigger`** widens the panel to at least the trigger width. Resolved side is on **`data-side`** on the menu node.
 
-**Runnable examples (this package):**
-
-| File | Scenario |
-|------|----------|
-| [`examples/actions-menu.tsx`](examples/actions-menu.tsx) | Icon trigger, icons in rows, separator, **`destructive`** |
-| [`examples/account-menu.tsx`](examples/account-menu.tsx) | Header + avatar, **`Inset`**, **`sameMinWidthAsTrigger`**, sign out |
-| [`examples/select-like-list.tsx`](examples/select-like-list.tsx) | Trigger label reflects choice; still menu semantics (not **Select**) |
-| [`examples/placement-demo.tsx`](examples/placement-demo.tsx) | **`align`** and **`side`** |
+**Runnable examples**
+
+**Playground snippets** (order matches [`playground/sections/DropdownSection.tsx`](../../../playground/sections/DropdownSection.tsx); keep **`examples/`** in sync when changing these):
+
+| Snippet | Scenario |
+|---------|----------|
+| [`playground/snippets/dropdown/sizes.tsx`](../../../playground/snippets/dropdown/sizes.tsx) | **`Content.size`** s–xl: panel, rows, group label, default **`ItemIcon`** size |
+| [`playground/snippets/dropdown/variants.tsx`](../../../playground/snippets/dropdown/variants.tsx) | Plain rows and **`Item.destructive`** |
+| [`playground/snippets/dropdown/states.tsx`](../../../playground/snippets/dropdown/states.tsx) | **`Item.disabled`** (no activation / no close) |
+| [`playground/snippets/dropdown/placement.tsx`](../../../playground/snippets/dropdown/placement.tsx) | **`align`** start/center/end and **`side`** top |
+| [`playground/snippets/dropdown/controlled.tsx`](../../../playground/snippets/dropdown/controlled.tsx) | **`open`** / **`onOpenChange`** on **`Root`** |
+| [`playground/snippets/dropdown/composition.tsx`](../../../playground/snippets/dropdown/composition.tsx) | **`Block`**, header slots, **`GroupLabel`**, **`ItemIcon`**, nested trailing **Button** |
+| [`playground/snippets/dropdown/full-width.tsx`](../../../playground/snippets/dropdown/full-width.tsx) | **`sameMinWidthAsTrigger`** with narrow trigger |
+| [`playground/snippets/dropdown/as-child.tsx`](../../../playground/snippets/dropdown/as-child.tsx) | **`Trigger`** merges props into a single child (e.g. link) |
+| [`playground/snippets/dropdown/inset.tsx`](../../../playground/snippets/dropdown/inset.tsx) | **`Inset`** **`padding`** / **`gap`** variants |
+
+**Package `examples/`** (same folder as this file; `@/` imports in-repo, **`prime-ui-kit`** for consumers):
+
+| File | Mirrors snippet | Scenario |
+|------|-----------------|----------|
+| [`examples/sizes.tsx`](examples/sizes.tsx) | `sizes.tsx` | Same as playground sizes |
+| [`examples/variants.tsx`](examples/variants.tsx) | `variants.tsx` | Same as playground variants |
+| [`examples/states.tsx`](examples/states.tsx) | `states.tsx` | Same as playground states |
+| [`examples/placement-demo.tsx`](examples/placement-demo.tsx) | `placement.tsx` | Same as playground placement |
+| [`examples/controlled.tsx`](examples/controlled.tsx) | `controlled.tsx` | Same as playground controlled |
+| [`examples/composition.tsx`](examples/composition.tsx) | `composition.tsx` | Same as playground composition |
+| [`examples/full-width.tsx`](examples/full-width.tsx) | `full-width.tsx` | Same as playground full-width |
+| [`examples/as-child.tsx`](examples/as-child.tsx) | `as-child.tsx` | Same as playground as-child |
+| [`examples/inset.tsx`](examples/inset.tsx) | `inset.tsx` | Same as playground inset |
+| [`examples/actions-menu.tsx`](examples/actions-menu.tsx) | — | Icon-only trigger, row icons, separator, **`destructive`** |
+| [`examples/account-menu.tsx`](examples/account-menu.tsx) | — | Header + avatar, **`Inset`**, **`sameMinWidthAsTrigger`**, sign out |
+| [`examples/select-like-list.tsx`](examples/select-like-list.tsx) | — | Trigger shows choice; still **`role="menu"`** (not **Select**) |
+
+Shared layout tokens for some examples: [`examples/dropdown-examples.module.css`](examples/dropdown-examples.module.css) (mirrors [`playground/snippets/dropdown/dropdown-snippets.module.css`](../../../playground/snippets/dropdown/dropdown-snippets.module.css)).
 
 **Minimal import:**
 
@@ -43,8 +69,6 @@ export function Example() {
 }
 ```
 
-Playground mirrors: `playground/snippets/dropdown/` (`composition`, `placement`, `controlled`, …).
-
 ---
 
 ## Extended

package/src/components/dropdown/examples/as-child.tsx

@@ -0,0 +1,26 @@
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+import styles from "./dropdown-examples.module.css";
+
+/** Триггер как единственный ребёнок: aria и клик сливаются с ссылкой — как в `playground/snippets/dropdown/as-child.tsx`. */
+export default function DropdownAsChildExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <a
+          href="/playground"
+          className={styles.linkTrigger}
+          onClick={(e) => {
+            e.preventDefault();
+          }}
+        >
+          Открыть как ссылка-триггер
+        </a>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Пункт 1</Dropdown.Item>
+        <Dropdown.Item>Пункт 2</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/composition.tsx

@@ -0,0 +1,93 @@
+import { BookOpen, HelpCircle, LayoutGrid, LogOut, Settings, UserRound } from "lucide-react";
+import { Avatar } from "@/components/avatar/Avatar";
+import { Badge } from "@/components/badge/Badge";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Block, Header, GroupLabel, ItemIcon, вложенная кнопка в трейлинге — как в `playground/snippets/dropdown/composition.tsx`. */
+export default function DropdownCompositionExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Меню пользователя
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content align="end">
+        <Dropdown.Block>
+          <Dropdown.Header>
+            <Dropdown.HeaderRow>
+              <Dropdown.HeaderLeading>
+                <Avatar.Root size="l">
+                  <Avatar.Fallback>АП</Avatar.Fallback>
+                </Avatar.Root>
+              </Dropdown.HeaderLeading>
+              <Dropdown.HeaderMain>
+                <Dropdown.HeaderTitle>Анна Петрова</Dropdown.HeaderTitle>
+                <Dropdown.HeaderDescription truncate>
+                  anna.petrova@example.com
+                </Dropdown.HeaderDescription>
+              </Dropdown.HeaderMain>
+              <Dropdown.HeaderTrailing>
+                <Badge.Root color="red" variant="light" size="s">
+                  PRO
+                </Badge.Root>
+              </Dropdown.HeaderTrailing>
+            </Dropdown.HeaderRow>
+            <Dropdown.Separator />
+          </Dropdown.Header>
+          <Dropdown.Group>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={UserRound} strokeWidth={2} />
+              Профиль и безопасность
+            </Dropdown.Item>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={LayoutGrid} strokeWidth={2} />
+              Интеграции
+            </Dropdown.Item>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={Settings} strokeWidth={2} />
+              Настройки
+            </Dropdown.Item>
+          </Dropdown.Group>
+        </Dropdown.Block>
+
+        <Dropdown.Block>
+          <Dropdown.Group>
+            <Dropdown.GroupLabel>Поддержка</Dropdown.GroupLabel>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={BookOpen} strokeWidth={2} />
+              Руководство
+            </Dropdown.Item>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={HelpCircle} strokeWidth={2} />
+              Справочный центр
+            </Dropdown.Item>
+          </Dropdown.Group>
+        </Dropdown.Block>
+
+        <Dropdown.Separator />
+        <Dropdown.Block>
+          <Dropdown.Header>
+            <Dropdown.HeaderRow>
+              <Dropdown.HeaderMain>
+                <Dropdown.HeaderTitle>Бесплатный план</Dropdown.HeaderTitle>
+                <Dropdown.HeaderDescription>12 000 просмотров в месяц</Dropdown.HeaderDescription>
+              </Dropdown.HeaderMain>
+              <Dropdown.HeaderTrailing alignSelf="center">
+                <Button.Root type="button" size="s" variant="primary" mode="stroke">
+                  Апгрейд
+                </Button.Root>
+              </Dropdown.HeaderTrailing>
+            </Dropdown.HeaderRow>
+            <Dropdown.Separator />
+          </Dropdown.Header>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={LogOut} strokeWidth={2} />
+            Выйти
+          </Dropdown.Item>
+        </Dropdown.Block>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/controlled.tsx

@@ -0,0 +1,31 @@
+import { useState } from "react";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+import { Typography } from "@/components/typography/Typography";
+
+import styles from "./dropdown-examples.module.css";
+
+/** Контролируемое `open` / `onOpenChange` — как в `playground/snippets/dropdown/controlled.tsx`. */
+export default function DropdownControlledExample() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className={styles.controlledRow}>
+      <Dropdown.Root open={open} onOpenChange={setOpen}>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+            Шаг 2 из 4
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content align="start">
+          <Dropdown.Item onSelect={() => setOpen(false)}>Шаг 1</Dropdown.Item>
+          <Dropdown.Item onSelect={() => setOpen(false)}>Шаг 2</Dropdown.Item>
+          <Dropdown.Item onSelect={() => setOpen(false)}>Шаг 3</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+      <Typography.Root as="span" variant="body-small" tone="muted">
+        Меню {open ? "открыто" : "закрыто"}
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/dropdown/examples/dropdown-examples.module.css

@@ -0,0 +1,33 @@
+/* Примеры Dropdown: только var(--prime-sys-*), без инлайнов. */
+
+.controlledRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.sizeRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.linkTrigger {
+  cursor: pointer;
+  text-decoration: underline;
+}
+
+.iconTriggerMin {
+  min-width: calc(
+    var(--prime-sys-spacing-4xl) +
+    var(--prime-sys-spacing-3xl) +
+    var(--prime-sys-spacing-m) +
+    var(--prime-sys-spacing-xs)
+  );
+}
+
+.insetNoteTight {
+  padding-inline: var(--prime-sys-spacing-x2);
+}

package/src/components/dropdown/examples/full-width.tsx

@@ -0,0 +1,28 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+import styles from "./dropdown-examples.module.css";
+
+/** `sameMinWidthAsTrigger` — как в `playground/snippets/dropdown/full-width.tsx`. */
+export default function DropdownFullWidthExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root
+          type="button"
+          size="m"
+          variant="neutral"
+          mode="stroke"
+          aria-label="Действия со строкой"
+          className={styles.iconTriggerMin}
+        >
+          ⋮
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content sameMinWidthAsTrigger>
+        <Dropdown.Item>Очень длинная подпись пункта меню в одну строку</Dropdown.Item>
+        <Dropdown.Item>Второй пункт</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/inset.tsx

@@ -0,0 +1,51 @@
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+import { Typography } from "@/components/typography/Typography";
+
+import styles from "./dropdown-examples.module.css";
+
+/** `Dropdown.Inset` с `padding` и `gap` — как в `playground/snippets/dropdown/inset.tsx`. */
+export default function DropdownInsetExample() {
+  return (
+    <>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+            С отступами по умолчанию
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Inset>
+            <Typography.Root as="div" variant="body-compact" tone="muted">
+              Короткая заметка над списком.
+            </Typography.Root>
+            <Dropdown.Item>Первый пункт</Dropdown.Item>
+            <Dropdown.Item>Второй пункт</Dropdown.Item>
+          </Dropdown.Inset>
+        </Dropdown.Content>
+      </Dropdown.Root>
+
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+            Плотная вставка
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Inset padding="none" gap="x2">
+            <Typography.Root
+              as="div"
+              variant="body-compact"
+              tone="muted"
+              className={styles.insetNoteTight}
+            >
+              Без внешнего inset-padding, меньший gap.
+            </Typography.Root>
+            <Dropdown.Item>Действие A</Dropdown.Item>
+            <Dropdown.Item>Действие B</Dropdown.Item>
+          </Dropdown.Inset>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </>
+  );
+}