teqo-backup/docs/plans/modo-focado-busca-no-focus.md
2026-07-30 01:22:56 -03:00

9.7 KiB
Raw Blame History

Modo focado da busca no focus (não na digitação)

Status: entregue (2026-07-30) Atualizado em: 2026-07-30 — as-built: predicado homeSearchUiFocused (inputFocused || query.isActive) já no contrato/hook (overlap B68); CampaignHomeLayout retrai summary+spacer (data-slot="home-chrome") e actions (grid 0fr/1fr + opacity 220ms ease-out, motion-reduce:transition-none) em vez de hidden; md:flex-none no chrome para não crescer no desktop; HomeSearchHitRow onMouseDown preventDefault (blur→click); e2e focus sem digitar + regressão com digitação; unit layout/search atualizados. Sem migration. Item do roadmap: docs/roadmap.md (Trilha B, item B66 — UX-1 busca Início) Impeccable: B — encaixe de motion/estado no chrome do Início (CampaignHomeLayout / CampaignHomeStaffChrome) sob tema campaign Appetite: ~0,5–0,75 dia eng; estado focused ≠ query.isActive + transição CSS; sem migration Responsável: —

Design (Impeccable)

Âncoras: PRODUCT.md (Clarity under pressure; Feel the action) / DESIGN.md · B47 CampaignHomeSearch / B46 layout · tema data-theme='campaign'.

Na implementação (implement-roadmap-item): craft compacto → critique → polish.

Brief compacto:

  • Persona / contexto: CG/assessor toca a busca no Início para achar um município; ainda não digitou — quer a tela limpa já, sem esperar a 1ª letra.
  • Job principal: ao focar o input, o resto do Início cede espaço com animação (como se a barra expandisse para ocupar a tela); resultados só quando a query passar o limiar B47/B48.
  • Estratégia de cor: Restrained — motion de layout/opacity, sem overlay escuro tipo modal.
  • Edit where you see: não — chrome de descoberta.
  • Anti-goals: modo focado só após digitar (decisão B47 supersedida); sumir o input; command palette ⌘K; position:fixed full-screen que compete com bottom nav / teclado.

Dados → decisão → apresentação

Dados: N/A — chrome + motion; hits continuam em B48–B55.

Contexto

B47 ✓ entregou input + modo focado, com decisão travada: expand = query não vazia (rejeitou focus-only para “não roubar o ritual de ações”). Em produção visual, quem foca a barra ainda vê strip/resumo/dock até digitar — atrito no gesto de busca.

Pedido de produto (2026-07-29): limpar a tela ao focar a barra (não ao começar a digitar) e animar a redução do resto do conteúdo, como se a busca expandisse para tomar a tela.

Isto emenda B47 (não reabre B48+). Hits, debounce 250 ms e limiar ≥2 chars permanecem.

Código vivo: focused = searchState.query.isActive em CampaignHomeStaffChrome.tsx; CampaignHomeLayout esconde spacer/strip com focused; contrato em campaignHomeSearchContract.ts.

Objetivos

  • Separar uiFocused (input com foco ou query ativa) de query.isActive (debounced ≥ limiar — dispara fetch B48).
  • Ao focus do input: entrar em modo focado imediatamente — strip de ações, spacer B46/B65, resumo B56 (quando landar) e demais chrome do Início fora da região busca+resultados retraem com transição (altura/opacity/transform — “expandir a busca”), não sumir em hard cut.
  • Ao blur com query vazia (após trim): sair do modo focado e restaurar o chrome (mesma transição inversa).
  • Com query ativa: permanecer focado mesmo se o foco for para um hit (Tab / toque na lista) — igual espírito atual, sem reaparecer strip no meio da leitura.
  • Escape: limpa query (B47) e, se ficar vazia, sai do modo focado (blur ou uiFocused=false).
  • prefers-reduced-motion: reduce → sem animação (só estado final).
  • Soft: se B65 já ancorou o dock no inferior, a animação parte dessa posição; se não, anima a partir do layout atual.
  • Soft: etapa B60 (busca só município) herda o mesmo critério se houver chrome residual no shell — senão N/A.
  • Sem migration / collection / Consent / mudança de contrato JSON de busca.
  • Pins: unit no predicado uiFocused / saídas blur+Escape; e2e leve “focus esconde strip antes de digitar” se estável.

Decisões travadas

  • Focus dispara limpeza; digitação dispara só hits. Opções rejeitadas: A) manter B47 “só query” (pedido explícito anula); B) focus e fetch com 0 chars (ruído / custo). Escolhido: uiFocused = inputFocused || query.isActive; fetch continua gated por isActive.
  • Animação = retração do chrome, não overlay modal. Rejeitado: scrim escuro / Sheet full-screen / fixed inset-0 que tapa bottom nav; teleportar o input para outro nó DOM (quebra foco/teclado).
  • Blur vazio restaura; blur com query ativa mantém focado. Rejeitado: sticky forever até Escape (rouba Início se o usuário toca fora sem limpar).
  • Emenda B47, não novo input. Reusa CampaignHomeSearch + layout; só o predicado e a transição mudam. Fonte: produto 2026-07-29.
  • i18n: ids uiFocused / home-search-expanding; copy intacta.

Questões em aberto

  • Duração / easing da transição? Opções: A ~200–250 ms ease-out (paridade Feel the action) | B ~150 ms | C só opacity sem height. Recomendação: A com height/opacity no grupo chrome; medir jank no mobile — se layout thrash, cair para C. (assumido — craft)
  • Pointer coarse: focus via tap já abre teclado — animar em paralelo ao teclado? Opções: A animar sempre | B adiar animação até visualViewport estabilizar. Recomendação: A na v1; B só se critique mostrar salto. (assumido)

Abordagem proposta

flowchart LR
  Focus["input focus"] --> UI["uiFocused=true"]
  UI --> Anim["transição: strip/spacer/resumo retraem"]
  Type["debounce ≥ limiar"] --> Hits["query.isActive → B48 fetch"]
  BlurEmpty["blur + raw vazio"] --> Restore["uiFocused=false"]
  Esc["Escape"] --> Clear["clear query"] --> Restore

Componentes:

  • useHomeSearchQuery / HomeSearchController: expor inputFocused + setters, ou mover uiFocused para CampaignHomeStaffChrome com onFocus/onBlur no input — depth: um predicado documentado, sem segundo hook.
  • CampaignHomeSearch: encaminhar onFocus/onBlur (cuidado com blur→click em hit: relatedTarget / pointerdown prevent — padrão lista; não fechar antes do click no resultado).
  • CampaignHomeLayout: focused passa a significar uiFocused; classes de transição (transition-[…], data-home-focused) no spacer/actions; results slot inalterado.
  • campaignHomeSearchContract: helper puro homeSearchUiFocused({ inputFocused, isActive }) + unit spec; JSDoc atualiza a semântica supersedida de B47.
  • Migration: Sem migration, sem collection, sem server action.

Dependências

  • Dura: B47 ✓ (chrome existe).
  • Soft: B65 (âncora inferior — animação parte do dock certo); B56 (resumo some no focus como o resto); B60 (paridade visual se couber).

Não escopo

  • Providers / layout de hits → B48–B55.
  • Âncora inferior idle → B65.
  • Chassis wizard / município sticky → B59.
  • Atalho ⌘K / busca na sidebar.

Rabbit holes

  • Framer Motion / lib de spring. Mitigação: CSS transitions + tokens; lib só se 3º call site de motion complexo.
  • Sincronizar pixel-perfect com teclado iOS. Mitigação: não amarrar a visualViewport na v1.
  • Reescrever B47 plan como se nunca tivesse rejeitado focus. Mitigação: as-built B47 fica; este item documenta a emenda.

Adiado com gatilho

  • Persistir ?q= na URL do Início. Já adiado em B47 — reabrir só com pedido de shareable search.
  • Gesture “puxar para baixo para fechar” no modo focado. Revisitar se mesa pedir dismiss sem Escape/blur.

Já resolvido no simplify (não reabrir)

  • HomeChromeRetractionShell extrai o wrapper retrátil duplicado (summary/spacer + actions).
  • data-slot="home-actions-chrome" para queries de teste estáveis (sem parentElement).
  • order-* só nos filhos do dock; removido de nós internos mortos.
  • Testes de retração só em campaignHomeLayout.unit.spec.tsx (removidos duplicados de campaignHomeSearch).
  • Comentário cross-ref RelationChipCell em HomeSearchHitRow (onMouseDown blur→click).

Explicitamente fora (pós-/simplify, defer)

Achado Gatilho para revisitar
Animar só opacity (sem grid-rows height) jank medido no mobile com teclado aberto
Extrair homeChromeRetractionClass para lib/ 3º call site de chrome retrátil
Context split para cortar re-render a cada keystroke perf medido com busca focada + digitação
onPointerDown em vez de onMouseDown nos hits QA reporta blur antes do tap em touch
Helper beforeEach compartilhado no e2e de ações descartado — boilerplate aceitável
Alinhar margin/flex-1 na transição do spacer polish cosmético; só se critique visual pedir

Referências

  • busca-global-inicio-input.md — decisão supersedida (“expand = query”)
  • ancorar-busca-acoes-inicio-mobile.md — dock idle
  • src/components/campaign/dashboard/CampaignHomeStaffChrome.tsx
  • src/components/campaign/dashboard/CampaignHomeLayout.tsx
  • src/components/campaign/dashboard/CampaignHomeSearch.tsx
  • src/components/campaign/dashboard/useHomeSearchQuery.ts
  • src/lib/campaignHomeSearchContract.ts
  • PRODUCT.md / DESIGN.md — Field Desk / Feel the action
  • AGENTS.md — naming; sem Consent