teqo-backup/docs/plans/filtros-salvos-municipios.md
Francisco Ignácio Fontoura Solla ac2390587e B18: saved municipality list filters in localStorage and sidebar submenu.
Bookmarks the canonical list recorte beside Limpar, syncs via useSyncExternalStore, and matches active URLs with a pure href comparator so the app layout never imports the heavy URL serializer.
2026-07-28 19:25:12 -03:00

76 lines
9.3 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.

# B18 — Filtros salvos na lista de Municípios (+ acesso rápido no sidebar)
Status: ✓ entregue (2026-07-28) — sem migration, sem collection, sem server action, sem `Consent`
Atualizado em: 2026-07-28
Item do roadmap: [docs/roadmap.md](../roadmap.md) (B18; superfície de coordenação)
Impeccable: B — craft + critique + polish em `MunicipalityFilters` e `CampaignSidebar`; sem rota nova
Appetite: ~1–1,5 dia eng (gasto: dentro)
Responsável: —
## O que ficou de pé
Em `/campanha/municipios`, um botão **Salvar filtro** ao lado de **Limpar** nomeia o recorte atual da URL, e o atalho passa a viver como **submenu de 2º nível sob Municípios** no sidebar — com chevron, estado persistido, item ativo, apagar com desfazer.
Três camadas:
- **`src/utilities/municipalitySavedFilters.ts`** — `localStorage` com cache de snapshot para `useSyncExternalStore`, `MAX_ENTRIES = 12`, `MAX_NAME_LENGTH = 60`, ordem alfabética, limpeza no logout.
- **`src/lib/listQueryMatch.ts`** — `isSameListHref(a, b, ignoredParams)`, puro e sem imports pesados.
- **`MunicipalityNavSavedFilters`** + **`SaveMunicipalityFilterControl`**, sincronizados pelo hook compartilhado `useMunicipalitySavedFilters`.
## Premissas do plano de 2026-07-24 que morreram na auditoria
Registradas porque cada uma custou trabalho que o appetite original não previa, e porque voltar a acreditar nelas custaria de novo:
1. **`SidebarMenuSub` / `SidebarMenuSubItem` / `SidebarMenuSubButton` / `SidebarMenuAction` NÃO existiam.** O plano dizia "existem no shadcn local e não são usados" — o Pass 2 W4b pôs knip `exports` em ERROR e o kit foi podado. Foi preciso **re-adicioná-los** do upstream. Ao fazê-lo apareceu um bug latente do kit: React renderiza `data-active={false}` como `data-active="false"`, e o seletor Tailwind `data-active:` casa com `[data-active]` — ou seja, **todo item não-ativo estava recebendo o estilo de ativo**. Agora o atributo só é emitido quando verdadeiro (`data-active={isActive || undefined}`), em `SidebarMenuButton` e `SidebarMenuSubButton`.
2. **`src/utilities/municipalityUi.ts` não existe** — o Pass 2 W1 o dividiu em `municipalityListUrl.ts`, `municipalityListFilters.ts`, `municipalityLabels.ts` e `municipalitySignal.ts`. `buildMunicipalitySavedFilterHref` nasceu em `municipalityListFilters.ts`.
3. **O estado da URL cresceu** muito além do que o plano listava (`q`, `regions[]`, `slugs[]`, `advisors[]`, `kind`, `coverage`, `priority`, `trends[]`, `classes[]`, `levels[]`, `compare`, `sort`, `dir`, `page`). Serializar o estado inteiro menos `page`/`compare` absorveu isso sozinho — nenhuma lista de params foi escrita à mão.
4. **B17 persiste em cookie, não `localStorage`.** A linha de contexto do plano estava errada. Não muda a decisão (o bookmark não precisa chegar ao render do servidor).
5. **"Ao lado de Limpar / Colunas" como uma fileira só é impossível:** `Limpar` está em `MunicipalityFilters` e `Colunas` está dentro de `CampaignTable`, numa fileira compartilhada pelas sete listas. Decidido na sessão: **barra de filtros, ao lado de Limpar**.
6. **`municipalityListHasSavableFilters` não precisou existir.** `formatMunicipalityActiveFiltersSummary` já é o gate "tem filtro?" (é o que o `Limpar` usa) **e** já produz o rótulo legível de todos os filtros — então ele é ao mesmo tempo a condição de montagem do botão e o **nome padrão** sugerido no Popover.
7. **Disclosure por hover morreu com B38 ✓.** Com `collapsible="offcanvas"`, recolhido no desktop a sidebar sai inteira da tela e não sobra rail para hover. Virou **collapsible com chevron e estado persistido**, decidido com o usuário.
8. **Renomear entrou no v1**, ao contrário do "adiado" do plano: como a identidade é o href e re-salvar é upsert, o botão simplesmente lê **"Renomear"** quando o recorte atual já está salvo, e o Popover abre pré-preenchido. Custou uma string, não uma fase.
## Decisões de engenharia que valem guardar
- **O casamento "URL atual == filtro salvo" não pode usar o serializador de URL do domínio.** A sidebar está no layout de `(app)`, então tudo que ela importa entra no First Load JS de **toda** rota `/campanha`, e o AGENTS.md já registra que importar `buildMunicipalityListHref` num island custou **21 kB** (arrasta `bahiaTerritories` + `municipalityCatalog`). Daí `src/lib/listQueryMatch.ts`: comparação de `URLSearchParams` insensível à ordem, que de quebra resolve um caso que o plano não previu — **estar na página 3 de um filtro salvo ainda é estar nele** (`page` é posição dentro do recorte, não parte dele).
- **Medido contra árvore limpa (`git stash`), que é a única forma de afirmar isso:** `/campanha` ficou **inalterado em 277 kB**; `/campanha/municipios` foi de **328 → 330 kB**. A fase `optimize` não disparou.
- **A identidade é o href, não um UUID.** O plano previa `id` + `name` + `href` + `savedAt`; sobrou `{ href, name }`. Um UUID só existiria para permitir dois atalhos que navegam para o mesmo lugar, que é exatamente o que o upsert existe para impedir — e `savedAt` não é lido por nada, porque a ordem é **alfabética** de propósito: um atalho nomeado que se reordena sozinho sob o cursor cada vez que é re-salvo é um bug de navegação. Recência é o trabalho de Visitados.
- **O teto é checado contra as OUTRAS entradas** (`others.length >= MAX_ENTRIES`), não contra o tamanho armazenado — senão renomear no limite passaria a ser recusado.
- **O `useSyncExternalStore` tem o server snapshot como constante congelada.** Devolver `[]` fresco ali é o loop de render clássico; o snapshot do cliente é cacheado e invalidado por escrita e por `storage` de outra aba (o evento nativo não dispara na aba que escreveu — daí o evento custom que cobre a outra metade).
## Dois bugs reais que só o e2e pegou
1. **O auto-open reabria o grupo em toda montagem, tornando a preferência persistida inobservável exatamente para quem mais usa filtros salvos:** o usuário recolhe o grupo, recarrega, e ele volta. A causa não é óbvia — o gatilho era `activeHref` aparecer, mas **o store responde vazio até o cliente ler o `localStorage`**, então um match surgindo da hidratação se parecia com uma navegação. O gatilho passou a ser a **URL mudar**; a preferência guardada vence na montagem e o "revelar onde você está" fica reservado à navegação que de fato muda o atalho corrente.
2. **Apagar uma linha derrubava o foco para `<body>`.** O sucessor é resolvido **antes** da remoção, porque esvaziar o grupo desmonta o componente inteiro — chevron incluído — e nesse caso o alvo tem de ser o link de nav.
## Achados de acessibilidade corrigidos no critique
- **SC 2.5.3 (Label in Name):** o botão mostrava "Salvar filtro" e tinha `aria-label="Salvar este filtro"`. O nome acessível precisa **conter** o rótulo visível, ou "clique em Salvar filtro" por voz não casa com nada. O `aria-label` saiu do caso de salvar; o de renomear fica, porque mantém a palavra visível na frente.
- A mensagem de recusa ganhou `aria-describedby` do input além do `role="alert"` que o `Alert` já traz: o alerta anuncia uma vez, o `describedby` é o que conta a quem volta ao campo **por que** ele ainda está inválido.
- O `<ul>` do submenu ganhou nome (`aria-label="Filtros salvos de Municípios"`), e os links ativos ganharam `aria-current="page"` — inclusive os de 1º nível, que não tinham.
- Apagar é revelado no hover/foco no desktop com `opacity-0` (que continua focável e no a11y tree, ao contrário de `hidden`) e é **permanentemente visível no toque**.
## Não escopo (mantido)
Sync multi-device / preferências em `campaignUser`; saved views em outras listas (FD2 já vetou o genérico); rota `/vistas/[id]`; incluir Cenário A10 ou `compare` do mapa no bookmark; salvar junto o viewport de colunas do B17.
## Adiado com gatilho
- **Árvore de navegação genérica em `nav.ts`.** Este item especializa **só** Municípios, via a constante exportada `MUNICIPALITY_NAV_HREF`. **Gatilho:** o 3º call site de submenu no sidebar.
- **Sync servidor / compartilhar recorte entre assessores.** **Gatilho:** evidência de multi-device **e** pedido explícito de "mandar este recorte" — aí sim collection + access, fora deste appetite.
## Testes
- `tests/unit/listQueryMatch.unit.spec.ts` — ordem trocada casa, `page` diferente casa, filtro a mais não casa, percent-encoding normaliza.
- `tests/unit/municipalitySavedFilters.unit.spec.ts` — upsert por href, cap, shape inválido, dedup, cache de snapshot.
- `tests/e2e/campaignSavedFilters.e2e.spec.ts` — filtrar → salvar → submenu → ativo na página 2 → restaurar → renomear → apagar → desfazer, e o disclosure persistido através de reload.
**Nota operacional:** `pnpm build` limpa `.next`, e o servidor de dev do e2e usa `NEXT_DIST_DIR=.next/e2e` — rodar o build entre duas rodadas de e2e derruba o cache de compilação e faz o projeto `setup` estourar os 90 s. Não é flake do teste.
## Referências
- `docs/plans/visitados-recentemente.md` — precedente de localStorage + logout
- `docs/plans/seletor-colunas-lista-municipios.md` (B17) — vizinho que persiste em **cookie**, porque o servidor precisa ler
- `src/utilities/municipalityListUrl.ts` / `municipalityListFilters.ts` — contrato de URL congelado
- `src/utilities/recentVisits.ts` — espelho de storage
- `src/components/ui/Sidebar.tsx` — `SidebarMenuSub*` / `SidebarMenuAction` re-adicionados