---
fonte: 01-canonicos/seed-componentes.md
versao_da_fonte: v1.43
secao: 11
titulo: "Combobox — `estável` · validado pelo Rafael em 2026-08-03 (preview v0.13 + suite de 63 testes)"
sequencia: 13 de 98
bytes_do_corpo: 4510
md5_do_corpo: b5e8686639d2d5e77d87a015c1926999
gerado_por: 06-validacao/geradores/gen-camada-ia.py
nota: fatia GERADA — o corpo abaixo é byte a byte o trecho do canônico; edite o canônico, nunca esta fatia. Canônico inteiro em https://ds.seed.eng.br/01-canonicos/seed-componentes.md
---
## 11. Combobox — `estável` · validado pelo Rafael em 2026-08-03 (preview v0.13 + suite de 63 testes)

> **Base (3 rodadas):** R1 — GOV.UK/alphagov accessible-autocomplete (venceu teste com usuários da Orange: instrução inicial + contagem anunciada), APG combobox ARIA 1.2. R2 — React Aria/shadcn Command (async, shouldFilter off em server-side), React Spectrum (tray mobile). R3 — Higley part 2 (filtro que estreita confunde — mitigar com contagem; ARIA 1.2 menos bugado), Baymard country selector (typos/sinônimos). H1–H7 conferidas no consolidado.

### 11.1 Papel

Escolha em lista >15 itens ou qualquer volume com busca (§7.1). É o SELECT que cresceu: mesma semântica de valor, mais um input de filtro. Caso canônico SEED: concessionária, municípios (H6). NÃO é a busca do §4 (que encontra conteúdo); combobox ESCOLHE um valor de lista fechada (ou criável — H5).

### 11.2 Decisões H1–H7

| # | Decisão | Porquê | Descartado |
|---|---|---|---|
| H1 | Comportamento de referência: GOV.UK accessible-autocomplete — instrução inicial no describedby ("Digite para filtrar…") + contagem de resultados na live region (§1.13) | Único padrão VALIDADO em teste com usuários de AT (Orange) | Padrões nunca testados com gente real |
| H2 | ARIA 1.2: `role="combobox"` no INPUT + `aria-activedescendant` (foco DOM fica no input); botão de abrir fora do Tab, presente para o toque | Higley: 1.2 menos bugado; APG | ARIA 1.1 (pior no teste); foco que pula pra lista (perde edição) |
| H3 | Mobile: tray/superfície plena com input dentro (herda D7/M3) | Orange: "a lista não é percebida no mobile" — o tray força a percepção | Dropdown ancorado sob teclado virtual |
| H4 | Async: debounce 300–500ms + "Carregando…" anunciado + filtro do cliente DESLIGADO quando o servidor filtra + skeleton | shadcn shouldFilter; dupla-filtragem some com resultados válidos | Spinner mudo |
| H5 | Somente-lista (padrão: valida contra a lista, restaura ao sair) × criável: opção explícita **"Criar 'Nova Venécia'"** no fim — só onde valor novo é legítimo | Baymard: typo não pode virar cadastro fantasma | Criação implícita no blur |
| H6 | Progressive enhancement do select: mesmos tokens de trigger, mesma moldura | O usuário não deve renotar a troca ao crescer a lista | Visual próprio (família desagregada) |
| H7 | Multi: chips removíveis SEMPRE visíveis no campo + contagem anunciada; ≤6 → checkboxes (§10); `<select multiple>` proibido (G5 mantido — o problema era a INVISIBILIDADE, os chips resolvem) | Higley multiselect; resolução do conflito G5×H7 da análise cruzada | Multi escondido em "3 selecionados" |

### 11.3 Anatomia

Trigger = input do §3 com chevron; painel = `surface-overlay` + `shadow-overlay`, opção ativa `--seed-surface-sunken` + `aria-selected`; contagem oculta na live region; zero resultados herda D9 ("Nenhum resultado para 'x'" + ação de recuperação — na captação: "Não achou? Fale com a engenharia"). Filtro: contém + normalização de acentos (herda D-família); realce do trecho em `<mark>` com peso, não cor sozinha.

### 11.4 Contrato

`role="combobox" aria-expanded aria-controls aria-activedescendant` no input; `role="listbox"`/`option` no painel; setas navegam, Enter seleciona, Esc fecha e restaura; `autocomplete="off"` no input (o browser não pode competir com o painel).

**H8 — Tab confirma e avança (decisão do Rafael, 2026-08-02):** Tab com uma opção DESTACADA confirma a seleção e segue para o próximo campo — é o comportamento `confirmOnBlur` default do accessible-autocomplete do GOV.UK (nossa referência H1), validado em teste com usuários; poupa um Enter em toda passagem de formulário. **Salvaguarda obrigatória:** o destaque só existe por ação ativa do usuário (setas) ou correspondência exata única — NUNCA auto-destacar a primeira opção da lista (quem digita "vit" e aperta Tab só para pular o campo levaria "Vitória (ES)" sem pedir — captura acidental, o risco documentado do padrão). Supersede: a linha "Tab fecha e mantém" do APG genérico fica substituída pela variante testada do GOV.UK.

### 11.5 Os 7 testes

1. Herda §3 + painel overlay 3:1. 2. Ativa = fundo + aria-selected (nunca só cor). 3. Grayscale: realce em bold. 4. Par combobox × busca §4: chevron × lupa (ícone distingue papel). 5. Uma lista, uma contagem. 6. Valor escolhido visível no input. 7. Tray no toque; 16px. ✅