Detalha chassis, busca de município, ajuste de votos, simplificação do sinal e fluxo de registro; atualiza o rascunho de fluxos e o roadmap.
5 KiB
Etapa de busca de município nos wizards
Status: rascunho Atualizado em: 2026-07-29 Item do roadmap: docs/roadmap.md (Trilha B, item B60 — UX-1 wizards) Impeccable: B — encaixe da UX da busca do Início (B47/B48) numa etapa de wizard, só municípios Appetite: ~1 dia eng; input + lista de hits + auto-avanço; soft reuso do loader B48 Responsável: —
Design (Impeccable)
Âncoras: PRODUCT.md / DESIGN.md · B47 CampaignHomeSearch / B48 linhas de município · tema campaign.
Na implementação: craft compacto → critique → polish.
Brief compacto:
- Persona: CG digita “Cairu” no meio do ritual A1/A2 e quer o município em 1 toque.
- Job principal: achar o município no escopo do ator e avançar sozinho ao selecionar.
- Estratégia de cor: Restrained.
- Edit where you see: não — seleção é navegação de fluxo.
- Anti-goals: grupos (TI/lideranças/…); botão “Continuar” após selecionar; card por linha.
Dados → decisão → apresentação
- Vou apresentar dados? Sim — hits de município (nome, TI, opcional “2022” se B48 já tiver o readout).
- Decisões: escolher qual município entra no fluxo.
- Forma: lista ranqueada por nome (word-start), igual espírito B48. Rejeitado: mapa; grupos multi-entidade.
- Profile: scoped ao access; tipicamente <20 hits.
- Anti-goals de dado: sem inventar métrica; sem TIs neste passo (wizard precisa de unidade operacional
municipality).
Contexto
No Início, B47 ✓ entrega input + modo focado; B48 lista Municípios (+ TIs no mesmo grupo). Nos wizards (pedido 2026-07-29): mesma experiência de busca, com duas diferenças — (1) sem grupos: só municípios; (2) selecionar = avançar ao próximo passo, sem confirmar.
Serve A1 (votos), A2 (sinal), A3/A4/A5 e qualquer fluxo que precise de local cedo (fluxos-acao-primeiro-inicio.md § contrato #2).
Objetivos
- Etapa reutilizável (ex.
WizardMunicipalitySearchStep) montada no B59: input debounce (mesmo espírito 250 ms de B47), lista de hits apenasmunicipality, escopooverrideAccess: false. - Clique/Enter no hit → callback/
router.pushpara o próximo passo com município escolhido (slug ou id na URL/query do fluxo). - Sem botão “Continuar” / “Confirmar município”.
- Recentres / prioritários opcionais acima da busca (soft; cortável) — 3 recentes se
recentVisitsjá existir no Início. - Match:
matchesAtWordStart/normalizeSearchPhrase(lib/wordStartFilter.ts). - Sem migration / Consent.
- Se B48 já tiver
searchHomeMunicipalities, filtrar/omitir TIs e reusar o loader; senão, loader mínimo só de municípios (depth: não duplicar fuzzy).
Decisões travadas
- Só municípios — TIs fora deste passo (wizard grava em
municipality). Rejeitado: copiar B48 com TIs (não hámunicipalitypara um TI). - Select = auto-avanço. Rejeitado: seleção + “Continuar” (pedido explícito; atrito no ritual).
- Mesma linguagem visual da busca do Início (linha sem card, tipografia). Rejeitado:
Command/Comboboxde lista (B27) como UI primária — é outro modelo mental. - i18n:
WizardMunicipalitySearch, copy “Em qual município?”.
Questões em aberto
- Mostrar votos 2022 à direita no wizard? Opções: A sim (paridade B48) | B só nome+TI. Recomendação: B no v1 se B48 ainda não landou; A quando o readout existir e não atrasar o appetite. (assumido)
Abordagem proposta
flowchart LR
Shell["B59 Shell"] --> Input["input debounce"]
Input --> Loader["searchMunicipalitiesScoped"]
Loader --> Hits["lista só município"]
Hits -->|select| Next["próximo passo + slug"]
Componentes:
WizardMunicipalitySearchStep(client island): input + results; registra seleção.- Loader — reuso B48 ou
utilities/municipality/comoverrideAccess: false. - Reuso:
useHomeSearchQuerypattern / debounce B47; não importar o chrome focado do Início inteiro. - Migration: Sem migration.
Dependências
- Dura: B59. Soft: B48 (UX/loader), B47 ✓ (debounce/modo focado como referência).
Não escopo
- Grupos lideranças/assessores/… → B49–B53 (só Início). Ajuste de votos → B61. Chassis → B59.
Rabbit holes
- Um único componente de busca para Início e wizard. Mitigação: compartilhar loader + row renderer; chrome (grupos vs só município, onSelect vs Link) fica nos wrappers — extrair shared só com 2 call sites reais medidos.
Adiado com gatilho
- Chips de recentes/prioritários acima do input. Revisitar se o CG pedir atalho sem digitar (sessão).
Referências
- busca-global-inicio-input.md · busca-global-resultados-municipios.md · chassis-wizard-campanha.md ·
lib/wordStartFilter.ts·recentVisitsutilities - AGENTS.md — access advisor;
overrideAccess: false PRODUCT.md/DESIGN.md