@etus/ui 0.1.0

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

@@ -0,0 +1,1286 @@
+# Select
+
+## Visão Geral
+
+O **Select** e um componente compound de selecao do Design System ETUS, usado para apresentar uma lista de opcoes ao usuario em um dropdown. Baseado no Radix UI Select, oferece acessibilidade completa, navegacao por teclado e suporte a grupos de opcoes.
+
+### Casos de Uso
+
+- Selecao de uma opcao entre varias alternativas
+- Formularios com campos de escolha unica
+- Filtros e configuracoes
+- Selecao de pais, estado, categoria, etc.
+- Menus de navegacao com opcoes predefinidas
+
+### Classificacao
+
+**Categoria:** Organism (Compound Component)
+**Dependencias:** `@radix-ui/react-select`, `lucide-react`
+
+---
+
+## Design Specs
+
+### Partes do Componente
+
+| Parte                    | Funcao                          | data-slot                   |
+| ------------------------ | ------------------------------- | --------------------------- |
+| `Select`                 | Container root, gerencia estado | `select`                    |
+| `SelectTrigger`          | Botao que abre o dropdown       | `select-trigger`            |
+| `SelectValue`            | Exibe o valor selecionado       | `select-value`              |
+| `SelectContent`          | Container do dropdown           | `select-content`            |
+| `SelectGroup`            | Agrupa itens relacionados       | `select-group`              |
+| `SelectLabel`            | Rotulo para grupos              | `select-label`              |
+| `SelectItem`             | Item selecionavel               | `select-item`               |
+| `SelectSeparator`        | Divisor entre grupos            | `select-separator`          |
+| `SelectScrollUpButton`   | Botao de scroll para cima       | `select-scroll-up-button`   |
+| `SelectScrollDownButton` | Botao de scroll para baixo      | `select-scroll-down-button` |
+
+### Tamanhos (`size`) - SelectTrigger
+
+| Tamanho   | Altura       | Uso                                        |
+| --------- | ------------ | ------------------------------------------ |
+| `sm`      | `h-8` (32px) | Espacos compactos, tabelas, filtros inline |
+| `default` | `h-9` (36px) | Uso geral em formularios                   |
+
+### Estados
+
+| Estado      | Classes/Atributos                          | Comportamento                     |
+| ----------- | ------------------------------------------ | --------------------------------- |
+| Default     | -                                          | Aparencia base                    |
+| Hover       | `hover:bg-input/50`                        | Leve destaque no fundo            |
+| Focus       | `focus-visible:ring-[3px]`                 | Ring de 3px com `ring-ring/50`    |
+| Open        | `data-[state=open]`                        | Animacao de entrada do content    |
+| Disabled    | `disabled:opacity-50`                      | 50% opacidade, sem pointer events |
+| Invalid     | `aria-invalid:ring-destructive/20`         | Ring vermelho para erro           |
+| Placeholder | `data-[placeholder]:text-muted-foreground` | Texto em cor secundaria           |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input             /* Borda do trigger */
+--background        /* Fundo do trigger */
+--popover           /* Fundo do content */
+--popover-foreground
+--muted-foreground  /* Placeholder, labels */
+--accent            /* Hover nos items */
+--accent-foreground
+--ring              /* Focus ring */
+--border            /* Borda do content, separador */
+--destructive       /* Estado de erro */
+
+/* Espacamento */
+gap-2               /* Entre icone e texto */
+px-3 py-2           /* Padding do trigger */
+p-1                 /* Padding do viewport */
+
+/* Tipografia */
+text-sm             /* 14px */
+text-xs             /* Labels de grupo */
+
+/* Bordas */
+rounded-md          /* var(--radius) */
+rounded-sm          /* Items */
+
+/* Sombras */
+shadow-xs           /* Trigger */
+shadow-md           /* Content */
+
+/* Animacoes */
+animate-in/out      /* Fade e zoom no content */
+slide-in-from-*     /* Direcao baseada em side */
+```
+
+### Posicionamento
+
+| Prop       | Valores                            | Padrao     | Descricao              |
+| ---------- | ---------------------------------- | ---------- | ---------------------- |
+| `position` | `"popper"` \| `"item-aligned"`     | `"popper"` | Modo de posicionamento |
+| `align`    | `"start"` \| `"center"` \| `"end"` | `"center"` | Alinhamento horizontal |
+| `side`     | `"top"` \| `"bottom"`              | `"bottom"` | Lado de abertura       |
+
+### Padrão de Tokens com Tailwind v4
+
+O componente Select utiliza tokens de design definidos em `@etus/tokens`. No Tailwind v4, variáveis CSS que contêm cores OKLCH precisam do prefixo `color:` para serem interpretadas corretamente.
+
+#### Tokens Disponíveis
+
+```css
+/* Gerados em packages/tokens/styles/tokens.css */
+/* Trigger */
+--select-trigger-padding-x-sm
+--select-trigger-padding-x-md
+--select-trigger-padding-x-lg
+--select-trigger-padding-y-sm
+--select-trigger-padding-y-md
+--select-trigger-padding-y-lg
+--select-trigger-height-sm
+--select-trigger-height-md
+--select-trigger-height-lg
+--select-trigger-text-sm
+--select-trigger-text-md
+--select-trigger-text-lg
+
+/* Content */
+--select-content-bg
+--select-content-fg
+--select-content-border
+--select-content-radius
+--select-content-min-width
+
+/* Item */
+--select-item-padding-y
+--select-item-padding-r
+--select-item-padding-l
+--select-item-radius
+--select-item-text
+--select-item-focus-bg
+--select-item-focus-fg
+```
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - cores precisam do prefixo color:
+bg-[color:var(--select-content-bg)]
+text-[color:var(--select-content-fg)]
+border-[color:var(--select-content-border)]
+bg-[color:var(--select-item-focus-bg)]
+text-[color:var(--select-item-focus-fg)]
+
+// ✅ CORRETO - dimensões não precisam de prefixo
+h-[var(--select-trigger-height-md)]
+px-[var(--select-trigger-padding-x-md)]
+rounded-[var(--select-content-radius)]
+
+// ✅ CORRETO - font-size precisa do prefixo length:
+text-[length:var(--select-trigger-text-md)]
+text-[length:var(--select-item-text)]
+
+// ❌ INCORRETO - nunca usar hsl() ou omitir prefixo para cores
+bg-[hsl(var(--select-content-bg))]
+bg-[var(--select-content-bg)]
+```
+
+#### Por que usar `color:` e `length:`?
+
+Os tokens de cor do Seven usam OKLCH (e.g., `oklch(81.06% 0.2032 150.12)`). O Tailwind v4 precisa do type hint `color:` para cores e `length:` para font-size quando usando a classe `text-[]`.
+
+---
+
+## API
+
+### Select (Root)
+
+| Prop            | Tipo                      | Padrao  | Descricao                    |
+| --------------- | ------------------------- | ------- | ---------------------------- |
+| `value`         | `string`                  | -       | Valor controlado             |
+| `defaultValue`  | `string`                  | -       | Valor inicial nao-controlado |
+| `onValueChange` | `(value: string) => void` | -       | Callback quando valor muda   |
+| `open`          | `boolean`                 | -       | Estado aberto controlado     |
+| `defaultOpen`   | `boolean`                 | `false` | Estado inicial aberto        |
+| `onOpenChange`  | `(open: boolean) => void` | -       | Callback quando abre/fecha   |
+| `disabled`      | `boolean`                 | `false` | Desabilita o select          |
+| `required`      | `boolean`                 | `false` | Campo obrigatorio            |
+| `name`          | `string`                  | -       | Nome para formularios        |
+
+### SelectTrigger
+
+| Prop        | Tipo                     | Padrao      | Descricao                         |
+| ----------- | ------------------------ | ----------- | --------------------------------- |
+| `size`      | `"sm"` \| `"default"`    | `"default"` | Tamanho do trigger                |
+| `className` | `string`                 | -           | Classes CSS adicionais            |
+| `children`  | `ReactNode`              | -           | Conteudo (geralmente SelectValue) |
+| `ref`       | `Ref<HTMLButtonElement>` | -           | Referencia ao elemento DOM        |
+
+> Herda todas as props de `React.ComponentProps<typeof SelectPrimitive.Trigger>`
+
+### SelectValue
+
+| Prop          | Tipo     | Padrao | Descricao                             |
+| ------------- | -------- | ------ | ------------------------------------- |
+| `placeholder` | `string` | -      | Texto quando nenhum valor selecionado |
+
+### SelectContent
+
+| Prop         | Tipo                               | Padrao     | Descricao              |
+| ------------ | ---------------------------------- | ---------- | ---------------------- |
+| `position`   | `"popper"` \| `"item-aligned"`     | `"popper"` | Modo de posicionamento |
+| `align`      | `"start"` \| `"center"` \| `"end"` | `"center"` | Alinhamento            |
+| `side`       | `"top"` \| `"bottom"`              | -          | Lado preferido         |
+| `sideOffset` | `number`                           | -          | Offset do trigger      |
+| `className`  | `string`                           | -          | Classes CSS adicionais |
+
+### SelectItem
+
+| Prop        | Tipo        | Padrao          | Descricao              |
+| ----------- | ----------- | --------------- | ---------------------- |
+| `value`     | `string`    | **obrigatorio** | Valor do item          |
+| `disabled`  | `boolean`   | `false`         | Desabilita o item      |
+| `textValue` | `string`    | -               | Texto para typeahead   |
+| `className` | `string`    | -               | Classes CSS adicionais |
+| `children`  | `ReactNode` | -               | Conteudo do item       |
+
+### SelectGroup & SelectLabel
+
+```tsx
+// SelectGroup agrupa itens relacionados
+// SelectLabel adiciona rotulo ao grupo
+<SelectGroup>
+  <SelectLabel>Frutas</SelectLabel>
+  <SelectItem value="apple">Maca</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectGroup>
+```
+
+### TypeScript
+
+```typescript
+import * as SelectPrimitive from "@radix-ui/react-select";
+
+// Props do Trigger com size customizado
+type SelectTriggerProps = React.ComponentProps<
+  typeof SelectPrimitive.Trigger
+> & {
+  size?: "sm" | "default";
+};
+
+// Props do Content
+type SelectContentProps = React.ComponentProps<typeof SelectPrimitive.Content>;
+
+// Props do Item
+type SelectItemProps = React.ComponentProps<typeof SelectPrimitive.Item>;
+```
+
+### 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 |
+| ------------------ | :--: | :----: | :---: | :--------: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: | :--------: |
+| **Compound**       |  ✓   |   ✓    |   ✓   |     ✓      |   -    |  -  |    -    |  -   |   -    |    ✓     |    ✓    |   -    |   -    |     -     |     -      |
+| **Controlled**     |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Groups**         |  ✓   |   ✓    |   ✓   |     ✓      |   -    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Searchable**     |  -   |   -    |   -   |     ✓      |   -    |  ✓  |    ✓    |  ✓   |   -    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Multi-select**   |  -   |   -    |   -   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Async loading**  |  -   |   -    |   -   |     ✓      |   -    |  -  |    -    |  ✓   |   -    |    -     |    -    |   -    |   -    |     -     |     ✓      |
+| **Virtualization** |  -   |   -    |   -   |     -      |   -    |  -  |    ✓    |  ✓   |   -    |    -     |    -    |   -    |   -    |     -     |     ✓      |
+| **clearable**      |  -   |   -    |   -   |     -      |   ✓    |  -  |    ✓    |  ✓   |   -    |    -     |    -    |   -    |   -    |     -     |     ✓      |
+| **Custom render**  |  ✓   |   ✓    |   ✓   |     ✓      |   -    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   -    |   -    |     ✓     |     ✓      |
+| **Portal**         |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Typeahead**      |  ✓   |   ✓    |   ✓   |     ✓      |   -    |  -  |    ✓    |  -   |   -    |    ✓     |    ✓    |   ✓    |   -    |     ✓     |     -      |
+| **data-slot**      |  ✓   |   ✓    |   -   |     -      |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |     -      |
+
+#### Comparativo de Arquitetura
+
+| Design System   | Arquitetura                 | Nota                               |
+| --------------- | --------------------------- | ---------------------------------- |
+| **ETUS/Shadcn** | Compound components (Radix) | Maximo controle, mais verboso      |
+| **Radix UI**    | Primitivos compostos        | Base para Shadcn, sem estilos      |
+| **React Aria**  | Hooks + componentes         | Maximo a11y, flexivel              |
+| **Chakra UI**   | Monolitico com props        | Simples, menos flexivel            |
+| **MUI**         | Monolitico + slots          | Sistema de slots para customizacao |
+| **Mantine**     | Monolitico + data           | Muito configuravel via props       |
+| **Ant Design**  | Monolitico enterprise       | Muitas features built-in           |
+| **NextUI**      | Compound (React Aria)       | Herda a11y do React Aria           |
+| **Headless UI** | Renderless + compound       | Tailwind-friendly                  |
+| **Ariakit**     | Compound + hooks            | Muito flexivel                     |
+| **Fluent UI**   | Monolitico Microsoft        | Tokens complexos                   |
+| **Carbon**      | Monolitico IBM              | Foco em data                       |
+| **Blueprint**   | Monolitico Palantir         | Data-dense UIs                     |
+| **PrimeReact**  | Monolitico enterprise       | Muito completo                     |
+
+#### Comparativo de Props por Design System
+
+| Prop          |      ETUS       |    Chakra    |   MUI   | Mantine |     AntD     |       NextUI        |
+| ------------- | :-------------: | :----------: | :-----: | :-----: | :----------: | :-----------------: |
+| `value`       |        ✓        |      ✓       |    ✓    |    ✓    |      ✓       |          ✓          |
+| `onChange`    | `onValueChange` |      ✓       |    ✓    |    ✓    |      ✓       | `onSelectionChange` |
+| `disabled`    |        ✓        | `isDisabled` |    ✓    |    ✓    |      ✓       |    `isDisabled`     |
+| `placeholder` |        ✓        |      ✓       |    -    |    ✓    |      ✓       |          ✓          |
+| `size`        |        ✓        |      ✓       |    ✓    |    ✓    |      ✓       |          ✓          |
+| `variant`     |        -        |      ✓       |    ✓    |    ✓    |      -       |          ✓          |
+| `multiple`    |        -        |      -       |    ✓    |    -    |    `mode`    |   `selectionMode`   |
+| `searchable`  |        -        |      -       |    -    |    ✓    | `showSearch` |          -          |
+| `clearable`   |        -        |      ✓       |    -    |    ✓    | `allowClear` |          -          |
+| `loading`     |        -        |      -       |    -    |    -    |      ✓       |          -          |
+| `error`       |        -        | `isInvalid`  | `error` | `error` |   `status`   |     `isInvalid`     |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo                  | Elemento | Descricao                    |
+| ------------------------- | -------- | ---------------------------- |
+| `role="combobox"`         | Trigger  | Identifica como combobox     |
+| `role="listbox"`          | Content  | Container de opcoes          |
+| `role="option"`           | Item     | Opcao selecionavel           |
+| `role="group"`            | Group    | Agrupa opcoes relacionadas   |
+| `aria-expanded`           | Trigger  | Estado aberto/fechado        |
+| `aria-haspopup="listbox"` | Trigger  | Indica que abre listbox      |
+| `aria-activedescendant`   | Trigger  | Item atualmente focado       |
+| `aria-selected`           | Item     | Indica item selecionado      |
+| `aria-disabled`           | Item     | Indica item desabilitado     |
+| `aria-labelledby`         | Group    | Referencia ao label do grupo |
+
+### Suporte a Teclado
+
+| Tecla             | Contexto        | Acao                                       |
+| ----------------- | --------------- | ------------------------------------------ |
+| `Space` / `Enter` | Trigger fechado | Abre o dropdown                            |
+| `Space` / `Enter` | Item focado     | Seleciona e fecha                          |
+| `ArrowDown`       | Trigger fechado | Abre e foca primeiro item                  |
+| `ArrowDown`       | Content aberto  | Move foco para proximo item                |
+| `ArrowUp`         | Trigger fechado | Abre e foca ultimo item                    |
+| `ArrowUp`         | Content aberto  | Move foco para item anterior               |
+| `Home`            | Content aberto  | Move foco para primeiro item               |
+| `End`             | Content aberto  | Move foco para ultimo item                 |
+| `Escape`          | Content aberto  | Fecha sem selecionar                       |
+| `Tab`             | Content aberto  | Fecha e move foco                          |
+| `A-Z`             | Content aberto  | Typeahead - foca item que comeca com letra |
+
+### Focus Management
+
+```tsx
+// Focus visible no trigger
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+
+// Focus nos items
+focus:bg-accent
+focus:text-accent-foreground
+```
+
+### Contraste de Cores (WCAG 2.1 AA)
+
+| 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 focused | `--accent-foreground`  | `--accent`     | >= 4.5:1 |
+| Label        | `--muted-foreground`   | `--popover`    | >= 4.5:1 |
+
+### Screen Readers
+
+- Anuncia "combobox, collapsed/expanded"
+- Anuncia opcao selecionada
+- Anuncia numero de opcoes disponiveis
+- Anuncia grupos e labels
+- Anuncia estado disabled de items
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature                   | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+| ------------------------- | :--: | :--------: | :---: | :-----: | :------: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: | :-------: | :--------: |
+| **WAI-ARIA 1.2**          |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ~    |  ~  |    ~    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ~      |
+| **Keyboard nav**          |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Typeahead**             |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   -    |  -  |    ✓    |  -   |   -    |   ✓    |   -    |     ✓     |     -      |
+| **Focus trap**            |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ✓     |     ~      |
+| **aria-activedescendant** |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   -    |  ✓  |    ✓    |  -   |   ✓    |   ✓    |   ✓    |     ✓     |     ~      |
+| **Screen reader tested**  |  ~   |     ✓      |   ✓   |    ✓    |    ✓     |   ~    |  ✓  |    ~    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ~      |
+| **RTL support**           |  -   |     ✓      |   -   |    -    |    -     |   ✓    |  ✓  |    ✓    |  ✓   |   -    |   ✓    |   ✓    |     -     |     ✓      |
+| **High contrast**         |  -   |     ✓      |   -   |    -    |    -     |   -    |  -  |    -    |  -   |   -    |   ✓    |   ✓    |     -     |     -      |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@etus/ui";
+
+function Example() {
+  return (
+    <Select>
+      <SelectTrigger className="w-[200px]">
+        <SelectValue placeholder="Selecione uma opcao" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="opcao1">Opcao 1</SelectItem>
+        <SelectItem value="opcao2">Opcao 2</SelectItem>
+        <SelectItem value="opcao3">Opcao 3</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+
+function ControlledExample() {
+  const [value, setValue] = useState<string>("");
+
+  return (
+    <Select value={value} onValueChange={setValue}>
+      <SelectTrigger className="w-[200px]">
+        <SelectValue placeholder="Selecione..." />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="react">React</SelectItem>
+        <SelectItem value="vue">Vue</SelectItem>
+        <SelectItem value="angular">Angular</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+### Com Grupos
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "@etus/ui";
+
+function GroupedExample() {
+  return (
+    <Select>
+      <SelectTrigger className="w-[240px]">
+        <SelectValue placeholder="Selecione um framework" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectGroup>
+          <SelectLabel>Frontend</SelectLabel>
+          <SelectItem value="react">React</SelectItem>
+          <SelectItem value="vue">Vue</SelectItem>
+          <SelectItem value="angular">Angular</SelectItem>
+        </SelectGroup>
+        <SelectSeparator />
+        <SelectGroup>
+          <SelectLabel>Backend</SelectLabel>
+          <SelectItem value="node">Node.js</SelectItem>
+          <SelectItem value="python">Python</SelectItem>
+          <SelectItem value="go">Go</SelectItem>
+        </SelectGroup>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+### Tamanhos
+
+```tsx
+// Tamanho padrao (h-9)
+<Select>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue placeholder="Default" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Item 1</SelectItem>
+  </SelectContent>
+</Select>
+
+// Tamanho pequeno (h-8)
+<Select>
+  <SelectTrigger size="sm" className="w-[200px]">
+    <SelectValue placeholder="Small" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Item 1</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Com Icones nos Items
+
+```tsx
+import { Apple, Banana, Cherry } from "lucide-react";
+
+function IconsExample() {
+  return (
+    <Select>
+      <SelectTrigger className="w-[200px]">
+        <SelectValue placeholder="Selecione uma fruta" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="apple">
+          <Apple className="size-4" />
+          Maca
+        </SelectItem>
+        <SelectItem value="banana">
+          <Banana className="size-4" />
+          Banana
+        </SelectItem>
+        <SelectItem value="cherry">
+          <Cherry className="size-4" />
+          Cereja
+        </SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+### Item Desabilitado
+
+```tsx
+<Select>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue placeholder="Selecione..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="available">Disponivel</SelectItem>
+    <SelectItem value="unavailable" disabled>
+      Indisponivel
+    </SelectItem>
+    <SelectItem value="coming">Em breve</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Em Formulario com React Hook Form
+
+```tsx
+import { useForm, Controller } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const schema = z.object({
+  country: z.string().min(1, "Selecione um pais"),
+});
+
+function FormExample() {
+  const {
+    control,
+    handleSubmit,
+    formState: { errors },
+  } = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: { country: "" },
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="country"
+        control={control}
+        render={({ field }) => (
+          <Select value={field.value} onValueChange={field.onChange}>
+            <SelectTrigger
+              className="w-[200px]"
+              aria-invalid={!!errors.country}
+            >
+              <SelectValue placeholder="Selecione um pais" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="br">Brasil</SelectItem>
+              <SelectItem value="us">Estados Unidos</SelectItem>
+              <SelectItem value="pt">Portugal</SelectItem>
+            </SelectContent>
+          </Select>
+        )}
+      />
+      {errors.country && (
+        <p className="text-sm text-destructive mt-1">
+          {errors.country.message}
+        </p>
+      )}
+    </form>
+  );
+}
+```
+
+### Responsivo
+
+```tsx
+// Largura responsiva
+<Select>
+  <SelectTrigger className="w-full sm:w-[200px] md:w-[300px]">
+    <SelectValue placeholder="Selecione..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Item 1</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Com Label e Field
+
+```tsx
+import { Label } from "@etus/ui";
+
+function FieldExample() {
+  return (
+    <div className="grid gap-2">
+      <Label htmlFor="framework">Framework</Label>
+      <Select>
+        <SelectTrigger id="framework" className="w-[200px]">
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="react">React</SelectItem>
+          <SelectItem value="vue">Vue</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Select.test.tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "./Select";
+
+describe("Select", () => {
+  it("renders trigger with placeholder", () => {
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    expect(screen.getByRole("combobox")).toBeInTheDocument();
+    expect(screen.getByText("Selecione...")).toBeInTheDocument();
+  });
+
+  it("has data-slot attribute", () => {
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Test" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    expect(screen.getByRole("combobox")).toHaveAttribute(
+      "data-slot",
+      "select-trigger",
+    );
+  });
+
+  it("applies size class", () => {
+    render(
+      <Select>
+        <SelectTrigger size="sm">
+          <SelectValue placeholder="Small" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    expect(screen.getByRole("combobox")).toHaveAttribute("data-size", "sm");
+  });
+});
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Select interactions", () => {
+  it("opens on click", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+    expect(screen.getByRole("option", { name: "Item 1" })).toBeInTheDocument();
+  });
+
+  it("selects item and closes", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    render(
+      <Select onValueChange={onValueChange}>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="item1">Item 1</SelectItem>
+          <SelectItem value="item2">Item 2</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+    await user.click(screen.getByRole("option", { name: "Item 1" }));
+
+    expect(onValueChange).toHaveBeenCalledWith("item1");
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+  });
+
+  it("shows selected value", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select defaultValue="item1">
+        <SelectTrigger>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="item1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    expect(screen.getByText("Item 1")).toBeInTheDocument();
+  });
+
+  it("does not select disabled item", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    render(
+      <Select onValueChange={onValueChange}>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="item1" disabled>
+            Disabled
+          </SelectItem>
+          <SelectItem value="item2">Enabled</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+    await user.click(screen.getByRole("option", { name: "Disabled" }));
+
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+});
+```
+
+### Testes de Teclado
+
+```tsx
+describe("Select keyboard navigation", () => {
+  it("opens with Enter key", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    screen.getByRole("combobox").focus();
+    await user.keyboard("{Enter}");
+
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+  });
+
+  it("navigates with arrow keys", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+          <SelectItem value="2">Item 2</SelectItem>
+          <SelectItem value="3">Item 3</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    screen.getByRole("combobox").focus();
+    await user.keyboard("{ArrowDown}");
+
+    // Primeiro item deve estar focado
+    expect(screen.getByRole("option", { name: "Item 1" })).toHaveFocus();
+
+    await user.keyboard("{ArrowDown}");
+    expect(screen.getByRole("option", { name: "Item 2" })).toHaveFocus();
+  });
+
+  it("closes with Escape", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+
+    await user.keyboard("{Escape}");
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+  });
+
+  it("supports typeahead", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="apple">Apple</SelectItem>
+          <SelectItem value="banana">Banana</SelectItem>
+          <SelectItem value="cherry">Cherry</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+    await user.keyboard("b");
+
+    expect(screen.getByRole("option", { name: "Banana" })).toHaveFocus();
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Select accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Select>
+        <SelectTrigger aria-label="Selecione uma opcao">
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("has proper ARIA attributes on trigger", () => {
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    const trigger = screen.getByRole("combobox");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveAttribute("aria-haspopup", "listbox");
+  });
+
+  it("updates aria-expanded when opened", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    const trigger = screen.getByRole("combobox");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("items have proper roles", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+          <SelectItem value="2">Item 2</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+
+    const items = screen.getAllByRole("option");
+    expect(items).toHaveLength(2);
+  });
+
+  it("groups have proper labelling", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Selecione..." />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectGroup>
+            <SelectLabel>Grupo 1</SelectLabel>
+            <SelectItem value="1">Item 1</SelectItem>
+          </SelectGroup>
+        </SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+
+    expect(screen.getByRole("group")).toBeInTheDocument();
+    expect(screen.getByText("Grupo 1")).toBeInTheDocument();
+  });
+});
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("Select edge cases", () => {
+  it("works with controlled value", async () => {
+    const user = userEvent.setup();
+
+    function ControlledSelect() {
+      const [value, setValue] = useState("");
+      return (
+        <>
+          <Select value={value} onValueChange={setValue}>
+            <SelectTrigger>
+              <SelectValue placeholder="Selecione..." />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="1">Item 1</SelectItem>
+              <SelectItem value="2">Item 2</SelectItem>
+            </SelectContent>
+          </Select>
+          <span data-testid="value">{value}</span>
+        </>
+      );
+    }
+
+    render(<ControlledSelect />);
+
+    await user.click(screen.getByRole("combobox"));
+    await user.click(screen.getByRole("option", { name: "Item 1" }));
+
+    expect(screen.getByTestId("value")).toHaveTextContent("1");
+  });
+
+  it("handles empty options gracefully", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="Sem opcoes" />
+        </SelectTrigger>
+        <SelectContent>{/* Sem items */}</SelectContent>
+      </Select>,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+  });
+
+  it("preserves custom className", () => {
+    render(
+      <Select>
+        <SelectTrigger className="custom-class">
+          <SelectValue placeholder="Test" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="1">Item 1</SelectItem>
+        </SelectContent>
+      </Select>,
+    );
+
+    expect(screen.getByRole("combobox")).toHaveClass("custom-class");
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### `searchable`
+
+Filtro de busca nos items do dropdown.
+
+```tsx
+// Proposta de API
+interface SelectProps {
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  onSearch?: (query: string) => void;
+}
+
+// Uso
+<Select searchable searchPlaceholder="Buscar...">
+  <SelectTrigger>
+    <SelectValue placeholder="Selecione..." />
+  </SelectTrigger>
+  <SelectContent>{/* items filtrados */}</SelectContent>
+</Select>;
+```
+
+**Referencias:** MUI (Autocomplete), Mantine (`searchable`), AntD (`showSearch`), Ariakit
+
+#### `multi-select`
+
+Selecao de multiplos valores.
+
+```tsx
+// Proposta de API
+interface SelectProps {
+  multiple?: boolean;
+  value?: string[];
+  onValueChange?: (values: string[]) => void;
+  maxSelections?: number;
+}
+
+// Uso
+<Select multiple value={selected} onValueChange={setSelected}>
+  <SelectTrigger>
+    <SelectValue placeholder="Selecione multiplos..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Item 1</SelectItem>
+    <SelectItem value="2">Item 2</SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+**Referencias:** Chakra, MUI, Mantine, AntD (`mode="multiple"`), NextUI (`selectionMode="multiple"`)
+
+### Prioridade Media
+
+#### `clearable`
+
+Botao para limpar selecao.
+
+```tsx
+// Proposta de API
+interface SelectTriggerProps {
+  clearable?: boolean;
+  onClear?: () => void;
+}
+
+// Uso
+<SelectTrigger clearable>
+  <SelectValue placeholder="Selecione..." />
+</SelectTrigger>;
+```
+
+**Referencias:** Chakra, Mantine (`clearable`), AntD (`allowClear`)
+
+#### `loading`
+
+Estado de carregamento para async data.
+
+```tsx
+// Proposta de API
+interface SelectContentProps {
+  loading?: boolean;
+  loadingText?: string;
+}
+
+// Uso
+<SelectContent loading loadingText="Carregando opcoes...">
+  {items.map((item) => (
+    <SelectItem key={item.value} value={item.value}>
+      {item.label}
+    </SelectItem>
+  ))}
+</SelectContent>;
+```
+
+**Referencias:** AntD (`loading`), PrimeReact
+
+#### `variant`
+
+Variantes visuais do trigger.
+
+```tsx
+// Proposta de API
+interface SelectTriggerProps {
+  variant?: "default" | "outline" | "filled" | "flushed";
+}
+
+// Uso
+<SelectTrigger variant="filled">
+  <SelectValue placeholder="Filled variant" />
+</SelectTrigger>;
+```
+
+**Referencias:** Chakra, MUI, NextUI
+
+### Prioridade Baixa
+
+#### `virtualized`
+
+Virtualizacao para listas grandes.
+
+```tsx
+// Proposta de API
+interface SelectContentProps {
+  virtualized?: boolean;
+  itemHeight?: number;
+}
+
+// Uso com milhares de items
+<SelectContent virtualized itemHeight={36}>
+  {largeDataset.map((item) => (
+    <SelectItem key={item.id} value={item.id}>
+      {item.label}
+    </SelectItem>
+  ))}
+</SelectContent>;
+```
+
+**Referencias:** Mantine, AntD, PrimeReact
+
+#### `creatable`
+
+Permitir criar novas opcoes.
+
+```tsx
+// Proposta de API
+interface SelectProps {
+  creatable?: boolean;
+  onCreate?: (value: string) => void;
+  createLabel?: (query: string) => string;
+}
+
+// Uso
+<Select creatable onCreate={handleCreate}>
+  ...
+</Select>;
+```
+
+**Referencias:** React Select, Mantine
+
+### Decisoes de Design
+
+| Feature       | Recomendacao  | Justificativa                               |
+| ------------- | ------------- | ------------------------------------------- |
+| `searchable`  | ✓ Implementar | Alta demanda, UX melhor para listas grandes |
+| `multiple`    | ✓ Implementar | Caso de uso muito comum                     |
+| `clearable`   | ✓ Implementar | UX basica esperada                          |
+| `loading`     | ✓ Implementar | Essencial para async                        |
+| `variant`     | ⚠️ Avaliar    | Pode usar className                         |
+| `virtualized` | ⚠️ Avaliar    | Complexidade vs. uso                        |
+| `creatable`   | ❌ Evitar     | Melhor como componente separado (Combobox)  |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System   | Documentacao Select                                                             | 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**         | [Select](https://mui.com/material-ui/react-select/)                             | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**     | [Select](https://mantine.dev/core/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**      | [Dropdown](https://carbondesignsystem.com/components/dropdown/usage/)           | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**   | [Select](https://blueprintjs.com/docs/#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/)
+- [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 - Select Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
+
+### Ferramentas Utilizadas
+
+- [Radix UI Select](https://www.radix-ui.com/primitives/docs/components/select)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)