prime-ui-kit 0.2.5 → 0.3.2

package/src/components/color-picker/COMPONENT.md

@@ -0,0 +1,171 @@
+# ColorPicker
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+`ColorPicker` is a **react-aria-components** color surface: one shared `Color` flows through a 2D area, channel sliders, optional preset swatches, a kit **HexInput**, and a channel strip with an eyedropper slot. **`ColorPicker.Root`** owns state; **`FormatProvider`** is mandatory for **`FormatSelect`** and **`ChannelStrip`**. **`parseColor`** and **`onChange`** use RAC **`Color`**; persist with **`color.toString("hex")`**, **`"css"`**, or **`"hexa"`** as needed.
+
+- **Use for:** theme/accent tuning, brand palettes, variant swatches, or any form field that stores a CSS-parseable color.
+- **Do not use for:** hex-only entry with no visual benefit (prefer [Input](../input/COMPONENT.md)); full chrome always inline in dense UI (mount the panel in [Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md), or [Drawer](../drawer/COMPONENT.md)); eyedropper as the only input path (it is absent without **`window.EyeDropper`**).
+
+Runnable TSX scenarios live in **`examples/`** (same folder as this file): `theme-accent.tsx`, `brand-kit.tsx`, `product-variant-swatch.tsx`, `controlled-form-field.tsx`, `minimal-popover.tsx`.
+
+## Extended
+
+### About
+
+The picker composes RAC primitives with kit styling (checkerboard for transparency on tracks/swatches). **`TriggerSwatch`** mirrors the live color for button triggers but is **`aria-hidden`**—name the control via visible label text or **`aria-label`**. Sliders are fixed at visual size **`m`**; only **`HexInput`** exposes the kit **`size`** axis (**`s`**–**`xl`**).
+
+### Scenarios
+
+| Scenario | Intent | Example file |
+|----------|--------|----------------|
+| **Theme accent** | Controlled value synced to design tokens or backend; show readout + popover editor. | `examples/theme-accent.tsx` |
+| **Brand kit** | Curated swatches plus free adjustment and hex field for design-system colors. | `examples/brand-kit.tsx` |
+| **Product variant swatch** | Fast selection from discrete SKUs; optional fine tuning in the same **`Root`**. | `examples/product-variant-swatch.tsx` |
+| **Controlled form field** | Parent owns **`value`/`onChange`**; label association + popover + **`HexInput`**. | `examples/controlled-form-field.tsx` |
+
+See also **`examples/minimal-popover.tsx`** for the smallest valid **`Popover`** composition.
+
+### Composition
+
+- **`ColorPicker.Root`** wraps every control that shares one color (trigger + panel). Keep **`TriggerSwatch`** under the same **`Root`** as the panel so the preview stays in sync.
+- Put the interactive surface (area, sliders, swatches, **`HexInput`**, **`ChannelStrip`**) inside **`Popover.Content`** (or modal/drawer) in product layouts; pair with [Button](../button/COMPONENT.md) + **`TriggerSwatch`** or an accessible trigger.
+- Wrap subtree that needs format switching or the strip in **`FormatProvider`** before **`FormatSelect`**, **`ChannelStrip`**, or strip-driven cells. **`FormatSelect`** returns **`null`** outside **`FormatProvider`**.
+- Typical panel order: **`FormatProvider`** → optional **`FormatSelect`** → **`Area`** + **`AreaThumb`** → **`Slider`** trees (**`SliderMeta`** optional, then **`SliderTrack`** → **`Thumb`**) → **`ChannelStrip`** (**`pipetteIcon`** required) → optional **`SwatchPicker`** / **`SwatchPickerItem`** / **`Swatch`** → optional **`HexInput`** or RAC **`Field`**.
+- **`EyeDropperButton`** is embedded in **`ChannelStrip`**; pass **`pipetteIcon`** (e.g. [Button.Icon](../button/COMPONENT.md) + icon). Standalone use is possible under the same **`Root`** with an explicit **`aria-label`** if needed.
+
+### Minimal example
+
+```tsx
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+
+export function MinimalColorField() {
+  return (
+    <ColorPicker.Root defaultValue="#3b82f6">
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Color
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <ColorPicker.FormatProvider>
+            <ColorPicker.FormatSelect />
+            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+              <ColorPicker.AreaThumb />
+            </ColorPicker.Area>
+            <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+          </ColorPicker.FormatProvider>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}
+```
+
+### Rules
+
+- **Controlled:** **`value`** + **`onChange`** when the parent owns color; **`defaultValue`** when uncontrolled. **`onChange`** receives **`Color`**.
+- Type with **`ColorPickerColorValue`** (re-export of RAC **`Color`**) or import **`Color`** from **`react-aria-components`**. Initialize **`useState`** from strings via **`parseColor`** from **`prime-ui-kit`** (**throws** on invalid strings).
+- **`children`** on **`Root`** may be a render function receiving **`ColorPickerRenderProps`** (`{ color }`).
+- There is **no** single **`isDisabled`** on **`Root`**—disable **`Area`**, **`Slider`**, **`SwatchPickerItem`**, or use a disabled **`fieldset`** where appropriate.
+- **`ChannelStrip`** must receive **`pipetteIcon`**. Without **`EyeDropper`**, the control is disabled and **`aria-hidden`**—do not rely on it alone.
+- **`FormatProvider`** sets initial strip mode via **`defaultFormat`**: **`"hsl"`** | **`"rgb"`** | **`"hex"`**.
+- **`HexInput`** and strip hex cells **revert** invalid input on blur/Enter; numeric strip cells **ignore** non-numeric commits.
+- **`SwatchPicker`** needs an accessible name (**`aria-label`** or associated label). Follow RAC for **`SwatchPicker`** / **`SwatchPickerItem`** selection props.
+- **`Area`**, **`Slider`**, **`Swatch`**, etc. use RAC prop surfaces (e.g. **`Area`**: **`colorSpace`**, **`xChannel`**, **`yChannel`**; **`Slider`**: **`channel`**, optional **`colorSpace`**, **`orientation`**, **`isDisabled`**).
+
+### API
+
+#### ColorPicker.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string \| Color` | — | No | Controlled color value |
+| defaultValue | `string \| Color` | — | No | Initial color when uncontrolled |
+| onChange | `(color: Color) => void` | — | No | Fires when any nested control changes the color |
+| children | `ReactNode \| (props: ColorPickerRenderProps) => ReactNode` | — | Yes | Pickers, triggers, and panels sharing state |
+| slot | `string \| null` | — | No | Slotted context name (RAC `SlotProps`) |
+| className | `string \| (values) => string` | — | No | Root element classes (RAC render props) |
+| …rest | RAC + DOM | — | No | Other **`ColorPickerRootProps`** / `AriaColorPickerProps` from react-aria-components |
+
+#### ColorPicker.FormatProvider
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `ReactNode` | — | Yes | Subtree that may use `FormatSelect` and `ChannelStrip` |
+| defaultFormat | `"hsl" \| "rgb" \| "hex"` | `"hsl"` | No | Initial format for the strip and format select |
+
+#### ColorPicker.FormatSelect
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the wrapper around the kit [Select](../select/COMPONENT.md) |
+
+Renders `null` when not under `FormatProvider`.
+
+#### ColorPicker.ChannelStrip
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| pipetteIcon | `ReactNode` | — | Yes | Icon for the embedded eyedropper ([Button.Icon](../button/COMPONENT.md) + icon) |
+| className | `string` | — | No | Class on the strip container |
+
+#### ColorPicker.HexInput
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Passed to kit [Input](../input/COMPONENT.md) |
+| label | `ReactNode` | `"Hex"` | No | Field label |
+| className | `string` | — | No | Class on `Input.Root` |
+
+#### ColorPicker.TriggerSwatch
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the preview square |
+
+#### ColorPicker.SliderMeta
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| label | `ReactNode` | — | Yes | Left label; current channel value on the right via `Output` |
+
+#### ColorPicker.EyeDropperButton
+
+Same props as **`Button.Root`** except **`variant`**, **`mode`**, and **`size`** are fixed (`neutral`, `stroke`, `m`). Forwarded ref: **`HTMLButtonElement`**. Children are usually **`Button.Icon`**.
+
+#### ColorPicker.Area, AreaThumb, Slider, SliderTrack, Thumb, Output, Field, SwatchPicker, SwatchPickerItem, Swatch
+
+Styled wrappers around matching **react-aria-components** primitives; use their RAC APIs. **`Swatch`** and **`SliderTrack`** add checkerboard layering for transparency in kit styles.
+
+#### `parseColor(value: string): Color`
+
+Parses a CSS color string into **`Color`**. **Throws** if parsing fails.
+
+Exported types: **`ColorPickerRootProps`**, **`ColorPickerHexInputProps`**, **`ColorPickerFormatProviderProps`**, **`ColorPickerTriggerSwatchProps`**, **`ColorValueFormat`**, **`ColorPickerRenderProps`**, **`ColorPickerColorValue`**.
+
+### Related
+
+- [Popover](../popover/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [Modal](../modal/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)
+
+## LLM note
+
+- Always place **`FormatProvider`** above **`FormatSelect`**, **`ChannelStrip`**, or any code path that calls into strip format context—missing provider throws at runtime.
+- **`ChannelStrip`** requires **`pipetteIcon`**; use a real icon node or a minimal **`<span aria-hidden />`** only for docs/tests.
+- **`TriggerSwatch`** is **`aria-hidden`**; the trigger **Button** (or other control) must expose the purpose via visible text or **`aria-label`**.
+- Controlled integration: **`value`** can be **`string | Color`**; **`onChange`** always yields **`Color`**—serialize with **`toString(...)`** for APIs expecting strings.
+- **`parseColor`** throws on bad input; guard user paste if you cannot tolerate exceptions.
+- Dense UIs: mount the picker body in **[Popover](../popover/COMPONENT.md)** / **[Modal](../modal/COMPONENT.md)** / **[Drawer](../drawer/COMPONENT.md)**, not inline in toolbars.
+- Do not assume **`EyeDropper`** exists; provide sliders, hex, or swatches as primary input paths.
+- For copy-paste recipes, start from **`examples/minimal-popover.tsx`** or the **Minimal example** above, then add sliders, **`SwatchPicker`**, or **`HexInput`** per scenario.

package/src/components/color-picker/examples/brand-kit.tsx

@@ -0,0 +1,48 @@
+import { Button, ColorPicker, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const BRAND_PRESETS = ["#0f172a", "#1d4ed8", "#0369a1", "#15803d", "#b45309", "#be123c"];
+
+/** Brand kit: fixed palette plus free adjustment — map presets to design tokens or CMS entries. */
+export function BrandKitExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <ColorPicker.Root defaultValue="#1d4ed8">
+      <Popover.Root onOpenChange={setOpen} open={open}>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Brand color
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <ColorPicker.FormatProvider>
+            <ColorPicker.FormatSelect />
+            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+              <ColorPicker.AreaThumb />
+            </ColorPicker.Area>
+            <ColorPicker.Slider channel="hue" colorSpace="hsl">
+              <ColorPicker.SliderMeta label="Hue" />
+              <ColorPicker.SliderTrack>
+                <ColorPicker.Thumb />
+              </ColorPicker.SliderTrack>
+            </ColorPicker.Slider>
+            <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+            <Typography.Root as="p" tone="muted" variant="body-small" weight="medium">
+              Brand presets
+            </Typography.Root>
+            <ColorPicker.SwatchPicker aria-label="Brand color presets">
+              {BRAND_PRESETS.map((c) => (
+                <ColorPicker.SwatchPickerItem color={c} key={c}>
+                  <ColorPicker.Swatch />
+                </ColorPicker.SwatchPickerItem>
+              ))}
+            </ColorPicker.SwatchPicker>
+            <ColorPicker.HexInput label="Hex" size="m" />
+          </ColorPicker.FormatProvider>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}

package/src/components/color-picker/examples/controlled-form-field.tsx

@@ -0,0 +1,40 @@
+import { Button, ColorPicker, Label, Popover, parseColor } from "prime-ui-kit";
+import * as React from "react";
+
+/** Form-friendly: parent owns string/Color state; popover for visual pick, HexInput for exact entry. */
+export function ControlledFormFieldExample() {
+  const [color, setColor] = React.useState(() => parseColor("#3b82f6"));
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div>
+      <Label.Root htmlFor="product-color-trigger" size="m">
+        Product color
+      </Label.Root>
+      <ColorPicker.Root onChange={setColor} value={color}>
+        <Popover.Root onOpenChange={setOpen} open={open}>
+          <Popover.Trigger asChild>
+            <Button.Root id="product-color-trigger" mode="stroke" size="m" variant="neutral">
+              <ColorPicker.TriggerSwatch />
+              Pick
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+            <ColorPicker.FormatProvider>
+              <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+                <ColorPicker.AreaThumb />
+              </ColorPicker.Area>
+              <ColorPicker.Slider channel="hue" colorSpace="hsl">
+                <ColorPicker.SliderTrack>
+                  <ColorPicker.Thumb />
+                </ColorPicker.SliderTrack>
+              </ColorPicker.Slider>
+              <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+            </ColorPicker.FormatProvider>
+          </Popover.Content>
+        </Popover.Root>
+        <ColorPicker.HexInput label="Hex value" size="m" />
+      </ColorPicker.Root>
+    </div>
+  );
+}

package/src/components/color-picker/examples/minimal-popover.tsx

@@ -0,0 +1,26 @@
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+
+/** Smallest valid popover field: matches the documented composition skeleton. */
+export function MinimalPopoverExample() {
+  return (
+    <ColorPicker.Root defaultValue="#3b82f6">
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Color
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <ColorPicker.FormatProvider>
+            <ColorPicker.FormatSelect />
+            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+              <ColorPicker.AreaThumb />
+            </ColorPicker.Area>
+            <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+          </ColorPicker.FormatProvider>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}

package/src/components/color-picker/examples/product-variant-swatch.tsx

@@ -0,0 +1,42 @@
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+const VARIANTS = [
+  { id: "midnight", color: "#0c0a09" },
+  { id: "clay", color: "#c2410c" },
+  { id: "sage", color: "#4d7c0f" },
+  { id: "mist", color: "#94a3b8" },
+];
+
+/** E-commerce variant color: fast swatch selection; optional fine tuning in the same root. */
+export function ProductVariantSwatchExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <ColorPicker.Root defaultValue={VARIANTS[0]?.color ?? "#000000"}>
+      <Popover.Root onOpenChange={setOpen} open={open}>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Color
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <ColorPicker.FormatProvider defaultFormat="hex">
+            <ColorPicker.SwatchPicker aria-label="Product color">
+              {VARIANTS.map((v) => (
+                <ColorPicker.SwatchPickerItem color={v.color} key={v.id}>
+                  <ColorPicker.Swatch />
+                </ColorPicker.SwatchPickerItem>
+              ))}
+            </ColorPicker.SwatchPicker>
+            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+              <ColorPicker.AreaThumb />
+            </ColorPicker.Area>
+            <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+          </ColorPicker.FormatProvider>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}

package/src/components/color-picker/examples/theme-accent.tsx

@@ -0,0 +1,46 @@
+import { Button, ColorPicker, Popover, parseColor, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/** Controlled accent: persist `color.toString("hex")` / `"css"` to your theme layer or API. */
+export function ThemeAccentExample() {
+  const [color, setColor] = React.useState(() => parseColor("hsl(220, 90%, 56%)"));
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div>
+      <Typography.Root as="p" variant="body-small" tone="muted">
+        Accent (CSS): {color.toString("css")}
+      </Typography.Root>
+      <ColorPicker.Root value={color} onChange={setColor}>
+        <Popover.Root onOpenChange={setOpen} open={open}>
+          <Popover.Trigger asChild>
+            <Button.Root
+              aria-label="Choose theme accent color"
+              mode="stroke"
+              size="m"
+              variant="neutral"
+            >
+              <ColorPicker.TriggerSwatch />
+              Accent
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+            <ColorPicker.FormatProvider>
+              <ColorPicker.FormatSelect />
+              <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+                <ColorPicker.AreaThumb />
+              </ColorPicker.Area>
+              <ColorPicker.Slider channel="hue" colorSpace="hsl">
+                <ColorPicker.SliderMeta label="Hue" />
+                <ColorPicker.SliderTrack>
+                  <ColorPicker.Thumb />
+                </ColorPicker.SliderTrack>
+              </ColorPicker.Slider>
+              <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
+            </ColorPicker.FormatProvider>
+          </Popover.Content>
+        </Popover.Root>
+      </ColorPicker.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,195 @@
+# CommandMenu
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+- **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.
+- **Examples (TSX):** [`examples/app-palette.tsx`](./examples/app-palette.tsx), [`examples/file-search.tsx`](./examples/file-search.tsx), [`examples/quick-actions.tsx`](./examples/quick-actions.tsx), [`examples/disabled-items.tsx`](./examples/disabled-items.tsx).
+
+## 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
+
+```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>
+  );
+}
+```
+
+### Scenario examples (source)
+
+| File | Scenario |
+|------|----------|
+| [examples/app-palette.tsx](./examples/app-palette.tsx) | Global app palette (pages + settings), ⌘K, footer key hints |
+| [examples/file-search.tsx](./examples/file-search.tsx) | File list: **`value`** / **`keywords`** for paths and tokens, **`ItemIcon`** |
+| [examples/quick-actions.tsx](./examples/quick-actions.tsx) | Contextual quick actions (clipboard, people) in groups |
+| [examples/disabled-items.tsx](./examples/disabled-items.tsx) | **`disabled`** excludes items from the list (not inactive rows) |
+
+Playground mirrors: `playground/snippets/command-menu/*`.
+
+### 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`**.
+
+## 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` |
+
+### CommandMenu.Input
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` (and other input value types) | — | 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`) |
+
+### 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`) |
+
+### CommandMenu.Group
+
+| 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 |
+
+### 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` |
+
+## 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; 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`**. Prefer the four **`examples/*.tsx`** files as structural templates (app routes, file picker, actions, disabled semantics).