prime-ui-kit 0.7.13 → 0.9.1

package/src/components/command-menu/COMPONENT.md

@@ -1,214 +1,196 @@
 # CommandMenu
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** overlays
+**Kind:** overlay
 
-## Canonical
+> A search palette over the page: the query filters commands and pages, Enter runs the active one.
 
-- **Namespace:** `CommandMenu` from `prime-ui-kit` — `Dialog`, `DialogTitle`, `DialogDescription`, `InputRow`, `Input`, `List`, `Group`, `Item`, `ItemIcon`, `TagSection` (+ `TagSectionLabel`, `TagRow`), `Footer`, `FooterKeyBox`.
-- **Shell:** `CommandMenu.Dialog` = [Modal](../modal/COMPONENT.md) + internal provider; controlled via **`open`** / **`onOpenChange`** (or **`defaultOpen`**).
-- **Tree:** `Dialog` → optional title/description → **`InputRow`** (optional `leading` / `trailing`, `density`) → **`Input`** → optional tag block → **`List`** → optional **`Footer`**. **`Item`** must live under **`List`** (inside **`Group`** recommended).
-- **Filtering:** case-insensitive match on **`Item`** **`value`** + **`keywords`**; empty query shows all non-disabled items. **`disabled`** items are **dropped from the visible list and keyboard order** (not grayed in-place).
-- **Input:** uncontrolled by default; **`value`** / **`onChange`** for controlled. **`type`** is fixed to `search`. From the combobox: ArrowUp/Down, Home, End, Enter (activate), Escape closes via Modal.
-- **Remount:** opening a fresh dialog subtree resets search, active id, and focuses the input on the next frame.
-- **Demos:** playground snippets in **`playground/snippets/command-menu/`** (order matches **`playground/sections/CommandMenuSection.tsx`**); package recipes in **`examples/`** (see **Playground snippets** + **Package examples** below).
+## When to use
+- Global search of an app opened with ⌘K / Ctrl+K: pages, records, settings.
+- Quick actions (create, invite, switch workspace) for keyboard users.
+- Picking one entry from a long list by typing, when a Select would be too small.
 
-## Extended
-
-### About
-
-A modal command palette: search field plus a filterable list of actions. Typing narrows visible options; users pick with pointer or keyboard while focus stays on the combobox input.
-
-**When to use**
-
-- **Dense navigation** — jump to sections, records, or actions without opening full menus (dashboards, CRM, admin).
-- **Power-user flows** — one surface for “go to…” and “do…” when labels map cleanly to filter strings and `keywords`.
-- **Keyboard-first desktops** — pair with your own global shortcut; arrow keys, Home, End, and Enter are handled from the search field.
-- **Grouped actions** — optional section headings and optional tag row under the search for scope chips.
-
-**When not to use**
-
-- **Multi-select or bulk pick** — only one active option; no built-in multi-value selection.
-- **Server-only search without a client list** — filtering is synchronous over registered items; huge lists need virtualization or a different pattern.
-- **Non-modal pickers** — use [Dropdown](../dropdown/COMPONENT.md) or [Select](../select/COMPONENT.md) for inline single choice.
-- **Built-in “no results” UX** — empty matches hide groups/items; you supply messaging or empty state markup yourself.
-- **Visible but non-clickable rows** — `disabled` removes items from the palette entirely; render a normal **`Item`** with explanation, or omit it, if you need a “locked” hint.
-
-### Composition
-
-- **`CommandMenu.Dialog`** wraps content in [Modal](../modal/COMPONENT.md) (`role="dialog"`) and mounts **`CommandMenuRootProvider`**: search string, active option, and item registry live here. Open state is controlled (`open` / `onOpenChange`) or uncontrolled (`defaultOpen`).
-- **Recommended top order:** optional **`DialogTitle`** / **`DialogDescription`** (same typography shell as modal headings) → **`InputRow`** (optional slots **`leading`** / **`trailing`**) → **`Input`** → optional **`TagSection`** → **`TagSectionLabel`** / **`TagRow`** → **`List`** → optional **`Footer`** (optional **`FooterKeyBox`** for key hints).
-- **`List`** is the **`listbox`** (`id` wired to the input’s **`aria-controls`**). **`Group`** wraps **`Item`** nodes; groups with no visible items get **`hidden`**. **`Item`** registers for filtering and keyboard activation; put **`ItemIcon`** and label text inside **`Item`**.
-- **`Input`** may sit directly under **`Dialog`** without **`InputRow`** (valid markup); **`InputRow`** is the styled search row when you need leading/trailing slots or density.
-
-### Minimal example
+## When not to use
+- A few actions next to a button → use [Dropdown](../dropdown/COMPONENT.md).
+- Choosing a form value → use [Select](../select/COMPONENT.md) (with `searchable`) or [TagSelect](../tag-select/COMPONENT.md).
+- A dialog with a form or a confirmation → use [Modal](../modal/COMPONENT.md).
 
+## Import
 ```tsx
-import * as React from "react";
 import { CommandMenu } from "prime-ui-kit";
-
-export function Example() {
-  const [open, setOpen] = React.useState(false);
-  return (
-    <CommandMenu.Dialog open={open} onOpenChange={setOpen}>
-      <CommandMenu.InputRow>
-        <CommandMenu.Input placeholder="Search" aria-label="Search commands" />
-      </CommandMenu.InputRow>
-      <CommandMenu.List>
-        <CommandMenu.Item value="action" onSelect={() => setOpen(false)}>
-          Action
-        </CommandMenu.Item>
-      </CommandMenu.List>
-    </CommandMenu.Dialog>
-  );
-}
 ```
 
-### Playground snippets
-
-Same order as **`playground/sections/CommandMenuSection.tsx`**. Sources use `@/` under **`playground/snippets/command-menu/`**:
-
-| Block | File | What it shows |
-|-------|------|----------------|
-| **Варианты** | [`variants-density-items.tsx`](../../../playground/snippets/command-menu/variants-density-items.tsx) | **`InputRow`** **`density`** (`compact` / `comfortable`) and **`Item`** **`size`** (`s` / `m`). |
-| **Состояния** | [`states-disabled-filter.tsx`](../../../playground/snippets/command-menu/states-disabled-filter.tsx) | **`disabled`** (excluded from navigation), empty **`value`** (always in results), footer note on empty filter. |
-| **Контролируемый режим** | [`controlled-open-search.tsx`](../../../playground/snippets/command-menu/controlled-open-search.tsx) | **`Dialog`** **`open`** / **`onOpenChange`** and controlled **`Input`** **`value`** / **`onChange`**. |
-| **Композиция** | [`composition-tags-footer.tsx`](../../../playground/snippets/command-menu/composition-tags-footer.tsx) | Custom title, **`InputRow`** **`leading`** / **`trailing`** (**`Kbd`**, close), **`TagSection`**, **`ItemIcon`**, **`Footer`**. |
-| **Full width** | [`full-width-panel.tsx`](../../../playground/snippets/command-menu/full-width-panel.tsx) | Wider panel via **`className`** on **`Dialog`** (playground: demo class; apps: e.g. **`dialogContentWide`** from **`CommandMenu.module.css`**). |
-| **Полиморфная разметка** | [`item-icon-as.tsx`](../../../playground/snippets/command-menu/item-icon-as.tsx) | **`ItemIcon`** **`as`** — SVG component or **`span`**. |
-| **Специфичные фичи** | [`features-keyboard-search.tsx`](../../../playground/snippets/command-menu/features-keyboard-search.tsx) | Global ⌘K / Ctrl+K, **`keywords`**, **`FooterKeyBox`** hints. |
-
-### Package examples (`examples/`)
-
-Runnable recipes use **`@/`** imports in-repo (consumers: **`prime-ui-kit`**). Aligned with the playground blocks above where noted.
-
-| Playground block | File |
-|------------------|------|
-| Варианты | [`variants-density-items.tsx`](./examples/variants-density-items.tsx) |
-| Состояния | [`disabled-items.tsx`](./examples/disabled-items.tsx) |
-| Контролируемый режим | [`controlled-open-search.tsx`](./examples/controlled-open-search.tsx) |
-| Композиция | [`composition-tags-footer.tsx`](./examples/composition-tags-footer.tsx) |
-| Full width | [`full-width-panel.tsx`](./examples/full-width-panel.tsx) |
-| Полиморфная разметка | [`item-icon-as.tsx`](./examples/item-icon-as.tsx) |
-| Специфичные фичи | [`app-palette.tsx`](./examples/app-palette.tsx) |
-| (extra) File list + **`keywords`** | [`file-search.tsx`](./examples/file-search.tsx) |
-| (extra) Grouped quick actions | [`quick-actions.tsx`](./examples/quick-actions.tsx) |
-
-### Rules
-
-- **Open state:** **`open`** + **`onOpenChange`** for controlled mode; **`defaultOpen`** (defaults to `false` via `Modal.Root`) for uncontrolled. Escape and overlay click close according to **`closeOnEscape`** and **`closeOnOverlayClick`** (both default `true`).
-- **Search state:** **`Input`** is uncontrolled by default (internal `search` drives filtering). Pass **`value`** / **`onChange`** for controlled input; when **`value`** is set, internal state tracks it via an effect. **`type`** is always **`search`**; **`size`** is not a valid prop on **`Input`**.
-- **Remount reset:** when the dialog content tree mounts, search and active item reset and the input is focused on the next animation frame—do not assume text persists across unmount.
-- **Filtering:** matches run against normalized **`value`** and **`keywords`** together. **`disabled`** items are **not** included in **`visibleIds`** (they do not appear in the listbox and cannot be focused via keyboard). **`Item`** **`value`** is required (use empty string only when you intentionally want a row always visible for any query—see Rules in code comments in snippets).
-- **Selection:** Enter activates the active option; click and pointer move on an enabled, visible item updates the active option and can fire **`onSelect`**. **`Item`** renders **`type="button"`**; do not rely on **`type`** override.
-- **Panel styling:** **`className`** and **`contentClassName`** merge onto the dialog panel; width/height helpers (e.g. `dialogContentWide`, `dialogContentNarrow`, `dialogContentTight`) live in the component CSS module—import those classes in your app if you need them.
-- **Accessibility:** set **`aria-labelledby`** (and **`DialogTitle`** with a matching **`id`**) or an appropriate **`aria-label`** on the dialog surface; **`Input`** exposes **`role="combobox"`**, **`aria-controls`**, and **`aria-activedescendant`**; **`List`** is **`listbox`**, **`Item`** is **`option`** with **`aria-selected`**. Modal focus trap and scroll lock follow [Modal](../modal/COMPONENT.md) behavior.
-- **FooterKeyBox** wraps [Badge](../badge/COMPONENT.md) (`size="s"`, `color="gray"`); **`tone="muted"`** maps to badge variant **`lighter`**, default maps to **`stroke`**.
+## Anatomy
+```
+CommandMenu.Root                 Modal + top-aligned palette panel, query state
+├── CommandMenu.Title            optional <h2>, names the dialog
+├── CommandMenu.Description      optional <p>
+├── CommandMenu.Input            search icon + role="combobox" field, faint hairline below
+├── CommandMenu.List             role="listbox", scrolls
+│   ├── CommandMenu.Empty        compact EmptyPage while nothing matches
+│   └── CommandMenu.Group        role="group", named by `label`
+│       └── CommandMenu.Item     <button role="option">
+│           ├── CommandMenu.ItemIcon
+│           ├── CommandMenu.ItemText       title + description line
+│           └── CommandMenu.ItemShortcut   Kbd at the end
+└── CommandMenu.Footer           key hints, hairline above
+    └── CommandMenu.FooterHint   Kbd per key + label
+```
 
 ## API
 
-### CommandMenu.Dialog
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Palette markup (provider runs inside the panel) |
-| open | `boolean` | — | no | Controlled open state |
-| defaultOpen | `boolean` | `false` | no | Initial open when uncontrolled |
-| onOpenChange | `(open: boolean) => void` | — | no | Open state change callback |
-| closeOnEscape | `boolean` | `true` | no | Close when Escape is pressed |
-| closeOnOverlayClick | `boolean` | `true` | no | Close when the overlay is clicked |
-| overlayClassName | `string` | — | no | Overlay wrapper class |
-| className | `string` | — | no | Panel class (merged with internal dialog layout) |
-| contentClassName | `string` | — | no | Additional panel class merged before `className` |
-| aria-labelledby | `string` | — | no | IDs of labelling element(s) |
-| aria-describedby | `string` | — | no | IDs of description element(s) |
-
-### CommandMenu.DialogTitle / CommandMenu.DialogDescription
-
-| Part | Element | Notes |
-|------|---------|--------|
-| DialogTitle | `h2` | `React.HTMLAttributes<HTMLHeadingElement>` and `className`; same title class stack as modal shell |
-| DialogDescription | `p` | `React.HTMLAttributes<HTMLParagraphElement>` and `className`; same description class stack as modal shell |
-
-### CommandMenu.InputRow
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Typically **`Input`** |
-| leading | `React.ReactNode` | — | no | Start slot |
-| trailing | `React.ReactNode` | — | no | End slot |
-| density | `"compact" \| "comfortable"` | `"compact"` | no | Search row vertical padding |
-| className | `string` | — | no | Wrapper class |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Forwarded to the row `div` |
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### CommandMenu.Root
+`ref` → `HTMLDivElement` (the dialog panel). A Modal with a top-aligned palette panel; owns the query (cleared on close) and the active item (a new opening starts empty, focus in the search field).
+
+| 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: Escape, scrim click, code. |
+| `value` | `string` | — | Controlled query; the list filters by it. Together with `onValueChange`. |
+| `defaultValue` | `string` | `""` | Initial query, uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new query: typing, and `""` when the palette closes. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim closes the palette; focus returns to the opener. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the palette. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the rows and the search row: item height, text, icon. |
+| `labels` | `Partial<CommandMenuLabels>` | — | Built-in strings, see Labels. |
+| `aria-label · aria-labelledby · aria-describedby` | `string` | — | Name and description of the dialog when there is no `CommandMenu.Title` / `Description`. |
+| `children` | `ReactNode` | — (required) | Title, Description, Input, List, Footer. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the dialog panel. |
+
+### CommandMenu.Title · CommandMenu.Description
+`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` / `<p>` above the search row; they name and describe the dialog. + native props except `id`.
 
 ### CommandMenu.Input
+`ref` → `HTMLInputElement`. The search row: a search icon and `<input role="combobox">` controlling the list; shows `CommandMenu.Root` `value`; takes focus on open; no focus ring (the caret is the indicator). + native input props except `value` / `defaultValue`.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string \| number \| readonly string[]` | — | no | Controlled value; when set, filters sync from this value |
-| onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | no | Standard change handler; internal state updates when uncontrolled |
-| className | `string` | — | no | Input class |
-| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" \| "type">` | — | no | Other attributes except `size` and `type` (`type` is fixed to `search`) |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `placeholder` | `string` | `labels.search` | Placeholder; also the default accessible name comes from `labels.search`. |
 
 ### CommandMenu.List
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Groups and/or items |
-| className | `string` | — | no | List surface class |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Passed through to the scroll container root (`role="listbox"`, stable `id` for `aria-controls`) |
+`ref` → `HTMLElement`. The scrolling `role="listbox"` (a ScrollContainer) under the search row. + native props.
 
 ### CommandMenu.Group
+`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while none of its items match. + native `<div>` props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| heading | `React.ReactNode` | — | no | Section label (string vs node pick different heading wrappers) |
-| children | `React.ReactNode` | — | no | **`Item`** elements |
-| className | `string` | — | no | Group container class |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Forwarded to the group `div`; container is **`hidden`** when no visible items belong to the group |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
 
 ### CommandMenu.Item
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | yes | Text participating in filter matching |
-| keywords | `string` | `""` | no | Extra space for matching (not shown as the label) |
-| size | `CommandMenuItemSize` (`"s"` \| `"m"`) | `"s"` | no | Row density / type scale |
-| onSelect | `() => void` | — | no | Called when the item is chosen (click or keyboard activate) |
-| disabled | `boolean` | — | no | Excluded from the visible list and activation (not shown as a dimmed option) |
-| className | `string` | — | no | Button class |
-| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "onSelect">` | — | no | Other button props; `type` is always `button` |
-
-### CommandMenu.ItemIcon
-
-Polymorphic icon slot: `as` (element type, default `"span"`), `className`, and remaining props forwarded to the chosen component (see `CommandMenuItemIconProps`).
-
-### CommandMenu.TagSection / TagSectionLabel / TagRow
-
-`React.HTMLAttributes<HTMLDivElement>` with `className` and `children` for the optional block between search and list.
-
-### CommandMenu.Footer
-
-`React.HTMLAttributes<HTMLDivElement>` with `className` and `children`; base styles from the module (e.g. footer layout tokens). Optional module classes such as `footerMuted` apply via `className` when you import the stylesheet.
-
-### CommandMenu.FooterKeyBox
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Key cap or icon (rendered inside `Badge.Icon`) |
-| tone | `"default" \| "muted"` | `"default"` | no | Badge visual variant (`stroke` vs `lighter`) |
-| className | `string` | — | no | Extra class on the badge root |
-| …rest | `Omit<React.HTMLAttributes<HTMLDivElement>, "color">` | — | no | Additional attributes except `color` |
+`ref` → `HTMLButtonElement`. `<button role="option">`; the active item has `aria-selected` and the highlight fill. + native button props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Text matched against the query together with `keywords`. |
+| `keywords` | `string` | — | Extra words for the query (synonyms, English names). |
+| `onSelect` | `() => void` | — | Runs the command: a click, or Enter while the item is active. |
+| `disabled` | `boolean` | `false` | Unavailable right now: shown muted with `aria-disabled`, skipped by the arrows, does not run. |
+
+### CommandMenu.ItemIcon · CommandMenu.ItemShortcut
+`ref` → `HTMLSpanElement` / `HTMLElement` (the `<kbd>`). An `aria-hidden` `<span>` holding the leading glyph at the tier icon size / a `Kbd` one tier below, pushed to the end of the item — a hint, not a handler. + native props.
+
+### CommandMenu.ItemText
+`ref` → `HTMLSpanElement`. A `<span>` column: the title with an ellipsis and an optional description line. + native `<span>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `description` | `ReactNode` | — | Second line (path, details): caption, muted. |
+
+### CommandMenu.Empty
+`ref` → `HTMLDivElement`. A compact EmptyPage with `role="status"`, shown only while nothing matches: `labels.empty`, `labels.emptyHint`, and `children` as an action under them.
+
+### CommandMenu.Footer · CommandMenu.FooterHint
+`ref` → `HTMLDivElement` / `HTMLSpanElement`. A bottom row of hints with a hairline above / one hint: every entry of `keys` in its own `Kbd`, then the label (`children`). + native props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `keys` | `ReactNode[]` | — (required) | FooterHint: the keys (text or icons). |
+
+## Variants
+One look: `bg-raised`, `--prime-modal-radius`, `shadow-modal`, `--prime-modal-width-l` wide, placed in the top part of the viewport so the search row never jumps while the list filters.
+
+### size (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | item 24, text 12/16, search row 40 | Dense tools | |
+| `s` | item 28, text 13/20, search row 40 | Compact apps | |
+| `m` | item 32, text 14/20, search row 48 | Most apps | yes |
+| `l` | item 36, text 16/24, search row 56 | Roomy layouts | |
+| `xl` | item 40, text 16/24, search row 56 | Touch-first screens | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `disabled` (Item) | muted row, `aria-disabled`, skipped by the arrows | The command is unavailable right now | `false` |
+| `closeOnOutsideClick={false}` | the scrim does not close it | A required pick | |
+| `closeOnEscape={false}` | Escape does nothing | A required pick that must not be skipped | |
+
+**Combinations** — one palette per app; open it with ⌘K / Ctrl+K and a visible button. Add a Footer with key hints when keyboard use is not obvious.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the scrim and the dialog (closed while the exit animation plays) |
+| active item | arrows, Home, End, pointer move | `aria-selected="true"`, `data-highlighted="true"`: a fill only, no movement |
+| filtered out | the query | `hidden` on items and on groups without matches |
+| matched text | the query | the first match in the item's text children and in `ItemText` is wrapped in a `<mark>` in `accent-text`, no fill (same as SmartFilter) |
+| nothing found | the query | `CommandMenu.Empty` with `role="status"` |
+| query | `value` / `defaultValue` / `onValueChange` on Root | the search field's value; cleared when the palette closes |
+| disabled item | `disabled` on Item | `aria-disabled="true"`, `data-disabled`; never active, not runnable |
+| size | `size` | `data-size` on the tier wrapper |
+
+## Layout & spacing
+- Width `--prime-modal-width-l`, max height 1.5 × `--prime-panel-max-height`; only the list scrolls.
+- One content column: title, search icon, group labels and item icons start 16 from the edge.
+- Search row and footer are separated from the list by hairlines; the search row hairline is faint.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowDown` · `ArrowUp` | Move the active item, wrapping; focus stays in the search field. |
+| `Home` · `End` | First / last matching item. |
+| `Enter` | Runs the active item. |
+| `Escape` | Closes the palette (`closeOnEscape`); focus returns to the opener. |
+
+### ARIA
+- The palette is `role="dialog"` with `aria-modal`, named by `CommandMenu.Title` or `aria-label`.
+- The field is `role="combobox"` with `aria-controls` on the list and `aria-activedescendant` on the active item; items are `role="option"`, the active one `aria-selected`.
+- `CommandMenu.Group` is `role="group"` named by its `label`; the empty result is `role="status"`.
+- The page behind is inert; after closing, focus returns to the opener.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `search` | `"Поиск"` | Default placeholder and accessible name of `CommandMenu.Input`. |
+| `empty` | `"Ничего не найдено"` | `CommandMenu.Empty`: nothing matches the query. |
+| `emptyHint` | `"Попробуйте изменить запрос"` | Second line of `CommandMenu.Empty`; `""` hides it. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A button or ⌘K opens the palette: the query filters the groups by value and keywords, Enter runs the active command — `CommandMenu.Item`, `keywords`. |
+| [structure.tsx](examples/structure.tsx) | Optional parts: a visible title and description, a description line and a key hint in items, and a footer with key hints — `CommandMenu.Title`, `CommandMenu.ItemText`, `CommandMenu.ItemShortcut`, `CommandMenu.Footer`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: rows, text, icons and the search row follow it; match the density of the app — `size`. |
+| [states.tsx](examples/states.tsx) | A disabled item stays visible but muted and is skipped by the arrows, and an empty result speaks in the words of the task — `disabled`, `labels`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A required pick during an import: a stray click on the scrim does not close the palette, only Escape or a choice — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the query: it shows the text outside and a command resets it; the palette clears it on close — `value`, `onValueChange`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: a button opens the palette and a command closes it — `open`, `onOpenChange`. |
+
+## Mistakes
+- An icon passed as a component (`as={Icon}`) → put the glyph inside `CommandMenu.ItemIcon`.
+- A hand-written `<kbd>` in items or the footer → `CommandMenu.ItemShortcut` / `CommandMenu.FooterHint`.
+- `CommandMenu.Group` with a separate heading element → pass the heading as `label`.
+- Items that differ only by an icon → give them distinct `value` texts; the query matches text, not icons.
+- No name for the dialog → add `CommandMenu.Title` (visually hidden if needed) or `aria-label`.
 
 ## Related
-
-- [Modal](../modal/COMPONENT.md) — dialog shell, focus trap, portal
-- [Badge](../badge/COMPONENT.md) — used inside **`FooterKeyBox`**
-- [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md) — triggers and links outside the palette
-- [Tag](../tag/COMPONENT.md) — common companion for **`TagRow`**
-- [Kbd](../kbd/COMPONENT.md) — shortcut hints in **`InputRow`** trailing slot
-- [Typography](../typography/COMPONENT.md) — titles, hints, footer copy
-- [Dropdown](../dropdown/COMPONENT.md), [Select](../select/COMPONENT.md) — non-modal single-choice lists
-
-## LLM note
-
-When generating or refactoring CommandMenu usage: import **`CommandMenu`** from **`prime-ui-kit`** only; do not reimplement modal, listbox, or filter logic. Always pass **`open`** / **`onOpenChange`** (or **`defaultOpen`**) on **`Dialog`**, put **`Input`** inside **`InputRow`** for standard chrome, and give **`Input`** an **`aria-label`** (or associated label). Every **`Item`** needs a **`value`** string (use **`""`** only when the row must stay visible for any query); add **`keywords`** for synonyms and path segments. Do not set **`disabled`** expecting a visible inactive row—those entries are removed from the palette; use conditional JSX or a non-**`Item`** hint if the UX must mention unavailable actions. For global palettes, document **`aria-labelledby`** + **`DialogTitle`** **`id`**. Mirror **`playground/snippets/command-menu/*`** and **`examples/*.tsx`** for density, controlled search, composition, wide panel, **`ItemIcon`**, keyboard shortcut + footer, file search, quick actions, and disabled / empty-value behavior.
+- **Built from:** [Modal](../modal/COMPONENT.md) (dialog, scrim, focus, Title / Description), [ScrollContainer](../scroll-container/COMPONENT.md) (`List`), [EmptyPage](../empty-page/COMPONENT.md) (`Empty`), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`, `FooterHint`)
+- **See also:** [Dropdown](../dropdown/COMPONENT.md), [Select](../select/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/src/components/command-menu/examples/controlled-open.tsx

@@ -0,0 +1,29 @@
+/** The parent owns the open state: a button opens the palette and a command closes it — `open`, `onOpenChange`. */
+import { Button, CommandMenu } from "prime-ui-kit";
+import * as React from "react";
+
+export default function CommandMenuControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Открыть команды
+      </Button.Root>
+      <CommandMenu.Root open={open} onOpenChange={setOpen} aria-label="Команды">
+        <CommandMenu.Input placeholder="Начните вводить" />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Команды">
+            <CommandMenu.Item value="новый проект" onSelect={() => setOpen(false)}>
+              Новый проект
+            </CommandMenu.Item>
+            <CommandMenu.Item value="закрыть палитру" onSelect={() => setOpen(false)}>
+              Закрыть палитру
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Root>
+    </>
+  );
+}

package/src/components/command-menu/examples/controlled.tsx

@@ -0,0 +1,42 @@
+/** The parent owns the query: it shows the text outside and a command resets it; the palette clears it on close — `value`, `onValueChange`. */
+import { Button, CommandMenu, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function CommandMenuControlledExample() {
+  const [open, setOpen] = React.useState(false);
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Найти отчёт
+      </Button.Root>
+      <Typography as="span" variant="body-s" tone="secondary">
+        Запрос: «{query || "…"}»
+      </Typography>
+      <CommandMenu.Root
+        open={open}
+        onOpenChange={setOpen}
+        value={query}
+        onValueChange={setQuery}
+        aria-label="Поиск по отчётам"
+      >
+        <CommandMenu.Input placeholder="Название отчёта" />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Отчёты">
+            <CommandMenu.Item value="выручка по месяцам">Выручка по месяцам</CommandMenu.Item>
+            <CommandMenu.Item value="воронка продаж">Воронка продаж</CommandMenu.Item>
+            <CommandMenu.Item
+              value="очистить запрос"
+              keywords="clear"
+              onSelect={() => setQuery("")}
+            >
+              Очистить запрос
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Root>
+    </>
+  );
+}

package/src/components/command-menu/examples/dismiss.tsx

@@ -0,0 +1,39 @@
+/** A required pick during an import: a stray click on the scrim does not close the palette, only Escape or a choice — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, CommandMenu } from "prime-ui-kit";
+import * as React from "react";
+
+const PROJECTS = ["Сайт компании", "Мобильное приложение", "Личный кабинет", "Платёжный шлюз"];
+
+export default function CommandMenuDismissExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root onClick={() => setOpen(true)}>Импортировать задачи</Button.Root>
+      <CommandMenu.Root
+        open={open}
+        onOpenChange={setOpen}
+        closeOnOutsideClick={false}
+        closeOnEscape
+        aria-label="Проект для импорта"
+      >
+        <CommandMenu.Input placeholder="Куда импортировать" />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Проекты">
+            {PROJECTS.map((project) => (
+              <CommandMenu.Item key={project} value={project} onSelect={() => setOpen(false)}>
+                {project}
+              </CommandMenu.Item>
+            ))}
+          </CommandMenu.Group>
+        </CommandMenu.List>
+        <CommandMenu.Footer>
+          <CommandMenu.FooterHint keys={["Esc"]}>
+            Закрыть — клик по фону не закрывает
+          </CommandMenu.FooterHint>
+        </CommandMenu.Footer>
+      </CommandMenu.Root>
+    </>
+  );
+}

package/src/components/command-menu/examples/overview.tsx

@@ -0,0 +1,61 @@
+/** A button or ⌘K opens the palette: the query filters the groups by value and keywords, Enter runs the active command — `CommandMenu.Item`, `keywords`. */
+import { Button, CommandMenu, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+export default function CommandMenuOverviewExample() {
+  const [open, setOpen] = React.useState(false);
+  const close = () => setOpen(false);
+
+  React.useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        setOpen((value) => !value);
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, []);
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Поиск по приложению · ⌘K
+      </Button.Root>
+      <CommandMenu.Root open={open} onOpenChange={setOpen} aria-label="Поиск по приложению">
+        <CommandMenu.Input placeholder="Попробуйте «отчёт» или «billing»" />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Страницы">
+            <CommandMenu.Item value="дашборд" keywords="home главная" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="nav.dashboard" />
+              </CommandMenu.ItemIcon>
+              Дашборд
+            </CommandMenu.Item>
+            <CommandMenu.Item value="отчёты" keywords="analytics аналитика" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.document" />
+              </CommandMenu.ItemIcon>
+              Отчёты
+            </CommandMenu.Item>
+            <CommandMenu.Item value="команда" keywords="people users" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.users" />
+              </CommandMenu.ItemIcon>
+              Команда
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group label="Настройки">
+            <CommandMenu.Item value="счета и оплата" keywords="billing invoices" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.receipt" />
+              </CommandMenu.ItemIcon>
+              Счета и оплата
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Root>
+    </>
+  );
+}

package/src/components/command-menu/examples/sizes.tsx

@@ -0,0 +1,53 @@
+/** Every size tier: rows, text, icons and the search row follow it; match the density of the app — `size`. */
+import { Button, CommandMenu, type ControlSize, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+const SIZES: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+
+const FILES = ["Договор поставки.pdf", "Счёт № 1042.pdf", "Акт сверки за сентябрь.pdf"];
+
+export default function CommandMenuSizesExample() {
+  const [open, setOpen] = React.useState(false);
+  const [size, setSize] = React.useState<ControlSize>("m");
+
+  return (
+    <>
+      {SIZES.map((tier) => (
+        <Button.Root
+          key={tier}
+          size={tier}
+          variant="soft"
+          tone="neutral"
+          onClick={() => {
+            setSize(tier);
+            setOpen(true);
+          }}
+        >
+          {tier}
+        </Button.Root>
+      ))}
+      <CommandMenu.Root
+        open={open}
+        onOpenChange={setOpen}
+        size={size}
+        aria-label="Поиск файлов"
+        labels={{ search: "Найти файл" }}
+      >
+        <CommandMenu.Input />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Файлы">
+            {FILES.map((file) => (
+              <CommandMenu.Item key={file} value={file} onSelect={() => setOpen(false)}>
+                <CommandMenu.ItemIcon>
+                  <Icon name="action.download" />
+                </CommandMenu.ItemIcon>
+                {file}
+              </CommandMenu.Item>
+            ))}
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Root>
+    </>
+  );
+}