prime-ui-kit 0.15.0 → 0.16.0

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

@@ -1,31 +1,36 @@
 /** A disabled area, hue slider and preset trigger keep showing the color but take no input — `disabled`. */
-import { ColorPresets } from "prime-ui-kit";
+import { ColorPresets, Typography } from "prime-ui-kit";
 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>
+    <div>
+      <div>
+        <ColorPicker.Root defaultValue="#30a46c">
+          <ColorPicker.Panel>
+            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness" disabled>
               <ColorPicker.Thumb />
-            </ColorPicker.SliderTrack>
-          </ColorPicker.Slider>
-        </ColorPicker.Panel>
-      </ColorPicker.Root>
-      <ColorPresets.Root disabled defaultValue="#22c55e" labels={{ trigger: "Цвет метки" }}>
-        <ColorPresets.Trigger>
-          <ColorPresets.SwatchButton />
-        </ColorPresets.Trigger>
-        <ColorPresets.Content />
-      </ColorPresets.Root>
-    </>
+            </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>
+      </div>
+      <div>
+        <ColorPresets.Root disabled defaultValue="#22c55e" labels={{ trigger: "Цвет метки" }}>
+          <ColorPresets.Trigger>
+            <ColorPresets.SwatchButton />
+          </ColorPresets.Trigger>
+          <ColorPresets.Content />
+        </ColorPresets.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+    </div>
   );
 }

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

@@ -38,11 +38,13 @@ ColorSwatches                 field frame: label → swatches → hint | error
 
 | 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. |
+| `mode` | `"color" \| "palette"` | `"color"` | `color` — any CSS color from `presets`; `palette` — a kit palette hue (`PaletteColor`) from `palette`, drawn from its solid step in both themes. |
+| `value` | `string \| null · PaletteColor \| null` | — | Controlled color (a hue with `palette`); `null` — no color. |
+| `defaultValue` | `string \| null · PaletteColor \| null` | `null` | Initial color when uncontrolled. |
+| `onValueChange` | `(value: string \| null) => void · (value: PaletteColor \| null) => void` | — | Called with the preset `value` (as written in `presets`), the hue with `palette`, or `null`. |
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | `color` mode: swatches in order, `{ value, label }`; the label is the swatch's accessible name and tooltip. |
+| `palette` | `readonly PaletteColor[]` | every hue | `palette` mode: the hues in order; each is named by `labels.colorNames`. |
+| `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`). |
@@ -72,6 +74,12 @@ ColorSwatches                 field frame: label → swatches → hint | error
 
 **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.
 
+### mode
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `color` | the `presets` as CSS colors; the value is the preset `value` | any color: a brand, a calendar event | yes |
+| `palette` | the kit hues (`palette`) from their solid step, the check in the hue's own foreground; the value is the hue name | a color the kit draws elsewhere: a Badge, a Kanban column, a tag | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -98,12 +106,14 @@ 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.
 - On a coarse pointer the swatches grow to the 44 px touch target (a dense grid cannot grow an invisible hit area past its neighbours) and wrap into more rows.
-- 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.
+- The keyboard focus ring sits outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep room for it, so the ring is never clipped. In your own clipping container, keep the same room.
 - Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Enters on the selected swatch (or the first one). |
@@ -112,6 +122,8 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 | `Home` · `End` | Jumps to the first / last swatch and selects it. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `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`.
@@ -124,6 +136,7 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 | `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`. |
+| `colorNames` | `"Серый · Красный · Оранжевый · Жёлтый · Зелёный · Бирюзовый · Голубой · Синий · Фиолетовый · Розовый"` | Names of the palette hues (`mode="palette"`), by `PaletteColor` key; merges by key. |
 
 ## Examples
 | Example | Shows |
@@ -131,7 +144,8 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 | [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. |
+| [wrapping.tsx](examples/wrapping.tsx) | Twelve stage colors in a narrow column wrap by themselves into even rows, and the arrows move by the visual rows — `presets`. |
+| [palette.tsx](examples/palette.tsx) | A pipeline stage takes a kit palette hue, so its badge and column read the same in both themes — `mode`, `palette`. |
 | [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`. |
 
@@ -143,5 +157,5 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 - Dozens of presets → use ColorPicker.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **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/examples.module.css

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

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

@@ -1,5 +1,5 @@
 /** 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 { Button, ColorSwatches, Fieldset, Input } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -17,22 +17,24 @@ export default function ColorSwatchesInFormExample() {
 
   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)}
-      />
+      <Fieldset>
+        <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)}
+        />
+      </Fieldset>
       <div className={styles.actions}>
         <Button.Root type="submit">Сохранить</Button.Root>
       </div>

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

@@ -0,0 +1,24 @@
+/** A pipeline stage takes a kit palette hue, so its badge and column read the same in both themes — `mode`, `palette`. */
+import { Badge, ColorSwatches, type PaletteColor } from "prime-ui-kit";
+import * as React from "react";
+
+const STAGE_HUES: PaletteColor[] = ["gray", "blue", "teal", "green", "yellow", "orange", "red"];
+
+export default function ColorSwatchesPaletteExample() {
+  const [hue, setHue] = React.useState<PaletteColor | null>("teal");
+
+  return (
+    <>
+      <ColorSwatches
+        mode="palette"
+        label="Цвет этапа «Переговоры»"
+        palette={STAGE_HUES}
+        value={hue}
+        onValueChange={setHue}
+      />
+      <div>
+        <Badge.Root color={hue ?? "gray"}>Переговоры</Badge.Root>
+      </div>
+    </>
+  );
+}

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

@@ -1,12 +1,27 @@
-/** In a narrow column the swatches wrap by themselves into even rows and the arrows move by the visual rows. */
+/** Twelve stage colors in a narrow column wrap by themselves into even rows, and the arrows move by the visual rows — `presets`. */
 import { ColorSwatches } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
+const STAGE_COLORS = [
+  { value: "#ef4444", label: "Красный" },
+  { value: "#f97316", label: "Оранжевый" },
+  { value: "#eab308", label: "Жёлтый" },
+  { value: "#22c55e", label: "Зелёный" },
+  { value: "#14b8a6", label: "Бирюзовый" },
+  { value: "#5068f5", label: "Синий" },
+  { value: "#b91c1c", label: "Тёмно-красный" },
+  { value: "#c2410c", label: "Тёмно-оранжевый" },
+  { value: "#a16207", label: "Горчичный" },
+  { value: "#15803d", label: "Тёмно-зелёный" },
+  { value: "#0f766e", label: "Тёмно-бирюзовый" },
+  { value: "#2f4ae0", label: "Тёмно-синий" },
+];
+
 export default function ColorSwatchesWrappingExample() {
   return (
     <div className={styles.narrow}>
-      <ColorSwatches label="Цвет этапа" defaultValue="#14b8a6" />
+      <ColorSwatches label="Цвет этапа" presets={STAGE_COLORS} defaultValue="#14b8a6" />
     </div>
   );
 }

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

@@ -64,65 +64,101 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query and lo
 | `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. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the rows and the search row: item height, text, icon. Without it the tier of the host it opens from, else `m`. |
 | `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`.
+`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` / `<p>` above the search row; they name and describe the dialog.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `children`, `className` and the other attributes 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`.
+`ref` → `HTMLInputElement`. The search row: a search icon and `<input role="combobox">` controlling the list, showing `CommandMenu.Root` `search`; takes focus on open.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `placeholder` | `string` | `labels.search` | Placeholder; also the default accessible name comes from `labels.search`. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "size" \| "type" \| "role" \| "value" \| "defaultValue">` | — | `className` and the other input attributes except `value` / `defaultValue`. |
 
 ### 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.
+`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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "role" \| "id">` | — | `children`, `className` and the other attributes. |
 
 ### CommandMenu.Group
-`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while none of its items match. + native `<div>` props.
+`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while none of its items match.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children`, `className` and the other div attributes. |
 
 ### CommandMenu.Item
-`ref` → `HTMLButtonElement`. `<button role="option">`; the active item has `aria-selected` and the highlight fill. + native button props.
+`ref` → `HTMLButtonElement`. `<button role="option">`; the active item has `aria-selected` and the highlight fill.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | — (required) | Text matched against the query together with `keywords`. |
+| `value` | `string` | — (required) | Text matched against the query together with `keywords`. With `""` the item shows only while the query is empty or `keywords` match. |
 | `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. |
 | `persistent` | `boolean` | `false` | Shown whatever the query and never counted as a match (`CommandMenu.Empty` still shows); the arrows reach it after the matches. One «create from the query» item at the end of the list. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "role" \| "id" \| "onSelect">` | — | `children`, `className` and the other button attributes. |
 
-### 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.ItemIcon
+`ref` → `HTMLSpanElement`. The `aria-hidden` leading glyph of the item.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the `Icon`), `className` and the other span attributes. |
+
+### CommandMenu.ItemShortcut
+`ref` → `HTMLElement` (the `<kbd>`). A `Kbd` key hint at the end of the item — a hint, not a handler.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The keys («⌘K»). |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children">` | — | `className` and the other attributes. |
 
 ### CommandMenu.ItemText
-`ref` → `HTMLSpanElement`. A `<span>` column: the title with an ellipsis and an optional description line. + native `<span>` props.
+`ref` → `HTMLSpanElement`. A `<span>` column: the title with an ellipsis and an optional description line.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `description` | `ReactNode` | — | Second line (path, details): caption, muted. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the title), `className` and the other span attributes. |
 
 ### CommandMenu.Empty
 `ref` → `HTMLDivElement`. A compact EmptyPage (`role="status"`) shown while nothing matches and nothing loads: `labels.empty` and `labels.emptyHint`, text only. An action for the query is a `persistent` `CommandMenu.Item` at the end of the list.
 
-### 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 |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role" \| "children">` | — | `className` and the other div attributes. |
+
+### CommandMenu.Footer
+`ref` → `HTMLDivElement`. A bottom row of `CommandMenu.FooterHint`s with a hairline above.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### CommandMenu.FooterHint
+`ref` → `HTMLSpanElement`. One hint: every entry of `keys` in its own `Kbd`, then the label (`children`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `keys` | `ReactNode[]` | — (required) | FooterHint: the keys (text or icons). |
+| `keys` | `ReactNode[]` | — (required) | The keys (text or icons). |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the label), `className` and the other span attributes. |
 
 ## 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.
+One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radius`, `shadow-modal`, the width of a Modal of size `l`, placed in the top part of the viewport (`placement="top"`) so the search row never jumps while the list filters.
 
 ### size (Root)
 | Value | Looks like | Use when | Default |
@@ -137,11 +173,11 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | 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` |
+| `filter` | items filter by the query; off, every item shows whatever the query and the query is still marked in the labels | Off when 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 | |
+| `closeOnOutsideClick` | a click on the scrim closes it; off, the scrim does not | Off for a required pick | `true` |
+| `closeOnEscape` | Escape closes it; off, Escape does nothing | Off for a required pick that must not be skipped | `true` |
 
 **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`. Creating from the query is ONE `persistent` `CommandMenu.Item` at the end of the List («Создать клиента «{query}»», rendered while the query is not empty): it stays when a namesake matches (the query may be a new client of the same name), it never counts as a match, and the arrows reach it after the matches; while nothing matches it is the active item, so Enter runs it. `CommandMenu.Empty` then holds only the text — never put the action in both places.
 
@@ -164,7 +200,7 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | 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.
+- The width of a Modal of size `l`; the list is at most 1.5 × `--prime-panel-max-height` tall and only it 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.
@@ -172,6 +208,8 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowDown` · `ArrowUp` | Move the active item, wrapping; focus stays in the search field. |
@@ -181,6 +219,8 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | `Escape` | Closes the palette (`closeOnEscape`); focus returns to the opener. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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`.
@@ -206,7 +246,7 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | [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`. |
+| [states.tsx](examples/states.tsx) | The palette while its first results load, with a disabled item that stays muted and is skipped by the arrows, and with an empty result in the words of the task — `loading`, `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; one persistent item at the end creates an order from the query, found or not — `search`, `onSearchChange`, `filter`, `loading`, `hasMore`, `loadingMore`, `onLoadMore`, `persistent`. |
 | [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`. |
@@ -225,5 +265,5 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 - The create action both in `CommandMenu.Empty` and in the list → one `persistent` item; `Empty` holds only the text.
 
 ## 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)
+- **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), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Dropdown](../dropdown/COMPONENT.md), [Select](../select/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/dist/skill/reference/components/command-menu/examples/sizes.tsx

@@ -1,5 +1,5 @@
 /** 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 { Button, CommandMenu, type ControlSize, Icon, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 const SIZES: ControlSize[] = ["xs", "s", "m", "l", "xl"];
@@ -12,20 +12,25 @@ export default function CommandMenuSizesExample() {
 
   return (
     <>
-      {SIZES.map((tier) => (
-        <Button.Root
-          key={tier}
-          size={tier}
-          variant="soft"
-          tone="neutral"
-          onClick={() => {
-            setSize(tier);
-            setOpen(true);
-          }}
-        >
-          {tier}
-        </Button.Root>
-      ))}
+      <div>
+        {SIZES.map((tier) => (
+          <div key={tier}>
+            <Button.Root
+              variant="soft"
+              tone="neutral"
+              onClick={() => {
+                setSize(tier);
+                setOpen(true);
+              }}
+            >
+              Найти файл
+            </Button.Root>
+            <Typography as="span" variant="caption" tone="muted">
+              {tier}
+            </Typography>
+          </div>
+        ))}
+      </div>
       <CommandMenu.Root
         open={open}
         onOpenChange={setOpen}

package/dist/skill/reference/components/command-menu/examples/states.tsx

@@ -1,46 +1,68 @@
-/** 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`. */
-import { Button, CommandMenu } from "prime-ui-kit";
+/** The palette while its first results load, with a disabled item that stays muted and is skipped by the arrows, and with an empty result in the words of the task — `loading`, `disabled`, `labels`. */
+import { Button, CommandMenu, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-const CITIES = [
-  "Москва",
-  "Санкт-Петербург",
-  "Новосибирск",
-  "Екатеринбург",
-  "Казань",
-  "Нижний Новгород",
-  "Самара",
-  "Краснодар",
-];
+type PaletteState = "loading" | "disabled" | "labels.empty";
+
+const STATES: PaletteState[] = ["loading", "disabled", "labels.empty"];
+
+const CITIES = ["Москва", "Санкт-Петербург", "Новосибирск", "Екатеринбург", "Казань", "Самара"];
+
+/** A city with no warehouse: the empty state opens on it. */
+const NO_WAREHOUSE_QUERY = "Владивосток";
 
 export default function CommandMenuStatesExample() {
   const [open, setOpen] = React.useState(false);
+  const [state, setState] = React.useState<PaletteState>("disabled");
+  const [search, setSearch] = React.useState("");
   const close = () => setOpen(false);
 
   return (
     <>
-      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
-        Выбрать склад
-      </Button.Root>
+      <div>
+        {STATES.map((item) => (
+          <div key={item}>
+            <Button.Root
+              variant="soft"
+              tone="neutral"
+              onClick={() => {
+                setState(item);
+                setSearch(item === "labels.empty" ? NO_WAREHOUSE_QUERY : "");
+                setOpen(true);
+              }}
+            >
+              Выбрать склад
+            </Button.Root>
+            <Typography as="span" variant="caption" tone="muted">
+              {item}
+            </Typography>
+          </div>
+        ))}
+      </div>
       <CommandMenu.Root
         open={open}
         onOpenChange={setOpen}
+        search={search}
+        onSearchChange={setSearch}
+        loading={state === "loading"}
         aria-label="Выбор склада"
         labels={{ empty: "Склад не найден", emptyHint: "В этом городе склада пока нет" }}
       >
         <CommandMenu.Input placeholder="Город склада" />
         <CommandMenu.List>
           <CommandMenu.Empty />
-          <CommandMenu.Group label="Склады">
-            {CITIES.map((city) => (
-              <CommandMenu.Item key={city} value={city} onSelect={close}>
-                {city}
+          {state === "loading" ? null : (
+            <CommandMenu.Group label="Склады">
+              {CITIES.map((city) => (
+                <CommandMenu.Item key={city} value={city} onSelect={close}>
+                  {city}
+                </CommandMenu.Item>
+              ))}
+              <CommandMenu.Item value="Калининград" disabled onSelect={close}>
+                Калининград — на ремонте
               </CommandMenu.Item>
-            ))}
-            <CommandMenu.Item value="Калининград" disabled onSelect={close}>
-              Калининград — на ремонте
-            </CommandMenu.Item>
-          </CommandMenu.Group>
+            </CommandMenu.Group>
+          )}
         </CommandMenu.List>
       </CommandMenu.Root>
     </>