prime-ui-kit 0.7.13 → 0.9.1

package/src/components/dropdown/COMPONENT.md

@@ -1,242 +1,203 @@
 # Dropdown
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** overlays
+**Kind:** overlay
 
-## Canonical
+> A menu of actions that opens from a trigger: picking an item runs it and closes the menu.
 
-**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.
+## When to use
+- Secondary actions of a card, row or document behind a «⋯» or labelled button.
+- An account / user menu in the app header.
+- A short list of commands (export formats, move to project) where picking one runs an action.
 
-**Parts:** `Root` → `Trigger` + `Content`. Inside `Content`: `Block`, `Header` (+ `HeaderRow`, `HeaderLeading`, `HeaderMain`, `HeaderTitle`, `HeaderDescription`, `HeaderTrailing`), `Group` + `GroupLabel`, `Separator`, `Item` (+ `ItemIcon`).
-
-**State:** Uncontrolled: **`defaultOpen`** on `Root`. Controlled: **`open`** + **`onOpenChange`**. **`Item.onSelect`** runs on activation, then the menu closes unless **`disabled`**.
-
-**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) |
-
-**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/actions-menu.tsx`](examples/actions-menu.tsx) | — | Icon-only trigger, row icons, separator, **`destructive`** |
-| [`examples/account-menu.tsx`](examples/account-menu.tsx) | — | Header + avatar, **`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:**
+## When not to use
+- Choosing and showing a value in a form → use [Select](../select/COMPONENT.md) (or [TagSelect](../tag-select/COMPONENT.md) for several).
+- Searching across many commands → use [CommandMenu](../command-menu/COMPONENT.md).
+- Free content, forms or filters in a floating panel → use [Popover](../popover/COMPONENT.md).
+- A hint on hover → use [Tooltip](../tooltip/COMPONENT.md).
+- Two to four always-visible actions → show [Button](../button/COMPONENT.md)s or a [ButtonGroup](../button-group/COMPONENT.md).
 
+## Import
 ```tsx
-import { Button, Dropdown } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Dropdown.Root>
-      <Dropdown.Trigger>
-        <Button.Root type="button" variant="neutral" mode="stroke">
-          Actions
-        </Button.Root>
-      </Dropdown.Trigger>
-      <Dropdown.Content>
-        <Dropdown.Item>Edit</Dropdown.Item>
-        <Dropdown.Item>Duplicate</Dropdown.Item>
-      </Dropdown.Content>
-    </Dropdown.Root>
-  );
-}
+import { Dropdown } from "prime-ui-kit";
 ```
 
----
-
-## 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.Block`** / **`Dropdown.Group`** / **`Dropdown.Item`** children inside it.
-- **`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.
-- **`Dropdown.Trigger`** accepts a **single** `ReactElement` — wrap composite UI in one node if needed.
-- **`onSelect`** on **`Dropdown.Item`** runs on activation, then the menu **closes**, unless the item is **`disabled`** (disabled items do not activate or close).
-- **Keyboard:** **ArrowUp** / **ArrowDown**, **Home**, **End** move focus among enabled menu items; **Enter** and **Space** activate; **Escape** closes and focus returns via the focus trap.
-- **Pointer / outside:** clicks outside the trigger and panel close the menu; outside clicks are suppressed for portaled Select listboxes owned by the panel container.
-- **A11y:** trigger gets **`aria-expanded`**, **`aria-haspopup="menu"`**, **`aria-controls`**; the menu has **`aria-labelledby`** pointing at the trigger **`id`**. Icon-only triggers need an accessible name (**`aria-label`** or visible text).
-- **`Dropdown.Content` · `size`** drives the tier for padding, row height, typography, and default **`ItemIcon`** size unless you pass an explicit **`size`** on **`ItemIcon`**.
-- **`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
-
-#### Dropdown.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| 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. |
-| children | `React.ReactNode` | — | Yes | Trigger, content, and nested parts. |
-
-#### 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
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| align | `"start" \| "center" \| "end"` | `"start"` | No | Horizontal alignment of the panel to the trigger. |
-| side | `"bottom" \| "top"` | `"bottom"` | No | Preferred side; may flip when space is tight. |
-| sameMinWidthAsTrigger | `boolean` | `false` | No | Panel minimum width is not less than the trigger width. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Tier for panel metrics, rows, group labels, and default icon size. |
-| className | `string` | — | No | Extra class on the portaled menu container. |
-| children | `React.ReactNode` | — | Yes | Menu body: blocks, groups, items, etc. |
-
-#### Dropdown.Block
-
-Inherits `React.HTMLAttributes<HTMLDivElement>` (e.g. `className`, `children`).
-
-#### Dropdown.Header
-
-Same as `Dropdown.Block`.
-
-#### Dropdown.HeaderRow
-
-Same as `Dropdown.Block`.
-
-#### Dropdown.HeaderLeading
-
-Same as `Dropdown.Block`.
-
-#### Dropdown.HeaderMain
-
-Same as `Dropdown.Block`.
-
-#### Dropdown.HeaderTitle
-
-Same as `Dropdown.Block`.
-
-#### Dropdown.HeaderDescription
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| truncate | `boolean` | — | No | Single-line truncation with ellipsis. |
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Description text. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
-
-#### Dropdown.HeaderTrailing
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| alignSelf | `"start" \| "center"` | `"start"` | No | Vertical alignment within the header row. |
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | No | Trailing slot content. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
-
-#### Dropdown.Item
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| onSelect | `() => void` | — | No | Called on activation; then the menu closes (if not `disabled`). |
-| disabled | `boolean` | — | No | Inactive item; no activation or close. |
-| destructive | `boolean` | — | No | Danger styling (`data-destructive`). |
-| className | `string` | — | No | Extra class on the `<button>`. |
-| children | `React.ReactNode` | — | Yes | Label, `ItemIcon`, etc. |
-
-#### Dropdown.ItemIcon
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| as | `React.ElementType` | `"span"` | No | Root element or icon component. |
-| aria-hidden | `boolean \| "true" \| "false"` | `true` | No | Hide decorative icons when the item has text. |
-| className | `string` | — | No | Extra class on the wrapper. |
-| children | `React.ReactNode` | — | No | Content when not using `as` alone. |
-| 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
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class (`role="group"`). |
-| children | `React.ReactNode` | — | No | Group label and items. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
-
-#### Dropdown.GroupLabel
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class. |
-| children | `React.ReactNode` | — | Yes | Group heading text. |
-
-#### Dropdown.Separator
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Extra class on the `hr`. |
-
-### Related
-
-- [Button](../button/COMPONENT.md) — typical trigger.
-- [Link button](../link-button/COMPONENT.md) — text-style trigger when a button chrome is not desired.
-- [Select](../select/COMPONENT.md) — single-value field with a labeled trigger.
-- [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
+## Anatomy
+```
+Dropdown.Root                     state and dismiss policy (no DOM)
+├── Dropdown.Trigger              clones its child; toggles the menu
+└── Dropdown.Content              portaled role="menu" on the floating surface, scrolls
+    ├── Dropdown.Header           non-interactive row: [avatar] [Title + Description] [badge]
+    │   ├── Dropdown.Title
+    │   └── Dropdown.Description
+    ├── Dropdown.Separator        full-bleed Divider
+    ├── Dropdown.Group            role="group", named by `label`
+    │   └── Dropdown.Item         <button role="menuitem">
+    │       ├── Dropdown.ItemIcon       leading glyph (aria-hidden)
+    │       └── Dropdown.ItemShortcut   Kbd at the end
+    └── Dropdown.Item
+```
 
-- **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.
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Dropdown.Root
+No DOM, no ref. Open state and dismiss policy.
+
+| 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, item pick, Escape, outside press, code. |
+| `closeOnOutsideClick` | `boolean` | `true` | A pointerdown outside the menu and its trigger closes it; focus follows the pointer. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the menu and returns focus to the trigger. |
+| `children` | `ReactNode` | — (required) | Trigger and Content. |
+
+### Dropdown.Trigger
+No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`, `data-state`; the child's own `id` wins. Other props given to it (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element, usually a Button. |
+
+### Dropdown.Content
+`ref` → `HTMLDivElement`. Portal + `role="menu"` on the floating surface (a ScrollContainer), named by the trigger; renders while open and during its exit animation. Focus moves to the first item; Tab closes the menu and returns focus to the trigger.
+
+| 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"` | Row tier: item height, text and icon; key hints one tier down. |
+| `matchTriggerWidth` | `boolean` | `false` | The menu is at least as wide as the trigger. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "role">` | — | `className`, `onKeyDown` (runs before the arrow-key navigation) and the other attributes of the menu. |
+
+### Dropdown.Item
+`ref` → `HTMLButtonElement`. A `<button role="menuitem">`; a click, Enter or Space runs `onSelect` and closes the menu. + native button props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onSelect` | `() => void` | — | The action of the item. |
+| `disabled` | `boolean` | `false` | Muted, `aria-disabled`, skipped by the arrow keys, does nothing on click. |
+| `tone` | `"neutral" \| "danger"` | `"neutral"` | `danger`: destructive action — danger text, icon and hover fill. |
+| `children` | `ReactNode` | — | `Dropdown.ItemIcon`, the label, `Dropdown.ItemShortcut`. |
+
+### Dropdown.ItemIcon · Dropdown.ItemShortcut
+`ref` → `HTMLSpanElement` / `HTMLElement` (the `<kbd>`). An `aria-hidden` `<span>` holding the leading glyph at the menu icon size (a kit `Icon` follows it) / a `Kbd` one tier below the menu, pushed to the end of the item — a hint, not a handler. + native props.
+
+### Dropdown.Group
+`ref` → `HTMLDivElement`. `<div role="group">` named by its visible `label`. + native `<div>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+
+### Dropdown.Separator
+`ref` → `HTMLDivElement`. A full-bleed Divider between items or groups.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the divider. |
+
+### Dropdown.Header · Dropdown.Title · Dropdown.Description
+`ref` → `HTMLDivElement`. A non-interactive row at the top (who is signed in, the plan): an avatar, Title + Description stacked in one column, a trailing badge or button — in the written order / the medium heading line / the muted line under it; both truncate. + native `<div>` props.
+
+## Variants
+The panel is the shared floating surface: `bg-raised`, `--prime-panel-radius` (12), padding 4, `shadow-overlay`; rows have radius 8 and the tier item height.
+
+### size (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | item 24, text 12/16, icon 14 | Dense toolbars | |
+| `s` | item 28, text 13/20, icon 16 | Table rows, compact headers | |
+| `m` | item 32, text 14/20, icon 16 | Most menus | yes |
+| `l` | item 36, text 16/24, icon 20 | Roomy layouts | |
+| `xl` | item 40, text 16/24, icon 20 | Touch-first screens | |
+
+### tone (Item)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | primary text, muted icon, subtle fill on hover | Regular actions | yes |
+| `danger` | danger text and icon, danger-soft fill on hover | Delete, revoke, leave | |
+
+### side / align (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `side="bottom"` | Below the trigger | 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 (account menu at the bottom of a sidebar) | |
+| `align="start"` | Start edges aligned | Default | yes |
+| `align="center"` | Centred on the trigger | Small triggers | |
+| `align="end"` | End edges aligned | «⋯» buttons at the end of a row | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `disabled` (Item) | Disabled text, skipped by arrows | Not allowed right now (say why in the label) | `false` |
+| `matchTriggerWidth` | Menu at least as wide as the trigger | Full-width buttons | `false` |
+| `closeOnOutsideClick={false}` · `closeOnEscape={false}` | Stays open until an item is picked | A required choice in an onboarding step | |
+
+**Combinations** — menu `size` = trigger `size`. Destructive items go last, after a separator. Key hints only for shortcuts the app really handles.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the menu (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` |
+| item hover / focus | pointer, arrow keys | subtle fill (danger-soft for `danger`), no movement |
+| item disabled | `disabled` | `aria-disabled="true"`, `data-disabled="true"` |
+| item tone | `tone` | `data-tone` |
+
+## Layout & spacing
+- Width is `max-content` between `--prime-panel-min-width` and twice that; items never wrap.
+- Max height = min(`--prime-panel-max-height`, the room on the resolved side); the menu scrolls inside.
+- Separators run edge to edge across the panel padding; group labels take `--prime-panel-group-label-height`.
+- Kept `--prime-space-2` from viewport edges; follows the trigger on scroll and resize.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | On the trigger opens the menu (focus on the first item); on an item runs it and returns focus to the trigger. |
+| `ArrowDown` · `ArrowUp` | Move focus to the next / previous enabled item, wrapping. |
+| `Home` · `End` | First / last enabled item. |
+| `Escape` | Closes the menu (`closeOnEscape`); focus returns to the trigger. |
+| `Tab` · `Shift+Tab` | Closes the menu; focus returns to the trigger (Tab then goes on to the next stop). |
+
+### ARIA
+- The menu is `role="menu"` named by the trigger; items are `role="menuitem"`, disabled ones `aria-disabled`.
+- The trigger gets `aria-haspopup="menu"`, `aria-expanded` and `aria-controls`.
+- `Dropdown.Group` is `role="group"` named by its `label`.
+- `Dropdown.ItemIcon` is hidden from screen readers; a key hint is text only — the app handles the shortcut.
+- An outside press closes the menu without moving focus back to the trigger: focus follows the pointer (foundation §8).
+
+### 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) | An icon-only button opens the row actions; picking an item runs it and closes the menu — `Dropdown.Item`, `onSelect`. |
+| [structure.tsx](examples/structure.tsx) | Optional parts of an account menu: a header with an avatar, a labelled group, item icons, key hints and separators — `Dropdown.Header`, `Dropdown.Group`, `Dropdown.ItemIcon`, `Dropdown.ItemShortcut`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier with icons, key hints and a destructive item; the menu 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 menu flips and shifts — `side`, `align`. |
+| [states.tsx](examples/states.tsx) | A regular, a disabled and a destructive item; arrow keys skip the disabled one — `disabled`, `tone`. |
+| [match-trigger-width.tsx](examples/match-trigger-width.tsx) | Under a full-width button the menu is at least as wide as the trigger — `matchTriggerWidth`. |
+| [long-list.tsx](examples/long-list.tsx) | More projects than fit: the grouped list scrolls inside the panel, capped by the room next to the trigger — `Dropdown.Group`. |
+| [dismiss.tsx](examples/dismiss.tsx) | An onboarding step keeps the menu open on an outside press and on Escape until an item is picked — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state and opens the menu from another button; the picked step updates the trigger — `open`, `onOpenChange`. |
+
+## Mistakes
+- Using Dropdown to pick a form value → Select shows the value and works with forms.
+- An icon passed as a component (`as={Icon}`) → put the glyph inside `Dropdown.ItemIcon`.
+- A hand-written shortcut `<kbd>` → `Dropdown.ItemShortcut` (a Kbd at the end of the item).
+- `Dropdown.Group` with a separate heading element → pass the heading as `label`.
+- A destructive item without `tone="danger"`, or in the middle of the list → mark it and put it last.
+
+## Related
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the menu), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`), [Divider](../divider/COMPONENT.md) (`Separator`)
+- **See also:** [Select](../select/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md)

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

@@ -0,0 +1,32 @@
+/** The parent owns the open state and opens the menu from another button; the picked step updates the trigger — `open`, `onOpenChange`. */
+import { Button, Dropdown } from "prime-ui-kit";
+import * as React from "react";
+
+const STEPS = ["Шаг 1 · Реквизиты", "Шаг 2 · Товары", "Шаг 3 · Оплата"];
+
+export default function DropdownControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+  const [step, setStep] = React.useState(STEPS[1]);
+
+  return (
+    <>
+      <Button.Root variant="ghost" tone="neutral" onClick={() => setOpen(true)}>
+        Перейти к шагу
+      </Button.Root>
+      <Dropdown.Root open={open} onOpenChange={setOpen}>
+        <Dropdown.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            {step}
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content>
+          {STEPS.map((item) => (
+            <Dropdown.Item key={item} onSelect={() => setStep(item)}>
+              {item}
+            </Dropdown.Item>
+          ))}
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,17 @@
+/** An onboarding step keeps the menu open on an outside press and on Escape until an item is picked — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, Dropdown } from "prime-ui-kit";
+
+export default function DropdownDismissExample() {
+  return (
+    <Dropdown.Root closeOnOutsideClick={false} closeOnEscape={false}>
+      <Dropdown.Trigger>
+        <Button.Root>Выберите роль в команде</Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Руководитель</Dropdown.Item>
+        <Dropdown.Item>Менеджер проектов</Dropdown.Item>
+        <Dropdown.Item>Бухгалтер</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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

@@ -0,0 +1,22 @@
+/* Layout of the Dropdown scenarios: semantic tokens only. */
+
+/* match-trigger-width.tsx: a column with a full-width button. */
+.column {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 3);
+}
+
+/* overview.tsx: a list row — the record on the left, its actions button at the end. */
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  padding-block: var(--prime-space-1);
+  padding-inline: var(--prime-space-4) var(--prime-space-1);
+  border-radius: var(--prime-radius-l);
+  background: var(--prime-color-card-bg);
+}

package/src/components/dropdown/examples/long-list.tsx

@@ -0,0 +1,42 @@
+/** More projects than fit: the grouped list scrolls inside the panel, capped by the room next to the trigger — `Dropdown.Group`. */
+import { Button, Dropdown } from "prime-ui-kit";
+
+const RECENT = ["Сайт компании", "Платёжный шлюз"];
+
+const PROJECTS = [
+  "Мобильное приложение",
+  "Личный кабинет",
+  "Админ-панель",
+  "Лендинг акции",
+  "Справочный центр",
+  "Внутренний портал",
+  "Аналитика продаж",
+  "CRM для партнёров",
+  "Бот поддержки",
+  "Дизайн-система",
+];
+
+export default function DropdownLongListExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Переместить в проект
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group label="Недавние">
+          {RECENT.map((name) => (
+            <Dropdown.Item key={name}>{name}</Dropdown.Item>
+          ))}
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Group label="Все проекты">
+          {PROJECTS.map((name) => (
+            <Dropdown.Item key={name}>{name}</Dropdown.Item>
+          ))}
+        </Dropdown.Group>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/match-trigger-width.tsx

@@ -0,0 +1,23 @@
+/** Under a full-width button the menu is at least as wide as the trigger — `matchTriggerWidth`. */
+import { Button, Dropdown } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DropdownMatchTriggerWidthExample() {
+  return (
+    <div className={styles.column}>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root variant="soft" tone="neutral" fullWidth>
+            Экспортировать отчёт
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content matchTriggerWidth>
+          <Dropdown.Item>PDF</Dropdown.Item>
+          <Dropdown.Item>Excel (.xlsx)</Dropdown.Item>
+          <Dropdown.Item>CSV</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,41 @@
+/** An icon-only button opens the row actions; picking an item runs it and closes the menu — `Dropdown.Item`, `onSelect`. */
+import { Button, Dropdown, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DropdownOverviewExample() {
+  const [status, setStatus] = React.useState("Счёт № 4821 · черновик");
+
+  return (
+    <div className={styles.row}>
+      <Typography as="span" variant="body-m">
+        {status}
+      </Typography>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root variant="ghost" tone="neutral" aria-label="Действия со счётом">
+            <Button.Icon>
+              <Icon name="action.more" />
+            </Button.Icon>
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content align="end">
+          <Dropdown.Item onSelect={() => setStatus("Счёт № 4821 · отправлен")}>
+            Отправить клиенту
+          </Dropdown.Item>
+          <Dropdown.Item onSelect={() => setStatus("Счёт № 4822 · копия")}>
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Item onSelect={() => setStatus("Счёт № 4821 · скачан")}>
+            Скачать PDF
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item tone="danger" onSelect={() => setStatus("Счёт № 4821 · удалён")}>
+            Удалить счёт
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </div>
+  );
+}