npm - @etus/ui - Versions diffs - 0.1.1 → 0.1.3 - Mend

@etus/ui 0.1.1 → 0.1.3

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/forms/Combobox/README.md DELETED Viewed

@@ -1,923 +0,0 @@
-# Combobox
-## Visao Geral
-O **Combobox** e um componente de selecao com busca integrada do Design System ETUS, combinando funcionalidades de input e dropdown. Permite ao usuario filtrar opcoes digitando e navegar via teclado, sendo ideal para listas extensas onde a busca facilita a localizacao do item desejado.
-### Casos de Uso
-- Selecao de pais/estado/cidade em formularios
-- Busca e selecao de usuarios ou clientes
-- Filtro de categorias ou tags
-- Selecao de timezone ou idioma
-- Qualquer cenario com muitas opcoes onde busca e essencial
-### Classificacao
-**Categoria:** Organism
-**Dependencias:** `@radix-ui/react-popover`, `cmdk`, `lucide-react`, `class-variance-authority`
----
-## Design Specs
-### Variantes (`variant`)
-| Variante | Uso | Tokens |
-|----------|-----|--------|
-| `default` | Uso padrao, formularios gerais | `border-input`, `shadow-xs` |
-| `filled` | Enfase visual, destaque | `bg-muted`, `border-transparent` |
-| `flushed` | Minimalista, inline | Sem bordas laterais/topo, apenas `border-b` |
-### Tamanhos (`size`)
-| Tamanho | Altura | Padding | Uso |
-|---------|--------|---------|-----|
-| `sm` | `h-8` (32px) | `px-2.5 py-1` | Espacos compactos, tabelas |
-| `md` | `h-9` (36px) | `px-3 py-2` | Uso geral |
-| `lg` | `h-10` (40px) | `px-3.5 py-2` | Destaque, formularios principais |
-### Estados
-| Estado | Classes/Atributos | Comportamento |
-|--------|-------------------|---------------|
-| Default | - | Aparencia base |
-| Hover | `dark:hover:bg-input/50` | Leve destaque |
-| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
-| Open | `aria-expanded="true"` | Dropdown visivel com animacao |
-| Disabled | `disabled:opacity-50` | 50% opacidade, sem pointer events |
-| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho |
-### Tokens Utilizados
-```css
-/* Cores */
---popover            /* Fundo do dropdown */
---popover-foreground /* Texto do dropdown */
---muted-foreground   /* Placeholder e icones */
---accent             /* Item selecionado */
---accent-foreground  /* Texto item selecionado */
---ring               /* Focus ring */
---input              /* Borda default */
---border             /* Bordas gerais */
-/* Espacamento */
-gap-2                /* Entre icone e texto */
-p-1                  /* Padding lista */
-sideOffset={4}       /* Distancia do trigger */
-/* Tipografia */
-text-sm              /* 14px */
-text-base            /* 16px, size lg */
-/* Bordas */
-rounded-md           /* var(--radius) */
-rounded-sm           /* Items */
-/* Transicoes */
-transition-[color,box-shadow]
-animate-in/out       /* Animacoes Radix */
-```
-### data-slot
-```html
-<button data-slot="combobox">...</button>
-<div data-slot="combobox-content">...</div>
-<input data-slot="combobox-input">...</input>
-<div data-slot="combobox-item">...</div>
-```
----
-## API
-### Props
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `options` | `ComboboxOption[]` | - | **Obrigatorio.** Array de opcoes para o dropdown |
-| `value` | `string` | - | Valor controlado da selecao |
-| `defaultValue` | `string` | - | Valor inicial para uso nao-controlado |
-| `placeholder` | `string` | `"Select an option..."` | Texto quando nenhum valor selecionado |
-| `searchPlaceholder` | `string` | `"Search..."` | Placeholder do campo de busca |
-| `emptyMessage` | `string` | `"No results found."` | Mensagem quando busca nao encontra resultados |
-| `disabled` | `boolean` | `false` | Desabilita o combobox |
-| `open` | `boolean` | - | Estado controlado de abertura do dropdown |
-| `defaultOpen` | `boolean` | `false` | Estado inicial de abertura para uso nao-controlado |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho visual do trigger |
-| `variant` | `"default" \| "filled" \| "flushed"` | `"default"` | Estilo visual do trigger |
-| `className` | `string` | - | Classes CSS adicionais para o trigger |
-> Herda todas as props de `React.ComponentProps<"button">` exceto `onChange` e `value`
-### ComboboxOption
-```typescript
-interface ComboboxOption {
-  value: string    // Valor usado para selecao
-  label: string    // Texto exibido na opcao
-  disabled?: boolean // Desabilita esta opcao especifica
-}
-```
-### Callbacks
-| Callback | Tipo | Descricao |
-|----------|------|-----------|
-| `onChange` | `(value: string) => void` | Disparado quando usuario seleciona uma opcao |
-| `onOpenChange` | `(open: boolean) => void` | Disparado quando dropdown abre/fecha |
-| `onSearch` | `(query: string) => void` | Disparado quando usuario digita na busca. Util para filtragem async/server-side |
-### TypeScript
-```typescript
-import type {
-  ComboboxProps,
-  ComboboxOption,
-  ComboboxSize,
-  ComboboxVariant
-} from "@etus/ui"
-// ComboboxProps inclui:
-interface ComboboxProps {
-  options: ComboboxOption[]
-  value?: string
-  defaultValue?: string
-  placeholder?: string
-  searchPlaceholder?: string
-  emptyMessage?: string
-  disabled?: boolean
-  open?: boolean
-  defaultOpen?: boolean
-  onOpenChange?: (open: boolean) => void
-  onChange?: (value: string) => void
-  onSearch?: (query: string) => void
-  size?: ComboboxSize
-  variant?: ComboboxVariant
-  // ... + todas as props de <button> exceto onChange/value
-}
-// Tipos derivados
-type ComboboxSize = "sm" | "md" | "lg"
-type ComboboxVariant = "default" | "filled" | "flushed"
-```
-### Comparativo com Design Systems de Referencia
-#### Matriz de Features (12 Design Systems)
-| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon |
-|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|
-| **Variantes** | 3 | - | - | 2 | 3 | 4 | 2 | 3 | - | - | 3 | 2 |
-| **Tamanhos** | 3 | 1 | - | 3 | 3 | 4 | 3 | 3 | - | - | 3 | 3 |
-| **Busca integrada** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Async/Server filter** | ✓ | ~ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
-| **Multi-select** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Creatable** | - | - | - | ✓ | ✓ | ✓ | - | - | - | ✓ | - | - |
-| **Groups/Categories** | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
-| **Virtualization** | - | - | - | - | ✓ | ✓ | ✓ | - | - | - | ✓ | - |
-| **Loading state** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
-| **Clear button** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
-| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Portal** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-#### Comparativo de Nomenclatura por Design System
-| Design System | Componente | Prop Busca | Prop Options |
-|---------------|------------|------------|--------------|
-| **ETUS** | `Combobox` | `onSearch` | `options` |
-| **Shadcn/ui** | `Combobox` (exemplo) | Manual | `CommandItem` children |
-| **Chakra UI** | `AutoComplete` | `onSearch` | `items` |
-| **MUI** | `Autocomplete` | `onInputChange` | `options` |
-| **Mantine** | `Autocomplete` / `Select` | `onSearchChange` | `data` |
-| **Ant Design** | `AutoComplete` / `Select` | `onSearch` | `options` |
-| **NextUI** | `Autocomplete` | `onInputChange` | `items` |
-| **Headless UI** | `Combobox` | `onChange` (input) | `Combobox.Option` children |
-| **Ariakit** | `Combobox` | `setValue` | `ComboboxItem` children |
-| **Fluent UI** | `Combobox` | `onInput` | `Option` children |
-| **Carbon** | `ComboBox` | `onChange` | `items` |
-#### Comparativo de Props por Design System
-| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Headless |
-|------|:----:|:------:|:---:|:-------:|:----:|:------:|:--------:|
-| `options`/`items` | ✓ | ✓ | ✓ | `data` | ✓ | ✓ | children |
-| `value` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `onChange` | ✓ | ✓ | ✓ | ✓ | ✓ | `onSelectionChange` | ✓ |
-| `onSearch` | ✓ | ✓ | `onInputChange` | ✓ | ✓ | ✓ | - |
-| `disabled` | ✓ | `isDisabled` | ✓ | ✓ | ✓ | `isDisabled` | ✓ |
-| `placeholder` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
-| `emptyMessage` | ✓ | `emptyState` | `noOptionsText` | `nothingFoundMessage` | `notFoundContent` | `emptyContent` | - |
-| `open` | ✓ | `isOpen` | ✓ | - | ✓ | `isOpen` | - |
-| `loading` | - | `isLoading` | `loading` | - | `loading` | `isLoading` | - |
-| `clearable` | - | `isClearable` | `clearable` | ✓ | `allowClear` | `isClearable` | - |
-| `multiple` | - | ✓ | ✓ | - | `mode` | `selectionMode` | `multiple` |
-| `creatable` | - | `creatable` | `freeSolo` | `creatable` | - | - | - |
-| `groupBy` | - | - | ✓ | `group` | - | - | - |
----
-## Acessibilidade (A11y)
-### ARIA Attributes
-| Atributo | Uso |
-|----------|-----|
-| `role="combobox"` | Identifica o trigger como combobox |
-| `aria-expanded` | Indica se dropdown esta aberto |
-| `aria-haspopup="listbox"` | Indica que controla um listbox |
-| `aria-disabled` | Quando `disabled={true}` |
-| `aria-activedescendant` | Item atualmente focado (gerenciado por cmdk) |
-| `aria-autocomplete="list"` | Indica que sugestoes sao filtradas |
-### Suporte a Teclado
-| Tecla | Acao |
-|-------|------|
-| `Tab` | Move foco para/do combobox |
-| `Enter` | Abre dropdown / Seleciona item focado |
-| `Space` | Abre dropdown quando fechado |
-| `Escape` | Fecha dropdown |
-| `ArrowDown` | Move foco para proximo item |
-| `ArrowUp` | Move foco para item anterior |
-| `Home` | Move foco para primeiro item |
-| `End` | Move foco para ultimo item |
-| Letras | Filtra opcoes pelo texto digitado |
-### Focus Management
-```tsx
-// Focus visible apenas para navegacao por teclado
-focus-visible:border-ring
-focus-visible:ring-ring/50
-focus-visible:ring-[3px]
-// Items recebem foco visual via data-[selected]
-data-[selected=true]:bg-accent
-data-[selected=true]:text-accent-foreground
-```
-### Contraste de Cores
-Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
-| Elemento | Foreground | Background | Ratio |
-|----------|------------|------------|-------|
-| Trigger | `--foreground` | `--background` | >= 4.5:1 |
-| Placeholder | `--muted-foreground` | `--background` | >= 4.5:1 |
-| Item | `--popover-foreground` | `--popover` | >= 4.5:1 |
-| Item Selected | `--accent-foreground` | `--accent` | >= 4.5:1 |
-### Screen Readers
-- Anuncia numero de resultados encontrados
-- Anuncia quando dropdown abre/fecha
-- Anuncia opcao selecionada
-- Anuncia quando nenhum resultado encontrado
-### Reduced Motion
-```tsx
-// Animacoes respeitam preferencia do usuario
-@media (prefers-reduced-motion: reduce) {
-  [data-slot="combobox-content"] {
-    animation: none;
-  }
-}
-```
-### Comparativo A11y (12 Design Systems)
-| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
-|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
-| **ARIA automatico** | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ~ | ~ | ~ | ✓ | ✓ | ✓ |
-| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Type-ahead** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Live regions** | ~ | ✓ | - | ✓ | ✓ | ~ | ✓ | ~ | ~ | ✓ | ✓ | ✓ |
-| **Reduced motion** | ~ | ✓ | - | - | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
-| **Screen reader tested** | - | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ~ | ~ | ✓ | ✓ | ✓ |
-**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
----
-## Exemplos
-### Uso Basico
-```tsx
-import { Combobox } from "@etus/ui"
-const fruits = [
-  { value: "apple", label: "Apple" },
-  { value: "banana", label: "Banana" },
-  { value: "orange", label: "Orange" },
-]
-function Example() {
-  return (
-    <Combobox
-      options={fruits}
-      placeholder="Select a fruit..."
-      onChange={(value) => console.log("Selected:", value)}
-    />
-  )
-}
-```
-### Controlado vs Nao-Controlado
-```tsx
-// Nao-controlado (gerencia estado internamente)
-<Combobox
-  options={options}
-  defaultValue="apple"
-  onChange={(value) => console.log(value)}
-/>
-// Controlado (voce gerencia o estado)
-function ControlledExample() {
-  const [value, setValue] = useState("")
-  return (
-    <Combobox
-      options={options}
-      value={value}
-      onChange={setValue}
-    />
-  )
-}
-```
-### Variantes
-```tsx
-<Combobox variant="default" options={options} placeholder="Default" />
-<Combobox variant="filled" options={options} placeholder="Filled" />
-<Combobox variant="flushed" options={options} placeholder="Flushed" />
-```
-### Tamanhos
-```tsx
-<Combobox size="sm" options={options} placeholder="Small" />
-<Combobox size="md" options={options} placeholder="Medium" />
-<Combobox size="lg" options={options} placeholder="Large" />
-```
-### Com Opcoes Desabilitadas
-```tsx
-const options = [
-  { value: "active", label: "Active" },
-  { value: "pending", label: "Pending", disabled: true },
-  { value: "completed", label: "Completed" },
-]
-<Combobox options={options} placeholder="Select status..." />
-```
-### Dropdown Controlado
-```tsx
-function ControlledDropdown() {
-  const [open, setOpen] = useState(false)
-  return (
-    <>
-      <Combobox
-        options={options}
-        open={open}
-        onOpenChange={setOpen}
-      />
-      <Button onClick={() => setOpen(true)}>Open Combobox</Button>
-    </>
-  )
-}
-```
-### Busca Server-Side (Async)
-```tsx
-function AsyncCombobox() {
-  const [options, setOptions] = useState<ComboboxOption[]>([])
-  const [loading, setLoading] = useState(false)
-  const handleSearch = async (query: string) => {
-    if (query.length < 2) {
-      setOptions([])
-      return
-    }
-    setLoading(true)
-    try {
-      const response = await fetch(`/api/search?q=${query}`)
-      const data = await response.json()
-      setOptions(data.map((item) => ({
-        value: item.id,
-        label: item.name,
-      })))
-    } finally {
-      setLoading(false)
-    }
-  }
-  return (
-    <Combobox
-      options={options}
-      onSearch={handleSearch}
-      placeholder="Search users..."
-      emptyMessage={loading ? "Loading..." : "No users found."}
-    />
-  )
-}
-```
-### Em Formulario
-```tsx
-import { useForm, Controller } from "react-hook-form"
-function FormExample() {
-  const { control, handleSubmit } = useForm()
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <Controller
-        name="country"
-        control={control}
-        render={({ field }) => (
-          <Combobox
-            options={countries}
-            value={field.value}
-            onChange={field.onChange}
-            placeholder="Select country..."
-          />
-        )}
-      />
-      <Button type="submit">Submit</Button>
-    </form>
-  )
-}
-```
-### Com Label e Erro
-```tsx
-import { Label } from "@etus/ui"
-function LabeledCombobox() {
-  const [error, setError] = useState<string | null>(null)
-  return (
-    <div className="space-y-2">
-      <Label htmlFor="category">Category</Label>
-      <Combobox
-        id="category"
-        options={categories}
-        aria-invalid={!!error}
-        aria-describedby={error ? "category-error" : undefined}
-      />
-      {error && (
-        <p id="category-error" className="text-sm text-destructive">
-          {error}
-        </p>
-      )}
-    </div>
-  )
-}
-```
-### Customizando Mensagens
-```tsx
-<Combobox
-  options={options}
-  placeholder="Selecione uma opcao..."
-  searchPlaceholder="Buscar..."
-  emptyMessage="Nenhum resultado encontrado."
-/>
-```
----
-## Testes
-### Testes Unitarios
-```tsx
-// Combobox.test.tsx
-import { render, screen } from "@testing-library/react"
-import userEvent from "@testing-library/user-event"
-import { describe, expect, it, vi } from "vitest"
-import { Combobox } from "./Combobox"
-const options = [
-  { value: "apple", label: "Apple" },
-  { value: "banana", label: "Banana" },
-  { value: "orange", label: "Orange" },
-]
-describe("Combobox", () => {
-  it("renders with placeholder", () => {
-    render(<Combobox options={options} placeholder="Select fruit..." />)
-    expect(screen.getByRole("combobox")).toHaveTextContent("Select fruit...")
-  })
-  it("opens dropdown on click", async () => {
-    const user = userEvent.setup()
-    render(<Combobox options={options} />)
-    await user.click(screen.getByRole("combobox"))
-    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
-  })
-  it("displays all options when opened", async () => {
-    const user = userEvent.setup()
-    render(<Combobox options={options} />)
-    await user.click(screen.getByRole("combobox"))
-    expect(screen.getByText("Apple")).toBeInTheDocument()
-    expect(screen.getByText("Banana")).toBeInTheDocument()
-    expect(screen.getByText("Orange")).toBeInTheDocument()
-  })
-  it("applies variant classes", () => {
-    render(<Combobox options={options} variant="filled" />)
-    expect(screen.getByRole("combobox")).toHaveClass("bg-muted")
-  })
-  it("applies size classes", () => {
-    render(<Combobox options={options} size="lg" />)
-    expect(screen.getByRole("combobox")).toHaveClass("h-10")
-  })
-  it("has data-slot attribute", () => {
-    render(<Combobox options={options} />)
-    expect(screen.getByRole("combobox")).toHaveAttribute("data-slot", "combobox")
-  })
-})
-```
-### Testes de Interacao
-```tsx
-describe("Combobox interactions", () => {
-  it("calls onChange when option selected", async () => {
-    const user = userEvent.setup()
-    const handleChange = vi.fn()
-    render(<Combobox options={options} onChange={handleChange} />)
-    await user.click(screen.getByRole("combobox"))
-    await user.click(screen.getByText("Banana"))
-    expect(handleChange).toHaveBeenCalledWith("banana")
-  })
-  it("filters options when typing", async () => {
-    const user = userEvent.setup()
-    render(<Combobox options={options} />)
-    await user.click(screen.getByRole("combobox"))
-    await user.type(screen.getByPlaceholderText("Search..."), "app")
-    expect(screen.getByText("Apple")).toBeInTheDocument()
-    expect(screen.queryByText("Banana")).not.toBeInTheDocument()
-  })
-  it("shows empty message when no results", async () => {
-    const user = userEvent.setup()
-    render(<Combobox options={options} emptyMessage="Nothing found" />)
-    await user.click(screen.getByRole("combobox"))
-    await user.type(screen.getByPlaceholderText("Search..."), "xyz")
-    expect(screen.getByText("Nothing found")).toBeInTheDocument()
-  })
-  it("closes dropdown after selection", async () => {
-    const user = userEvent.setup()
-    render(<Combobox options={options} />)
-    await user.click(screen.getByRole("combobox"))
-    await user.click(screen.getByText("Apple"))
-    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "false")
-  })
-  it("does not select disabled options", async () => {
-    const user = userEvent.setup()
-    const handleChange = vi.fn()
-    const optionsWithDisabled = [
-      ...options,
-      { value: "disabled", label: "Disabled", disabled: true },
-    ]
-    render(<Combobox options={optionsWithDisabled} onChange={handleChange} />)
-    await user.click(screen.getByRole("combobox"))
-    await user.click(screen.getByText("Disabled"))
-    expect(handleChange).not.toHaveBeenCalled()
-  })
-})
-```
-### Testes de Acessibilidade
-```tsx
-import { axe, toHaveNoViolations } from "jest-axe"
-expect.extend(toHaveNoViolations)
-describe("Combobox accessibility", () => {
-  it("has no accessibility violations", async () => {
-    const { container } = render(<Combobox options={options} />)
-    const results = await axe(container)
-    expect(results).toHaveNoViolations()
-  })
-  it("has correct ARIA attributes", () => {
-    render(<Combobox options={options} />)
-    const combobox = screen.getByRole("combobox")
-    expect(combobox).toHaveAttribute("aria-haspopup", "listbox")
-    expect(combobox).toHaveAttribute("aria-expanded", "false")
-  })
-  it("can be navigated with keyboard", async () => {
-    const user = userEvent.setup()
-    const handleChange = vi.fn()
-    render(<Combobox options={options} onChange={handleChange} />)
-    // Open with Enter
-    screen.getByRole("combobox").focus()
-    await user.keyboard("{Enter}")
-    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
-    // Navigate and select
-    await user.keyboard("{ArrowDown}")
-    await user.keyboard("{Enter}")
-    expect(handleChange).toHaveBeenCalled()
-  })
-  it("closes with Escape", async () => {
-    const user = userEvent.setup()
-    render(<Combobox options={options} />)
-    await user.click(screen.getByRole("combobox"))
-    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
-    await user.keyboard("{Escape}")
-    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "false")
-  })
-})
-```
-### Testes de Estado Controlado
-```tsx
-describe("Combobox controlled state", () => {
-  it("respects controlled value", () => {
-    render(<Combobox options={options} value="banana" />)
-    expect(screen.getByRole("combobox")).toHaveTextContent("Banana")
-  })
-  it("respects controlled open state", () => {
-    render(<Combobox options={options} open={true} />)
-    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
-  })
-  it("calls onOpenChange when toggled", async () => {
-    const user = userEvent.setup()
-    const handleOpenChange = vi.fn()
-    render(<Combobox options={options} onOpenChange={handleOpenChange} />)
-    await user.click(screen.getByRole("combobox"))
-    expect(handleOpenChange).toHaveBeenCalledWith(true)
-  })
-  it("calls onSearch when typing", async () => {
-    const user = userEvent.setup()
-    const handleSearch = vi.fn()
-    render(<Combobox options={options} onSearch={handleSearch} />)
-    await user.click(screen.getByRole("combobox"))
-    await user.type(screen.getByPlaceholderText("Search..."), "test")
-    expect(handleSearch).toHaveBeenCalledWith("t")
-    expect(handleSearch).toHaveBeenCalledWith("te")
-    expect(handleSearch).toHaveBeenCalledWith("tes")
-    expect(handleSearch).toHaveBeenCalledWith("test")
-  })
-})
-```
----
-## Roadmap / Features Futuras
-Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
-### Prioridade Alta
-#### `loading`
-Estado de carregamento para buscas async.
-```tsx
-// Proposta de API
-interface ComboboxProps {
-  loading?: boolean
-}
-// Uso
-<Combobox options={options} loading={isLoading} />
-```
-**Referencias:** Chakra (`isLoading`), MUI (`loading`), AntD (`loading`), NextUI (`isLoading`)
-#### `clearable` / `onClear`
-Botao para limpar selecao.
-```tsx
-// Proposta de API
-interface ComboboxProps {
-  clearable?: boolean
-  onClear?: () => void
-}
-// Uso
-<Combobox options={options} clearable onClear={() => setValue("")} />
-```
-**Referencias:** MUI, Mantine, AntD (`allowClear`), NextUI (`isClearable`)
-### Prioridade Media
-#### `multiple`
-Suporte a selecao multipla.
-```tsx
-// Proposta de API
-interface ComboboxProps {
-  multiple?: boolean
-  value?: string | string[]
-  onChange?: (value: string | string[]) => void
-}
-// Uso
-<Combobox multiple options={options} onChange={(values) => console.log(values)} />
-```
-**Referencias:** MUI, Mantine, AntD (`mode="multiple"`), Headless UI
-#### `groups`
-Suporte a agrupamento de opcoes.
-```tsx
-// Proposta de API
-interface ComboboxGroup {
-  label: string
-  options: ComboboxOption[]
-}
-interface ComboboxProps {
-  options: ComboboxOption[] | ComboboxGroup[]
-}
-// Uso
-<Combobox
-  options={[
-    { label: "Fruits", options: [{ value: "apple", label: "Apple" }] },
-    { label: "Vegetables", options: [{ value: "carrot", label: "Carrot" }] },
-  ]}
-/>
-```
-**Referencias:** Shadcn/ui, MUI (`groupBy`), AntD, Mantine
-#### `virtualization`
-Renderizacao virtualizada para listas grandes.
-```tsx
-// Proposta de API
-interface ComboboxProps {
-  virtualized?: boolean
-  itemHeight?: number
-}
-// Uso
-<Combobox options={largeList} virtualized />
-```
-**Referencias:** MUI, Mantine, AntD
-### Prioridade Baixa
-#### `creatable`
-Permitir criar novas opcoes.
-```tsx
-// Proposta de API
-interface ComboboxProps {
-  creatable?: boolean
-  onCreate?: (value: string) => void
-}
-// Uso
-<Combobox
-  creatable
-  options={options}
-  onCreate={(newValue) => addOption(newValue)}
-/>
-```
-**Referencias:** Chakra, MUI (`freeSolo`), Mantine, Ariakit
-#### `renderOption`
-Customizar renderizacao de opcoes.
-```tsx
-// Proposta de API
-interface ComboboxProps {
-  renderOption?: (option: ComboboxOption, state: { selected: boolean }) => ReactNode
-}
-// Uso
-<Combobox
-  options={users}
-  renderOption={(user, { selected }) => (
-    <div className="flex items-center gap-2">
-      <Avatar src={user.avatar} />
-      <span>{user.label}</span>
-      {selected && <CheckIcon />}
-    </div>
-  )}
-/>
-```
-**Referencias:** MUI, Mantine, AntD
-### Decisoes de Design
-| Feature | Recomendacao | Justificativa |
-|---------|--------------|---------------|
-| `loading` | ✓ Implementar | Essencial para async, UX melhor |
-| `clearable` | ✓ Implementar | Alta demanda, padrao em forms |
-| `multiple` | ✓ Implementar | Caso de uso comum |
-| `groups` | ✓ Implementar | Melhora organizacao de opcoes |
-| `virtualization` | ⚠️ Avaliar | Necessario apenas para listas muito grandes |
-| `creatable` | ⚠️ Avaliar | Complexidade adicional |
-| `renderOption` | ❌ Evitar | Usar composicao com children |
----
-## Referencias
-### Design Systems Analisados
-| Design System | Documentacao Combobox/Autocomplete | GitHub |
-|---------------|-----------------------------------|--------|
-| **Shadcn/ui** | [Combobox](https://ui.shadcn.com/docs/components/combobox) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
-| **Radix UI** | [Popover](https://www.radix-ui.com/primitives/docs/components/popover) | [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--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) |
-| **cmdk** | [Command](https://cmdk.paco.me/) | [pacocoursey/cmdk](https://github.com/pacocoursey/cmdk) |
-### Especificacoes e Padroes
-- [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
-- [CVA - Class Variance Authority](https://cva.style/docs)
-- [Tailwind CSS](https://tailwindcss.com/docs)
-- [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover)
-- [cmdk](https://cmdk.paco.me/)
-- [Lucide Icons](https://lucide.dev/icons/)