prime-ui-kit 0.3.2 → 0.4.0

package/src/components/color-picker/examples/field-eyedropper.tsx

@@ -0,0 +1,58 @@
+import { Pipette } from "lucide-react";
+import { Button, ColorPicker, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+import { Input as RacInput } from "react-aria-components";
+
+/** RAC `ColorPicker.Field` + `EyeDropperButton`, area and hue slider (playground `features`). */
+export function FieldEyedropperExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <ColorPicker.Root defaultValue="hsl(340, 82%, 52%)">
+      <Popover.Root onOpenChange={setOpen} open={open}>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Field + eyedropper
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <div style={{ width: "19.5rem", maxWidth: "100%", minWidth: 0 }}>
+            <ColorPicker.FormatProvider>
+              <Typography.Root as="p" tone="muted" variant="body-small" weight="medium">
+                Hex via ColorField + RAC Input; eyedropper uses Web API when available.
+              </Typography.Root>
+              <div
+                style={{
+                  display: "flex",
+                  alignItems: "flex-start",
+                  gap: "var(--prime-sys-spacing-x2, 0.5rem)",
+                }}
+              >
+                <div style={{ flex: 1, minWidth: 0 }}>
+                  <ColorPicker.Field aria-label="Hex color code">
+                    <RacInput />
+                  </ColorPicker.Field>
+                </div>
+                <ColorPicker.EyeDropperButton aria-label="Eyedropper">
+                  <Button.Icon>
+                    <Pipette aria-hidden size={18} strokeWidth={1.75} />
+                  </Button.Icon>
+                </ColorPicker.EyeDropperButton>
+              </div>
+              <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.FormatProvider>
+          </div>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}

package/src/components/color-picker/examples/format-variants.tsx

@@ -0,0 +1,58 @@
+import { Pipette } from "lucide-react";
+import { Button, ColorPicker, type ColorValueFormat, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+function FormatPopover({
+  title,
+  defaultFormat,
+}: {
+  title: string;
+  defaultFormat: ColorValueFormat;
+}) {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", minWidth: 0, flexDirection: "column", gap: "0.5rem" }}>
+      <Typography.Root as="p" variant="body-small" weight="medium">
+        {title}
+      </Typography.Root>
+      <ColorPicker.Root defaultValue="hsl(200, 75%, 52%)">
+        <Popover.Root onOpenChange={setOpen} open={open}>
+          <Popover.Trigger asChild>
+            <Button.Root mode="stroke" size="m" variant="neutral">
+              <ColorPicker.TriggerSwatch />
+              Open ({defaultFormat.toUpperCase()})
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+            <ColorPicker.FormatProvider defaultFormat={defaultFormat}>
+              <ColorPicker.FormatSelect />
+              <ColorPicker.ChannelStrip
+                pipetteIcon={<Pipette aria-hidden size={18} strokeWidth={1.75} />}
+              />
+            </ColorPicker.FormatProvider>
+          </Popover.Content>
+        </Popover.Root>
+      </ColorPicker.Root>
+    </div>
+  );
+}
+
+/** Three `FormatProvider` defaults: HSL, RGB, hex channel strip (playground `format-variants`). */
+export function FormatVariantsExample() {
+  return (
+    <div
+      style={{
+        display: "grid",
+        width: "100%",
+        maxWidth: "100%",
+        gap: "1rem",
+        gridTemplateColumns: "repeat(auto-fit, minmax(12rem, 1fr))",
+      }}
+    >
+      <FormatPopover defaultFormat="hsl" title="HSL channels + alpha" />
+      <FormatPopover defaultFormat="rgb" title="RGB channels + alpha" />
+      <FormatPopover defaultFormat="hex" title="Hex #RRGGBB" />
+    </div>
+  );
+}

package/src/components/color-picker/examples/full-width.tsx

@@ -0,0 +1,49 @@
+import { Pipette } from "lucide-react";
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+/** Wide `Popover.Content` and inner surface stretched to full width (playground `full-width`). */
+export function FullWidthPanelExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <ColorPicker.Root defaultValue="hsl(30, 85%, 52%)">
+      <Popover.Root onOpenChange={setOpen} open={open}>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            <ColorPicker.TriggerSwatch />
+            Full-width panel
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <div style={{ minWidth: "min(100vw - 2rem, 28rem)" }}>
+            <ColorPicker.FormatProvider>
+              <div
+                style={{
+                  display: "flex",
+                  width: "100%",
+                  maxWidth: "min(28rem, 100%)",
+                  flexDirection: "column",
+                  gap: "var(--prime-sys-spacing-x3, 0.75rem)",
+                }}
+              >
+                <ColorPicker.FormatSelect />
+                <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={<Pipette aria-hidden size={18} strokeWidth={1.75} />}
+                />
+              </div>
+            </ColorPicker.FormatProvider>
+          </div>
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}

package/src/components/color-picker/examples/hex-input-sizes.tsx

@@ -0,0 +1,34 @@
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+const SIZES = ["s", "m", "l", "xl"] as const;
+
+function HexSizePopover({ size }: { size: (typeof SIZES)[number] }) {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <ColorPicker.Root defaultValue="#3b82f6">
+      <Popover.Root onOpenChange={setOpen} open={open}>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            Hex ({size})
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+          <ColorPicker.HexInput label={`Hex (${size})`} size={size} />
+        </Popover.Content>
+      </Popover.Root>
+    </ColorPicker.Root>
+  );
+}
+
+/** HexInput `size` axis (`s`–`xl`); each control uses its own popover (playground `hex-input-sizes`). */
+export function HexInputSizesExample() {
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", alignItems: "flex-end", gap: "1rem" }}>
+      {SIZES.map((size) => (
+        <HexSizePopover key={size} size={size} />
+      ))}
+    </div>
+  );
+}

package/src/components/color-picker/examples/panel-placement.tsx

@@ -0,0 +1,68 @@
+import { Pipette } from "lucide-react";
+import { Button, ColorPicker, Popover, Typography } from "prime-ui-kit";
+
+const PRESETS = ["#6366f1", "#a855f7", "#ec4899", "#f97316"];
+
+function Panel() {
+  return (
+    <ColorPicker.FormatProvider>
+      <ColorPicker.FormatSelect />
+      <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={<Pipette aria-hidden size={18} strokeWidth={1.75} />}
+      />
+      <Typography.Root as="p" tone="muted" variant="body-small" weight="medium">
+        Presets
+      </Typography.Root>
+      <ColorPicker.SwatchPicker aria-label="Quick colors">
+        {PRESETS.map((c) => (
+          <ColorPicker.SwatchPickerItem key={c} color={c}>
+            <ColorPicker.Swatch />
+          </ColorPicker.SwatchPickerItem>
+        ))}
+      </ColorPicker.SwatchPicker>
+    </ColorPicker.FormatProvider>
+  );
+}
+
+/** Same panel with `Popover.Content` `side="bottom"` vs `side="top"` (playground `panel-placement`). */
+export function PanelPlacementExample() {
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", gap: "1rem", alignItems: "flex-start" }}>
+      <ColorPicker.Root defaultValue="hsl(265, 80%, 55%)">
+        <Popover.Root>
+          <Popover.Trigger asChild>
+            <Button.Root mode="stroke" size="m" variant="neutral">
+              <ColorPicker.TriggerSwatch />
+              Bottom
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+            <Panel />
+          </Popover.Content>
+        </Popover.Root>
+      </ColorPicker.Root>
+
+      <ColorPicker.Root defaultValue="hsl(200, 70%, 48%)">
+        <Popover.Root>
+          <Popover.Trigger asChild>
+            <Button.Root mode="stroke" size="m" variant="neutral">
+              <ColorPicker.TriggerSwatch />
+              Top
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="top">
+            <Panel />
+          </Popover.Content>
+        </Popover.Root>
+      </ColorPicker.Root>
+    </div>
+  );
+}

package/src/components/color-picker/examples/readout-trigger.tsx

@@ -0,0 +1,70 @@
+import { Pipette } from "lucide-react";
+import { Button, ColorPicker, type ColorPickerColorValue, Popover, parseColor } from "prime-ui-kit";
+import * as React from "react";
+
+const PRESETS = ["#ef4444", "#f97316", "#eab308", "#22c55e", "#14b8a6", "#3b82f6", "#8b5cf6"];
+
+/**
+ * Custom color square on the trigger (`style.backgroundColor`) instead of `TriggerSwatch`;
+ * `ColorPicker.Root` lives inside `Popover.Content` (playground `popover`).
+ */
+export function ReadoutTriggerExample() {
+  const [color, setColor] = React.useState<ColorPickerColorValue | undefined>(
+    parseColor("#3b82f6"),
+  );
+  const [open, setOpen] = React.useState(false);
+
+  const colorString = color?.toString("css") ?? "#000000";
+
+  return (
+    <Popover.Root onOpenChange={setOpen} open={open}>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" size="m" variant="neutral">
+          <span
+            aria-hidden
+            style={{
+              boxSizing: "border-box",
+              display: "inline-block",
+              flexShrink: 0,
+              width: "1rem",
+              height: "1rem",
+              borderRadius: "var(--prime-sys-shape-radius-s, 0.25rem)",
+              border: "1px solid var(--prime-sys-color-border-primary, currentColor)",
+              backgroundColor: colorString,
+            }}
+          />
+          {colorString}
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+        <ColorPicker.Root onChange={setColor} value={color}>
+          <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.Slider channel="alpha">
+              <ColorPicker.SliderTrack>
+                <ColorPicker.Thumb />
+              </ColorPicker.SliderTrack>
+            </ColorPicker.Slider>
+            <ColorPicker.ChannelStrip
+              pipetteIcon={<Pipette aria-hidden size={18} strokeWidth={1.75} />}
+            />
+            <ColorPicker.SwatchPicker aria-label="Quick colors">
+              {PRESETS.map((c) => (
+                <ColorPicker.SwatchPickerItem key={c} color={c}>
+                  <ColorPicker.Swatch />
+                </ColorPicker.SwatchPickerItem>
+              ))}
+            </ColorPicker.SwatchPicker>
+          </ColorPicker.FormatProvider>
+        </ColorPicker.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/color-picker/examples/states.tsx

@@ -0,0 +1,79 @@
+import { Pipette } from "lucide-react";
+import { Button, ColorPicker, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+const PRESETS = ["#ef4444", "#22c55e", "#3b82f6"];
+
+/** Disabled `SwatchPickerItem` and disabled hue `Slider` (playground `states`). */
+export function StatesExample() {
+  const [openSwatch, setOpenSwatch] = React.useState(false);
+  const [openSlider, setOpenSlider] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", gap: "2rem", alignItems: "flex-start" }}>
+      <div>
+        <p style={{ margin: "0 0 0.5rem", fontSize: "0.875rem", opacity: 0.8 }}>
+          Preset with isDisabled
+        </p>
+        <ColorPicker.Root defaultValue="#22c55e">
+          <Popover.Root onOpenChange={setOpenSwatch} open={openSwatch}>
+            <Popover.Trigger asChild>
+              <Button.Root mode="stroke" size="m" variant="neutral">
+                <ColorPicker.TriggerSwatch />
+                Palette
+              </Button.Root>
+            </Popover.Trigger>
+            <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+              <ColorPicker.FormatProvider>
+                <ColorPicker.SwatchPicker aria-label="Palette with one disabled swatch">
+                  {PRESETS.map((c, i) => (
+                    <ColorPicker.SwatchPickerItem key={c} color={c} isDisabled={i === 0}>
+                      <ColorPicker.Swatch />
+                    </ColorPicker.SwatchPickerItem>
+                  ))}
+                </ColorPicker.SwatchPicker>
+              </ColorPicker.FormatProvider>
+            </Popover.Content>
+          </Popover.Root>
+        </ColorPicker.Root>
+      </div>
+      <div>
+        <p style={{ margin: "0 0 0.5rem", fontSize: "0.875rem", opacity: 0.8 }}>
+          Hue slider with isDisabled
+        </p>
+        <ColorPicker.Root defaultValue="hsl(200, 75%, 52%)">
+          <Popover.Root onOpenChange={setOpenSlider} open={openSlider}>
+            <Popover.Trigger asChild>
+              <Button.Root mode="stroke" size="m" variant="neutral">
+                <ColorPicker.TriggerSwatch />
+                Disabled slider
+              </Button.Root>
+            </Popover.Trigger>
+            <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom">
+              <ColorPicker.FormatProvider>
+                <div
+                  style={{
+                    display: "flex",
+                    width: "12.5rem",
+                    maxWidth: "100%",
+                    flexDirection: "column",
+                    gap: "0.5rem",
+                  }}
+                >
+                  <ColorPicker.Slider channel="hue" colorSpace="hsl" isDisabled>
+                    <ColorPicker.SliderTrack>
+                      <ColorPicker.Thumb />
+                    </ColorPicker.SliderTrack>
+                  </ColorPicker.Slider>
+                  <ColorPicker.ChannelStrip
+                    pipetteIcon={<Pipette aria-hidden size={18} strokeWidth={1.75} />}
+                  />
+                </div>
+              </ColorPicker.FormatProvider>
+            </Popover.Content>
+          </Popover.Root>
+        </ColorPicker.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -10,7 +10,7 @@
 - **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).
+- **Demos:** playground snippets in **`playground/snippets/command-menu/`** (order matches **`playground/sections/CommandMenuSection.tsx`**); package recipes in **`examples/`** (see **Playground snippets** + **Package examples** below).
 
 ## Extended
 
@@ -63,16 +63,35 @@ export function Example() {
 }
 ```
 
-### Scenario examples (source)
+### Playground snippets
 
-| 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) |
+Same order as **`playground/sections/CommandMenuSection.tsx`**. Sources use `@/` under **`playground/snippets/command-menu/`**:
 
-Playground mirrors: `playground/snippets/command-menu/*`.
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Варианты** | [`variants-density-items.tsx`](../../../playground/snippets/command-menu/variants-density-items.tsx) | **`InputRow`** **`density`** (`compact` / `comfortable`) and **`Item`** **`size`** (`s` / `m`). |
+| **Состояния** | [`states-disabled-filter.tsx`](../../../playground/snippets/command-menu/states-disabled-filter.tsx) | **`disabled`** (excluded from navigation), empty **`value`** (always in results), footer note on empty filter. |
+| **Контролируемый режим** | [`controlled-open-search.tsx`](../../../playground/snippets/command-menu/controlled-open-search.tsx) | **`Dialog`** **`open`** / **`onOpenChange`** and controlled **`Input`** **`value`** / **`onChange`**. |
+| **Композиция** | [`composition-tags-footer.tsx`](../../../playground/snippets/command-menu/composition-tags-footer.tsx) | Custom title, **`InputRow`** **`leading`** / **`trailing`** (**`Kbd`**, close), **`TagSection`**, **`ItemIcon`**, **`Footer`**. |
+| **Full width** | [`full-width-panel.tsx`](../../../playground/snippets/command-menu/full-width-panel.tsx) | Wider panel via **`className`** on **`Dialog`** (playground: demo class; apps: e.g. **`dialogContentWide`** from **`CommandMenu.module.css`**). |
+| **Полиморфная разметка** | [`item-icon-as.tsx`](../../../playground/snippets/command-menu/item-icon-as.tsx) | **`ItemIcon`** **`as`** — SVG component or **`span`**. |
+| **Специфичные фичи** | [`features-keyboard-search.tsx`](../../../playground/snippets/command-menu/features-keyboard-search.tsx) | Global ⌘K / Ctrl+K, **`keywords`**, **`FooterKeyBox`** hints. |
+
+### Package examples (`examples/`)
+
+Runnable recipes use **`@/`** imports in-repo (consumers: **`prime-ui-kit`**). Aligned with the playground blocks above where noted.
+
+| Playground block | File |
+|------------------|------|
+| Варианты | [`variants-density-items.tsx`](./examples/variants-density-items.tsx) |
+| Состояния | [`disabled-items.tsx`](./examples/disabled-items.tsx) |
+| Контролируемый режим | [`controlled-open-search.tsx`](./examples/controlled-open-search.tsx) |
+| Композиция | [`composition-tags-footer.tsx`](./examples/composition-tags-footer.tsx) |
+| Full width | [`full-width-panel.tsx`](./examples/full-width-panel.tsx) |
+| Полиморфная разметка | [`item-icon-as.tsx`](./examples/item-icon-as.tsx) |
+| Специфичные фичи | [`app-palette.tsx`](./examples/app-palette.tsx) |
+| (extra) File list + **`keywords`** | [`file-search.tsx`](./examples/file-search.tsx) |
+| (extra) Grouped quick actions | [`quick-actions.tsx`](./examples/quick-actions.tsx) |
 
 ### Rules
 
@@ -125,7 +144,7 @@ Playground mirrors: `playground/snippets/command-menu/*`.
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| value | `string` (and other input value types) | — | no | Controlled value; when set, filters sync from this value |
+| value | `string \| number \| readonly string[]` | — | no | Controlled value; when set, filters sync from this value |
 | onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | no | Standard change handler; internal state updates when uncontrolled |
 | className | `string` | — | no | Input class |
 | …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" \| "type">` | — | no | Other attributes except `size` and `type` (`type` is fixed to `search`) |
@@ -192,4 +211,4 @@ Polymorphic icon slot: `as` (element type, default `"span"`), `className`, and r
 
 ## 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).
+When generating or refactoring CommandMenu usage: import **`CommandMenu`** from **`prime-ui-kit`** only; do not reimplement modal, listbox, or filter logic. Always pass **`open`** / **`onOpenChange`** (or **`defaultOpen`**) on **`Dialog`**, put **`Input`** inside **`InputRow`** for standard chrome, and give **`Input`** an **`aria-label`** (or associated label). Every **`Item`** needs a **`value`** string (use **`""`** only when the row must stay visible for any query); add **`keywords`** for synonyms and path segments. Do not set **`disabled`** expecting a visible inactive row—those entries are removed from the palette; use conditional JSX or a non-**`Item`** hint if the UX must mention unavailable actions. For global palettes, document **`aria-labelledby`** + **`DialogTitle`** **`id`**. Mirror **`playground/snippets/command-menu/*`** and **`examples/*.tsx`** for density, controlled search, composition, wide panel, **`ItemIcon`**, keyboard shortcut + footer, file search, quick actions, and disabled / empty-value behavior.

package/src/components/command-menu/examples/composition-tags-footer.tsx

@@ -0,0 +1,136 @@
+import { FileText, Search, Settings, Sparkles, X } from "lucide-react";
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { CommandMenu } from "@/components/command-menu/CommandMenu";
+import { Kbd } from "@/components/kbd/Kbd";
+import { Tag } from "@/components/tag/Tag";
+import { Typography } from "@/components/typography/Typography";
+
+const inputIconStyle: React.CSSProperties = {
+  width: "var(--prime-sys-size-control-m-icon)",
+  height: "var(--prime-sys-size-control-m-icon)",
+  color: "var(--prime-sys-color-content-muted)",
+  flexShrink: 0,
+};
+
+const dialogHeaderPadStyle: React.CSSProperties = {
+  padding: "var(--prime-sys-spacing-x4) var(--prime-sys-spacing-x4) 0",
+};
+
+const dialogHeaderLeadStyle: React.CSSProperties = {
+  marginTop: "var(--prime-sys-spacing-x1)",
+};
+
+const footerMutedStyle: React.CSSProperties = {
+  background: "var(--prime-sys-color-surface-default)",
+};
+
+/**
+ * Custom header, `InputRow` slots, `TagSection`, `ItemIcon`, muted `Footer` (playground `composition-tags-footer.tsx`).
+ */
+export default function CommandMenuExampleCompositionTagsFooter() {
+  const [open, setOpen] = React.useState(false);
+  const [scopes, setScopes] = React.useState(["Docs", "Commands"]);
+
+  return (
+    <>
+      <Button.Root size="m" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Full composition
+      </Button.Root>
+
+      <CommandMenu.Dialog
+        open={open}
+        onOpenChange={setOpen}
+        aria-labelledby="cmd-composition-title"
+      >
+        <div style={dialogHeaderPadStyle}>
+          <Typography.Root
+            as="div"
+            id="cmd-composition-title"
+            role="heading"
+            aria-level={2}
+            variant="body-large"
+            weight="semibold"
+          >
+            Palette
+          </Typography.Root>
+          <Typography.Root variant="body-small" tone="muted" style={dialogHeaderLeadStyle}>
+            Search sections and run quick actions
+          </Typography.Root>
+        </div>
+
+        <CommandMenu.InputRow
+          leading={<Search style={inputIconStyle} strokeWidth={2} aria-hidden />}
+          trailing={
+            <>
+              <Kbd.Root aria-label="Open shortcut">⌘K</Kbd.Root>
+              <Button.Root
+                size="m"
+                variant="neutral"
+                mode="ghost"
+                aria-label="Close"
+                onClick={() => setOpen(false)}
+              >
+                <Button.Icon>
+                  <X size={18} strokeWidth={2} aria-hidden />
+                </Button.Icon>
+              </Button.Root>
+            </>
+          }
+        >
+          <CommandMenu.Input placeholder="Where to…" aria-label="Search" />
+        </CommandMenu.InputRow>
+
+        <CommandMenu.TagSection>
+          <CommandMenu.TagSectionLabel>
+            <Typography.Root variant="body-compact" tone="muted">
+              Scope
+            </Typography.Root>
+          </CommandMenu.TagSectionLabel>
+          <CommandMenu.TagRow>
+            {scopes.map((s) => (
+              <Tag.Root
+                key={s}
+                size="m"
+                onRemove={() => setScopes((p) => p.filter((x) => x !== s))}
+              >
+                {s}
+              </Tag.Root>
+            ))}
+          </CommandMenu.TagRow>
+        </CommandMenu.TagSection>
+
+        <CommandMenu.List>
+          <CommandMenu.Group heading="File">
+            <CommandMenu.Item value="new document" onSelect={() => setOpen(false)}>
+              <CommandMenu.ItemIcon as={FileText} strokeWidth={2} />
+              New document
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group heading="System">
+            <CommandMenu.Item
+              value="settings"
+              keywords="preferences profile"
+              onSelect={() => setOpen(false)}
+            >
+              <CommandMenu.ItemIcon as={Settings} strokeWidth={2} />
+              Settings
+            </CommandMenu.Item>
+            <CommandMenu.Item value="tips" keywords="help tips" onSelect={() => setOpen(false)}>
+              <CommandMenu.ItemIcon as={Sparkles} strokeWidth={2} />
+              Tips
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+
+        <CommandMenu.Footer style={footerMutedStyle}>
+          <Typography.Root variant="body-compact" tone="muted">
+            Arrows and Enter work from the search field; groups hide when they have no visible
+            items.
+          </Typography.Root>
+        </CommandMenu.Footer>
+      </CommandMenu.Dialog>
+    </>
+  );
+}