@etus/ui 0.1.1 → 0.1.3

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

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