---

## CommandPalette
Keyboard-driven command palette with search, grouped results,
and arrow-key navigation. Composes Dialog + search input into a ready-to-use overlay.
Open via bind:open or the built-in Cmd+K shortcut. A row is a command, or with
`kind: 'info'` a line of information the keyboard passes over; the footer's key hints are
drawn with `Kbd` and can be replaced through the `footer` snippet.

**Import:** `import { CommandPalette } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CommandPalette
  items={commands}
  bind:open
  onSelect={(item) => handleCommand(item)}
  placeholder="Type a command..."
/>
```

```svelte
<CommandPalette
  items={[
    { id: 'new', label: 'New File', category: 'File', shortcut: 'Ctrl+N' },
    { id: 'open', label: 'Open File', category: 'File', shortcut: 'Ctrl+O' },
    { id: 'theme', label: 'Toggle Theme', category: 'Settings' },
    { id: 'search', label: 'Search', category: 'Navigation', shortcut: 'Ctrl+F' }
  ]}
  bind:open={paletteOpen}
  onSelect={(item) => runAction(item.id)}
  size="md"
  showFooter
/>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `CommandPaletteItem[]` | yes |  | Items to display. Grouped automatically by `category`. |
| ...HTMLDialogAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'open' | 'title' | 'draggable') |
| class | `string` | no |  | Additional CSS classes on the root wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| customEmpty | `Snippet<[query: string]>` | no |  | Custom empty-state renderer. Receives the current query string. |
| customItem | `Snippet<[item: CommandPaletteItem, highlighted: boolean, index: number, select: () => void]>` | no |  | Replace the default per-row rendering. Receives the item, whether its row is highlighted, the item's flat index into the filtered list, and a `select` callback (call it to run the same selection the row's click runs; it is a no-op on a disabled item and on an `info` row). It draws `info` rows too: `highlighted` is always `false` for them.  **Render visible content only — nothing focusable, nothing interactive.** A `<button>` or `<a>` inside the row is nested-interactive HTML on the `role="option"` container, a tab stop inside the Dialog's focus trap that the input's keyboard handling never reaches, and a click that bubbles into the row's own, so `onSelect` fires twice. `select` is for a snippet that dispatches from its own non-interactive logic — a pointer gesture on the content, say — and for parity with Select's `toggle`.  The outer `<div role="option">` container is still owned by CommandPalette: its id is what the input's `aria-activedescendant` points at, its `data-command-palette-selected` attribute is what the scroll-into-view query finds, and it carries the row's click and hover-highlight. An `info` row's container is a plain `<div role="presentation">` with neither.  Styling the row is `slotClasses.item` plus the state slot (`itemHighlighted`, `itemDisabled`, `itemInfo` or `itemDefault`), which reach the container here as well; the `itemIcon`, `itemText`, `itemLabel`, `itemExcerpt` and `itemShortcut` slots style the default contents and go unused under `customItem`.  Positional args: `(item, highlighted, index, select)`. |
| emptyText | `string` | no | 'No results found.' | Message shown when the filter returns no results. |
| filter | `(item: CommandPaletteItem, query: string) => boolean` | no |  | Custom filter function. Receives each item and the current query. Return `true` to keep the item. When omitted, a case-insensitive label + category substring match is used. |
| footer | `Snippet<[footer: { hints: CommandPaletteHint[] }]>` | no |  | Replace the footer's contents. Receives `{ hints }`, the palette's own key hints in their default order — `navigate` (↑↓), `select` (↵) and `close` (esc), keys and labels already translated — to render all, some, or none of, next to hints of your own. Render a key through `Kbd`: `<Kbd keys={hint.keys} size="sm" />` draws it the way the default footer does. The footer bar itself stays the palette's, styled by the `footer` slot, and `showFooter={false}` hides it with the snippet in it.  Positional args: `({ hints })`. |
| id | `string` | no |  | The `<dialog>` element's id, and the prefix of the results list (`<id>-list`) and its rows (`<id>-item-N`). Generated per instance when omitted. |
| onClosed | `() => void` | no |  | Fires once the palette has finished closing — the exit animation has ended and focus is back on the element that had it before the palette opened, unless that element is gone or still inert: when stacked surfaces close together, focus can end on the page body. Fires once for every close that finishes: Escape, a backdrop click, a selection, or `open = false` from you. Not for a close interrupted by reopening before the animation ends, nor when the palette is destroyed while open or mid-close. `onOpenChange(false)` fires an animation earlier, while focus is still in the palette; this is the place to move focus elsewhere or open a follow-up surface. The query and the highlight have been reset by then. |
| onOpenChange | `(open: boolean) => void` | no |  | Fired when the open state changes (close via Escape, backdrop, or selection). |
| onSelect | `(item: CommandPaletteItem) => void` | no |  | Fired when an item is selected via click or Enter. |
| open | `boolean` | no | false | Controls visibility. Supports `bind:open`. |
| placeholder | `string` | no | 'Search...' | Placeholder text for the search input. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CommandPalette: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| query | `string` | no | '' | Current search text. Supports `bind:query`. Reset to `''` when the palette has finished closing, just before `onClosed` fires, so it does not empty while it animates out. A query you set once it has closed — in `onClosed` or later, before or after `open = true` — is what it opens with; one you write between `open = false` and `onClosed` is reset. A close that does not finish resets nothing: one vetoed by writing `open = true` back in `onOpenChange`, one interrupted by reopening (from `onSelect` too, so a drill-down that swaps `items` there sets `query = ''` itself), or the palette destroyed before it ends, as an `{#if}` that unmounts it on close does: clear your bound query where you unmount it. Selecting an item leaves the query as it was until then.  For async or remote search, watch the bound `query`, fetch your own results, and pass them back via `items` with `filter={() => true}` so the built-in label match does not filter them a second time. |
| shortcut | `string | false` | no | 'mod+k' | Register a global keyboard shortcut that toggles the palette. `mod` is Cmd on macOS and Ctrl elsewhere. Set to `false` to disable. |
| showFooter | `boolean` | no | true | Show the footer with the keyboard hints. `false` hides the footer bar, a `footer` snippet included. |
| size | `CommandPaletteVariants['size']` | no | 'md' | Maximum width of the palette panel. |
| slotClasses | `Partial<Record<CommandPaletteSlots, string>>` | no |  | Per-slot class overrides. A row is built from four sources in order — the library's `item` classes, the library's classes for the row's state (`itemInfo` for an `info` row, `itemDisabled` when the item is disabled, `itemHighlighted` when selected, `itemDefault` otherwise), then your `item` entry, then your entry for that state slot. Each source displaces the earlier ones per Tailwind bucket, so an `item` entry that collides with a state class *removes* it: `slotClasses={{ item: 'bg-white' }}` also drops the selected row's `bg-primary-subtle`. Write the state slot as well to keep both. `kbd` reaches the `Kbd` each default footer hint renders, after its own classes. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles, the modal Dialog's included. |

Inherited from:
- Omit<HTMLDialogAttributes, 'children' | 'open' | 'title' | 'draggable'> (omit-pattern)

### Types
```ts
interface CommandPaletteItem {
/** Unique identifier. Falls back to `label` when omitted. */
  id?: string;
  /** Display text shown in the list. */
  label: string;
  /**
   * Secondary line rendered under the label, truncated to one line: context the
   * label cannot carry, a description or an excerpt around a search match. In the
   * default row it is part of the command's accessible name, read with the label.
   */
  excerpt?: string;
  /** Group header this item belongs to. Items with the same category are grouped together. */
  category?: string;
  /** Optional keyboard shortcut displayed on the right side. */
  shortcut?: string;
  /**
   * Leading icon component. Pass an icon directly (`import { SearchIcon } from
   * '@urbicon-ui/blocks'`), not an icon *name* — a name would have to be
   * resolved through the registry at runtime, and that dynamic lookup drags all
   * the entire icon set into the consumer bundle (see docs/ICON-DESIGN.md). Rendered at
   * the slot's own size, inheriting `currentColor`.
   */
  icon?: IconComponent;
  /**
   * `'info'` makes the row information, not a command: keyboard and pointer skip it,
   * it cannot be selected, it has no locked look (`itemInfo` styles it), and a screen
   * reader reads it in reading mode only, never while the user types: what must be heard
   * goes in the `excerpt` of an enabled command. `disabled` has no effect. @default 'action'
   */
  kind?: 'action' | 'info';
  /**
   * A command that cannot run right now: dimmed, skipped by the keyboard, not
   * selectable, read as unavailable in reading mode only. @default false
   */
  disabled?: boolean;
  /** Arbitrary payload forwarded to `onSelect`. */
  data?: unknown;
}
```

```ts
interface CommandPaletteHint {
/**
   * Which hint this is. The palette's own are `'navigate'`, `'select'` and
   * `'close'`; pick or drop one by its id. Give a hint you add an id the
   * others do not use, so an `{#each}` can key on it.
   */
  id: string;
  /**
   * The key, in the form `Kbd`'s `keys` takes: a string is one keycap, an
   * array is a chord drawn in one keycap (`['Ctrl', 'K']` → Ctrl + K). The
   * palette's own come from its translations (`commandPalette.keys.*`).
   */
  keys: string | string[];
  /** What the key does, already translated. */
  label: string;
}
```

```ts
type IconComponent = Component<IconProps>
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`wrapper`, `inputWrapper`, `input`, `inputIcon`, `clearButton`, `list`, `groupLabel`, `item`, `itemHighlighted`, `itemDefault`, `itemDisabled`, `itemInfo`, `itemIcon`, `itemText`, `itemLabel`, `itemExcerpt`, `itemShortcut`, `empty`, `footer`, `footerHint`, `kbd`, `separator`