npm - @etus/ui - Versions diffs - 0.1.0 → 0.1.2 - Mend

@etus/ui 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1080) hide show

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

@@ -1,1259 +0,0 @@
-# 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/)