@etus/ui 0.1.0

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

@@ -0,0 +1,897 @@
+# MultiSelect
+
+## Visao Geral
+
+O **MultiSelect** e um componente de selecao multipla do Design System ETUS que permite aos usuarios escolher varios itens de uma lista. Os itens selecionados sao exibidos como tags removiveis no campo de entrada, combinando a funcionalidade de um combobox com a visualizacao de chips/tags.
+
+### Casos de Uso
+
+- Selecao de multiplas categorias ou tags
+- Filtros com multiplos valores
+- Atribuicao de labels ou etiquetas
+- Selecao de destinatarios em formularios de email
+- Configuracao de permissoes ou roles
+
+### Classificacao
+
+**Categoria:** Molecule
+**Dependencias:** `@radix-ui/react-popover`, `cmdk`, `class-variance-authority`, `lucide-react`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Uso padrao | `border-input`, `shadow-xs` |
+| `filled` | Maior destaque visual | `bg-muted`, `border-transparent` |
+| `flushed` | Estilo minimalista | Sem bordas laterais, apenas borda inferior |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura Minima | Padding | Uso |
+|---------|---------------|---------|-----|
+| `sm` | `min-h-8` (32px) | `px-2.5 py-1` | Espacos compactos, tabelas |
+| `md` | `min-h-9` (36px) | `px-3 py-2` | Uso geral |
+| `lg` | `min-h-10` (40px) | `px-3.5 py-2` | CTAs, formularios destacados |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparencia base |
+| Hover | `dark:hover:bg-input/50` | Leve destaque em dark mode |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
+| Open | `aria-expanded="true"` | Dropdown visivel |
+| Disabled | `disabled:opacity-50` | 50% opacidade, sem interacoes |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--primary          /* Checkbox selecionado */
+--primary-foreground
+--secondary        /* Fundo das tags */
+--secondary-foreground
+--muted            /* Fundo variant filled */
+--muted-foreground /* Placeholder, icones */
+--popover          /* Fundo dropdown */
+--popover-foreground
+--accent           /* Hover em items */
+--accent-foreground
+--ring             /* Focus ring */
+--input            /* Borda padrao */
+--border           /* Bordas gerais */
+
+/* Espacamento */
+gap-1              /* Entre tags */
+gap-2              /* Entre trigger e chevron */
+
+/* Tipografia */
+text-sm            /* 14px */
+text-xs            /* Tags */
+font-medium        /* Tags */
+
+/* Bordas */
+rounded-md         /* Trigger e content */
+rounded-sm         /* Tags e items */
+
+/* Transicoes */
+transition-[color,box-shadow]
+```
+
+### data-slot
+
+```html
+<div data-slot="multi-select">
+  <div data-slot="multi-select-trigger">
+    <span data-slot="multi-select-tag" data-value="value">...</span>
+  </div>
+</div>
+<div data-slot="multi-select-content">
+  <input data-slot="multi-select-input" />
+  <div data-slot="multi-select-item" data-selected data-disabled>...</div>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `options` | `MultiSelectOption[]` | - | **Obrigatorio.** Array de opcoes disponiveis |
+| `value` | `string[]` | - | Valor controlado (array de valores selecionados) |
+| `defaultValue` | `string[]` | `[]` | Valor inicial para uso nao-controlado |
+| `placeholder` | `string` | `"Select options..."` | Texto quando nada selecionado |
+| `searchPlaceholder` | `string` | `"Search..."` | Placeholder do campo de busca |
+| `emptyMessage` | `string` | `"No results found."` | Mensagem quando busca nao retorna resultados |
+| `disabled` | `boolean` | `false` | Desabilita o componente |
+| `maxSelected` | `number` | - | Limite maximo de itens selecionaveis |
+| `open` | `boolean` | - | Estado controlado do dropdown |
+| `defaultOpen` | `boolean` | `false` | Estado inicial do dropdown |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback quando dropdown abre/fecha |
+| `onChange` | `(values: string[]) => void` | - | Callback quando selecao muda |
+| `onSearch` | `(query: string) => void` | - | Callback para busca server-side |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho do componente |
+| `variant` | `"default" \| "filled" \| "flushed"` | `"default"` | Estilo visual |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"div">` exceto `onChange`
+
+### MultiSelectOption
+
+```typescript
+interface MultiSelectOption {
+  value: string      // Valor unico da opcao
+  label: string      // Texto exibido
+  disabled?: boolean // Opcao desabilitada
+}
+```
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(values: string[]) => void` | Disparado quando selecao muda |
+| `onOpenChange` | `(open: boolean) => void` | Disparado quando dropdown abre/fecha |
+| `onSearch` | `(query: string) => void` | Disparado a cada caractere digitado na busca |
+
+### TypeScript
+
+```typescript
+import type {
+  MultiSelectProps,
+  MultiSelectOption,
+  MultiSelectSize,
+  MultiSelectVariant
+} from "@etus/ui"
+
+// MultiSelectProps inclui:
+interface MultiSelectProps extends Omit<ComponentProps<"div">, "onChange"> {
+  options: MultiSelectOption[]
+  value?: string[]
+  defaultValue?: string[]
+  placeholder?: string
+  searchPlaceholder?: string
+  emptyMessage?: string
+  disabled?: boolean
+  maxSelected?: number
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  onChange?: (values: string[]) => void
+  onSearch?: (query: string) => void
+  size?: MultiSelectSize
+  variant?: MultiSelectVariant
+}
+
+// Tipos derivados
+type MultiSelectSize = "sm" | "md" | "lg"
+type MultiSelectVariant = "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 |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|
+| **Multi-select nativo** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Tags removiveis** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Busca/Filtro** | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Async/Server search** | ✓ | - | - | - | - | ✓ | ✓ | - | - | - | - | ✓ |
+| **Max selection** | ✓ | - | - | - | - | ✓ | ✓ | - | - | - | - | - |
+| **CVA/cva** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - |
+| **Controlled/Uncontrolled** | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Grupos de opcoes** | - | - | - | - | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ |
+| **Criar opcoes** | - | - | - | - | - | ✓ | ✓ | - | - | - | - | - |
+| **Virtualizacao** | - | - | - | - | - | ✓ | ✓ | - | - | - | - | ✓ |
+| **Clear all** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Select all** | - | - | - | - | - | - | ✓ | - | - | - | - | ✓ |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `options` | ✓ | `options` | - | `data` | `options` | `items` | `options` |
+| `value` | ✓ | ✓ | ✓ | ✓ | ✓ | `selectedKeys` | `selectedOptions` |
+| `onChange` | ✓ | ✓ | ✓ | ✓ | ✓ | `onSelectionChange` | ✓ |
+| `disabled` | ✓ | `isDisabled` | ✓ | ✓ | ✓ | `isDisabled` | ✓ |
+| `placeholder` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `searchable` | ✓* | - | - | ✓ | `showSearch` | - | - |
+| `maxSelected` | ✓ | - | - | `maxSelectedValues` | `maxCount` | - | - |
+| `clearable` | - | `isClearable` | - | `clearable` | `allowClear` | - | - |
+| `loading` | - | - | ✓ | - | `loading` | `isLoading` | - |
+| `creatable` | - | `isCreatable` | - | `creatable` | `mode="tags"` | - | - |
+
+*Busca sempre habilitada no ETUS MultiSelect
+
+#### Analise por Categoria
+
+**Headless/Primitivos (maxima flexibilidade):**
+- **Radix UI** - Nao possui MultiSelect, usar Select + customizacao
+- **Headless UI** - Listbox/Combobox como base
+- **Ariakit** - Combobox com multipla selecao
+- **React Aria** - useListBox + useTag
+
+**Styled/Opinionated (produtividade):**
+- **Chakra UI** - Select com `isMulti`, baseado em react-select
+- **MUI** - Autocomplete com `multiple`
+- **Mantine** - MultiSelect dedicado, muito completo
+- **Ant Design** - Select com `mode="multiple"`, enterprise
+
+**Hybrid (meio-termo):**
+- **Shadcn/ui** - Nao possui, precisa construir com Command + Popover
+- **NextUI** - Select com `selectionMode="multiple"`
+- **ETUS** - MultiSelect dedicado com Popover + cmdk
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="combobox"` | No trigger, indica campo com dropdown |
+| `aria-expanded` | Indica se dropdown esta aberto |
+| `aria-haspopup="listbox"` | Indica que abre uma lista |
+| `aria-disabled` | Quando `disabled={true}` |
+| `aria-label` | No botao de remover tag |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para/do trigger |
+| `Enter` | Abre dropdown / Seleciona item focado |
+| `Space` | Abre dropdown / Seleciona item focado |
+| `Escape` | Fecha dropdown |
+| `ArrowDown` | Abre dropdown / Move para proximo item |
+| `ArrowUp` | Move para item anterior |
+| `Home` | Move para primeiro item |
+| `End` | Move para ultimo item |
+| `Backspace` | Remove ultima tag (quando input vazio) |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+
+// Trigger focavel
+tabIndex={disabled ? -1 : 0}
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Tag | `--secondary-foreground` | `--secondary` | >= 4.5:1 |
+| Item selecionado | `--primary-foreground` | `--primary` | >= 4.5:1 |
+| Placeholder | `--muted-foreground` | `--background` | >= 4.5:1 |
+
+### Screen Readers
+
+- Tags anunciam label e botao "Remove [label]"
+- Items anunciam estado selecionado via checkbox visual
+- Mensagem de lista vazia e anunciada
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Animacoes de entrada/saida desabilitadas */
+  [data-state="open"], [data-state="closed"] {
+    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** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Screen reader** | ~ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ~ | ~ | ✓ | ✓ | ✓ |
+| **Tag removal a11y** | ✓ | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Live regions** | - | ✓ | - | ✓ | - | - | ✓ | - | - | - | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { MultiSelect } from "@etus/ui"
+
+const options = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "cherry", label: "Cherry" },
+  { value: "grape", label: "Grape" },
+]
+
+function Example() {
+  return (
+    <MultiSelect
+      options={options}
+      placeholder="Select fruits..."
+      onChange={(values) => console.log(values)}
+    />
+  )
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react"
+import { MultiSelect } from "@etus/ui"
+
+function ControlledExample() {
+  const [selected, setSelected] = useState<string[]>(["apple"])
+
+  return (
+    <MultiSelect
+      options={options}
+      value={selected}
+      onChange={setSelected}
+    />
+  )
+}
+```
+
+### Com Limite de Selecao
+
+```tsx
+<MultiSelect
+  options={options}
+  maxSelected={3}
+  placeholder="Select up to 3 items..."
+  onChange={(values) => console.log(values)}
+/>
+```
+
+### Variantes
+
+```tsx
+<MultiSelect variant="default" options={options} placeholder="Default" />
+<MultiSelect variant="filled" options={options} placeholder="Filled" />
+<MultiSelect variant="flushed" options={options} placeholder="Flushed" />
+```
+
+### Tamanhos
+
+```tsx
+<MultiSelect size="sm" options={options} placeholder="Small" />
+<MultiSelect size="md" options={options} placeholder="Medium" />
+<MultiSelect size="lg" options={options} placeholder="Large" />
+```
+
+### Com Opcoes Desabilitadas
+
+```tsx
+const optionsWithDisabled = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana", disabled: true },
+  { value: "cherry", label: "Cherry" },
+]
+
+<MultiSelect
+  options={optionsWithDisabled}
+  placeholder="Some options disabled..."
+/>
+```
+
+### Busca Server-Side (Async)
+
+```tsx
+import { useState, useCallback } from "react"
+import { MultiSelect } from "@etus/ui"
+
+function AsyncExample() {
+  const [options, setOptions] = useState<MultiSelectOption[]>([])
+  const [loading, setLoading] = useState(false)
+
+  const handleSearch = useCallback(async (query: string) => {
+    if (!query) {
+      setOptions([])
+      return
+    }
+
+    setLoading(true)
+    try {
+      const response = await fetch(`/api/search?q=${query}`)
+      const data = await response.json()
+      setOptions(data.results)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  return (
+    <MultiSelect
+      options={options}
+      onSearch={handleSearch}
+      searchPlaceholder="Type to search..."
+      emptyMessage={loading ? "Loading..." : "No results found."}
+    />
+  )
+}
+```
+
+### Em Formulario
+
+```tsx
+import { useForm, Controller } from "react-hook-form"
+import { MultiSelect } from "@etus/ui"
+
+function FormExample() {
+  const { control, handleSubmit } = useForm({
+    defaultValues: {
+      categories: []
+    }
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="categories"
+        control={control}
+        rules={{ required: "Select at least one category" }}
+        render={({ field, fieldState }) => (
+          <div>
+            <label>Categories</label>
+            <MultiSelect
+              options={categoryOptions}
+              value={field.value}
+              onChange={field.onChange}
+              aria-invalid={!!fieldState.error}
+            />
+            {fieldState.error && (
+              <span className="text-destructive text-sm">
+                {fieldState.error.message}
+              </span>
+            )}
+          </div>
+        )}
+      />
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```
+
+### Dropdown Controlado
+
+```tsx
+import { useState } from "react"
+import { MultiSelect } from "@etus/ui"
+
+function ControlledOpenExample() {
+  const [open, setOpen] = useState(false)
+  const [selected, setSelected] = useState<string[]>([])
+
+  return (
+    <div>
+      <button onClick={() => setOpen(true)}>Open MultiSelect</button>
+      <MultiSelect
+        options={options}
+        value={selected}
+        onChange={setSelected}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    </div>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+// Full width em mobile
+<MultiSelect
+  options={options}
+  className="w-full sm:w-[300px] lg:w-[400px]"
+  placeholder="Responsive width"
+/>
+
+// Tamanho responsivo via className
+<MultiSelect
+  options={options}
+  className="min-h-8 sm:min-h-9 lg:min-h-10"
+/>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// MultiSelect.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { MultiSelect } from "./MultiSelect"
+
+const options = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "cherry", label: "Cherry" },
+]
+
+describe("MultiSelect", () => {
+  it("renders with placeholder", () => {
+    render(<MultiSelect options={options} placeholder="Select fruits" />)
+    expect(screen.getByText("Select fruits")).toBeInTheDocument()
+  })
+
+  it("renders selected values as tags", () => {
+    render(
+      <MultiSelect
+        options={options}
+        defaultValue={["apple", "banana"]}
+      />
+    )
+    expect(screen.getByText("Apple")).toBeInTheDocument()
+    expect(screen.getByText("Banana")).toBeInTheDocument()
+  })
+
+  it("has combobox role", () => {
+    render(<MultiSelect options={options} />)
+    expect(screen.getByRole("combobox")).toBeInTheDocument()
+  })
+
+  it("applies variant classes", () => {
+    render(<MultiSelect options={options} variant="filled" />)
+    expect(screen.getByRole("combobox")).toHaveClass("bg-muted")
+  })
+
+  it("applies size classes", () => {
+    render(<MultiSelect options={options} size="lg" />)
+    expect(screen.getByRole("combobox")).toHaveClass("min-h-10")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<MultiSelect options={options} />)
+    expect(screen.getByRole("combobox")).toHaveAttribute("data-slot", "multi-select")
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("MultiSelect interactions", () => {
+  it("opens dropdown on click", async () => {
+    const user = userEvent.setup()
+    render(<MultiSelect options={options} />)
+
+    await user.click(screen.getByRole("combobox"))
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
+  })
+
+  it("selects option on click", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+    render(<MultiSelect options={options} onChange={handleChange} />)
+
+    await user.click(screen.getByRole("combobox"))
+    await user.click(screen.getByText("Apple"))
+
+    expect(handleChange).toHaveBeenCalledWith(["apple"])
+  })
+
+  it("removes tag on click", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+    render(
+      <MultiSelect
+        options={options}
+        defaultValue={["apple"]}
+        onChange={handleChange}
+      />
+    )
+
+    await user.click(screen.getByLabelText("Remove Apple"))
+    expect(handleChange).toHaveBeenCalledWith([])
+  })
+
+  it("filters options when searching", async () => {
+    const user = userEvent.setup()
+    render(<MultiSelect 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("respects maxSelected limit", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+    render(
+      <MultiSelect
+        options={options}
+        maxSelected={2}
+        defaultValue={["apple", "banana"]}
+        onChange={handleChange}
+      />
+    )
+
+    await user.click(screen.getByRole("combobox"))
+    await user.click(screen.getByText("Cherry"))
+
+    // Should not add Cherry since max is reached
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("does not open when disabled", async () => {
+    const user = userEvent.setup()
+    render(<MultiSelect options={options} disabled />)
+
+    await user.click(screen.getByRole("combobox"))
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "false")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("MultiSelect accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<MultiSelect options={options} />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("can be navigated with keyboard", async () => {
+    const user = userEvent.setup()
+    render(<MultiSelect options={options} />)
+
+    const trigger = screen.getByRole("combobox")
+    trigger.focus()
+
+    await user.keyboard("{Enter}")
+    expect(trigger).toHaveAttribute("aria-expanded", "true")
+
+    await user.keyboard("{Escape}")
+    expect(trigger).toHaveAttribute("aria-expanded", "false")
+  })
+
+  it("has accessible remove buttons", () => {
+    render(<MultiSelect options={options} defaultValue={["apple"]} />)
+    expect(screen.getByLabelText("Remove Apple")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Estado Controlado
+
+```tsx
+describe("MultiSelect controlled state", () => {
+  it("respects controlled value", () => {
+    const { rerender } = render(
+      <MultiSelect options={options} value={["apple"]} />
+    )
+    expect(screen.getByText("Apple")).toBeInTheDocument()
+
+    rerender(<MultiSelect options={options} value={["banana"]} />)
+    expect(screen.queryByText("Apple")).not.toBeInTheDocument()
+    expect(screen.getByText("Banana")).toBeInTheDocument()
+  })
+
+  it("respects controlled open state", async () => {
+    const user = userEvent.setup()
+    const handleOpenChange = vi.fn()
+
+    render(
+      <MultiSelect
+        options={options}
+        open={false}
+        onOpenChange={handleOpenChange}
+      />
+    )
+
+    await user.click(screen.getByRole("combobox"))
+    expect(handleOpenChange).toHaveBeenCalledWith(true)
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Implementado
+
+- Selecao multipla com tags removiveis
+- Busca/filtro local
+- Suporte a busca server-side (`onSearch`)
+- Limite de selecao (`maxSelected`)
+- Controlled/Uncontrolled
+- Tres variantes visuais
+- Tres tamanhos
+- Opcoes desabilitadas individualmente
+
+### Prioridade Alta
+
+#### `clearAll`
+
+Botao para limpar todas as selecoes de uma vez.
+
+```tsx
+// Proposta de API
+interface MultiSelectProps {
+  clearable?: boolean
+  onClear?: () => void
+}
+
+// Uso
+<MultiSelect clearable options={options} />
+```
+
+**Referencias:** Chakra (`isClearable`), MUI, Mantine (`clearable`), AntD (`allowClear`)
+
+#### `loading`
+
+Estado de carregamento para buscas async.
+
+```tsx
+// Proposta de API
+interface MultiSelectProps {
+  loading?: boolean
+}
+
+// Uso
+<MultiSelect loading options={options} onSearch={handleSearch} />
+```
+
+**Referencias:** MUI, AntD (`loading`), NextUI (`isLoading`)
+
+### Prioridade Media
+
+#### `selectAll`
+
+Opcao para selecionar todos os itens visiveis.
+
+```tsx
+// Proposta de API
+interface MultiSelectProps {
+  showSelectAll?: boolean
+  selectAllLabel?: string
+}
+
+// Uso
+<MultiSelect showSelectAll selectAllLabel="Select all" options={options} />
+```
+
+**Referencias:** AntD, Carbon
+
+#### Grupos de Opcoes
+
+Agrupar opcoes por categoria.
+
+```tsx
+// Proposta de API
+interface MultiSelectOptionGroup {
+  label: string
+  options: MultiSelectOption[]
+}
+
+// Uso
+<MultiSelect
+  options={[
+    { label: "Fruits", options: [{ value: "apple", label: "Apple" }] },
+    { label: "Vegetables", options: [{ value: "carrot", label: "Carrot" }] },
+  ]}
+/>
+```
+
+**Referencias:** MUI, Mantine, AntD, Fluent UI, Carbon
+
+### Prioridade Baixa
+
+#### `creatable`
+
+Permitir criar novas opcoes.
+
+```tsx
+// Proposta de API
+interface MultiSelectProps {
+  creatable?: boolean
+  onCreate?: (value: string) => void
+}
+
+// Uso
+<MultiSelect creatable onCreate={(val) => addOption(val)} options={options} />
+```
+
+**Referencias:** Chakra (`isCreatable`), Mantine (`creatable`), AntD (`mode="tags"`)
+
+#### Virtualizacao
+
+Renderizar apenas itens visiveis para listas grandes.
+
+```tsx
+// Proposta de API
+interface MultiSelectProps {
+  virtualized?: boolean
+  itemHeight?: number
+}
+```
+
+**Referencias:** Mantine, AntD, Carbon
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `clearAll` | Implementar | Alta demanda, UX melhor |
+| `loading` | Implementar | Necessario para async |
+| `selectAll` | Avaliar | Util para listas medias |
+| Grupos | Implementar | Comum em UIs enterprise |
+| `creatable` | Avaliar | Complexidade adicional |
+| Virtualizacao | Avaliar | Necessario para listas grandes |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao | 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** | [useTagGroup](https://react-spectrum.adobe.com/react-aria/useTagGroup.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Select](https://chakra-ui.com/docs/components/select) | [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** | [MultiSelect](https://mantine.dev/core/multi-select/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Select](https://ant.design/components/select) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Select](https://nextui.org/docs/components/select) | [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** | [Dropdown](https://react.fluentui.dev/?path=/docs/components-dropdown) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [MultiSelect](https://carbondesignsystem.com/components/dropdown/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+
+### 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/)
+
+### 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/)