# Command

## Overview

A command palette for searching and executing actions via keyboard — triggered by `⌘K` / `Ctrl+K`. Provides a searchable, filterable list of commands, navigation items, and quick actions. Built on `cmdk`.

---

## When to Use

- Global search and quick-nav (Ctrl+K pattern)
- Quick action palette for power users
- Searchable select inputs for large option sets

---

## Anatomy

```
<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Type a command..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
      <CommandItem>Search Emoji</CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>
```

---

## Examples

### Global Command Palette

```tsx
import {
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
} from 'xertica-ui/ui';
import { useEffect, useState } from 'react';
import { useNavigate } from 'react-router-dom';

export function CommandPalette() {
  const [open, setOpen] = useState(false);
  const navigate = useNavigate();

  useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        setOpen(prev => !prev);
      }
    };
    document.addEventListener('keydown', down);
    return () => document.removeEventListener('keydown', down);
  }, []);

  return (
    <CommandDialog open={open} onOpenChange={setOpen}>
      <CommandInput placeholder="Search commands..." />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Navigation">
          <CommandItem
            onSelect={() => {
              navigate('/dashboard');
              setOpen(false);
            }}
          >
            Dashboard
          </CommandItem>
          <CommandItem
            onSelect={() => {
              navigate('/users');
              setOpen(false);
            }}
          >
            Users
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Settings">
          <CommandItem
            onSelect={() => {
              navigate('/settings');
              setOpen(false);
            }}
          >
            Preferences
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </CommandDialog>
  );
}
```

---

## AI Rules

- Always register a keyboard shortcut (`⌘K`/`Ctrl+K`) when using `CommandDialog` — the component is invisible otherwise.
- `CommandEmpty` is required — it shows when the search returns no results.
- Close the command palette (`setOpen(false)`) after executing any `onSelect` action.
- Use `CommandDialog` for the modal variant; use `Command` directly for embedding in a custom panel.