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.
9.3 KiB
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 (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—localStoragecom cache de snapshot parauseSyncExternalStore,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 compartilhadouseMunicipalitySavedFilters.
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:
SidebarMenuSub/SidebarMenuSubItem/SidebarMenuSubButton/SidebarMenuActionNÃO existiam. O plano dizia "existem no shadcn local e não são usados" — o Pass 2 W4b pôs knipexportsem ERROR e o kit foi podado. Foi preciso re-adicioná-los do upstream. Ao fazê-lo apareceu um bug latente do kit: React renderizadata-active={false}comodata-active="false", e o seletor Tailwinddata-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}), emSidebarMenuButtoneSidebarMenuSubButton.src/utilities/municipalityUi.tsnão existe — o Pass 2 W1 o dividiu emmunicipalityListUrl.ts,municipalityListFilters.ts,municipalityLabels.tsemunicipalitySignal.ts.buildMunicipalitySavedFilterHrefnasceu emmunicipalityListFilters.ts.- 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 menospage/compareabsorveu isso sozinho — nenhuma lista de params foi escrita à mão. - 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). - "Ao lado de Limpar / Colunas" como uma fileira só é impossível:
Limparestá emMunicipalityFilterseColunasestá dentro deCampaignTable, numa fileira compartilhada pelas sete listas. Decidido na sessão: barra de filtros, ao lado de Limpar. municipalityListHasSavableFiltersnão precisou existir.formatMunicipalityActiveFiltersSummaryjá é o gate "tem filtro?" (é o que oLimparusa) 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.- 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. - 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 importarbuildMunicipalityListHrefnum island custou 21 kB (arrastabahiaTerritories+municipalityCatalog). Daísrc/lib/listQueryMatch.ts: comparação deURLSearchParamsinsensí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:/campanhaficou inalterado em 277 kB;/campanha/municipiosfoi de 328 → 330 kB. A faseoptimizenã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 — esavedAtnã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
useSyncExternalStoretem 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 porstoragede 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
- 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
activeHrefaparecer, mas o store responde vazio até o cliente ler olocalStorage, 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. - 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. Oaria-labelsaiu do caso de salvar; o de renomear fica, porque mantém a palavra visível na frente. - A mensagem de recusa ganhou
aria-describedbydo input além dorole="alert"que oAlertjá traz: o alerta anuncia uma vez, odescribedbyé 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 ganharamaria-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 dehidden) 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 exportadaMUNICIPALITY_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,pagediferente 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 + logoutdocs/plans/seletor-colunas-lista-municipios.md(B17) — vizinho que persiste em cookie, porque o servidor precisa lersrc/utilities/municipalityListUrl.ts/municipalityListFilters.ts— contrato de URL congeladosrc/utilities/recentVisits.ts— espelho de storagesrc/components/ui/Sidebar.tsx—SidebarMenuSub*/SidebarMenuActionre-adicionados