prime-ui-kit 0.3.1 → 0.4.0

package/src/components/dropdown/COMPONENT.md

@@ -2,29 +2,52 @@
 
 **Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
 
-## About
+## Canonical
 
-A composite **action menu**: the trigger toggles a portaled panel with commands, optional groups, a header block, and separators. Positioning and focus behavior follow a single-level `role="menu"` pattern.
+**What:** `Dropdown` is a **portaled action menu** (`role="menu"`): one trigger toggles a floating list of **`menuitem`** rows. **`Dropdown.Trigger`** clones **exactly one** child element and merges **`aria-expanded`**, **`aria-haspopup="menu"`**, **`aria-controls`**, **`id`**, ref, and toggle **`onClick`**. **`Dropdown.Content`** renders **only when open**, applies focus trap, Escape/outside close, and arrow-key roving focus among items.
 
-- **Use** for secondary operations on cards, table rows, or toolbars without a full settings page.
-- **Use** when you need a compact “more” menu next to an avatar, text, or icon trigger.
-- **Use** with **controlled** `open` / `onOpenChange` when another part of the UI must stay in sync (tours, hints, analytics).
-- **Use** `destructive` items and **groups** when you must separate safe vs dangerous or unrelated actions.
-- **Do not use** for choosing a single value shown on the trigger — that is **[Select](../select/COMPONENT.md)**.
-- **Do not use** for arbitrary floating content without menu semantics — prefer **[Popover](../popover/COMPONENT.md)**.
-- **Do not use** for nested multi-level submenus; the API is a **flat** menu only.
+**Parts:** `Root` → `Trigger` + `Content`. Inside `Content`: optional `Inset`, `Block`, `Header` (+ `HeaderRow`, `HeaderLeading`, `HeaderMain`, `HeaderTitle`, `HeaderDescription`, `HeaderTrailing`), `Group` + `GroupLabel`, `Separator`, `Item` (+ `ItemIcon`).
 
-## Composition
+**State:** Uncontrolled: **`defaultOpen`** on `Root`. Controlled: **`open`** + **`onOpenChange`**. **`Item.onSelect`** runs on activation, then the menu closes unless **`disabled`**.
 
-- **`Dropdown.Root`** wraps everything and owns open state (controlled or uncontrolled).
-- **`Dropdown.Trigger`** must wrap **exactly one** React element; refs, `id`, `aria-*`, and toggle `onClick` are merged into that child.
-- **`Dropdown.Content`** renders **only when open** (portal + `role="menu"`). Put **`Dropdown.Inset`** or direct **`Dropdown.Block`** / **`Dropdown.Group`** / **`Dropdown.Item`** children inside it.
-- **`Dropdown.Inset`** optional wrapper: padding and vertical gap between **direct** children.
-- **`Dropdown.Block`** — generic section; **`Dropdown.Header`** and **`HeaderRow`**, **`HeaderLeading`**, **`HeaderMain`**, **`HeaderTitle`**, **`HeaderDescription`**, **`HeaderTrailing`** compose a header area inside the panel.
-- **`Dropdown.Item`** — actionable row (`role="menuitem"`); may include **`Dropdown.ItemIcon`** before text.
-- **`Dropdown.Group`** + **`Dropdown.GroupLabel`** label a set of items; **`Dropdown.Separator`** is an `hr` between blocks.
+**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**
+
+**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 |
 
-### Minimal example
+**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:**
 
 ```tsx
 import { Button, Dropdown } from "prime-ui-kit";
@@ -46,7 +69,33 @@ export function Example() {
 }
 ```
 
-## Rules
+---
+
+## Extended
+
+### About
+
+A composite **action menu**: the trigger toggles a portaled panel with commands, optional groups, a header block, and separators. Positioning and focus behavior follow a single-level `role="menu"` pattern.
+
+- **Use** for secondary operations on cards, table rows, or toolbars without a full settings page.
+- **Use** when you need a compact “more” menu next to an avatar, text, or icon trigger.
+- **Use** with **controlled** `open` / `onOpenChange` when another part of the UI must stay in sync (tours, hints, analytics).
+- **Use** `destructive` items and **groups** when you must separate safe vs dangerous or unrelated actions.
+- **Do not use** for choosing a single value shown on the trigger — that is **[Select](../select/COMPONENT.md)**.
+- **Do not use** for arbitrary floating content without menu semantics — prefer **[Popover](../popover/COMPONENT.md)**.
+- **Do not use** for nested multi-level submenus; the API is a **flat** menu only.
+
+### Composition
+
+- **`Dropdown.Root`** wraps everything and owns open state (controlled or uncontrolled).
+- **`Dropdown.Trigger`** must wrap **exactly one** React element; refs, `id`, `aria-*`, and toggle `onClick` are merged into that child.
+- **`Dropdown.Content`** renders **only when open** (portal + `role="menu"`). Put **`Dropdown.Inset`** or direct **`Dropdown.Block`** / **`Dropdown.Group`** / **`Dropdown.Item`** children inside it.
+- **`Dropdown.Inset`** optional wrapper: padding and vertical gap between **direct** children.
+- **`Dropdown.Block`** — generic section; **`Dropdown.Header`** and **`HeaderRow`**, **`HeaderLeading`**, **`HeaderMain`**, **`HeaderTitle`**, **`HeaderDescription`**, **`HeaderTrailing`** compose a header area inside the panel.
+- **`Dropdown.Item`** — actionable row (`role="menuitem"`); may include **`Dropdown.ItemIcon`** before text.
+- **`Dropdown.Group`** + **`Dropdown.GroupLabel`** label a set of items; **`Dropdown.Separator`** is an `hr` between blocks.
+
+### Rules
 
 - **Uncontrolled:** set **`defaultOpen`** on `Root` (defaults to `false`); internal state updates on toggle.
 - **Controlled:** pass **`open`** and **`onOpenChange`**; the parent is the source of truth for visibility.
@@ -59,9 +108,9 @@ export function Example() {
 - **`align`** / **`side`** are preferences; **`data-side`** on the menu reflects the **resolved** side after layout.
 - **Portal:** the menu is not a DOM child of the trigger — mind **z-index** and stacking when opening from **[Modal](../modal/COMPONENT.md)** or **[Drawer](../drawer/COMPONENT.md)**.
 
-## API
+### API
 
-### Dropdown.Root
+#### Dropdown.Root
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -70,14 +119,14 @@ export function Example() {
 | onOpenChange | `(open: boolean) => void` | — | No | Called when open state changes. |
 | children | `React.ReactNode` | — | Yes | Trigger, content, and nested parts. |
 
-### Dropdown.Trigger
+#### Dropdown.Trigger
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | children | `React.ReactElement` | — | Yes | Single element; ref, `id`, ARIA, and merged `onClick` are applied to it. |
 | asChild | `boolean` | `true` | No | Kept for API consistency; the trigger always clones the child element. |
 
-### Dropdown.Content
+#### Dropdown.Content
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -88,7 +137,7 @@ export function Example() {
 | className | `string` | — | No | Extra class on the portaled menu container. |
 | children | `React.ReactNode` | — | Yes | Menu body: inset, blocks, groups, items, etc. |
 
-### Dropdown.Inset
+#### Dropdown.Inset
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -98,31 +147,31 @@ export function Example() {
 | children | `React.ReactNode` | — | Yes | Nested blocks and items. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
 
-### Dropdown.Block
+#### Dropdown.Block
 
 Inherits `React.HTMLAttributes<HTMLDivElement>` (e.g. `className`, `children`).
 
-### Dropdown.Header
+#### Dropdown.Header
 
 Same as `Dropdown.Block`.
 
-### Dropdown.HeaderRow
+#### Dropdown.HeaderRow
 
 Same as `Dropdown.Block`.
 
-### Dropdown.HeaderLeading
+#### Dropdown.HeaderLeading
 
 Same as `Dropdown.Block`.
 
-### Dropdown.HeaderMain
+#### Dropdown.HeaderMain
 
 Same as `Dropdown.Block`.
 
-### Dropdown.HeaderTitle
+#### Dropdown.HeaderTitle
 
 Same as `Dropdown.Block`.
 
-### Dropdown.HeaderDescription
+#### Dropdown.HeaderDescription
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -131,7 +180,7 @@ Same as `Dropdown.Block`.
 | children | `React.ReactNode` | — | No | Description text. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
 
-### Dropdown.HeaderTrailing
+#### Dropdown.HeaderTrailing
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -140,7 +189,7 @@ Same as `Dropdown.Block`.
 | children | `React.ReactNode` | — | No | Trailing slot content. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
 
-### Dropdown.Item
+#### Dropdown.Item
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -150,7 +199,7 @@ Same as `Dropdown.Block`.
 | className | `string` | — | No | Extra class on the `<button>`. |
 | children | `React.ReactNode` | — | Yes | Label, `ItemIcon`, etc. |
 
-### Dropdown.ItemIcon
+#### Dropdown.ItemIcon
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -161,7 +210,7 @@ Same as `Dropdown.Block`.
 | size | `number` | from `Content` `size` tier | No | Icon size in px; overrides the automatic tier size. |
 | …rest | `Record<string, unknown>` | — | No | Passed through to the `as` element (e.g. icon props), except reserved fields. |
 
-### Dropdown.Group
+#### Dropdown.Group
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
@@ -169,20 +218,20 @@ Same as `Dropdown.Block`.
 | children | `React.ReactNode` | — | No | Group label and items. |
 | …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
 
-### Dropdown.GroupLabel
+#### Dropdown.GroupLabel
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | className | `string` | — | No | Extra class. |
 | children | `React.ReactNode` | — | Yes | Group heading text. |
 
-### Dropdown.Separator
+#### Dropdown.Separator
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | className | `string` | — | No | Extra class on the `hr`. |
 
-## Related
+### Related
 
 - [Button](../button/COMPONENT.md) — typical trigger.
 - [Link button](../link-button/COMPONENT.md) — text-style trigger when a button chrome is not desired.
@@ -190,3 +239,17 @@ Same as `Dropdown.Block`.
 - [Popover](../popover/COMPONENT.md) — generic portaled surface without `menu` / `menuitem` behavior.
 - [Modal](../modal/COMPONENT.md) / [Drawer](../drawer/COMPONENT.md) — shells where menus often open from headers or rows.
 - [Avatar](../avatar/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Typography](../typography/COMPONENT.md) — common header and row content.
+
+---
+
+## LLM note
+
+- **Do not** invent submenu APIs or nest another `role="menu"` inside items — flat list only.
+- **Trigger contract:** `Dropdown.Trigger` → single `ReactElement`; fragments or multiple nodes break `cloneElement`.
+- **Prefer `Button.Root`** (or `LinkButton`) as trigger with **`type="button"`** when inside forms.
+- **Icon-only trigger:** set **`aria-label`** on the trigger element (merged onto the cloned child).
+- **Choosing a form value** with listbox/combobox semantics → **Select**, not Dropdown; a “workspace switcher” that only mimics selection in the trigger label is still a menu — call that out in copy if users might confuse them.
+- **Destructive actions:** use **`destructive`** on **`Dropdown.Item`**, often after **`Separator`**, not a different component.
+- **Layout:** `Content.align="end"` is common for right-aligned toolbars; pair with **`sameMinWidthAsTrigger`** when the panel should match a narrow control.
+- **Imports for consumers:** `import { Dropdown, … } from "prime-ui-kit"`. In-repo examples under `examples/` use `@/components/...` paths.
+- **Playground source of truth for visuals:** `playground/snippets/dropdown/*.tsx` — keep docs and snippets aligned when API changes.

package/src/components/dropdown/examples/account-menu.tsx

@@ -0,0 +1,52 @@
+import { LogOut, Settings, UserRound } from "lucide-react";
+import { Avatar } from "@/components/avatar/Avatar";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Меню аккаунта: шапка с идентичностью, группа настроек, выход. */
+export default function DropdownAccountMenuExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+          Аккаунт
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content align="end" sameMinWidthAsTrigger>
+        <Dropdown.Inset>
+          <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>
+                    ivan.petrov@example.com
+                  </Dropdown.HeaderDescription>
+                </Dropdown.HeaderMain>
+              </Dropdown.HeaderRow>
+              <Dropdown.Separator />
+            </Dropdown.Header>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={UserRound} strokeWidth={2} />
+              Профиль
+            </Dropdown.Item>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon as={Settings} strokeWidth={2} />
+              Настройки
+            </Dropdown.Item>
+          </Dropdown.Block>
+          <Dropdown.Separator />
+          <Dropdown.Item destructive>
+            <Dropdown.ItemIcon as={LogOut} strokeWidth={2} />
+            Выйти
+          </Dropdown.Item>
+        </Dropdown.Inset>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/actions-menu.tsx

@@ -0,0 +1,37 @@
+import { Copy, Pencil, Trash2 } from "lucide-react";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Меню действий над сущностью: безопасные операции и отдельный деструктивный блок. */
+export default function DropdownActionsMenuExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root
+          type="button"
+          variant="neutral"
+          mode="stroke"
+          size="m"
+          aria-label="Действия с документом"
+        >
+          ⋯
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content align="end">
+        <Dropdown.Item>
+          <Dropdown.ItemIcon as={Pencil} strokeWidth={2} />
+          Редактировать
+        </Dropdown.Item>
+        <Dropdown.Item>
+          <Dropdown.ItemIcon as={Copy} strokeWidth={2} />
+          Дублировать
+        </Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item destructive>
+          <Dropdown.ItemIcon as={Trash2} strokeWidth={2} />
+          Удалить
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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>
+    </>
+  );
+}