@etus/ui 0.1.0

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

@@ -0,0 +1,1033 @@
+# NativeSelect
+
+## Visão Geral
+
+O **NativeSelect** e um componente de selecao que utiliza o elemento HTML `<select>` nativo, oferecendo a experiencia padrao do navegador com estilizacao consistente do Design System ETUS. Ideal para formularios onde a acessibilidade nativa e o comportamento mobile otimizado sao prioridades.
+
+### Quando Usar
+
+| Cenario | Recomendacao |
+|---------|--------------|
+| Formularios simples | **NativeSelect** - Melhor performance e acessibilidade nativa |
+| Listas curtas (< 10 opcoes) | **NativeSelect** - Experiencia mobile otimizada |
+| Listas longas ou complexas | **Select** (Radix) - Busca, virtualizacao, customizacao |
+| Multi-selecao | **MultiSelect** - Chips, busca, tags |
+| Opcoes com icones/avatars | **Select** (Radix) - Renderizacao customizada |
+| SEO e acessibilidade critica | **NativeSelect** - Semantica HTML nativa |
+
+### Vantagens do Select Nativo
+
+- **Performance**: Zero JavaScript para interacao basica
+- **Acessibilidade**: Suporte completo a leitores de tela sem configuracao
+- **Mobile**: Interface nativa otimizada (picker nativo iOS/Android)
+- **SEO**: Semantica HTML pura, indexavel
+- **Bundle Size**: Sem dependencias adicionais
+
+### Classificacao
+
+**Categoria:** Form Control
+**Dependencias:** `lucide-react` (icone chevron)
+**Componentes Relacionados:** `Select`, `Field`, `Form`
+
+---
+
+## Design Specs
+
+### Anatomia
+
+```
++------------------------------------------+
+| NativeSelect (wrapper)                   |
+|  +------------------------------------+  |
+|  | <select>              | ChevronDown|  |
+|  +------------------------------------+  |
++------------------------------------------+
+```
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Borda `border-input`, fundo transparente |
+| Hover | `dark:hover:bg-input/50` | Leve escurecimento (dark mode) |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50`, borda `border-ring` |
+| Disabled | `disabled:opacity-50` | 50% opacidade, cursor not-allowed, wrapper com `has-[select:disabled]:opacity-50` |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho, borda `border-destructive` |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input             /* Borda default */
+--ring              /* Focus ring */
+--destructive       /* Estado invalido */
+--muted-foreground  /* Icone chevron */
+--primary           /* Selection background */
+--primary-foreground /* Selection text */
+--background        /* Fundo dark mode: bg-input/30 */
+
+/* Espacamento */
+h-9                 /* Altura: 36px */
+px-3                /* Padding horizontal */
+py-2                /* Padding vertical */
+pr-9                /* Padding right (espaco para icone) */
+
+/* Tipografia */
+text-sm             /* 14px */
+
+/* Bordas */
+rounded-md          /* var(--radius) */
+
+/* Transicoes */
+transition-[color,box-shadow]  /* Suave em cores e sombras */
+
+/* Icone */
+size-4              /* 16px */
+right-3.5           /* Posicionamento */
+opacity-50          /* Sutileza visual */
+```
+
+### data-slot
+
+```html
+<div data-slot="native-select-wrapper">
+  <select data-slot="native-select">
+    <optgroup data-slot="native-select-optgroup">
+      <option data-slot="native-select-option">...</option>
+    </optgroup>
+  </select>
+  <ChevronDownIcon data-slot="native-select-icon" />
+</div>
+```
+
+---
+
+## API
+
+### NativeSelect
+
+Componente principal que renderiza o `<select>` nativo estilizado.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais para o `<select>` |
+| `disabled` | `boolean` | `false` | Desabilita a selecao |
+| `required` | `boolean` | `false` | Marca como obrigatorio |
+| `name` | `string` | - | Nome do campo para formularios |
+| `value` | `string` | - | Valor selecionado (controlado) |
+| `defaultValue` | `string` | - | Valor inicial (nao-controlado) |
+| `children` | `ReactNode` | - | Options e OptGroups |
+| `ref` | `Ref<HTMLSelectElement>` | - | Referencia ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"select">`
+
+### NativeSelectOption
+
+Componente para opcoes individuais.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `value` | `string` | - | Valor da opcao |
+| `disabled` | `boolean` | `false` | Desabilita a opcao |
+| `children` | `ReactNode` | - | Texto da opcao |
+
+> Herda todas as props de `React.ComponentProps<"option">`
+
+### NativeSelectOptGroup
+
+Componente para agrupar opcoes.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `label` | `string` | - | Label do grupo (obrigatorio) |
+| `disabled` | `boolean` | `false` | Desabilita todas as opcoes do grupo |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Options do grupo |
+
+> Herda todas as props de `React.ComponentProps<"optgroup">`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(event: ChangeEvent<HTMLSelectElement>) => void` | Disparado ao mudar selecao |
+| `onFocus` | `(event: FocusEvent<HTMLSelectElement>) => void` | Disparado ao receber foco |
+| `onBlur` | `(event: FocusEvent<HTMLSelectElement>) => void` | Disparado ao perder foco |
+
+### TypeScript
+
+```typescript
+import type { ComponentProps } from "react"
+
+// Props do componente principal
+type NativeSelectProps = ComponentProps<"select">
+
+// Props da opcao
+type NativeSelectOptionProps = ComponentProps<"option">
+
+// Props do grupo
+type NativeSelectOptGroupProps = ComponentProps<"optgroup">
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:------:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| **Native select** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ | ✓ |
+| **Custom dropdown** | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **OptGroup** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Placeholder** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **Tamanhos** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | - | ✓ |
+| **Variantes** | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - | - | - |
+| **Left icon** | - | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - | - | ✓ |
+| **Clearable** | - | - | - | - | - | - | ✓ | ✓ | ✓ | - | - | - | - | - | ✓ |
+| **Searchable** | - | - | - | - | - | - | ✓ | ✓ | - | ✓ | ✓ | - | - | - | ✓ |
+| **Multi-select** | - | - | - | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Async options** | - | - | - | - | - | - | - | ✓ | - | - | - | - | - | - | ✓ |
+
+#### Comparativo de Nomenclatura
+
+| Design System | Componente Nativo | Componente Custom |
+|---------------|-------------------|-------------------|
+| **ETUS** | `NativeSelect` | `Select` |
+| **Shadcn/ui** | (parte do Select) | `Select` (Radix-based) |
+| **React Aria** | - | `Select` |
+| **Chakra UI** | `Select` (native) | `Menu` (dropdown) |
+| **MUI** | `NativeSelect` | `Select` |
+| **Mantine** | `NativeSelect` | `Select` |
+| **Ant Design** | - | `Select` |
+| **NextUI** | - | `Select` |
+| **Fluent UI** | `Dropdown` (native) | `Combobox` |
+| **Carbon** | `Select` (native) | `Dropdown` |
+| **Blueprint** | `HTMLSelect` | `Select` |
+| **PrimeReact** | - | `Dropdown` |
+
+#### Analise por Categoria
+
+**Componentes Nativos (melhor a11y/mobile):**
+- **ETUS** - `NativeSelect` focado em simplicidade
+- **MUI** - `NativeSelect` com sx prop
+- **Mantine** - `NativeSelect` muito completo
+- **Chakra** - `Select` e nativo por padrao
+- **Carbon** - `Select` nativo, otimizado para forms
+
+**Componentes Custom (mais features):**
+- **Radix/Shadcn** - `Select` headless, estilizavel
+- **React Aria** - Hooks para comportamento
+- **Ariakit** - Maximo controle
+- **Headless UI** - Renderless
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+O `<select>` nativo fornece semantica ARIA automaticamente:
+
+| Atributo | Comportamento |
+|----------|---------------|
+| `role="combobox"` | Automatico pelo navegador |
+| `aria-expanded` | Automatico pelo navegador |
+| `aria-haspopup="listbox"` | Automatico pelo navegador |
+| `aria-disabled` | Quando `disabled={true}` |
+| `aria-required` | Quando `required={true}` |
+| `aria-invalid` | Quando validacao falha |
+| `aria-describedby` | Conecta com mensagem de erro |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para/do select |
+| `Space` / `Enter` | Abre dropdown |
+| `Arrow Up/Down` | Navega entre opcoes |
+| `Home` / `End` | Vai para primeira/ultima opcao |
+| `Esc` | Fecha dropdown |
+| `Page Up/Down` | Navega em blocos |
+| Typing | Busca por primeira letra |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Texto | `--foreground` | `--background` | >= 4.5:1 |
+| Placeholder | `--muted-foreground` | `--background` | >= 4.5:1 |
+| Icone | `--muted-foreground` | `--background` | >= 3:1 (decorativo) |
+| Focus ring | `--ring` | `--background` | >= 3:1 |
+
+### Screen Readers
+
+- Leitores de tela anunciam automaticamente:
+  - Label associada via `id` + `htmlFor`
+  - Opcao selecionada
+  - Estado expandido/colapsado
+  - Numero de opcoes disponiveis
+- Usar `<FieldLabel>` ou `<label>` sempre
+- OptGroups sao anunciados como grupos
+
+### Validacao com Forms
+
+```tsx
+// Integracao com FieldError e aria-describedby
+<Field>
+  <FieldLabel htmlFor="country">Pais</FieldLabel>
+  <NativeSelect
+    id="country"
+    aria-invalid={!!errors.country}
+    aria-describedby={errors.country ? "country-error" : undefined}
+  >
+    <NativeSelectOption value="">Selecione...</NativeSelectOption>
+    <NativeSelectOption value="br">Brasil</NativeSelectOption>
+  </NativeSelect>
+  {errors.country && (
+    <FieldError id="country-error">{errors.country.message}</FieldError>
+  )}
+</Field>
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:---------:|:----------:|
+| **ARIA nativo** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ~ |
+| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Screen reader** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ~ |
+| **Mobile picker** | ✓ | - | - | - | - | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | - |
+| **RTL support** | - | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | - |
+| **High contrast** | - | ✓ | - | - | - | - | - | - | - | - | ✓ | ✓ | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { NativeSelect, NativeSelectOption } from "@etus/ui"
+
+function Example() {
+  return (
+    <NativeSelect>
+      <NativeSelectOption value="">Selecione uma opcao</NativeSelectOption>
+      <NativeSelectOption value="option1">Opcao 1</NativeSelectOption>
+      <NativeSelectOption value="option2">Opcao 2</NativeSelectOption>
+      <NativeSelectOption value="option3">Opcao 3</NativeSelectOption>
+    </NativeSelect>
+  )
+}
+```
+
+### Com Field (Label + Descricao + Erro)
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+} from "@etus/ui"
+import { NativeSelect, NativeSelectOption } from "@etus/ui"
+
+function FieldExample() {
+  return (
+    <Field>
+      <FieldLabel htmlFor="country">Pais</FieldLabel>
+      <FieldDescription>
+        Selecione seu pais de residencia
+      </FieldDescription>
+      <NativeSelect id="country" name="country">
+        <NativeSelectOption value="">Selecione...</NativeSelectOption>
+        <NativeSelectOption value="br">Brasil</NativeSelectOption>
+        <NativeSelectOption value="pt">Portugal</NativeSelectOption>
+        <NativeSelectOption value="us">Estados Unidos</NativeSelectOption>
+      </NativeSelect>
+    </Field>
+  )
+}
+```
+
+### Com OptGroup (Opcoes Agrupadas)
+
+```tsx
+import {
+  NativeSelect,
+  NativeSelectOption,
+  NativeSelectOptGroup,
+} from "@etus/ui"
+
+function GroupedExample() {
+  return (
+    <NativeSelect defaultValue="">
+      <NativeSelectOption value="">Selecione um carro</NativeSelectOption>
+
+      <NativeSelectOptGroup label="Europeus">
+        <NativeSelectOption value="bmw">BMW</NativeSelectOption>
+        <NativeSelectOption value="audi">Audi</NativeSelectOption>
+        <NativeSelectOption value="mercedes">Mercedes</NativeSelectOption>
+      </NativeSelectOptGroup>
+
+      <NativeSelectOptGroup label="Japoneses">
+        <NativeSelectOption value="toyota">Toyota</NativeSelectOption>
+        <NativeSelectOption value="honda">Honda</NativeSelectOption>
+        <NativeSelectOption value="nissan">Nissan</NativeSelectOption>
+      </NativeSelectOptGroup>
+
+      <NativeSelectOptGroup label="Americanos">
+        <NativeSelectOption value="ford">Ford</NativeSelectOption>
+        <NativeSelectOption value="chevrolet">Chevrolet</NativeSelectOption>
+      </NativeSelectOptGroup>
+    </NativeSelect>
+  )
+}
+```
+
+### Controlado (useState)
+
+```tsx
+import { useState } from "react"
+import { NativeSelect, NativeSelectOption } from "@etus/ui"
+
+function ControlledExample() {
+  const [value, setValue] = useState("")
+
+  return (
+    <>
+      <NativeSelect
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      >
+        <NativeSelectOption value="">Selecione...</NativeSelectOption>
+        <NativeSelectOption value="small">Pequeno</NativeSelectOption>
+        <NativeSelectOption value="medium">Medio</NativeSelectOption>
+        <NativeSelectOption value="large">Grande</NativeSelectOption>
+      </NativeSelect>
+
+      <p>Valor selecionado: {value || "Nenhum"}</p>
+    </>
+  )
+}
+```
+
+### Com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+import { Field, FieldLabel, FieldError } from "@etus/ui"
+import { NativeSelect, NativeSelectOption } from "@etus/ui"
+import { Button } from "@etus/ui"
+
+const schema = z.object({
+  priority: z.string().min(1, "Selecione uma prioridade"),
+})
+
+type FormData = z.infer<typeof schema>
+
+function FormExample() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm<FormData>({
+    resolver: zodResolver(schema),
+    defaultValues: { priority: "" },
+  })
+
+  const onSubmit = (data: FormData) => {
+    console.log(data)
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Field data-invalid={!!errors.priority}>
+        <FieldLabel htmlFor="priority">Prioridade</FieldLabel>
+        <NativeSelect
+          id="priority"
+          aria-invalid={!!errors.priority}
+          {...register("priority")}
+        >
+          <NativeSelectOption value="">Selecione...</NativeSelectOption>
+          <NativeSelectOption value="low">Baixa</NativeSelectOption>
+          <NativeSelectOption value="medium">Media</NativeSelectOption>
+          <NativeSelectOption value="high">Alta</NativeSelectOption>
+          <NativeSelectOption value="urgent">Urgente</NativeSelectOption>
+        </NativeSelect>
+        <FieldError errors={[errors.priority]} />
+      </Field>
+
+      <Button type="submit">Enviar</Button>
+    </form>
+  )
+}
+```
+
+### Estados
+
+```tsx
+import { NativeSelect, NativeSelectOption } from "@etus/ui"
+
+function StatesExample() {
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Default */}
+      <NativeSelect>
+        <NativeSelectOption value="">Default</NativeSelectOption>
+      </NativeSelect>
+
+      {/* Disabled */}
+      <NativeSelect disabled>
+        <NativeSelectOption value="">Disabled</NativeSelectOption>
+      </NativeSelect>
+
+      {/* Invalid */}
+      <NativeSelect aria-invalid="true">
+        <NativeSelectOption value="">Invalid</NativeSelectOption>
+      </NativeSelect>
+
+      {/* Required */}
+      <NativeSelect required>
+        <NativeSelectOption value="">Required</NativeSelectOption>
+      </NativeSelect>
+
+      {/* Com opcao disabled */}
+      <NativeSelect>
+        <NativeSelectOption value="">Selecione...</NativeSelectOption>
+        <NativeSelectOption value="active">Ativa</NativeSelectOption>
+        <NativeSelectOption value="inactive" disabled>
+          Inativa (desabilitada)
+        </NativeSelectOption>
+      </NativeSelect>
+    </div>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+import { NativeSelect, NativeSelectOption } from "@etus/ui"
+
+function ResponsiveExample() {
+  return (
+    <NativeSelect className="w-full md:w-64 lg:w-80">
+      <NativeSelectOption value="">Selecione...</NativeSelectOption>
+      <NativeSelectOption value="1">Opcao 1</NativeSelectOption>
+      <NativeSelectOption value="2">Opcao 2</NativeSelectOption>
+    </NativeSelect>
+  )
+}
+```
+
+### Com Container Queries
+
+```tsx
+function ContainerQueryExample() {
+  return (
+    <div className="@container">
+      <NativeSelect className="w-full @sm:w-48 @md:w-64">
+        <NativeSelectOption value="">Responsivo ao container</NativeSelectOption>
+        <NativeSelectOption value="1">Opcao 1</NativeSelectOption>
+      </NativeSelect>
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// NativeSelect.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import {
+  NativeSelect,
+  NativeSelectOption,
+  NativeSelectOptGroup,
+} from "./NativeSelect"
+
+describe("NativeSelect", () => {
+  it("renders options correctly", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOption value="1">Option 1</NativeSelectOption>
+        <NativeSelectOption value="2">Option 2</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("combobox")).toBeInTheDocument()
+    expect(screen.getByRole("option", { name: "Option 1" })).toBeInTheDocument()
+    expect(screen.getByRole("option", { name: "Option 2" })).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute on wrapper", () => {
+    const { container } = render(
+      <NativeSelect>
+        <NativeSelectOption value="1">Option</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(
+      container.querySelector('[data-slot="native-select-wrapper"]')
+    ).toBeInTheDocument()
+  })
+
+  it("has data-slot attribute on select", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOption value="1">Option</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("combobox")).toHaveAttribute(
+      "data-slot",
+      "native-select"
+    )
+  })
+
+  it("merges custom className", () => {
+    render(
+      <NativeSelect className="custom-class">
+        <NativeSelectOption value="1">Option</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("combobox")).toHaveClass("custom-class")
+  })
+
+  it("renders chevron icon", () => {
+    const { container } = render(
+      <NativeSelect>
+        <NativeSelectOption value="1">Option</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(
+      container.querySelector('[data-slot="native-select-icon"]')
+    ).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("NativeSelect interactions", () => {
+  it("calls onChange when selection changes", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <NativeSelect onChange={handleChange}>
+        <NativeSelectOption value="">Select...</NativeSelectOption>
+        <NativeSelectOption value="1">Option 1</NativeSelectOption>
+        <NativeSelectOption value="2">Option 2</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    await user.selectOptions(screen.getByRole("combobox"), "1")
+    expect(handleChange).toHaveBeenCalledTimes(1)
+  })
+
+  it("updates selected value", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <NativeSelect defaultValue="">
+        <NativeSelectOption value="">Select...</NativeSelectOption>
+        <NativeSelectOption value="1">Option 1</NativeSelectOption>
+        <NativeSelectOption value="2">Option 2</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    const select = screen.getByRole("combobox")
+    await user.selectOptions(select, "2")
+
+    expect(select).toHaveValue("2")
+  })
+
+  it("does not call onChange when disabled", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <NativeSelect onChange={handleChange} disabled>
+        <NativeSelectOption value="1">Option 1</NativeSelectOption>
+        <NativeSelectOption value="2">Option 2</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    const select = screen.getByRole("combobox")
+    await user.selectOptions(select, "2").catch(() => {})
+
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("handles keyboard navigation", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <NativeSelect defaultValue="">
+        <NativeSelectOption value="">Select...</NativeSelectOption>
+        <NativeSelectOption value="a">Alpha</NativeSelectOption>
+        <NativeSelectOption value="b">Beta</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    const select = screen.getByRole("combobox")
+    select.focus()
+
+    // Navegacao com setas varia por navegador
+    // Teste focado na existencia do elemento focavel
+    expect(select).toHaveFocus()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("NativeSelect accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <label>
+        Country
+        <NativeSelect>
+          <NativeSelectOption value="">Select...</NativeSelectOption>
+          <NativeSelectOption value="br">Brazil</NativeSelectOption>
+        </NativeSelect>
+      </label>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("supports aria-invalid", () => {
+    render(
+      <NativeSelect aria-invalid="true">
+        <NativeSelectOption value="">Invalid</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-invalid", "true")
+  })
+
+  it("supports aria-describedby for error messages", () => {
+    render(
+      <>
+        <NativeSelect aria-describedby="error-msg">
+          <NativeSelectOption value="">Select...</NativeSelectOption>
+        </NativeSelect>
+        <span id="error-msg">This field is required</span>
+      </>
+    )
+
+    expect(screen.getByRole("combobox")).toHaveAttribute(
+      "aria-describedby",
+      "error-msg"
+    )
+  })
+
+  it("is focusable", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOption value="">Focus me</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    const select = screen.getByRole("combobox")
+    select.focus()
+    expect(select).toHaveFocus()
+  })
+
+  it("is not focusable when disabled", () => {
+    render(
+      <NativeSelect disabled>
+        <NativeSelectOption value="">Disabled</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("combobox")).toBeDisabled()
+  })
+})
+```
+
+### Testes com OptGroup
+
+```tsx
+describe("NativeSelectOptGroup", () => {
+  it("renders optgroup with label", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOptGroup label="Group A">
+          <NativeSelectOption value="1">Option 1</NativeSelectOption>
+        </NativeSelectOptGroup>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("group", { name: "Group A" })).toBeInTheDocument()
+  })
+
+  it("disables all options when group is disabled", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOptGroup label="Disabled Group" disabled>
+          <NativeSelectOption value="1">Option 1</NativeSelectOption>
+          <NativeSelectOption value="2">Option 2</NativeSelectOption>
+        </NativeSelectOptGroup>
+      </NativeSelect>
+    )
+
+    const group = screen.getByRole("group", { name: "Disabled Group" })
+    expect(group).toBeDisabled()
+  })
+
+  it("has data-slot on optgroup", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOptGroup label="Test Group">
+          <NativeSelectOption value="1">Option</NativeSelectOption>
+        </NativeSelectOptGroup>
+      </NativeSelect>
+    )
+
+    expect(screen.getByRole("group")).toHaveAttribute(
+      "data-slot",
+      "native-select-optgroup"
+    )
+  })
+})
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("NativeSelect edge cases", () => {
+  it("works with empty options list", () => {
+    render(<NativeSelect>{/* No options */}</NativeSelect>)
+
+    expect(screen.getByRole("combobox")).toBeInTheDocument()
+  })
+
+  it("handles rapid selection changes", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(
+      <NativeSelect onChange={handleChange}>
+        <NativeSelectOption value="1">1</NativeSelectOption>
+        <NativeSelectOption value="2">2</NativeSelectOption>
+        <NativeSelectOption value="3">3</NativeSelectOption>
+      </NativeSelect>
+    )
+
+    const select = screen.getByRole("combobox")
+    await user.selectOptions(select, "1")
+    await user.selectOptions(select, "2")
+    await user.selectOptions(select, "3")
+
+    expect(handleChange).toHaveBeenCalledTimes(3)
+  })
+
+  it("works in form submission", async () => {
+    const user = userEvent.setup()
+    const handleSubmit = vi.fn((e) => e.preventDefault())
+
+    render(
+      <form onSubmit={handleSubmit}>
+        <NativeSelect name="color" defaultValue="red">
+          <NativeSelectOption value="red">Red</NativeSelectOption>
+          <NativeSelectOption value="blue">Blue</NativeSelectOption>
+        </NativeSelect>
+        <button type="submit">Submit</button>
+      </form>
+    )
+
+    await user.click(screen.getByRole("button"))
+    expect(handleSubmit).toHaveBeenCalled()
+  })
+
+  it("supports controlled component pattern", async () => {
+    const user = userEvent.setup()
+
+    function ControlledTest() {
+      const [value, setValue] = useState("")
+      return (
+        <>
+          <NativeSelect
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+          >
+            <NativeSelectOption value="">Select</NativeSelectOption>
+            <NativeSelectOption value="a">A</NativeSelectOption>
+          </NativeSelect>
+          <span data-testid="output">{value}</span>
+        </>
+      )
+    }
+
+    render(<ControlledTest />)
+
+    await user.selectOptions(screen.getByRole("combobox"), "a")
+    expect(screen.getByTestId("output")).toHaveTextContent("a")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### Variantes de Tamanho
+
+```tsx
+// Proposta de API
+interface NativeSelectProps {
+  size?: "sm" | "default" | "lg"
+}
+
+// Uso
+<NativeSelect size="sm">...</NativeSelect>
+<NativeSelect size="lg">...</NativeSelect>
+```
+
+**Referencias:** MUI, Mantine, Chakra, AntD, NextUI, Fluent UI
+
+#### Left Icon / Prefix
+
+```tsx
+// Proposta de API
+interface NativeSelectProps {
+  leftIcon?: ReactNode
+}
+
+// Uso
+<NativeSelect leftIcon={<GlobeIcon />}>
+  <NativeSelectOption value="br">Brasil</NativeSelectOption>
+</NativeSelect>
+```
+
+**Referencias:** Chakra, MUI, Mantine, AntD, NextUI, Fluent
+
+### Prioridade Media
+
+#### Variantes de Estilo
+
+```tsx
+// Proposta de API
+interface NativeSelectProps {
+  variant?: "default" | "ghost" | "filled"
+}
+
+// Uso
+<NativeSelect variant="filled">...</NativeSelect>
+```
+
+**Referencias:** Chakra, MUI, Mantine
+
+#### Loading State
+
+```tsx
+// Proposta de API
+interface NativeSelectProps {
+  loading?: boolean
+}
+
+// Uso
+<NativeSelect loading>...</NativeSelect>
+```
+
+**Referencias:** AntD, Mantine, PrimeReact
+
+### Prioridade Baixa
+
+#### Clearable
+
+```tsx
+// Proposta de API
+interface NativeSelectProps {
+  clearable?: boolean
+  onClear?: () => void
+}
+```
+
+**Referencias:** Mantine, AntD, NextUI
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `size` | ✓ Implementar | Consistencia com outros form controls |
+| `leftIcon` | ✓ Implementar | UX melhorada, comum em forms |
+| `variant` | ⚠️ Avaliar | Tailwind className pode resolver |
+| `loading` | ⚠️ Avaliar | Caso de uso limitado para native |
+| `clearable` | ❌ Evitar | Complexidade, usar Select (Radix) |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentacao | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Select](https://ui.shadcn.com/docs/components/select) | [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** | [Select](https://react-spectrum.adobe.com/react-aria/Select.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** | [NativeSelect](https://mui.com/material-ui/react-select/#native-select) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [NativeSelect](https://mantine.dev/core/native-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** | [Listbox](https://headlessui.com/react/listbox) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Select](https://ariakit.org/components/select) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Dropdown](https://react.fluentui.dev/?path=/docs/components-dropdown--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Select](https://carbondesignsystem.com/components/select/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [HTMLSelect](https://blueprintjs.com/docs/#core/components/html-select) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [Dropdown](https://primereact.org/dropdown/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificacoes e Padroes
+
+- [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 - Select Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
+- [HTML Spec - Select](https://html.spec.whatwg.org/multipage/form-elements.html#the-select-element)
+
+### Ferramentas Utilizadas
+
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)
+- [React Hook Form](https://react-hook-form.com/)
+- [Zod](https://zod.dev/)