prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/components/color-picker/examples/sizes.tsx

@@ -0,0 +1,26 @@
+/** Every size of the hex field with a swatch button of the same tier — `size`. */
+import { Button } from "prime-ui-kit";
+import { ColorPicker } from "prime-ui-kit/color-picker";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ColorPickerSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <ColorPicker.Root key={size} defaultValue="#0090ff">
+          <div className={styles.fieldRow}>
+            <ColorPicker.HexInput label={size} size={size} />
+            <Button.Root variant="soft" tone="neutral" size={size} aria-label="Открыть палитру">
+              <Button.Icon>
+                <ColorPicker.TriggerSwatch />
+              </Button.Icon>
+            </Button.Root>
+          </div>
+        </ColorPicker.Root>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/color-picker/examples/states.tsx

@@ -0,0 +1,22 @@
+/** A disabled area and hue slider keep showing the color but take no input — `disabled`. */
+import { ColorPicker } from "prime-ui-kit/color-picker";
+
+import styles from "./examples.module.css";
+
+export default function ColorPickerStatesExample() {
+  return (
+    <ColorPicker.Root defaultValue="#30a46c">
+      <ColorPicker.Panel className={styles.panel}>
+        <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness" disabled>
+          <ColorPicker.AreaThumb />
+        </ColorPicker.Area>
+        <ColorPicker.Slider channel="hue" colorSpace="hsl" disabled>
+          <ColorPicker.SliderMeta label="disabled" />
+          <ColorPicker.SliderTrack>
+            <ColorPicker.Thumb />
+          </ColorPicker.SliderTrack>
+        </ColorPicker.Slider>
+      </ColorPicker.Panel>
+    </ColorPicker.Root>
+  );
+}

package/dist/skill/reference/components/color-picker/examples/validation.tsx

@@ -0,0 +1,24 @@
+/** A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint under the other field, invalid text reverts on blur — `hint`, `error`. */
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+const MAX_LIGHTNESS = 80;
+
+export default function ColorPickerValidationExample() {
+  const [color, setColor] = React.useState(() => parseColor("#f5f5f5"));
+  const tooLight = color.toFormat("hsl").getChannelValue("lightness") > MAX_LIGHTNESS;
+
+  return (
+    <>
+      <ColorPicker.Root defaultValue="#0090ff">
+        <ColorPicker.HexInput label="Цвет ссылок" hint="Формат #RRGGBB или #RRGGBBAA" />
+      </ColorPicker.Root>
+      <ColorPicker.Root value={color} onValueChange={setColor}>
+        <ColorPicker.HexInput
+          label="Цвет кнопок"
+          error={tooLight ? "Слишком светлый: белый текст на нём не читается" : undefined}
+        />
+      </ColorPicker.Root>
+    </>
+  );
+}

package/dist/skill/reference/components/color-swatches/COMPONENT.md

@@ -0,0 +1,146 @@
+# ColorSwatches
+
+**Category:** selection
+**Kind:** control
+
+> An inline color choice: preset swatches that fill the width of a form or panel and wrap, without a popover.
+
+## When to use
+- Picking a color for an entity in a form or dialog (pipeline stage, tag, project, calendar).
+- The palette is short (up to ~20 presets) and the choice should be visible at once.
+- Settings pages where every option is shown inline.
+
+## When not to use
+- A compact color next to a field or in a dense list row (one trigger per row) → use [ColorPresets](../color-picker/COMPONENT.md) (trigger + popover palette).
+- A free color (any hex, eyedropper, channels) → use [ColorField](../color-field/COMPONENT.md) in a form, [ColorPicker](../color-picker/COMPONENT.md) for a panel of its own.
+- Choosing a mode or a value that is not a color → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Radio](../radio/COMPONENT.md).
+
+## Import
+```tsx
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+ColorSwatches                 field frame: label → swatches → hint | error
+└─ radiogroup                 swatches sharing the width, wrapping into rows
+   ├─ radio × presets         swatch button (color fill, faint inner ring, check when selected)
+   ├─ radio «Без цвета»       checkerboard swatch (`allowEmpty`)
+   └─ input[type=hidden]      submits the value (`name`)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ColorSwatches
+`ref` → `HTMLDivElement` (the field frame). The field frame (label → swatches → hint | error) around a `role="radiogroup"` of swatch buttons with a roving tab stop.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| null` | — | Controlled color; `null` — no color. |
+| `defaultValue` | `string \| null` | `null` | Initial color when uncontrolled. |
+| `onValueChange` | `(value: string \| null) => void` | — | Called with the preset `value` (as written in `presets`) or `null`. |
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches in order: `{ value, label }`; the label is the swatch's accessible name and tooltip. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the swatches (height 20 · 24 · 28 · 32 · 40); the label and hint keep the host tier. Without it the swatches take the host tier too. |
+| `label` | `ReactNode` | — | Label above the swatches; names the radiogroup (`aria-labelledby`). |
+| `required` | `boolean` | — | Red `*` after the label and `aria-required` on the group. |
+| `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the swatches. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | — | Danger inner edge on every swatch and `aria-invalid`. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disables every swatch (grey, half transparent). |
+| `allowEmpty` | `boolean` | `false` | Adds the «no color» checkerboard swatch after the presets (value `null`). |
+| `name` | `string` | — | Form field name: a hidden input submits the selected color (empty string for no color). |
+| `id` | `string` | — | Id of the radiogroup; hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-label` | `string` | — | Accessible name when there is no visible `label` (else `labels.group`). |
+| `aria-labelledby` | `string` | — | Names the group by an outside element. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `labels` | `Partial<ColorSwatchesLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | Swatch 20, gap 4, radius 4 | Dense side panels | |
+| `s` | Swatch 24, gap 8, radius 6 | Compact dialogs and popovers | |
+| `m` | Swatch 28, gap 8, radius 6 | Forms and modals | yes |
+| `l` | Swatch 32, gap 8, radius 8 | Spacious settings pages | |
+| `xl` | Swatch 40, gap 12, radius 8 | Touch-first layouts | |
+
+**Sizes:** `size` sets the swatches only; the label and the hint keep the tier of the form around (else `m`), so larger swatches never enlarge the label. Without `size` the swatches take the host tier: an `m` form gets `m` swatches (28) on the same 4px rhythm as `m` fields.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `allowEmpty` | an extra checkerboard swatch «Без цвета» at the end | the color is optional | `false` |
+| `invalid` | the inner edge of every swatch turns danger | the message is shown elsewhere; otherwise pass `error` | — |
+| `disabled` | every swatch grey at half opacity | the choice is unavailable | `false` |
+
+**Combinations**
+- Recommended: `label` + `name` inside a form; `allowEmpty` + `optional` for optional colors; `COLOR_PRESETS.slice(0, 8)` for one row of eight.
+- Avoid: more than ~24 presets (switch to ColorPicker); `required` together with `allowEmpty` (an empty choice cannot satisfy it).
+- The swatches are a field: they follow the field → field spacing (20) and never get their own card or border.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| selected | `value` / `defaultValue` | `aria-checked="true"`, `data-state="checked"` on the radio; the check mark (light or dark by color contrast) draws in and grows from 0.6 (`base` · emphasized) and retracts faster (`fast` · exit); no ring — the check is the selection |
+| hover | pointer | the swatch scales to 1.08 (fine pointers only) |
+| focus-visible | keyboard | focus ring outside the swatch |
+| invalid | `invalid` / `error` | `aria-invalid`, `data-invalid` on the group; the inner edge of every swatch turns `danger-border`; the control shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | `disabled` | native `disabled` on every radio, `data-disabled` on the group; the arrow keys do nothing |
+
+Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
+
+## Layout & spacing
+- The swatches take the container width in equal columns: each one stretches across its column (the height stays the tier's). A row wraps only when they no longer fit, and then the swatches split evenly over the rows (16 → 8 + 8, never 14 + 2); no column count to set. In a content-sized container they stand in one row at the tier size.
+- The keyboard focus ring sits outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the ring is never clipped. In your own `overflow` container, keep that padding.
+- Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Enters on the selected swatch (or the first one). |
+| `ArrowRight` · `ArrowLeft` | Moves to the next / previous swatch and selects it. |
+| `ArrowDown` · `ArrowUp` | Moves one visual row down / up and selects. |
+| `Home` · `End` | Jumps to the first / last swatch and selects it. |
+
+### ARIA
+- `role="radiogroup"` with one `role="radio"` button per swatch; the color name is the radio's name and `title`.
+- Named by `label`, `aria-labelledby`, `aria-label` or `labels.group`; the hint or the error is linked through `aria-describedby`.
+- The check mark is decorative; the selection is announced by `aria-checked`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `group` | `"Цвет"` | Accessible name of the group without a visible `label` and `aria-label`. |
+| `empty` | `"Без цвета"` | Name of the «no color» swatch (`allowEmpty`). |
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The kit palette inline under a field label, one color chosen — `label`, `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size: the swatch height 20 to 40 px with the tier gap, the label stays the form's — `size`. |
+| [states.tsx](examples/states.tsx) | A default palette next to an invalid and a disabled one — `invalid`, `disabled`. |
+| [wrapping.tsx](examples/wrapping.tsx) | In a narrow column the swatches wrap by themselves into even rows and the arrows move by the visual rows. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the color, «no color» included, and names it in the hint — `value`, `onValueChange`, `allowEmpty`. |
+| [in-form.tsx](examples/in-form.tsx) | A calendar event form: the color is submitted by `name` and required on save: submitting an empty title or no color shakes the field, picking or typing clears the error — `name`, `required`, `error`. |
+
+## Mistakes
+- `<ColorSwatches.Root>` → the component is a single export: `<ColorSwatches />`.
+- A visible heading next to the swatches made by hand → pass `label`.
+- Presets without names → every preset needs a `label`; it is the swatch's accessible name.
+- A larger `size` to make the swatches fill a wide field → they already fill it; `size` changes only their height.
+- Dozens of presets → use ColorPicker.
+
+## Related
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [ColorField](../color-field/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md) (`ColorPresets`, `ColorPicker.Swatches`), [Radio](../radio/COMPONENT.md)

package/dist/skill/reference/components/color-swatches/examples/controlled.tsx

@@ -0,0 +1,22 @@
+/** The parent owns the color, «no color» included, and names it in the hint — `value`, `onValueChange`, `allowEmpty`. */
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+import * as React from "react";
+
+const PRESETS = COLOR_PRESETS.slice(0, 8);
+
+export default function ColorSwatchesControlledExample() {
+  const [color, setColor] = React.useState<string | null>(null);
+  const name = PRESETS.find((preset) => preset.value === color)?.label ?? "без цвета";
+
+  return (
+    <ColorSwatches
+      label="Цвет метки"
+      optional
+      presets={PRESETS}
+      allowEmpty
+      value={color}
+      onValueChange={setColor}
+      hint={`Выбрано: ${name}`}
+    />
+  );
+}

package/dist/skill/reference/components/color-swatches/examples/examples.module.css

@@ -0,0 +1,19 @@
+/* Layout of the ColorSwatches scenarios: semantic tokens only. */
+
+/* in-form.tsx: field → field 20, group → actions 32. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.actions {
+  display: flex;
+  margin-top: var(--prime-space-3);
+}
+
+/* wrapping.tsx: a narrow column. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-16) * 3));
+}

package/dist/skill/reference/components/color-swatches/examples/in-form.tsx

@@ -0,0 +1,41 @@
+/** A calendar event form: the color is submitted by `name` and required on save: submitting an empty title or no color shakes the field, picking or typing clears the error — `name`, `required`, `error`. */
+import { Button, ColorSwatches, Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function ColorSwatchesInFormExample() {
+  const [titleError, setTitleError] = React.useState<string>();
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    setTitleError(String(data.get("title") ?? "").trim() ? undefined : "Введите название события");
+    setError(data.get("color") ? undefined : "Выберите цвет события");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Input.Root label="Название события" required error={titleError} reserveSupportRow>
+        <Input.Wrapper>
+          <Input.Field
+            name="title"
+            defaultValue="Встреча с поставщиком"
+            onValueChange={() => setTitleError(undefined)}
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <ColorSwatches
+        label="Цвет в календаре"
+        name="color"
+        required
+        error={error}
+        onValueChange={() => setError(undefined)}
+      />
+      <div className={styles.actions}>
+        <Button.Root type="submit">Сохранить</Button.Root>
+      </div>
+    </form>
+  );
+}

package/dist/skill/reference/components/color-swatches/examples/overview.tsx

@@ -0,0 +1,6 @@
+/** The kit palette inline under a field label, one color chosen — `label`, `defaultValue`. */
+import { ColorSwatches } from "prime-ui-kit";
+
+export default function ColorSwatchesOverviewExample() {
+  return <ColorSwatches label="Цвет проекта" defaultValue="#5068f5" />;
+}

package/dist/skill/reference/components/color-swatches/examples/sizes.tsx

@@ -0,0 +1,19 @@
+/** Every size: the swatch height 20 to 40 px with the tier gap, the label stays the form's — `size`. */
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+const PRESETS = COLOR_PRESETS.slice(0, 6);
+
+export default function ColorSwatchesSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <div>
+            <ColorSwatches size={size} label={size} presets={PRESETS} defaultValue="#5068f5" />
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/color-swatches/examples/states.tsx

@@ -0,0 +1,20 @@
+/** A default palette next to an invalid and a disabled one — `invalid`, `disabled`. */
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+
+const PRESETS = COLOR_PRESETS.slice(0, 6);
+
+export default function ColorSwatchesStatesExample() {
+  return (
+    <div>
+      <div>
+        <ColorSwatches label="default" presets={PRESETS} defaultValue="#22c55e" />
+      </div>
+      <div>
+        <ColorSwatches label="invalid" presets={PRESETS} defaultValue="#22c55e" invalid />
+      </div>
+      <div>
+        <ColorSwatches label="disabled" presets={PRESETS} defaultValue="#22c55e" disabled />
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/color-swatches/examples/wrapping.tsx

@@ -0,0 +1,12 @@
+/** In a narrow column the swatches wrap by themselves into even rows and the arrows move by the visual rows. */
+import { ColorSwatches } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ColorSwatchesWrappingExample() {
+  return (
+    <div className={styles.narrow}>
+      <ColorSwatches label="Цвет этапа" defaultValue="#14b8a6" />
+    </div>
+  );
+}

package/dist/skill/reference/components/command-menu/COMPONENT.md

@@ -0,0 +1,225 @@
+# CommandMenu
+
+**Category:** overlays
+**Kind:** overlay
+
+> A search palette over the page: the query filters commands and pages, Enter runs the active one.
+
+## 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.
+- Searching records on the server (orders, clients, invoices): `search` / `onSearchChange`, `filter={false}`, `loading`, `hasMore` + `onLoadMore`, `loadError` + `onRetry`.
+
+## 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 { CommandMenu } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+CommandMenu.Root                 Modal + top-aligned palette panel, query and load 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; skeleton rows while loading / loading more
+│   ├── CommandMenu.Empty        compact EmptyPage while nothing matches; may hold a CommandMenu.Item
+│   └── 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
+├── load error                   after the List: compact EmptyPage, role="alert", retry Button
+└── CommandMenu.Footer           key hints, hairline above
+    └── CommandMenu.FooterHint   Kbd per key + label
+```
+
+## API
+
+<!-- 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), the active item (a new opening starts empty, focus in the search field) and the load state of server results.
+
+| 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. |
+| `search` | `string` | — | Controlled query; the list filters by it. Together with `onSearchChange`. |
+| `defaultSearch` | `string` | `""` | Initial query, uncontrolled. |
+| `onSearchChange` | `(search: string) => void` | — | Called with the new query: typing, and `""` when the palette closes. Load the matching results here for a server search. |
+| `filter` | `boolean` | `true` | The palette filters its items by the query. `false` when the results come from a server: every item shows, the query is still marked in the labels. |
+| `loading` | `boolean` | `false` | Results are loading: skeleton rows in the list while no item matches (items already on screen stay), `aria-busy`. |
+| `loadingMore` | `boolean` | `false` | More results are loading at the end: skeleton rows after the items. |
+| `hasMore` | `boolean` | `false` | More results exist: reaching the end of the list calls `onLoadMore`. |
+| `onLoadMore` | `() => void \| Promise<void>` | — | Called once per round with `hasMore` when the end of the list scrolls into view or the arrows reach the last item; set `loadingMore` while it runs. |
+| `loadError` | `ReactNode` | — | The results failed to load: the message replaces the list in `role="alert"`. |
+| `onRetry` | `() => void \| Promise<void>` | — | A retry button (`labels.retry`) under `loadError`; Enter in the search field runs it too. Return the request's promise to keep the button loading until it settles. |
+| `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, showing `CommandMenu.Root` `search`; takes focus on open. + native input props except `value` / `defaultValue`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `placeholder` | `string` | `labels.search` | Placeholder; also the default accessible name comes from `labels.search`. |
+
+### CommandMenu.List
+`ref` → `HTMLElement`. The scrolling `role="listbox"` under the search row; draws the load states of Root: skeleton rows, more rows loading at the end, the error with a retry. + 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 | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+
+### CommandMenu.Item
+`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>`). The `aria-hidden` leading glyph / a `Kbd` key hint at 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 (`role="status"`) shown while nothing matches and nothing loads: `labels.empty`, `labels.emptyHint`, and `children` as an action — a button or a `CommandMenu.Item`.
+
+### 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: the floating layer of the ladder (it is a Modal), `--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` |
+| `filter={false}` | every item shows whatever the query; the query is still marked in the labels | The owner searches on the server (`search`, `onSearchChange`) | `true` |
+| `loading` | skeleton rows in the item geometry while no item is on screen; items on screen stay | Results load asynchronously | `false` |
+| `loadingMore` | skeleton rows after the items | The next page is loading (`hasMore` + `onLoadMore`) | `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. A server search: `search` / `onSearchChange` + `filter={false}` + `loading`; paging adds `hasMore`, `loadingMore`, `onLoadMore`; a failed request `loadError` + `onRetry`. A «create from the query» action is a `CommandMenu.Item` inside `CommandMenu.Empty`: it shows only while nothing matches, the arrows and Enter reach it, and it never counts as a match.
+
+## 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"`; hidden while loading or after a load error. A `CommandMenu.Item` inside it (create from the query) is reached by the arrows and Enter and never counts as a match |
+| query | `search` / `defaultSearch` / `onSearchChange` on Root | the search field's value; cleared when the palette closes |
+| loading | `loading` | `aria-busy` on the list and the field; with no item on screen, `aria-hidden` skeleton rows (`data-skeleton`); `labels.loading` in a polite live region |
+| loading more | `loadingMore` | skeleton rows after the items; the end of the list is watched while `hasMore` (`onLoadMore` once per batch) |
+| load error | `loadError` | the list is `hidden`; a compact EmptyPage with `role="alert"` and a retry Button (`onRetry`) |
+| retrying | `onRetry` returned a pending promise | the retry Button is `loading` (`aria-busy`); a press or Enter does not retry again until it settles; on resolve clear `loadError` and the results swap in; on reject the error stays and the button is ready again |
+| state swap | loading ↔ items ↔ load error | the new content fades in (`swapMotion`), the first render stays still |
+| 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.
+- `CommandMenu.ItemIcon` holds the glyph at the tier icon size; `CommandMenu.ItemShortcut` is a `Kbd` one tier below, pushed to the end of the item.
+- 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; with a load error, retries (`onRetry`). |
+| `Tab` | With a load error, moves focus to the retry button. |
+| `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 search field takes focus on open and has no focus ring: the caret is the indicator. Its `onChange`, `onKeyDown`, `onFocus` and `onBlur` reach the input.
+- 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"`.
+- While loading the list and the field are `aria-busy` and `labels.loading` is announced politely; skeleton rows are hidden from screen readers; a load error is `role="alert"`.
+- The arrows reaching the last item ask for the next batch the same way scrolling does.
+- 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. |
+| `loading` | `"Загрузка…"` | Announced while `loading` or `loadingMore`. |
+| `retry` | `"Повторить"` | The retry button under `loadError` (`onRetry`). |
+
+## 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`. |
+| [server-search.tsx](examples/server-search.tsx) | Orders searched on the server: the parent loads results for the query and the next page at the end of the list; with nothing found the palette offers to create an order — `search`, `onSearchChange`, `filter`, `loading`, `hasMore`, `loadingMore`, `onLoadMore`, `CommandMenu.Empty`. |
+| [load-error.tsx](examples/load-error.tsx) | The results failed to load: the palette says so instead of the list, and a retry asks again with the button loading until the server answers; the first retry fails too, the second brings the results — `loadError`, `onRetry`. |
+| [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 — `search`, `onSearchChange`. |
+| [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`.
+- Server results squeezed through `keywords` so the kit filter keeps them → set `filter={false}`.
+- A hand-drawn spinner or «Загрузка…» item → set `loading` (skeleton rows) and `loadingMore`.
+- A «Создать …» action placed beside the results with a hand-made visibility check → put it in `CommandMenu.Empty` as a `CommandMenu.Item`.
+
+## Related
+- **Built from:** [Modal](../modal/COMPONENT.md) (dialog, scrim, focus, Title / Description), [ScrollContainer](../scroll-container/COMPONENT.md) (`List`), [EmptyPage](../empty-page/COMPONENT.md) (`Empty`, load error), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [Button](../button/COMPONENT.md) (retry), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`, `FooterHint`), `Icon` (search glyph, retry)
+- **See also:** [Dropdown](../dropdown/COMPONENT.md), [Select](../select/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/dist/skill/reference/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>
+    </>
+  );
+}