teqo-backup/docs/plans/omnibox-limpar-mobile-impl.md

140 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Impl: C221 — "Limpar" do omnibox não pode quebrar linha no mobile
Status: aprovado
Atualizado em: 2026-09-24
Issue: #1313
Intenção: docs/plans/omnibox-limpar-mobile.md
Appetite restante: herdado (~2h eng, fill-in) — cabe: gate de design + e2e RED/GREEN + fix de classes no dono + gates; sem schema, sem server
Aprovação: `--auto` (work-issue) — plano auto-aprovado em 2026-09-24; pausa do GATE 3c dispensada pela flag
## Leitura da intenção
- **Outcome:** com chip de busca longo no mobile, o "X" de limpar do `CampaignListOmnibox` continua ancorado ao campo/chips — nunca vira linha órfã abaixo do chip, em **todas** as 17 listas que usam o shell — sem tocar desktop, a11y ou contrato de URL/filtros.
- **O que NÃO negociar:** comportamento do X (limpa tudo, refoca o input, não reabre o popover) e a11y (`aria-label="Limpar"`, `invisible`/fora da a11y tree quando vazio, anúncio sr-only); desktop `md:` (borda/ring/altura/label/"Limpar" texto/trailing cluster); barra mobile 44–48px no estado padrão (B196); marcador `campaign-list-omnibox-form` (contrato do `:has()` em `CampaignQuickActionsHost.tsx:17`) e o sticky no `<form>` do caller; font-size 16px touch (B183); URL/filtros e adaptadores intocados.
- **O que reavaliar:**
1. "O cluster `flex-wrap` é o culpado" — **confirmada**, com a geometria: a 390 o conteúdo útil do campo é 342px (form 358 − `px-2` do campo); um chip entre ~166px e ~208px deixa chip + input (min `8rem` = 128px) na linha 1 e o X (`size-9`, `shrink-0`) **sozinho na linha 2**, encostado à esquerda (não há `justify`). A faixa vazia é essa linha do X.
2. "X fora do fluxo é a estratégia mais simples" — é a recomendação de engenharia, mas **a estrutura visual final é do `designer`** (trigger (a)): o impl plan fixa o mecanismo e os invariantes, não as classes finais.
3. "Limitar a largura do chip no mobile" — só vira decisão se o artefato aprovado optar por cap/truncamento; não é decisão de engenharia (mexe em legibilidade do filtro ativo).
## Abordagem recomendada
```mermaid
flowchart LR
A[designer - trigger a<br/>estende o ui-design do omnibox] --> B[e2e RED a 390<br/>chip longo: X órfão]
B --> C[C221 no CampaignListOmnibox<br/>X fora do fluxo do wrap + folga no campo]
C --> D[e2e GREEN + regressão 390/1280]
D --> E[gates - changelog - push<br/>crítica do designer - trigger c]
```
**Opções consideradas:** A | B | C | D
**Recomendação:** A — **tirar o X do fluxo de wrap** (abaixo de `md`, posicionado de forma absoluta dentro do próprio campo, que vira `relative`; a folga do final da linha é reservada por um padding mobile no campo, de modo que chips/input não passem sob o X). É o menor diff que garante o invariante por construção: um elemento fora do fluxo nunca quebra linha. Mantém o pai do input como o campo (âncora do popover), não muda ordem DOM/tab order, não existe no desktop (`md:hidden`), e tem precedente no repo (`relative` + filho `absolute right-*` em `RelationChipCell`, `MunicipalityRelationEditor`, `CampaignInlineEditableCell`).
**Rejeitadas:**
- **B — invólucro flex interno para chips+input + X ancorado à linha do input:** muda o pai do input, quebrando `omniboxInput.locator('..')` — locator que B184/B196 usam para medir o campo (`toHaveCSS('border-top-width', …)`, `boxShadow`) — e adiciona um nível de DOM/ARIA numa área pinada por e2e; risco desproporcional ao appetite.
- **C — cap de largura do chip abaixo de `md` (`max-md:max-w-[9rem]` etc.):** tecnicamente garante o encaixe, mas trunca agressivamente o rótulo do filtro ativo (perda de contexto do recorte) e é craft/copy — se o designer quiser o campo em uma linha, ele especifica o cap; não é o fix de engenharia.
- **D — `max-md:min-w-0` no input/chip para forçar linha única:** comprime o chip até sobrar só o botão de remover e o input a ~0; destrói a leitura do filtro e o alvo de toque.
### Decisões de engenharia
- **D1 — Mecanismo do não-órfão.**
- **Opções:** A) X absoluto no campo com folga reservada por padding mobile; B) invólucro interno chips+input; C) cap de largura de chip; D) `min-w-0` no input/chip.
- **Recomendação:** A — invariante por construção (fora do fluxo = nunca quebra), menor superfície, sem mudar o pai do input nem a âncora do popover.
- **Rejeitadas:** B/C/D pelos motivos acima.
- **D2 — Fronteira engenharia × craft (designer).** Engenharia garante: o X permanece **dentro da div do campo** (o `PopoverAnchor`; o popover usa `var(--radix-popover-trigger-width)`), a folga é **padding no content box** do campo (não espaçador absoluto) para `max-w-full`/`truncate` dos chips e o `flex-1` do input continuarem corretos, e o móvel é escopado por variantes `max-md:`/`md:`. Craft (artefato do designer): offset e tamanho exato da folga, ancoragem vertical do X (centro do campo vs. linha do input), cap/truncamento de chip se houver, e se o campo pode permanecer em 2 linhas com chip longo (comportamento pré-existente; a intenção proíbe apenas o X órfão).
- **D3 — Camada de teste.**
- **Opções:** A) estender o e2e de municípios (B184) com cenário de chip longo medindo geometria a 390; B) unit de componente com Testing Library; C) snapshot/visual regression.
- **Recomendação:** A — é a única camada que mede layout de verdade (jsdom não faz layout; `getBoundingClientRect` é zero); o idioma de medição (`boundingBox` + `expect.poll`) já existe em B196; o spec irmão (`campaignMunicipalities`) já é acordado pelo prefixo do shell no manifesto.
- **Rejeitadas:** B — não prova quebra de linha e pinaria strings de classe (frágil); C — o repo não tem infra de baseline visual (inventar infra viola o appetite).
- **D4 — Manifesto e2e / blast radius do PR.**
- **Opções:** A) não tocar o manifesto (PR seleciona a família municípios, que já contém B184/B196); B) adicionar `campaignIosInputZoom` ao entry que contém o prefixo `src/components/campaign/shared/CampaignListOmnibox`; C) adicionar também os pesados (`campaignActivity`, `campaignSpeechAcervo`).
- **Recomendação:** B — `campaignIosInputZoom` é o pin barato e direto do contrato do campo (font-size 16px touch) e hoje está **fora do manifesto** (só roda no full); este diff toca exatamente o dono do campo, então o check obrigatório `checks` deve vê-lo. A família municípios (A dentro dela: B184/B196) continua sendo o grosso da cobertura.
- **Rejeitadas:** A — deixa um contrato tocado sem cobertura no gate de PR; C — encarece todo diff futuro da área com specs que pinam superfícies que este item não muda; o full verify do deploy cobre as verticais do acervo.
### Componentes / mudanças
- **`CampaignListOmnibox`** (`src/components/campaign/shared/CampaignListOmnibox.tsx`) — único arquivo de produto:
- cluster do campo (`:213-223`): passa a `relative` e ganha folga de fim de linha **só abaixo de `md`** (padding mobile; `md:` restaura `px-2`/borda/ring/altura);
- botão de limpar (`:293-322`): abaixo de `md` sai do fluxo (`absolute`, ancorado à direita do campo) mantendo `size-9 shrink-0 md:hidden`, o `invisible pointer-events-none` quando `!(hasChips || query.length > 0)` e todo o `onClick`/a11y atuais;
- comentário do fix com tag **C221** (a convenção do arquivo cita B184/B196/B200/C100/C125);
- **nada mais** muda: `campaignListOmniboxFormClassName`, chips, input, popover, trailing cluster desktop e regiões `sr-only` intocados.
- **`E2E_AFFECTED_MANIFEST`** (`scripts/lib/e2e-affected-manifest.mjs`): `campaignIosInputZoom` entra no entry que já contém `src/components/campaign/shared/CampaignListOmnibox` (D4).
- **Teste** (`tests/e2e/campaignMunicipalities.e2e.spec.ts`): novo `test` dentro do describe `Municípios — filtro e cards sem moldura no celular (B184)` (viewport 390 herdado).
- **Design:** `docs/plans/omnibox-limpar-mobile-ui-design.html` (novo artefato; o design da C219 não cobre o X dentro do campo nem a quebra — trigger (a)).
- **Changelog:** `docs/changelog/2026-09-24-c221.md` (uma entrada, formato dos recentes).
- **Migration:** sem migration.
- **Access / Consent:** nenhum (zero paths de escrita/PII; componente de apresentação).
- **UI:** Impeccable B — ajuste de encaixe do shell existente; shape→craft→critique→polish com o `designer` (trigger (a) antes do markup; trigger (c) no fechamento, screenshot 390/1280 contra o artefato; tier registrado no PR; `DEGRADED` fail-closed: `work-issue` para antes do push para sign-off, `agent-work-issue` comenta e bloqueia sem PR).
### Superfícies afetadas (17 call sites, zero edições por consumidor)
Todas usam o mesmo shell; o fix no dono as cobre sem tocar arquivo por arquivo:
- **Acervo — Câmara:** `speech/SpeechAcervoFilters.tsx:215`, `speech/SpeechCutLibraryFilters.tsx`
- **Acervo — Gravações:** `recording/RecordingAcervoFilters.tsx:232`
- **Fora do acervo (amostras de regressão):** `municipality/MunicipalityFilters`, `municipality/CampaignUpdatesFilters`, `municipality/TerritoryFilters`, `activity/ActivityFilters`, `activity/ActivityAgendaFilters`, `advisor/AdvisorFilters`, `contacts/ContactFilters`, `content/ContentPieceFilters`, `demand/DemandFilters`, `leadership/LeadershipFilters`, `organization/OrganizationFilters`, `people/PeopleFilters`, `stateDeputy/StateDeputyFilters`, `supporter/SupporterFilters`
### Dados → forma
N/A — nenhuma métrica/dado novo; é encaixe de superfície existente.
## Fases verificáveis
1. **Design (trigger a) — bloqueante, antes de qualquer markup.** O `designer` estende/cria o artefato hi-fi com cenas 390 (campo com chip de busca longo commitado, chip curto + texto digitado, vazio — X visível e invisível) e 1280 (intocado), usando os tokens da campanha. Saída: artefato certificado em tier primário, ou `DEGRADED` com sign-off humano registrado. Referências do débito: `/tmp/opencode/c219-shots/06-mobile-empty.png` e `11-mobile-camara-long-chip.png` (se ainda existirem na máquina da sessão).
2. **Tracer — e2e RED (~30–40min).** Adicionar ao describe B184: login, `page.goto('/campanha/municipios?q=<texto longo>')` (o `?q=` renderiza o chip `Busca: <texto>` de forma determinística, sem depender de sugestão do popover), esperar o chip e o X (`getByRole('button', { name: 'Limpar', exact: true })`), e assertar com `boundingBox` + `expect.poll` (idioma de B196):
- **(1) X ancorado à direita do campo:** `field.x + field.width − (x.x + x.width) <= 16` (o bug deixa o X à esquerda: inset ≈ 300px);
- **(2) X compartilha a faixa vertical do conteúdo:** centro do X `< input.y + input.height`;
- **calibrar o texto do `?q=` até o teste ficar vermelho no código atual** (janela do órfão: chip entre ~166 e ~208px; documentar a aritmética num comentário do teste). Se o comprimento não cair na janela, ajustar o texto — nunca afrouxar a asserção. Prova: teste vermelho com o componente pré-fix.
3. **Fix (~30–45min).** Portar o artefato aprovado classe-a-classe, restrito ao dono (D1/D2). Invariantes: pai do input continua o campo; X dentro da âncora; `invisible` quando vazio; `md:` restaura tudo; nenhum adapter/URL tocado.
4. **Verde + regressão (~30min).** E2e novo verde; rodar localmente os e2e da mesma superfície — `campaignMunicipalities`, `campaignIosInputZoom`, `campaignUpdatesMobile`, `campaignActivity` (discricionário OPS72; o CI do PR seleciona a família municípios + `campaignIosInputZoom`); capturas manuais a **390** em uma lista de cada vertical do acervo (Câmara em `/campanha/comunicacao/acervo`, Gravações na mesma rota com `?source=enviadas`) + uma fora do acervo (`/campanha/municipios`), com chip longo, chip curto + digitado e vazio; desktop **1280** no mesmo estado. `pnpm gate:fast`.
5. **Fechamento (~15min).** `/simplify`; crítica final do `designer` (trigger c) contra o app renderizado; changelog; `pnpm push`; PR ready cuja descrição lista as superfícies, o tier de design e a nota do manifesto.
## Rabbit holes / Não escopo (engenharia)
- **Invólucro em volta do input** (para agrupar chips+input) — proibido: quebra `omniboxInput.locator('..')` de B184/B196 e a âncora do popover; se o artefato do designer propuser isso, é divergência material e volta ao humano.
- Renomear `campaign-list-omnibox-form` ou mover o sticky do `<form>` do caller — contrato do `:has()`/B196.
- Redesenhar a barra, os facet popovers, o `CampaignSearchModeControl` ou o trailing desktop.
- Cap/truncamento de chip como decisão de engenharia — só se o artefato pedir.
- "Consertar" o campo em 2 linhas com chip longo — comportamento pré-existente; o aceite é o X não ser linha própria.
- Unit de layout em jsdom ou infra de snapshot visual nova — não existe no repo; não inventar.
- Tocar `styles.css` (regra B183) ou o `text-sm` do input.
- Editar os 17 consumidores ou qualquer adapter/URL.
## Riscos e mitigação
- **Falso verde do e2e** (asserção que passa no código quebrado): mitigado por (i) **prova RED obrigatória** na Fase 2 antes do fix; (ii) asserção principal com margem enorme (inset ≈ 300px no bug vs ≤ 16px no fix); (iii) janela do órfão documentada no comentário para calibrar o texto. Se a fonte do CI mudar métricas, o teste pode voltar a passar por acidente — o segundo cenário de regressão manual (390, chip longo) é o backstop; gatilho para reabrir: B184 quebrar sem o teste acusar.
- **Regressão de desktop:** `relative` é inerte e a folga/posicionamento entram sob variantes `max-md:`; B184 já asserta a volta do desktop (borda 1px, label visível, "Limpar" texto); 1280 manual na Fase 4.
- **Altura da barra:** absoluto não adiciona linha; a folga horizontal não muda a altura; B196 segue pinando 44–48px no estado padrão.
- **X sumir/sobrepor conteúdo:** folga via padding de content box (chips `max-w-full`/`truncate` e input `flex-1` respeitam); X continua dentro da âncora, então o popover mantém `var(--radix-popover-trigger-width)` e a área de toque.
- **A11y:** ordem DOM/tab order inalterada; `invisible` continua tirando o X da a11y tree quando vazio (B184: `toHaveCount(0)`); `aria-label`/ring/sr-only intocados.
- **iOS 16px (B183):** nenhum font-size de form control é alterado; a regra `(pointer: coarse)` continua dona. `campaignIosInputZoom` entra no selecionado (D4).
- **Design `DEGRADED`:** fail-closed conforme pipeline — sem tier primário não há certificação; `work-issue` para antes do push, pool não abre PR.
- **Cobertura das verticais do acervo no PR:** o prefixo do shell no manifesto só acorda a família municípios; as demais verticais ficam com a rodada local discricionária + full verify do deploy — registrado no PR (D4).
## Débitos (triage do /simplify, 2026-09-24)
- **Deferido — viewports <390px (ex. iPhone SE, 375px):** o cap de 168px + o input `min-w-[8rem]` podem voltar a ocupar 2 linhas (a barra cresce ~46px), com o X ainda ancorado/centrado (aceite preservado). O design aprovado e o e2e cobrem o alvo 390. **Gatilho:** reporte real em aparelho estreito ou o próximo ajuste do shell de filtros.
- **Deferido — warning React de key (dev) no omnibox de assessores:** o console guard local acusa `Each child in a list should have a unique "key" prop — CampaignListOmnibox` na página de assessores (pré-existente, não determinístico, ausente em prod/build). **Gatilho:** warning determinístico no console guard ou a próxima passagem pelo `campaignColumnPicker`.
- **Descartados:** hidratação divergente do `AISidebarSurfaces` em capturas temporárias (intermitente, alheia); flakiness de login/POST do e2e local sob carga alta (ambiente, não débito do item).
## Aceite de engenharia
- [ ] Com chip de busca longo a 390, o X permanece ancorado ao campo/chips (novo e2e com **RED provado antes do fix**), em todas as listas (mesmo shell, sem edição por consumidor)
- [ ] A11y intacta: `aria-label="Limpar"`, ring de foco, `invisible` fora da a11y tree quando vazio, anúncio sr-only
- [ ] Desktop `md:` intocado (B184 desktop leg + captura 1280); barra mobile 44–48px (B196); font-size touch 16px (B183)
- [ ] URL/filtros e adaptadores intocados (diff não toca nenhum)
- [ ] Sem migration, sem access, sem Consent, sem PII
- [ ] Regressão manual 390: Câmara (acervo), Gravações (`?source=enviadas`) e uma lista fora do acervo (municípios), nos estados chip longo/curto+digitado/vazio
- [ ] `pnpm gate:fast` + e2e locais da superfície; changelog `docs/changelog/2026-09-24-c221.md`; `pnpm push`
- [ ] Design: artefato `docs/plans/omnibox-limpar-mobile-ui-design.html` estendido/certificado (trigger a) e crítica final (trigger c); tier registrado no PR
## Self-score (decision-quality, gate ≥4)
| Critério | Nota | Justificativa |
| ----------------------------- | ---- | ---------------------------------------------------------------------------------------------------- |
| Decisões caras com rejeitadas | 5/5 | D1–D4 no formato Opções/Recomendação/Rejeitadas; mecanismo, craft, teste e manifesto deliberados |
| Abordagem cabe no appetite | 5/5 | 1 arquivo de produto + 1 teste + 1 linha de manifesto; sem schema/server; ~2h |
| Rabbit holes nomeados | 5/5 | Invólucro no input, cap de chip, campo em 2 linhas, unit jsdom, 17 consumidores, `styles.css` |
| Depth check (reusa donos) | 5/5 | Fix no dono do encaixe (`CampaignListOmnibox`), e2e no spec dono do B184, sem módulo/collection novo |
| Intenção preservada | 5/5 | Aceite de produto (X nunca órfão) intacto; engenharia não reescreveu outcome nem escopo |
**Agregado: 5/5 — aprovado em modo `--auto`.**