@etus/ui 0.1.0

package/src/components/forms/Autocomplete/README.md

@@ -0,0 +1,919 @@
+# Autocomplete
+
+## Visão Geral
+
+O **Autocomplete** é um componente de busca com sugestões dinâmicas, projetado para cenários que exigem filtragem assíncrona, debounce de input e estados de carregamento. Combina o padrão Combobox com suporte completo a navegação por teclado e acessibilidade.
+
+### Casos de Uso
+
+- Busca de usuários, produtos ou entidades com dados do servidor
+- Campos de busca com sugestões em tempo real
+- Seleção de itens de grandes conjuntos de dados
+- Formulários com autocompletar baseado em API
+- Pesquisa com debounce para otimização de requisições
+
+### Classificação
+
+**Categoria:** Form
+**Dependências:** `lucide-react` (ícones), `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Input padrão com borda | `border-input`, `shadow-xs` |
+| `filled` | Fundo preenchido | `bg-muted`, `border-transparent` |
+| `flushed` | Apenas borda inferior | `border-b-input`, sem shadow |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura | Padding | Uso |
+|---------|--------|---------|-----|
+| `sm` | `h-8` (32px) | `px-2.5 py-1` | Espaços compactos |
+| `md` | `h-9` (36px) | `px-3 py-2` | Uso geral |
+| `lg` | `h-10` (40px) | `px-3.5 py-2` | Formulários destacados |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparência base |
+| Hover | `dark:hover:bg-input/50` | Leve destaque no dark mode |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
+| Loading | `data-loading`, spinner | Spinner animado no input |
+| Disabled | `disabled:opacity-50` | 50% opacidade, cursor not-allowed |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho |
+| Open | `data-state="open"` | Dropdown visível com animação |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input              /* Borda padrão */
+--muted              /* Fundo filled */
+--ring               /* Focus ring */
+--background         /* Fundo base */
+--popover            /* Fundo dropdown */
+--popover-foreground /* Texto dropdown */
+--accent             /* Item destacado */
+--accent-foreground  /* Texto item destacado */
+--muted-foreground   /* Texto placeholder/empty */
+
+/* Espaçamento */
+gap-2              /* Entre ícone e texto no item */
+p-1                /* Padding da lista */
+mt-1               /* Margem do dropdown */
+
+/* Tipografia */
+text-sm            /* 14px */
+
+/* Bordas */
+rounded-md         /* var(--radius) */
+rounded-sm         /* Items da lista */
+
+/* Transições */
+transition-[color,box-shadow]  /* Input */
+animate-in/animate-out         /* Dropdown */
+```
+
+### data-slot
+
+```html
+<div data-slot="autocomplete">
+  <input data-slot="autocomplete-input" />
+  <div data-slot="autocomplete-content">
+    <div data-slot="autocomplete-list">
+      <div data-slot="autocomplete-item">...</div>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `string` | - | Valor controlado do autocomplete |
+| `defaultValue` | `string` | - | Valor inicial para uso não-controlado |
+| `options` | `AutocompleteOption[]` | `[]` | Array de opções para o dropdown |
+| `placeholder` | `string` | `"Search..."` | Texto placeholder do input |
+| `loading` | `boolean` | `false` | Mostra spinner de carregamento |
+| `disabled` | `boolean` | `false` | Desabilita o componente |
+| `emptyMessage` | `string` | `"No results found."` | Mensagem quando não há resultados |
+| `loadingMessage` | `string` | `"Loading..."` | Mensagem durante carregamento |
+| `debounceMs` | `number` | `300` | Delay em ms para debounce do input |
+| `minChars` | `number` | `1` | Mínimo de caracteres para mostrar sugestões |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho visual do componente |
+| `variant` | `"default" \| "filled" \| "flushed"` | `"default"` | Variante visual |
+| `open` | `boolean` | - | Estado controlado do dropdown |
+| `defaultOpen` | `boolean` | `false` | Estado inicial do dropdown |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"div">` exceto `onChange`
+
+### AutocompleteOption
+
+```typescript
+interface AutocompleteOption {
+  value: string      // Valor usado na seleção
+  label: string      // Texto exibido ao usuário
+  disabled?: boolean // Opção desabilitada
+}
+```
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onChange` | `(value: string) => void` | Disparado quando uma opção é selecionada |
+| `onInputChange` | `(value: string) => void` | Disparado ao digitar (após debounce) |
+| `onOpenChange` | `(open: boolean) => void` | Disparado ao abrir/fechar dropdown |
+
+### TypeScript
+
+```typescript
+import type {
+  AutocompleteProps,
+  AutocompleteOption,
+  AutocompleteSize,
+  AutocompleteVariant
+} from "@etus/ui"
+
+// AutocompleteProps inclui:
+interface AutocompleteProps {
+  value?: string
+  defaultValue?: string
+  options?: AutocompleteOption[]
+  placeholder?: string
+  loading?: boolean
+  disabled?: boolean
+  emptyMessage?: string
+  loadingMessage?: string
+  onChange?: (value: string) => void
+  onInputChange?: (value: string) => void
+  debounceMs?: number
+  minChars?: number
+  size?: AutocompleteSize
+  variant?: AutocompleteVariant
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  // ... + todas as props de <div> exceto onChange
+}
+
+// Tipos derivados
+type AutocompleteSize = "sm" | "md" | "lg"
+type AutocompleteVariant = "default" | "filled" | "flushed"
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | React Aria | PrimeReact |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:----------:|:----------:|
+| **Async loading** | ✓ | ~ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Debounce** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **minChars** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **Variantes** | 3 | - | - | 4 | 3 | 4 | 2 | 4 | - | - | 3 | 2 | - | 3 |
+| **Tamanhos** | 3 | - | - | 4 | 3 | 5 | 3 | 4 | - | - | 4 | 2 | - | 3 |
+| **CVA/cva** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **Controlled/Uncontrolled** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Empty state** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Loading state** | ✓ | ~ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Multi-select** | - | - | - | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Creatable** | - | - | - | ✓ | ✓ | ✓ | - | - | - | ✓ | - | - | - | - |
+| **Grouping** | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Virtualization** | - | - | - | - | ✓ | ✓ | ✓ | - | - | - | ✓ | - | ✓ | ✓ |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `value` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `options` | ✓ | ✓ | ✓ | `data` | `options` | `items` | ✓ |
+| `onChange` | ✓ | ✓ | ✓ | ✓ | `onSelect` | `onSelectionChange` | ✓ |
+| `onInputChange` | ✓ | ✓ | ✓ | `onSearchChange` | `onSearch` | ✓ | ✓ |
+| `loading` | ✓ | `isLoading` | `loading` | `loading` | `loading` | `isLoading` | - |
+| `disabled` | ✓ | `isDisabled` | ✓ | ✓ | ✓ | `isDisabled` | ✓ |
+| `placeholder` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `debounceMs` | ✓ | - | - | - | - | - | - |
+| `minChars` | ✓ | - | - | - | - | - | - |
+| `emptyMessage` | ✓ | `noOptionsMessage` | `noOptionsText` | `nothingFoundMessage` | `notFoundContent` | `emptyContent` | - |
+| `open` | ✓ | `isOpen` | `open` | ✓ | `open` | `isOpen` | ✓ |
+| `filterOption` | - | - | ✓ | `filter` | `filterOption` | - | - |
+| `clearable` | - | `isClearable` | ✓ | `clearable` | `allowClear` | `isClearable` | ✓ |
+| `freeSolo` | - | `isCreatable` | ✓ | `creatable` | - | `allowsCustomValue` | `allowFreeform` |
+
+#### Análise por Categoria
+
+**Headless/Primitivos (máxima flexibilidade):**
+- **Radix UI** - Combobox primitivo, sem estilos
+- **Headless UI** - Combobox renderless, focado em a11y
+- **Ariakit** - useCombobox hook, máxima composabilidade
+- **React Aria** - useComboBox hook, padrão ouro a11y
+
+**Styled/Opinionated (produtividade):**
+- **Chakra UI** - AsyncSelect, Select creatable
+- **MUI** - Autocomplete completo, virtualization
+- **Mantine** - Autocomplete, Select, MultiSelect separados
+- **Ant Design** - AutoComplete + Select combinados
+
+**Hybrid (meio-termo):**
+- **Shadcn/ui** - Command (cmdk) para buscas avançadas
+- **NextUI** - Autocomplete baseado em React Aria
+- **ETUS** - Autocomplete com debounce built-in
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso | Valor |
+|----------|-----|-------|
+| `role="combobox"` | No input | Identifica como combobox |
+| `aria-expanded` | No input | `true` quando dropdown aberto |
+| `aria-haspopup` | No input | `"listbox"` |
+| `aria-autocomplete` | No input | `"list"` |
+| `aria-controls` | No input | ID do listbox quando aberto |
+| `aria-activedescendant` | No input | ID da opção destacada |
+| `role="listbox"` | Na lista | Container de opções |
+| `role="option"` | Em cada item | Opção selecionável |
+| `aria-selected` | Em cada item | `true` na opção selecionada |
+| `aria-disabled` | Em cada item | `true` em opções desabilitadas |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `↓` (ArrowDown) | Move para próxima opção / Abre dropdown |
+| `↑` (ArrowUp) | Move para opção anterior / Abre dropdown |
+| `Enter` | Seleciona opção destacada |
+| `Escape` | Fecha dropdown e remove foco |
+| `Tab` | Fecha dropdown e move foco |
+| Digitação | Filtra opções (com debounce) |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegação por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+
+// Scroll automático para item destacado
+scrollIntoView({ block: "nearest" })
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Input | `--foreground` | `--background` | ≥ 4.5:1 |
+| Placeholder | `--muted-foreground` | `--background` | ≥ 4.5:1 |
+| Item | `--popover-foreground` | `--popover` | ≥ 4.5:1 |
+| Item highlighted | `--accent-foreground` | `--accent` | ≥ 4.5:1 |
+
+### Screen Readers
+
+- Input anuncia role `combobox` e estado expandido
+- Navegação por setas anuncia opções via `aria-activedescendant`
+- Seleção anuncia item escolhido
+- Estado de loading e empty são anunciados
+
+### Reduced Motion
+
+```css
+/* Respeitar preferência do usuário */
+@media (prefers-reduced-motion: reduce) {
+  .animate-in, .animate-out {
+    animation: none;
+  }
+  .animate-spin {
+    animation: none;
+  }
+}
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **ARIA completo** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-activedescendant** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Screen reader tested** | ~ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ~ | ~ | ✓ | ✓ | ✓ |
+| **Reduced motion** | ✓ | ✓ | - | - | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **RTL support** | - | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Autocomplete } from "@etus/ui"
+
+function Example() {
+  const options = [
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+    { value: "angular", label: "Angular" },
+  ]
+
+  return (
+    <Autocomplete
+      options={options}
+      placeholder="Select a framework..."
+      onChange={(value) => console.log("Selected:", value)}
+    />
+  )
+}
+```
+
+### Busca Assíncrona
+
+```tsx
+import { useState } from "react"
+import { Autocomplete, type AutocompleteOption } from "@etus/ui"
+
+function AsyncExample() {
+  const [options, setOptions] = useState<AutocompleteOption[]>([])
+  const [loading, setLoading] = useState(false)
+
+  const handleSearch = async (query: string) => {
+    setLoading(true)
+    try {
+      const response = await fetch(`/api/users?search=${query}`)
+      const users = await response.json()
+      setOptions(users.map((u: User) => ({
+        value: u.id,
+        label: u.name
+      })))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <Autocomplete
+      options={options}
+      loading={loading}
+      onInputChange={handleSearch}
+      placeholder="Search users..."
+      debounceMs={300}
+      minChars={2}
+    />
+  )
+}
+```
+
+### Variantes
+
+```tsx
+<Autocomplete variant="default" placeholder="Default variant" />
+<Autocomplete variant="filled" placeholder="Filled variant" />
+<Autocomplete variant="flushed" placeholder="Flushed variant" />
+```
+
+### Tamanhos
+
+```tsx
+<Autocomplete size="sm" placeholder="Small" />
+<Autocomplete size="md" placeholder="Medium (default)" />
+<Autocomplete size="lg" placeholder="Large" />
+```
+
+### Controlado vs Não-Controlado
+
+```tsx
+// Controlado
+function ControlledExample() {
+  const [value, setValue] = useState("")
+
+  return (
+    <Autocomplete
+      value={value}
+      onChange={setValue}
+      options={options}
+    />
+  )
+}
+
+// Não-controlado
+function UncontrolledExample() {
+  return (
+    <Autocomplete
+      defaultValue="react"
+      options={options}
+    />
+  )
+}
+```
+
+### Com Opções Desabilitadas
+
+```tsx
+const options = [
+  { value: "1", label: "Available" },
+  { value: "2", label: "Disabled", disabled: true },
+  { value: "3", label: "Also available" },
+]
+
+<Autocomplete options={options} />
+```
+
+### Customização de Mensagens
+
+```tsx
+<Autocomplete
+  options={options}
+  loading={loading}
+  emptyMessage="Nenhum resultado encontrado."
+  loadingMessage="Carregando..."
+  placeholder="Pesquisar..."
+/>
+```
+
+### Em Formulário
+
+```tsx
+import { useForm, Controller } from "react-hook-form"
+
+function FormExample() {
+  const { control, handleSubmit } = useForm()
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="framework"
+        control={control}
+        render={({ field }) => (
+          <Autocomplete
+            value={field.value}
+            onChange={field.onChange}
+            options={frameworks}
+            placeholder="Select framework"
+          />
+        )}
+      />
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+### Controle de Estado do Dropdown
+
+```tsx
+function ControlledDropdown() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open Autocomplete</Button>
+      <Autocomplete
+        open={open}
+        onOpenChange={setOpen}
+        options={options}
+      />
+    </>
+  )
+}
+```
+
+### Composição com Label e Erro
+
+```tsx
+import { Label, Autocomplete } from "@etus/ui"
+
+function WithLabel() {
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="country">Country</Label>
+      <Autocomplete
+        id="country"
+        options={countries}
+        placeholder="Select country..."
+      />
+      <p className="text-sm text-destructive">Please select a country</p>
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Autocomplete.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { Autocomplete } from "./Autocomplete"
+
+const options = [
+  { value: "1", label: "Option 1" },
+  { value: "2", label: "Option 2" },
+  { value: "3", label: "Option 3" },
+]
+
+describe("Autocomplete", () => {
+  it("renders with placeholder", () => {
+    render(<Autocomplete placeholder="Search..." />)
+    expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument()
+  })
+
+  it("has correct ARIA attributes", () => {
+    render(<Autocomplete options={options} />)
+    const input = screen.getByRole("combobox")
+    expect(input).toHaveAttribute("aria-expanded", "false")
+    expect(input).toHaveAttribute("aria-haspopup", "listbox")
+    expect(input).toHaveAttribute("aria-autocomplete", "list")
+  })
+
+  it("applies size classes", () => {
+    render(<Autocomplete size="lg" />)
+    const input = screen.getByRole("combobox")
+    expect(input).toHaveClass("h-10")
+  })
+
+  it("applies variant classes", () => {
+    render(<Autocomplete variant="filled" />)
+    const input = screen.getByRole("combobox")
+    expect(input).toHaveClass("bg-muted")
+  })
+
+  it("has data-slot attributes", () => {
+    render(<Autocomplete />)
+    expect(screen.getByRole("combobox").closest("[data-slot]"))
+      .toHaveAttribute("data-slot", "autocomplete")
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("Autocomplete interactions", () => {
+  it("opens dropdown on focus and typing", async () => {
+    const user = userEvent.setup()
+    render(<Autocomplete options={options} minChars={1} />)
+
+    const input = screen.getByRole("combobox")
+    await user.type(input, "O")
+
+    expect(input).toHaveAttribute("aria-expanded", "true")
+    expect(screen.getByRole("listbox")).toBeInTheDocument()
+  })
+
+  it("selects option on click", async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+
+    render(<Autocomplete options={options} onChange={onChange} />)
+
+    const input = screen.getByRole("combobox")
+    await user.type(input, "Option")
+    await user.click(screen.getByText("Option 1"))
+
+    expect(onChange).toHaveBeenCalledWith("1")
+  })
+
+  it("debounces onInputChange", async () => {
+    vi.useFakeTimers()
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    const onInputChange = vi.fn()
+
+    render(
+      <Autocomplete
+        onInputChange={onInputChange}
+        debounceMs={300}
+      />
+    )
+
+    await user.type(screen.getByRole("combobox"), "test")
+
+    // Should not be called immediately
+    expect(onInputChange).not.toHaveBeenCalled()
+
+    // Advance timers
+    vi.advanceTimersByTime(300)
+
+    expect(onInputChange).toHaveBeenCalledWith("test")
+    vi.useRealTimers()
+  })
+
+  it("respects minChars before showing suggestions", async () => {
+    const user = userEvent.setup()
+    render(<Autocomplete options={options} minChars={3} />)
+
+    const input = screen.getByRole("combobox")
+    await user.type(input, "Op")
+
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument()
+
+    await user.type(input, "t")
+
+    expect(screen.getByRole("listbox")).toBeInTheDocument()
+  })
+
+  it("closes on Escape", async () => {
+    const user = userEvent.setup()
+    render(<Autocomplete options={options} />)
+
+    const input = screen.getByRole("combobox")
+    await user.type(input, "Option")
+    await user.keyboard("{Escape}")
+
+    expect(input).toHaveAttribute("aria-expanded", "false")
+  })
+})
+```
+
+### Testes de Teclado
+
+```tsx
+describe("Autocomplete keyboard navigation", () => {
+  it("navigates with arrow keys", async () => {
+    const user = userEvent.setup()
+    render(<Autocomplete options={options} />)
+
+    const input = screen.getByRole("combobox")
+    await user.type(input, "O")
+    await user.keyboard("{ArrowDown}")
+
+    const listbox = screen.getByRole("listbox")
+    const firstOption = listbox.querySelector("[data-highlighted=true]")
+    expect(firstOption).toHaveTextContent("Option 1")
+
+    await user.keyboard("{ArrowDown}")
+    const secondOption = listbox.querySelector("[data-highlighted=true]")
+    expect(secondOption).toHaveTextContent("Option 2")
+  })
+
+  it("selects with Enter", async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+
+    render(<Autocomplete options={options} onChange={onChange} />)
+
+    await user.type(screen.getByRole("combobox"), "O")
+    await user.keyboard("{ArrowDown}{Enter}")
+
+    expect(onChange).toHaveBeenCalledWith("1")
+  })
+
+  it("skips disabled options", async () => {
+    const user = userEvent.setup()
+    const optionsWithDisabled = [
+      { value: "1", label: "Option 1" },
+      { value: "2", label: "Option 2", disabled: true },
+      { value: "3", label: "Option 3" },
+    ]
+
+    render(<Autocomplete options={optionsWithDisabled} />)
+
+    await user.type(screen.getByRole("combobox"), "O")
+    await user.keyboard("{ArrowDown}{ArrowDown}")
+
+    const listbox = screen.getByRole("listbox")
+    const highlighted = listbox.querySelector("[data-highlighted=true]")
+    expect(highlighted).toHaveTextContent("Option 3")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Autocomplete accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Autocomplete options={options} placeholder="Search" />
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations when open", async () => {
+    const user = userEvent.setup()
+    const { container } = render(<Autocomplete options={options} />)
+
+    await user.type(screen.getByRole("combobox"), "O")
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("announces loading state", () => {
+    render(<Autocomplete loading loadingMessage="Loading..." />)
+    // Spinner is aria-hidden, message is visible in dropdown
+    expect(screen.getByRole("combobox")).toBeInTheDocument()
+  })
+
+  it("is disabled when disabled prop is true", () => {
+    render(<Autocomplete disabled />)
+    expect(screen.getByRole("combobox")).toBeDisabled()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems:
+
+### ✅ Implementado
+
+- Async loading com estado de carregamento
+- Debounce configurável para input
+- Mínimo de caracteres para sugestões
+- Três variantes visuais
+- Três tamanhos
+- Controle de estado (controlado/não-controlado)
+- Navegação completa por teclado
+- ARIA compliant (combobox pattern)
+
+### Prioridade Alta
+
+#### `clearable`
+
+Botão para limpar seleção.
+
+```tsx
+// Proposta de API
+interface AutocompleteProps {
+  clearable?: boolean
+  onClear?: () => void
+}
+
+// Uso
+<Autocomplete clearable onClear={() => setSelection(null)} />
+```
+
+**Referências:** Chakra (`isClearable`), MUI, Mantine, AntD (`allowClear`)
+
+#### `filterOption`
+
+Função customizada para filtrar opções localmente.
+
+```tsx
+// Proposta de API
+interface AutocompleteProps {
+  filterOption?: (option: AutocompleteOption, inputValue: string) => boolean
+}
+
+// Uso
+<Autocomplete
+  filterOption={(opt, input) =>
+    opt.label.toLowerCase().includes(input.toLowerCase())
+  }
+/>
+```
+
+**Referências:** MUI, Mantine (`filter`), AntD
+
+### Prioridade Média
+
+#### `grouping`
+
+Agrupar opções por categoria.
+
+```tsx
+// Proposta de API
+interface AutocompleteOption {
+  group?: string
+}
+
+// Uso
+const options = [
+  { value: "1", label: "React", group: "JavaScript" },
+  { value: "2", label: "Django", group: "Python" },
+]
+```
+
+**Referências:** Shadcn (Command groups), MUI, Mantine, AntD
+
+#### `multiselect`
+
+Seleção múltipla.
+
+```tsx
+// Proposta de API
+interface AutocompleteProps {
+  multiple?: boolean
+  value?: string[]
+  onChange?: (values: string[]) => void
+}
+
+// Uso
+<Autocomplete multiple value={selected} onChange={setSelected} />
+```
+
+**Referências:** Chakra, MUI, Mantine, AntD, React Aria
+
+### Prioridade Baixa
+
+#### `creatable`
+
+Permitir criar novas opções.
+
+```tsx
+// Proposta de API
+interface AutocompleteProps {
+  creatable?: boolean
+  onCreate?: (value: string) => void
+}
+
+// Uso
+<Autocomplete creatable onCreate={(v) => addOption(v)} />
+```
+
+**Referências:** Chakra (`isCreatable`), MUI (`freeSolo`), Mantine
+
+#### `virtualization`
+
+Para grandes listas de opções.
+
+```tsx
+// Proposta de API
+interface AutocompleteProps {
+  virtualized?: boolean
+  itemHeight?: number
+}
+```
+
+**Referências:** MUI, Mantine, AntD, React Aria, PrimeReact
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `clearable` | ✅ Implementar | UX básica esperada |
+| `filterOption` | ✅ Implementar | Flexibilidade local |
+| `grouping` | ✅ Implementar | Organização visual |
+| `multiselect` | ⚠️ Avaliar | Componente separado? |
+| `creatable` | ⚠️ Avaliar | Complexidade |
+| `virtualization` | ❌ Sob demanda | Performance edge case |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Componente | GitHub |
+|---------------|------------|--------|
+| **Shadcn/ui** | [Combobox](https://ui.shadcn.com/docs/components/combobox) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Select](https://www.radix-ui.com/primitives/docs/components/select) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [ComboBox](https://react-spectrum.adobe.com/react-aria/ComboBox.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Autocomplete](https://chakra-ui.com/docs/components/autocomplete) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Autocomplete](https://mui.com/material-ui/react-autocomplete/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Autocomplete](https://mantine.dev/core/autocomplete/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **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** | [Combobox](https://react.fluentui.dev/?path=/docs/components-combobox) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [ComboBox](https://carbondesignsystem.com/components/dropdown/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [Suggest](https://blueprintjs.com/docs/#select/suggest) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [AutoComplete](https://primereact.org/autocomplete/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [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)
+- [Combobox Autocomplete Best Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)