@etus/ui 0.1.0

package/src/components/advanced/Command/README.md

@@ -0,0 +1,1259 @@
+# Command
+
+## Visão Geral
+
+O **Command** é um componente avançado de menu de comandos e combobox acessível do Design System ETUS. Baseado na biblioteca [cmdk](https://cmdk.paco.me), fornece uma interface de busca rápida estilo ⌘K para navegação, execução de ações e seleção de itens. Como organismo, combina múltiplos elementos (input, lista, grupos, itens) em uma experiência de busca e navegação coesa.
+
+### Casos de Uso
+
+- Command palettes (menus ⌘K/Ctrl+K)
+- Busca global em aplicações
+- Navegação rápida entre páginas/recursos
+- Seleção de ações com filtro automático
+- Comboboxes acessíveis com autocomplete
+- Lançadores de aplicações/shortcuts
+
+### Classificação
+
+**Categoria:** Organism (Advanced)
+**Dependências:** `cmdk`, `@/components/feedback/Dialog`, `lucide-react`
+
+---
+
+## Design Specs
+
+### Compound Components
+
+O Command é um sistema de compound components com as seguintes partes:
+
+| Componente | Descrição | data-slot |
+|------------|-----------|-----------|
+| `Command` | Container raiz do menu | `command` |
+| `CommandDialog` | Wrapper com Dialog modal | - |
+| `CommandInput` | Campo de busca com ícone | `command-input` |
+| `CommandList` | Container scrollável de itens | `command-list` |
+| `CommandEmpty` | Estado vazio quando sem resultados | `command-empty` |
+| `CommandGroup` | Agrupa itens com heading | `command-group` |
+| `CommandItem` | Item selecionável | `command-item` |
+| `CommandSeparator` | Linha divisória entre grupos | `command-separator` |
+| `CommandShortcut` | Exibe atalho de teclado | `command-shortcut` |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparência base |
+| Selected | `data-selected="true"` | Background `bg-accent` no item |
+| Disabled | `data-disabled="true"` | 50% opacidade, sem pointer events |
+| Empty | - | Exibe `CommandEmpty` |
+| Loading | - | Exibe indicador de loading |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--popover               /* Fundo do Command */
+--popover-foreground    /* Texto principal */
+--accent               /* Background item selecionado */
+--accent-foreground    /* Texto item selecionado */
+--muted-foreground     /* Texto secundário, ícones, placeholders */
+--border               /* Borda inferior do input */
+
+/* Espaçamento */
+px-2, px-3             /* Padding horizontal items/input */
+py-1.5, py-3, py-6     /* Padding vertical items/empty */
+gap-2                  /* Entre ícone e texto */
+
+/* Tipografia */
+text-sm                /* 14px - items e input */
+text-xs                /* 12px - group headings, shortcuts */
+font-medium            /* 500 - group headings */
+
+/* Bordas */
+rounded-md             /* var(--radius) */
+rounded-sm             /* Items */
+
+/* Dimensões */
+h-9, h-12              /* Altura do input wrapper */
+max-h-[300px]          /* Altura máxima da lista */
+size-4, size-5         /* Tamanho dos ícones */
+```
+
+### data-slot
+
+```html
+<div data-slot="command">
+  <div data-slot="command-input-wrapper">
+    <input data-slot="command-input" />
+  </div>
+  <div data-slot="command-list">
+    <div data-slot="command-group">
+      <div data-slot="command-item">
+        <span data-slot="command-shortcut">⌘K</span>
+      </div>
+    </div>
+    <div data-slot="command-separator" />
+    <div data-slot="command-empty">No results.</div>
+  </div>
+</div>
+```
+
+---
+
+## API
+
+### Command (Root)
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `shouldFilter` | `boolean` | `true` | Habilita filtro automático |
+| `filter` | `(value: string, search: string) => number` | - | Função de filtro customizada |
+| `value` | `string` | - | Item selecionado (controlado) |
+| `onValueChange` | `(value: string) => void` | - | Callback de seleção |
+| `loop` | `boolean` | `false` | Navegação circular no teclado |
+| `children` | `ReactNode` | - | Conteúdo do command |
+
+> Herda todas as props de `React.ComponentProps<typeof CommandPrimitive>`
+
+### CommandDialog
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `open` | `boolean` | - | Estado de abertura (controlado) |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback de abertura/fechamento |
+| `title` | `string` | `"Command Palette"` | Título acessível do dialog |
+| `description` | `string` | `"Search for a command..."` | Descrição acessível |
+| `showCloseButton` | `boolean` | `true` | Exibe botão de fechar |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo do dialog |
+
+> Herda todas as props de `Dialog`
+
+### CommandInput
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `placeholder` | `string` | - | Placeholder do input |
+| `value` | `string` | - | Valor do input (controlado) |
+| `onValueChange` | `(value: string) => void` | - | Callback de digitação |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<typeof CommandPrimitive.Input>`
+
+### CommandList
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Grupos e items |
+
+> Expõe CSS variable `--cmdk-list-height` para animação
+
+### CommandEmpty
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `children` | `ReactNode` | - | Mensagem de estado vazio |
+
+### CommandGroup
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `heading` | `string` | - | Título do grupo |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Items do grupo |
+
+### CommandItem
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `string` | - | Valor para filtro/seleção |
+| `keywords` | `string[]` | - | Palavras-chave adicionais para busca |
+| `disabled` | `boolean` | `false` | Desabilita o item |
+| `onSelect` | `(value: string) => void` | - | Callback de seleção |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo do item |
+
+### CommandShortcut
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `children` | `ReactNode` | - | Texto do atalho (ex: `⌘K`) |
+| `className` | `string` | - | Classes CSS adicionais |
+
+### CommandSeparator
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+
+### TypeScript
+
+```typescript
+import type { ComponentProps } from "react"
+import type { Command as CommandPrimitive } from "cmdk"
+import type { Dialog } from "@/components/feedback/Dialog"
+
+// Props dos componentes
+type CommandProps = ComponentProps<typeof CommandPrimitive>
+
+type CommandDialogProps = ComponentProps<typeof Dialog> & {
+  title?: string
+  description?: string
+  className?: string
+  showCloseButton?: boolean
+}
+
+type CommandInputProps = ComponentProps<typeof CommandPrimitive.Input>
+type CommandListProps = ComponentProps<typeof CommandPrimitive.List>
+type CommandEmptyProps = ComponentProps<typeof CommandPrimitive.Empty>
+type CommandGroupProps = ComponentProps<typeof CommandPrimitive.Group>
+type CommandItemProps = ComponentProps<typeof CommandPrimitive.Item>
+type CommandSeparatorProps = ComponentProps<typeof CommandPrimitive.Separator>
+type CommandShortcutProps = ComponentProps<"span">
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Mantine | MUI | Chakra | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint |
+|---------|:----:|:------:|:-------:|:---:|:------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|
+| **Command Palette** | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ | - | ✓ |
+| **Combobox Mode** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Auto Filter** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ |
+| **Groups** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard Nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Dialog Mode** | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ | - | ✓ |
+| **Shortcuts Display** | ✓ | ✓ | ✓ | - | - | - | - | - | - | ✓ | - | ✓ |
+| **Loading State** | ~ | ~ | ✓ | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | ✓ |
+| **Async Items** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ |
+| **Custom Filter** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ |
+| **Virtualization** | - | - | ✓ | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+#### Componentes Equivalentes por Design System
+
+| Design System | Componente | Notas |
+|---------------|------------|-------|
+| **ETUS** | `Command`, `CommandDialog` | Baseado em cmdk |
+| **Shadcn/ui** | `Command` | Baseado em cmdk |
+| **Mantine** | `Spotlight` | Modal de busca global |
+| **MUI** | `Autocomplete` | Combobox, sem command palette |
+| **Chakra UI** | `Menu` + custom | Requer composição manual |
+| **Ant Design** | `AutoComplete` | Combobox, sem command palette |
+| **NextUI** | `Autocomplete` | Combobox, sem command palette |
+| **Headless UI** | `Combobox` | Primitivo headless |
+| **Ariakit** | `Combobox` | Primitivo composable |
+| **Fluent UI** | `SearchBox` + `Menu` | Requer composição |
+| **Carbon** | `ComboBox` | Combobox, sem command palette |
+| **Blueprint** | `Omnibar` | Command palette completo |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Shadcn | Mantine Spotlight | MUI Autocomplete | Ariakit |
+|------|:----:|:------:|:-----------------:|:----------------:|:-------:|
+| `shouldFilter` | ✓ | ✓ | `filter` | `filterOptions` | - |
+| `value` | ✓ | ✓ | `query` | `value` | `value` |
+| `onValueChange` | ✓ | ✓ | `onQueryChange` | `onChange` | `setValue` |
+| `loop` | ✓ | ✓ | - | - | `focusLoop` |
+| `onSelect` (item) | ✓ | ✓ | `onActionClick` | `onChange` | `onItemClick` |
+| `keywords` | ✓ | ✓ | `keywords` | - | - |
+| `disabled` | ✓ | ✓ | `disabled` | `disabled` | `disabled` |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Elemento | Uso |
+|----------|----------|-----|
+| `role="combobox"` | Input | Identifica como combobox |
+| `role="listbox"` | List | Identifica lista de opções |
+| `role="option"` | Item | Identifica item selecionável |
+| `role="group"` | Group | Agrupa opções relacionadas |
+| `aria-expanded` | Input | Estado de expansão da lista |
+| `aria-activedescendant` | Input | Item atualmente focado |
+| `aria-selected` | Item | Item selecionado |
+| `aria-disabled` | Item | Item desabilitado |
+| `aria-label` | Dialog | Título acessível do modal |
+| `aria-describedby` | Dialog | Descrição do modal |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `↓` / `↑` | Navega entre items |
+| `Enter` | Seleciona item focado |
+| `Escape` | Fecha dialog / limpa busca |
+| `Home` | Vai para primeiro item |
+| `End` | Vai para último item |
+| `Tab` | Move foco (comportamento padrão) |
+
+### Focus Management
+
+```tsx
+// Focus automático no input ao abrir
+<CommandDialog>
+  <CommandInput /> // Auto-focus
+
+// Focus visible nos items
+[&_[cmdk-item]]:focus-visible:ring-2
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Input text | `--popover-foreground` | `--popover` | ≥ 4.5:1 |
+| Item default | `--foreground` | `--popover` | ≥ 4.5:1 |
+| Item selected | `--accent-foreground` | `--accent` | ≥ 4.5:1 |
+| Placeholder | `--muted-foreground` | `--popover` | ≥ 4.5:1 |
+
+### Screen Readers
+
+- `CommandDialog` usa Dialog acessível com título/descrição sr-only
+- Items anunciam label e estado (selecionado, desabilitado)
+- Grupos anunciam heading antes dos items
+- Estado vazio é anunciado automaticamente
+
+### Reduced Motion
+
+```tsx
+// Respeitar preferência do usuário
+motion-reduce:transition-none
+```
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Mantine | MUI | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:-------:|:---:|:------:|:------:|
+| **ARIA combobox** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Focus management** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-activedescendant** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Group labels** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Screen reader tested** | ~ | ✓ | - | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Reduced motion** | ~ | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ |
+| **High contrast** | - | ✓ | - | - | - | - | - | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@etus/ui"
+
+function Example() {
+  return (
+    <Command className="rounded-lg border shadow-md">
+      <CommandInput placeholder="Buscar..." />
+      <CommandList>
+        <CommandEmpty>Nenhum resultado encontrado.</CommandEmpty>
+        <CommandGroup heading="Sugestões">
+          <CommandItem>Calendário</CommandItem>
+          <CommandItem>Configurações</CommandItem>
+          <CommandItem>Perfil</CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  )
+}
+```
+
+### Command Dialog (⌘K Menu)
+
+```tsx
+import { useEffect, useState } from "react"
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandShortcut,
+} from "@etus/ui"
+import { Calculator, Calendar, CreditCard, Settings, User } from "lucide-react"
+
+function CommandMenu() {
+  const [open, setOpen] = useState(false)
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault()
+        setOpen((open) => !open)
+      }
+    }
+
+    document.addEventListener("keydown", down)
+    return () => document.removeEventListener("keydown", down)
+  }, [])
+
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <CommandInput placeholder="Digite um comando ou busque..." />
+      <CommandList>
+        <CommandEmpty>Nenhum resultado encontrado.</CommandEmpty>
+        <CommandGroup heading="Sugestões">
+          <CommandItem onSelect={() => setOpen(false)}>
+            <Calendar className="mr-2 h-4 w-4" />
+            <span>Calendário</span>
+          </CommandItem>
+          <CommandItem onSelect={() => setOpen(false)}>
+            <User className="mr-2 h-4 w-4" />
+            <span>Perfil</span>
+            <CommandShortcut>⌘P</CommandShortcut>
+          </CommandItem>
+          <CommandItem onSelect={() => setOpen(false)}>
+            <Settings className="mr-2 h-4 w-4" />
+            <span>Configurações</span>
+            <CommandShortcut>⌘S</CommandShortcut>
+          </CommandItem>
+        </CommandGroup>
+        <CommandGroup heading="Ferramentas">
+          <CommandItem>
+            <Calculator className="mr-2 h-4 w-4" />
+            <span>Calculadora</span>
+          </CommandItem>
+          <CommandItem>
+            <CreditCard className="mr-2 h-4 w-4" />
+            <span>Pagamentos</span>
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  )
+}
+```
+
+### Com Ícones e Shortcuts
+
+```tsx
+import { File, FileText, Image, Music, Video } from "lucide-react"
+
+<Command>
+  <CommandInput placeholder="Buscar arquivos..." />
+  <CommandList>
+    <CommandGroup heading="Arquivos Recentes">
+      <CommandItem>
+        <FileText className="mr-2 h-4 w-4" />
+        <span>Documento.pdf</span>
+        <CommandShortcut>⌘1</CommandShortcut>
+      </CommandItem>
+      <CommandItem>
+        <Image className="mr-2 h-4 w-4" />
+        <span>Foto.jpg</span>
+        <CommandShortcut>⌘2</CommandShortcut>
+      </CommandItem>
+      <CommandItem>
+        <Video className="mr-2 h-4 w-4" />
+        <span>Video.mp4</span>
+        <CommandShortcut>⌘3</CommandShortcut>
+      </CommandItem>
+      <CommandItem>
+        <Music className="mr-2 h-4 w-4" />
+        <span>Audio.mp3</span>
+        <CommandShortcut>⌘4</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Com Grupos e Separadores
+
+```tsx
+import { CommandSeparator } from "@etus/ui"
+import { Home, LogOut, Settings, User } from "lucide-react"
+
+<Command>
+  <CommandInput placeholder="Buscar..." />
+  <CommandList>
+    <CommandGroup heading="Navegação">
+      <CommandItem>
+        <Home className="mr-2 h-4 w-4" />
+        <span>Início</span>
+      </CommandItem>
+      <CommandItem>
+        <User className="mr-2 h-4 w-4" />
+        <span>Perfil</span>
+      </CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Configurações">
+      <CommandItem>
+        <Settings className="mr-2 h-4 w-4" />
+        <span>Preferências</span>
+      </CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandItem>
+      <LogOut className="mr-2 h-4 w-4" />
+      <span>Sair</span>
+    </CommandItem>
+  </CommandList>
+</Command>
+```
+
+### Items Desabilitados
+
+```tsx
+<Command>
+  <CommandInput placeholder="Buscar ações..." />
+  <CommandList>
+    <CommandGroup heading="Ações">
+      <CommandItem>
+        <span>Salvar</span>
+        <CommandShortcut>⌘S</CommandShortcut>
+      </CommandItem>
+      <CommandItem disabled>
+        <span>Excluir</span>
+        <CommandShortcut>⌘D</CommandShortcut>
+      </CommandItem>
+      <CommandItem>
+        <span>Exportar</span>
+        <CommandShortcut>⌘E</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Com Filtro Customizado
+
+```tsx
+<Command
+  shouldFilter={false}
+  filter={(value, search) => {
+    // Filtro customizado: apenas matches exatos
+    if (value.toLowerCase() === search.toLowerCase()) return 1
+    if (value.toLowerCase().includes(search.toLowerCase())) return 0.5
+    return 0
+  }}
+>
+  <CommandInput placeholder="Busca exata..." />
+  <CommandList>
+    <CommandGroup>
+      <CommandItem value="react">React</CommandItem>
+      <CommandItem value="react-dom">React DOM</CommandItem>
+      <CommandItem value="react-native">React Native</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Com Keywords para Busca
+
+```tsx
+<Command>
+  <CommandInput placeholder="Buscar configurações..." />
+  <CommandList>
+    <CommandGroup heading="Configurações">
+      <CommandItem keywords={["dark", "light", "appearance"]}>
+        <span>Tema</span>
+      </CommandItem>
+      <CommandItem keywords={["language", "locale", "i18n"]}>
+        <span>Idioma</span>
+      </CommandItem>
+      <CommandItem keywords={["password", "security", "2fa"]}>
+        <span>Segurança</span>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Com Loading Assíncrono
+
+```tsx
+import { useEffect, useState } from "react"
+import { Loader2 } from "lucide-react"
+
+function AsyncCommand() {
+  const [loading, setLoading] = useState(false)
+  const [items, setItems] = useState<string[]>([])
+  const [search, setSearch] = useState("")
+
+  useEffect(() => {
+    if (!search) {
+      setItems([])
+      return
+    }
+
+    setLoading(true)
+    const timeout = setTimeout(async () => {
+      // Simula API call
+      const results = await fetchResults(search)
+      setItems(results)
+      setLoading(false)
+    }, 300)
+
+    return () => clearTimeout(timeout)
+  }, [search])
+
+  return (
+    <Command shouldFilter={false}>
+      <CommandInput
+        placeholder="Buscar usuários..."
+        value={search}
+        onValueChange={setSearch}
+      />
+      <CommandList>
+        {loading ? (
+          <div className="flex items-center justify-center py-6">
+            <Loader2 className="h-6 w-6 animate-spin" />
+          </div>
+        ) : items.length === 0 && search ? (
+          <CommandEmpty>Nenhum usuário encontrado.</CommandEmpty>
+        ) : (
+          <CommandGroup heading="Usuários">
+            {items.map((item) => (
+              <CommandItem key={item} value={item}>
+                {item}
+              </CommandItem>
+            ))}
+          </CommandGroup>
+        )}
+      </CommandList>
+    </Command>
+  )
+}
+```
+
+### Navegação com Router
+
+```tsx
+import { useNavigate } from "@tanstack/react-router"
+import { File, Home, Settings, User } from "lucide-react"
+
+function NavigationCommand() {
+  const [open, setOpen] = useState(false)
+  const navigate = useNavigate()
+
+  const handleSelect = (path: string) => {
+    navigate({ to: path })
+    setOpen(false)
+  }
+
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <CommandInput placeholder="Ir para..." />
+      <CommandList>
+        <CommandGroup heading="Páginas">
+          <CommandItem onSelect={() => handleSelect("/")}>
+            <Home className="mr-2 h-4 w-4" />
+            Início
+          </CommandItem>
+          <CommandItem onSelect={() => handleSelect("/profile")}>
+            <User className="mr-2 h-4 w-4" />
+            Perfil
+          </CommandItem>
+          <CommandItem onSelect={() => handleSelect("/settings")}>
+            <Settings className="mr-2 h-4 w-4" />
+            Configurações
+          </CommandItem>
+          <CommandItem onSelect={() => handleSelect("/documents")}>
+            <File className="mr-2 h-4 w-4" />
+            Documentos
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  )
+}
+```
+
+### Dentro de Popover (Combobox)
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui"
+import { Button } from "@etus/ui"
+import { ChevronsUpDown } from "lucide-react"
+
+function ComboboxExample() {
+  const [open, setOpen] = useState(false)
+  const [value, setValue] = useState("")
+
+  const frameworks = [
+    { value: "next", label: "Next.js" },
+    { value: "remix", label: "Remix" },
+    { value: "astro", label: "Astro" },
+    { value: "nuxt", label: "Nuxt" },
+  ]
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button variant="outline" className="w-[200px] justify-between">
+          {value
+            ? frameworks.find((f) => f.value === value)?.label
+            : "Selecione..."}
+          <ChevronsUpDown className="ml-2 h-4 w-4 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[200px] p-0">
+        <Command>
+          <CommandInput placeholder="Buscar framework..." />
+          <CommandList>
+            <CommandEmpty>Nenhum framework encontrado.</CommandEmpty>
+            <CommandGroup>
+              {frameworks.map((framework) => (
+                <CommandItem
+                  key={framework.value}
+                  value={framework.value}
+                  onSelect={(currentValue) => {
+                    setValue(currentValue === value ? "" : currentValue)
+                    setOpen(false)
+                  }}
+                >
+                  {framework.label}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Command.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "./Command"
+
+describe("Command", () => {
+  it("renders input and items correctly", () => {
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem>Item 1</CommandItem>
+            <CommandItem>Item 2</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument()
+    expect(screen.getByText("Item 1")).toBeInTheDocument()
+    expect(screen.getByText("Item 2")).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute on root", () => {
+    render(
+      <Command data-testid="command">
+        <CommandInput />
+        <CommandList />
+      </Command>
+    )
+
+    expect(screen.getByTestId("command")).toHaveAttribute("data-slot", "command")
+  })
+
+  it("filters items based on search input", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem value="apple">Apple</CommandItem>
+            <CommandItem value="banana">Banana</CommandItem>
+            <CommandItem value="cherry">Cherry</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    const input = screen.getByPlaceholderText("Search...")
+    await user.type(input, "ban")
+
+    expect(screen.getByText("Banana")).toBeVisible()
+    expect(screen.queryByText("Apple")).not.toBeVisible()
+    expect(screen.queryByText("Cherry")).not.toBeVisible()
+  })
+
+  it("shows empty state when no results", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandEmpty>No results found.</CommandEmpty>
+          <CommandGroup>
+            <CommandItem value="apple">Apple</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    const input = screen.getByPlaceholderText("Search...")
+    await user.type(input, "xyz")
+
+    expect(screen.getByText("No results found.")).toBeVisible()
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("Command interactions", () => {
+  it("calls onSelect when item is clicked", async () => {
+    const user = userEvent.setup()
+    const handleSelect = vi.fn()
+
+    render(
+      <Command>
+        <CommandInput />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem value="test" onSelect={handleSelect}>
+              Test Item
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    await user.click(screen.getByText("Test Item"))
+    expect(handleSelect).toHaveBeenCalledWith("test")
+  })
+
+  it("navigates with arrow keys", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem value="first">First</CommandItem>
+            <CommandItem value="second">Second</CommandItem>
+            <CommandItem value="third">Third</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    const input = screen.getByPlaceholderText("Search...")
+    await user.click(input)
+    await user.keyboard("{ArrowDown}")
+    await user.keyboard("{ArrowDown}")
+
+    const secondItem = screen.getByText("Second").closest("[cmdk-item]")
+    expect(secondItem).toHaveAttribute("data-selected", "true")
+  })
+
+  it("selects item with Enter key", async () => {
+    const user = userEvent.setup()
+    const handleSelect = vi.fn()
+
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem value="test" onSelect={handleSelect}>
+              Test
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    const input = screen.getByPlaceholderText("Search...")
+    await user.click(input)
+    await user.keyboard("{ArrowDown}")
+    await user.keyboard("{Enter}")
+
+    expect(handleSelect).toHaveBeenCalledWith("test")
+  })
+
+  it("does not call onSelect for disabled items", async () => {
+    const user = userEvent.setup()
+    const handleSelect = vi.fn()
+
+    render(
+      <Command>
+        <CommandInput />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem value="test" disabled onSelect={handleSelect}>
+              Disabled Item
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    await user.click(screen.getByText("Disabled Item"))
+    expect(handleSelect).not.toHaveBeenCalled()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Command accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup heading="Options">
+            <CommandItem>Option 1</CommandItem>
+            <CommandItem>Option 2</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("input has combobox role", () => {
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList />
+      </Command>
+    )
+
+    expect(screen.getByRole("combobox")).toBeInTheDocument()
+  })
+
+  it("list has listbox role", () => {
+    render(
+      <Command>
+        <CommandInput />
+        <CommandList data-testid="list">
+          <CommandGroup>
+            <CommandItem>Item</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    expect(screen.getByRole("listbox")).toBeInTheDocument()
+  })
+
+  it("items have option role", () => {
+    render(
+      <Command>
+        <CommandInput />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem>Item</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    expect(screen.getByRole("option")).toBeInTheDocument()
+  })
+
+  it("is keyboard navigable", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <Command>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem>Item 1</CommandItem>
+            <CommandItem>Item 2</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    )
+
+    const input = screen.getByPlaceholderText("Search...")
+    input.focus()
+    expect(input).toHaveFocus()
+
+    await user.keyboard("{ArrowDown}")
+    // First item should be selected
+    expect(screen.getByText("Item 1").closest("[cmdk-item]")).toHaveAttribute(
+      "data-selected",
+      "true"
+    )
+  })
+})
+```
+
+### Testes de Composição (Dialog)
+
+```tsx
+describe("CommandDialog", () => {
+  it("opens and closes correctly", async () => {
+    const user = userEvent.setup()
+    const handleOpenChange = vi.fn()
+
+    render(
+      <CommandDialog open={true} onOpenChange={handleOpenChange}>
+        <CommandInput placeholder="Search..." />
+        <CommandList>
+          <CommandGroup>
+            <CommandItem>Item</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </CommandDialog>
+    )
+
+    expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument()
+
+    await user.keyboard("{Escape}")
+    expect(handleOpenChange).toHaveBeenCalledWith(false)
+  })
+
+  it("auto-focuses input when opened", () => {
+    render(
+      <CommandDialog open={true} onOpenChange={() => {}}>
+        <CommandInput placeholder="Search..." />
+        <CommandList />
+      </CommandDialog>
+    )
+
+    expect(screen.getByPlaceholderText("Search...")).toHaveFocus()
+  })
+
+  it("has accessible title and description", () => {
+    render(
+      <CommandDialog
+        open={true}
+        onOpenChange={() => {}}
+        title="Command Menu"
+        description="Search for commands"
+      >
+        <CommandInput />
+        <CommandList />
+      </CommandDialog>
+    )
+
+    expect(screen.getByText("Command Menu")).toBeInTheDocument()
+    expect(screen.getByText("Search for commands")).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+#### Virtualização para Listas Grandes
+
+Suporte a listas com milhares de items sem perda de performance.
+
+```tsx
+// Proposta de API
+interface CommandListProps {
+  virtualized?: boolean
+  itemHeight?: number
+  overscan?: number
+}
+
+// Uso
+<CommandList virtualized itemHeight={40}>
+  {/* 10,000+ items */}
+</CommandList>
+```
+
+**Referências:** Mantine (`virtualizedItems`), MUI (`ListboxComponent`), AntD (`virtual`)
+
+#### Loading State Nativo
+
+Estado de carregamento com componente dedicado.
+
+```tsx
+// Proposta de API (já suportado pelo cmdk)
+import { Command } from "cmdk"
+
+<Command.Loading>
+  <Spinner /> Loading...
+</Command.Loading>
+
+// Wrapper ETUS
+<CommandLoading>Carregando...</CommandLoading>
+```
+
+**Referências:** cmdk (`Command.Loading`), Mantine (`loading`), MUI (`loading`)
+
+### Prioridade Média
+
+#### Highlight de Match
+
+Destaque visual do texto que matcheia a busca.
+
+```tsx
+// Proposta de API
+interface CommandItemProps {
+  highlightMatch?: boolean
+  highlightClassName?: string
+}
+
+// Uso
+<CommandItem highlightMatch>
+  React Native {/* "nat" seria destacado */}
+</CommandItem>
+```
+
+**Referências:** Blueprint Omnibar, Algolia InstantSearch
+
+#### Footer com Ações
+
+Área fixa no rodapé para ações ou dicas de atalho.
+
+```tsx
+// Proposta de API
+<Command>
+  <CommandInput />
+  <CommandList />
+  <CommandFooter>
+    <span>↑↓ para navegar</span>
+    <span>↵ para selecionar</span>
+    <span>esc para fechar</span>
+  </CommandFooter>
+</Command>
+```
+
+**Referências:** Spotlight (Mantine), Linear, Vercel
+
+### Prioridade Baixa
+
+#### Recent Items
+
+Seção de items recentes com persistência.
+
+```tsx
+// Proposta de API
+<Command>
+  <CommandInput />
+  <CommandList>
+    <CommandRecents max={5} />
+    <CommandGroup heading="Todos">
+      {/* items */}
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+**Referências:** Spotlight (Mantine), Raycast
+
+#### Multiple Selection
+
+Seleção múltipla de items.
+
+```tsx
+// Proposta de API
+interface CommandProps {
+  multiple?: boolean
+  value?: string[]
+  onValueChange?: (value: string[]) => void
+}
+
+// Uso
+<Command multiple value={selected} onValueChange={setSelected}>
+  <CommandItem value="a">
+    <Checkbox checked={selected.includes("a")} />
+    Item A
+  </CommandItem>
+</Command>
+```
+
+**Referências:** MUI Autocomplete (`multiple`), Mantine MultiSelect
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `virtualized` | ✅ Implementar | Performance crítica para listas grandes |
+| `CommandLoading` | ✅ Implementar | Já suportado pelo cmdk, apenas wrapper |
+| `highlightMatch` | ⚠️ Avaliar | Útil mas complexo de implementar |
+| `CommandFooter` | ⚠️ Avaliar | Bom UX, pode ser feito via composição |
+| `CommandRecents` | ❌ Evitar | Muito específico, melhor via composição |
+| `multiple` | ❌ Evitar | Muda natureza do componente, usar MultiSelect |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Command](https://ui.shadcn.com/docs/components/command) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **cmdk** | [Documentation](https://cmdk.paco.me) | [pacocoursey/cmdk](https://github.com/pacocoursey/cmdk) |
+| **Mantine** | [Spotlight](https://mantine.dev/x/spotlight/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **MUI** | [Autocomplete](https://mui.com/material-ui/react-autocomplete/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Chakra UI** | [Menu](https://chakra-ui.com/docs/components/menu) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Ant Design** | [AutoComplete](https://ant.design/components/auto-complete) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Autocomplete](https://nextui.org/docs/components/autocomplete) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | [Combobox](https://headlessui.com/react/combobox) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Combobox](https://ariakit.org/components/combobox) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [SearchBox](https://react.fluentui.dev/?path=/docs/components-searchbox--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [ComboBox](https://carbondesignsystem.com/components/combo-box/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [Omnibar](https://blueprintjs.com/docs/#select/omnibar) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [WAI-ARIA APG - Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - ARIA: combobox role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role)
+
+### Ferramentas Utilizadas
+
+- [cmdk](https://cmdk.paco.me) - Command menu primitivo
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Radix Dialog](https://www.radix-ui.com/primitives/docs/components/dialog)
+- [Lucide Icons](https://lucide.dev/icons/)