prime-ui-kit 0.9.0 → 0.9.2

package/src/components/drawer/examples/{variants-sides.tsx → placement.tsx}

@@ -1,36 +1,35 @@
-/** `side="left"` and `side="right"`: right (default) for details and forms, left for filters and navigation. */
+/** The panel slides from the right for details, from the left for filters and up from the bottom as a sheet — `side`. */
 import { Button, Drawer, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIDES = [
-  { side: "left", label: "Слева", title: "Фильтры" },
-  { side: "right", label: "Справа", title: "Детали заказа" },
+  { side: "left", title: "Фильтры" },
+  { side: "right", title: "Детали заказа" },
+  { side: "bottom", title: "Действия с заказом" },
 ] as const;
 
-export default function DrawerVariantsSidesExample() {
+export default function DrawerPlacementExample() {
   return (
-    <div className={styles.row}>
-      {SIDES.map(({ side, label, title }) => (
+    <>
+      {SIDES.map(({ side, title }) => (
         <Drawer.Root key={side}>
           <Drawer.Trigger>
             <Button.Root variant="soft" tone="neutral">
-              {label}
+              {side}
             </Button.Root>
           </Drawer.Trigger>
           <Drawer.Content side={side} size="s">
             <Drawer.Header>
               <Drawer.Title>{title}</Drawer.Title>
-              <Drawer.Description>side="{side}"</Drawer.Description>
             </Drawer.Header>
             <Drawer.Body>
-              <Typography.Root variant="body-m" tone="secondary">
-                Скругление только со стороны страницы, подложка затемняет остальное.
-              </Typography.Root>
+              <Typography variant="body-m" tone="secondary">
+                Скругление только со стороны страницы, подложка затемняет остальное. Свайп к краю
+                закрывает панель.
+              </Typography>
             </Drawer.Body>
           </Drawer.Content>
         </Drawer.Root>
       ))}
-    </div>
+    </>
   );
 }

package/src/components/drawer/examples/sizes.tsx

@@ -1,8 +1,6 @@
-/** Drawer.Content widths s · m · l · xl. Below 640px of viewport the panel always takes the full width. */
+/** Every panel width, 360 to 800 px; below 640 px of viewport the panel takes the full width — `size`. */
 import { Button, Drawer, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = [
   { size: "s", width: "360 px" },
   { size: "m", width: "480 px" },
@@ -12,31 +10,27 @@ const SIZES = [
 
 export default function DrawerSizesExample() {
   return (
-    <div className={styles.row}>
+    <>
       {SIZES.map(({ size, width }) => (
         <Drawer.Root key={size}>
           <Drawer.Trigger>
             <Button.Root variant="soft" tone="neutral">
-              Размер {size}
+              {size}
             </Button.Root>
           </Drawer.Trigger>
           <Drawer.Content size={size}>
             <Drawer.Header>
-              <Drawer.Title>Панель размера {size}</Drawer.Title>
-              <Drawer.Description>Ширина {width}</Drawer.Description>
+              <Drawer.Title>Детали заказа</Drawer.Title>
+              <Drawer.Description>Ширина панели {width}</Drawer.Description>
             </Drawer.Header>
             <Drawer.Body>
-              <Typography.Root variant="body-m" tone="secondary">
-                Ширина берётся из{" "}
-                <Typography.Root as="span" variant="code" tone="secondary">
-                  --prime-drawer-width-{size}
-                </Typography.Root>
-                . На экране уже 640 px панель занимает всю ширину и теряет скругления.
-              </Typography.Root>
+              <Typography variant="body-m" tone="secondary">
+                На экране уже 640 px панель занимает всю ширину и теряет скругления.
+              </Typography>
             </Drawer.Body>
           </Drawer.Content>
         </Drawer.Root>
       ))}
-    </div>
+    </>
   );
 }

package/src/components/drawer/examples/structure.tsx

@@ -0,0 +1,35 @@
+/** Optional parts: an icon tile in the header and one full-width action in the footer — `Drawer.Icon`, `Drawer.Footer`, `layout`. */
+import { Button, Drawer, Icon, Typography } from "prime-ui-kit";
+
+export default function DrawerStructureExample() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Как считается выручка
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content size="s">
+        <Drawer.Header>
+          <Drawer.Icon tone="info">
+            <Icon name="status.info" />
+          </Drawer.Icon>
+          <Drawer.Title>Выручка</Drawer.Title>
+          <Drawer.Description>Справка по отчёту</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Typography variant="body-m" tone="secondary">
+            В выручку входят оплаченные заказы за период без возвратов и отменённых доставок.
+          </Typography>
+        </Drawer.Body>
+        <Drawer.Footer layout="fill">
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Понятно
+            </Button.Root>
+          </Drawer.Close>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

package/src/components/dropdown/COMPONENT.md

@@ -1,13 +1,14 @@
 # Dropdown
 
 **Category:** overlays
+**Kind:** overlay
 
-> A menu of actions that opens from a trigger: groups, a profile header and destructive items.
+> A menu of actions that opens from a trigger: picking an item runs it and closes the menu.
 
 ## 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, sort order) where picking one runs an action.
+- A short list of commands (export formats, move to project) where picking one runs an action.
 
 ## 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).
@@ -23,224 +24,194 @@ import { Dropdown } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Dropdown.Root                     state (no DOM)
-├── Dropdown.Trigger              clones its single child (usually a Button)
-└── Dropdown.Content              portaled role="menu" panel, scrolls
-    ├── Dropdown.Block            vertical section (header + list)
-    │   └── Dropdown.Header       user / plan header
-    │       └── Dropdown.HeaderRow
-    │           ├── Dropdown.HeaderLeading      avatar / icon
-    │           ├── Dropdown.HeaderMain
-    │           │   ├── Dropdown.HeaderTitle
-    │           │   └── Dropdown.HeaderDescription
-    │           └── Dropdown.HeaderTrailing     badge / button
-    ├── Dropdown.Group            role="group"
-    │   ├── Dropdown.GroupLabel
-    │   └── Dropdown.Item         role="menuitem" button
-    │       ├── Dropdown.ItemIcon
-    │       ├── label
-    │       └── Dropdown.ItemShortcut
-    └── Dropdown.Separator        full-bleed hairline
+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.CheckboxItem     <button role="menuitemcheckbox">: label + check mark at the end while checked; stays open
+    └── Dropdown.Item
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Dropdown.Root
-No DOM, no ref.
+No DOM, no ref. Open state and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `open` | `boolean` | — | Controlled visibility. |
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on trigger click, item select, Escape and outside press. |
-| `closeOnOutsideClick` | `boolean` | `true` | A pointerdown outside the panel and its trigger closes it. |
+| `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 of its own: clones the child (`cloneElement`), like `asChild`. Merges the child's `ref`, sets `id`, `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`, `data-state`, chains `onClick` (toggles).
+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) | Exactly one element. |
+| `children` | `ReactElement` | — (required) | One element, usually a Button. |
 
 ### Dropdown.Content
-No ref. Rendered in a portal while open and during its exit animation. Traps focus while open and returns it to the trigger on close.
+`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. Below 640px of viewport the menu is a bottom sheet: a scrim, a grab handle, swipe down to close (with `closeOnOutsideClick`), page scroll locked.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `side` | `"bottom" \| "top"` | `"bottom"` | Preferred side; flips when it does not fit. |
-| `align` | `"start" \| "center" \| "end"` | `"start"` | Horizontal alignment to the trigger. |
-| `sameMinWidthAsTrigger` | `boolean` | `false` | The panel is at least as wide as the trigger. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Item height, text and icon tier; size context for controls inside. |
-| `className` | `string` | — | Extra class on the panel. |
-| `children` | `ReactNode` | — (required) | Items, groups, blocks, separators. |
+| `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
-No ref. Renders `<button type="button" role="menuitem">`. Activating it calls `onSelect` and closes the menu.
+`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` | — | Action on click / Enter / Space. |
-| `disabled` | `boolean` | — | `aria-disabled`, `tabIndex={-1}`, skipped by arrow keys, does not close the menu. |
-| `tone` | `"neutral" \| "danger"` | `"neutral"` | `danger` for destructive actions (delete, revoke). |
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — (required) | ItemIcon, label, ItemShortcut. |
+| `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
-`forwardRef` to the rendered element. Polymorphic.
+### Dropdown.CheckboxItem
+`ref` → `HTMLButtonElement`. A `<button role="menuitemcheckbox">` with `aria-checked`: the label (and an `ItemIcon`) on the left like any item, an accent check mark at the end while checked and nothing while not; a click, Enter or Space toggles it and the menu stays open. + native button props.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `as` | `ElementType` | `"span"` | Icon component (e.g. a lucide icon); receives `size`. |
-| `size` | `number` | tier icon (14 · 16 · 16 · 20 · 20) | Icon size in px; by default follows the Content `size`. |
-| `aria-hidden` | `boolean` | `true` | Decorative by default. |
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Glyph when `as` is a wrapper. |
-
-+ any other props, passed to the `as` element (e.g. `strokeWidth`).
+| `checked` | `boolean` | — | Checked state (controlled). |
+| `defaultChecked` | `boolean` | `false` | Initial state (uncontrolled). |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state. |
+| `disabled` | `boolean` | `false` | Muted, `aria-disabled`, skipped by the arrow keys, does not toggle. |
+| `children` | `ReactNode` | — | The label (optionally after a `Dropdown.ItemIcon`). |
 
-### Dropdown.ItemShortcut
-No ref. Renders `<kbd>` at the end of the item. A hint only: bind the key yourself. + native `HTMLAttributes<HTMLElement>`.
+### 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
-No ref. `<div role="group">`. + native `<div>` props.
-
-### Dropdown.GroupLabel
-No ref.
+`ref` → `HTMLDivElement`. `<div role="group">` named by its visible `label`. + native `<div>` props.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Group heading. |
-| `className` | `string` | — | Extra class. |
+| `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
 
 ### Dropdown.Separator
-No ref. Renders `<hr>`.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `className` | `string` | — | Extra class. |
-
-### Dropdown.Block · Header · HeaderRow · HeaderLeading · HeaderMain · HeaderTitle
-No ref. Layout `<div>`s. + native `<div>` props.
-
-### Dropdown.HeaderDescription
-No ref.
+`ref` → `HTMLDivElement`. A full-bleed Divider between items or groups.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `truncate` | `boolean` | — | One line with an ellipsis (long emails). |
-
-+ native `<div>` props.
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the divider. |
 
-### Dropdown.HeaderTrailing
-No ref.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `alignSelf` | `"start" \| "center"` | `"start"` | Vertical alignment in the header row (`center` for a button). |
-
-+ native `<div>` props.
+### 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 has one look: `bg-raised` fill, `--prime-panel-radius` (12), `--prime-panel-padding` (4), `shadow-overlay`; items have radius 8.
+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 | xs triggers | |
-| `s` | item 28, text 13/20, icon 16 | Dense toolbars, s triggers | |
+| `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 | l triggers | |
-| `xl` | item 40, text 16/24, icon 20 | xl triggers | |
+| `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, `fill-subtle` on hover / focus | Regular actions | yes |
-| `danger` | `danger-text` label and icon, `danger-soft` on hover / focus | Delete, revoke, leave — last in the menu after a Separator | |
+| `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, `--prime-space-1` away | Default | yes |
+| `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 to the trigger | Small centred triggers | |
-| `align="end"` | End edges aligned | «⋯» buttons and user menus at the right edge | |
+| `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 |
 |---|---|---|---|
-| `sameMinWidthAsTrigger` | Panel at least trigger width | Full-width triggers | `false` |
-| `disabled` (Item) | `text-disabled`, no hover fill | Unavailable action that should stay visible | — |
-| `truncate` (HeaderDescription) | One line with ellipsis | Long emails | — |
-| `alignSelf` (HeaderTrailing) `start` · `center` | Trailing slot at the top or centred | Badge (`start`), button (`center`) | `start` |
-
-**Combinations** — Content `size` = trigger `size`. Destructive item: `tone="danger"` placed last, separated by `Dropdown.Separator`. A disabled danger item looks like any disabled item.
+| `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 | |
 
-**Hierarchy** — keep the primary action outside the menu as a visible button; the menu holds secondary actions. Group long menus with `GroupLabel`; one danger group at the end.
+**Combinations** — menu `size` = trigger `size`. Destructive items go last, after a separator. Key hints only for shortcuts the app really handles.
 
 ## States
-- Closed / open: uncontrolled by default; `open` + `onOpenChange` for controlled. Selecting an item closes the menu.
-- Panel DOM: `data-state="open" | "closed"`, `data-side` (resolved), `data-size`, `data-overlay-portal-layer`.
-- Item DOM: `data-tone`, `data-disabled="true"`, `aria-disabled`.
-- Trigger DOM: `data-state`, `aria-expanded`.
-- Hover and keyboard focus highlight the row with background (`fill-subtle` / `danger-soft`), not a ring; active `fill-subtle-active`.
-- No built-in search or empty state.
+| 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 | a hovering pointer, arrow keys | subtle fill (danger-soft for `danger`), no movement; a tap leaves no hover fill |
+| item disabled | `disabled` | `aria-disabled="true"`, `data-disabled="true"` |
+| item tone | `tone` | `data-tone` |
+| sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the menu; the sheet carries `data-state`, the menu keeps its role and ref; page scroll locked; a swipe down from the handle closes it (with `closeOnOutsideClick`) |
 
 ## Layout & spacing
-- Width `max-content` between `--prime-panel-min-width` and twice that; max height `--prime-panel-max-height` or the free space, then the list scrolls.
-- Item padding-x `--prime-panel-item-padding-x` (8); icon → label gap is the tier gap; the shortcut is pushed to the end with `--prime-space-4` before it.
-- Separators are full-bleed hairlines with `--prime-panel-padding` above and below.
-- Kept `--prime-space-2` from viewport edges.
+- 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
-- Panel `role="menu"` labelled by the trigger; items `role="menuitem"`; groups `role="group"`.
-- Keyboard: Arrow Down / Up move between enabled items (wrapping), Home / End jump to the first / last, Enter / Space activate, Tab is kept inside (focus trap), Escape closes and returns focus to the trigger.
-- An outside press closes without moving focus back (foundation §8); only the topmost layer reacts.
-- Icon-only triggers need `aria-label`. ItemIcon is `aria-hidden` by default.
-- No `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | `size` xs → xl with icons, shortcuts, danger item | Matching the menu to the trigger |
-| [variants.tsx](examples/variants.tsx) | Item kinds, groups, disabled and `tone="danger"` | Document actions menu |
-| [states.tsx](examples/states.tsx) | Long scrolling list with groups and a disabled row | Many items |
-| [row-actions.tsx](examples/row-actions.tsx) | Card toolbar with a visible primary action and «⋯» menu | Secondary actions of a card / row |
-| [composition.tsx](examples/composition.tsx) | Account menu with header, avatar, badge and plan block | User menu |
-| [placement.tsx](examples/placement.tsx) | `align` × `side` | Placing near edges |
-| [full-width.tsx](examples/full-width.tsx) | `sameMinWidthAsTrigger` | Full-width triggers |
-| [controlled.tsx](examples/controlled.tsx) | `open` + `onOpenChange` in parent state | Syncing with other UI |
-| [as-child.tsx](examples/as-child.tsx) | Text-link button as the trigger | Inline switches |
+### 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; on a checkbox item toggles it and the menu stays open. |
+| `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). |
 
-```tsx
-import { Button, Dropdown } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Dropdown.Root>
-      <Dropdown.Trigger>
-        <Button.Root variant="soft" tone="neutral">
-          Действия
-        </Button.Root>
-      </Dropdown.Trigger>
-      <Dropdown.Content>
-        <Dropdown.Item onSelect={() => {}}>Переименовать</Dropdown.Item>
-        <Dropdown.Separator />
-        <Dropdown.Item tone="danger">Удалить</Dropdown.Item>
-      </Dropdown.Content>
-    </Dropdown.Root>
-  );
-}
-```
+### ARIA
+- The menu is `role="menu"` named by the trigger; items are `role="menuitem"`, checkbox items `role="menuitemcheckbox"` with `aria-checked`, 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`. |
+| [checkbox-items.tsx](examples/checkbox-items.tsx) | A column chooser: toggles in the menu keep it open, the key column cannot be hidden — `Dropdown.CheckboxItem`, `checked`, `onCheckedChange`. |
+| [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
-- `onClick` on Dropdown.Item → use `onSelect` (Item has no `onClick` prop).
-- Using Dropdown as a form select that shows the chosen value → use Select.
-- `tone="error"` → destructive tone is `danger`.
-- A different `size` on the trigger and the panel → use the same tier.
-- Setting `size` on every `ItemIcon` → leave it, it follows the panel.
+- 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
-[Select](../select/COMPONENT.md) · [CommandMenu](../command-menu/COMPONENT.md) · [Popover](../popover/COMPONENT.md) · [Kbd](../kbd/COMPONENT.md) · [Avatar](../avatar/COMPONENT.md)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the menu), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`), [Divider](../divider/COMPONENT.md) (`Separator`), Icon (`action.check` of `CheckboxItem`)
+- **See also:** [Select](../select/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md)

package/src/components/dropdown/examples/checkbox-items.tsx

@@ -0,0 +1,48 @@
+/** A column chooser: toggles in the menu keep it open, the key column cannot be hidden — `Dropdown.CheckboxItem`, `checked`, `onCheckedChange`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+const COLUMNS = [
+  { id: "number", label: "Номер", locked: true },
+  { id: "client", label: "Клиент", locked: false },
+  { id: "status", label: "Статус", locked: false },
+  { id: "amount", label: "Сумма", locked: false },
+  { id: "due", label: "Срок оплаты", locked: false },
+];
+
+export default function DropdownCheckboxItemsExample() {
+  const [hidden, setHidden] = React.useState<string[]>(["due"]);
+  const shown = COLUMNS.length - hidden.length;
+
+  const toggle = (id: string, visible: boolean) =>
+    setHidden((list) => (visible ? list.filter((item) => item !== id) : [...list, id]));
+
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="action.settings" />
+          </Button.Icon>
+          Колонки: {shown} из {COLUMNS.length}
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group label="Показывать">
+          {COLUMNS.map((column) => (
+            <Dropdown.CheckboxItem
+              key={column.id}
+              checked={!hidden.includes(column.id)}
+              disabled={column.locked}
+              onCheckedChange={(visible) => toggle(column.id, visible)}
+            >
+              {column.label}
+            </Dropdown.CheckboxItem>
+          ))}
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Item onSelect={() => setHidden([])}>Показать все</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

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