# B158 — Colunas adaptativas na tabela de Municípios Status: rascunho revisado Atualizado em: 2026-08-05 Issue: #364 Priority: P1 Model: composer-2.5 Impeccable: Adapt / modo Operate — densidade progressiva dentro do painel de conteúdo Canvas UI: `/Users/francisco.solla/.cursor/projects/Users-francisco-solla-cursor-worktrees-teqo-5hoy/canvases/plan-b158-ui-draft.canvas.tsx` (referência histórica; o contrato abaixo prevalece) Appetite: ~1,5–2 dias eng; um outcome verificável Responsável: — ## Intenção A tabela de Municípios em `/campanha/municipios` tem 10+ colunas no modo staff. O espaço útil não depende mais apenas da viewport: a página pode dividir a largura entre **sidebar, painel de conteúdo e chat**, cada um aberto ou fechado. Breakpoints de tela não representam o espaço que a tabela realmente recebeu. A lista deve responder à largura do **painel de conteúdo**, mostrar primeiro as colunas que sustentam a decisão e acrescentar as demais uma a uma conforme houver espaço — sem scroll horizontal e sem exigir configuração prévia do ator. O seletor manual de colunas (B17) continua existindo. Ele expressa preferência; as container queries expressam capacidade física do painel. ## Decisões de produto consolidadas 1. **Container queries, não media queries.** O wrapper da lista vira um named container. Abrir ou fechar sidebar/chat recalcula as colunas sem JavaScript de resize. 2. **Território na segunda linha do nome.** A coluna `region` deixa de existir. `TerritoryLink` aparece sob o nome do município, em texto secundário e truncado. 3. **Filtro de território preservado no omnibox.** `MunicipalityFilters` já oferece sugestões e chips de território; essa passa a ser a entrada canônica. Remover a coluna não remove `regionFilterOptions`, `?region=` nem o estado do filtro. 4. **Sort legado por território preservado.** `sort=region` continua válido por compatibilidade de URL e aparece no resumo quando ativo, mas deixa de ter um header clicável. Não será criada uma segunda affordance de sort neste item. 5. **Ausência de nível vira `—`.** O filtro `sem_nivel` continua sendo uma resposta operacional real; somente a célula usa o padrão visual de ausência. 6. **Headers curtos:** `Assessor`, `Liderança`, `Dobradinha`, `2026`, `Sinal`. O header `2026` explica a estimativa no tooltip B22. 7. **Cobertura e Sinal ocultos por padrão.** Novos estados de preferência começam com `goalCoverage` e `lastSignal` ocultos; ambos continuam disponíveis no seletor. 8. **Densidade progressiva.** Colunas entram individualmente conforme o container cresce. `Tendência` e `Sinal` são adaptativas: usam ícone compacto quando não cabe o readout completo, sem montar um segundo editor. 9. **Ações cobre apenas ocultação manual.** Se o ator ocultar `trend` ou `lastSignal`, a coluna interna `actions` monta o editor correspondente. Container query nunca duplica o controle: uma coluna adaptativa compacta no próprio lugar. 10. **Sem fallback horizontal.** A tabela não usa `overflow-x-auto`; cards continuam sendo a superfície do container realmente estreito. ## Persona e job - **Persona:** coordenador, candidato ou assessor usando tablet/laptop de campo, com sidebar e/ou chat alternando o espaço disponível. - **Job:** escanear nome, base de 2022, estimativa de 2026, nível e classe; reconhecer tendência e manter ações rápidas acessíveis; receber mais contexto de rede conforme o painel cresce. - **Princípio:** adaptar ao espaço que o conteúdo recebeu, não ao dispositivo que o hospeda. ## Fluxo desejado 1. O painel de conteúdo abre estreito: a lista usa cards. 2. Ao ganhar largura suficiente, entra a tabela essencial. 3. Cada faixa adicional introduz uma coluna, sem salto de três ou quatro colunas de uma vez. 4. Abrir o chat ou a sidebar faz o processo inverso imediatamente via CSS. 5. `Tendência` e `Sinal`, quando escolhidos no B17, encolhem para um trigger de ícone antes de desaparecerem. 6. Se o ator os ocultar manualmente, seus triggers migram no render do servidor para `Ações`, no extremo direito. 7. O filtro de território continua disponível no omnibox e seus chips continuam refletindo `?region=`. ## Contrato entre preferência e capacidade A regra efetiva é: ```text coluna renderizada = permitida pelo papel AND não ocultada manualmente AND faixa do container permite a coluna ``` Exceções: - `name` é obrigatória. - `trend` e `lastSignal`, quando manualmente visíveis, permanecem renderizados na tabela e alternam **compacto ↔ completo** conforme o container. - Se `trend` ou `lastSignal` estiver manualmente oculto, seu editor é renderizado uma única vez dentro de `actions`. - Mostrar manualmente uma coluna não força o painel a ultrapassar sua capacidade. O automático vence apenas na dimensão de espaço; a preferência continua guardada para quando houver largura. ## Matriz canônica por largura do container Os valores abaixo são **breakpoints iniciais do painel de conteúdo**, não da viewport. Devem ser calibrados no craft contra o conteúdo real, mas a ordem de entrada é contrato de produto. Uma calibração pode mover um corte; não pode agrupar colunas nem trocar a prioridade sem atualizar este plano. | Faixa do container | Superfície / coluna que entra | Estado acumulado | | ------------------- | ----------------------------- | ----------------------------------------------------------------------------------- | | `< 48rem` (< 768px) | Cards | Cards existentes; tabela ausente | | `C0 >= 48rem` | Tabela essencial | Nome+Território, 2022, 2026, Nível, Classe, Tendência compacta, Ações se necessária | | `C1 >= 54rem` | Assessor | C0 + Assessor | | `C2 >= 60rem` | Tendência completa | C1; trigger troca ícone por badge/readout no mesmo controle | | `C3 >= 66rem` | Liderança | C2 + Liderança | | `C4 >= 72rem` | Dobradinha | C3 + Dobradinha, somente coordinator/candidate | | `C5 >= 78rem` | Cobertura opt-in | C4 + Cobertura, se habilitada no B17 | | `C6 >= 84rem` | Sinal completo opt-in | C5; Sinal, se habilitado, troca ícone por readout de idade | ### Ordem visual estável Quando todas estão disponíveis: 1. `name` — Município + Território 2. `votos` — 2022 3. `expectedVotes` — 2026 4. `level` — Nível 5. `classe` — Classe 6. `advisors` — Assessor 7. `trend` — Tendência 8. `leaderships` — Liderança 9. `stateDeputies` — Dobradinha, quando o papel permite 10. `goalCoverage` — Cobertura, opt-in 11. `lastSignal` — Sinal, opt-in 12. `actions` — somente quando Tendência e/ou Sinal foram ocultos manualmente A ordem prioriza diagnóstico/decisão, depois responsabilidade e rede. A tabela não muda a ordem ao cruzar faixas; apenas acrescenta ou compacta células. ## Colunas adaptativas e montagem única ### Tendência - Manualmente visível: - C0–C1: um trigger de ícone com cor semântica do status atual. - C2+: o mesmo `MunicipalityListTrendControl` mostra o badge completo. - Manualmente oculta: a coluna `trend` não é renderizada e uma única instância do controle aparece em `actions`. - Estado sem tendência usa ícone neutro e nome acessível “Tendência não registrada”. ### Sinal - Manualmente visível: - C0–C5: o mesmo `MunicipalityListSignalControl` usa trigger de adicionar/atualizar sinal. - C6+: troca para `SignalAgeReadout` no mesmo controle. - Manualmente oculto: uma única instância aparece em `actions`. ### Ações - ID interno: `actions`. - Não entra em `MunicipalityListColumnId`, `municipalityColumnLabels`, `municipalityColumnDescriptions` nem no picker B17. - Usa um tipo local, por exemplo `MunicipalityTableColumnId = MunicipalityListColumnId | 'actions'`. - Possui header visualmente oculto “Ações” para manter a semântica da tabela. - Só entra no DOM quando `trend` ou `lastSignal` está manualmente oculto. - Os triggers têm nome acessível, tooltip redundante e alvo mínimo de 44×44px. - Nunca existem duas instâncias do mesmo editor na mesma linha. ## Defaults do B17 sem ambiguidade O cookie atual omite uma lista cujo conjunto de ocultas é vazio. Portanto, “nunca configurou” e “restaurou todas” são indistinguíveis. B158 precisa evoluir o formato antes de aplicar defaults. ### Contrato escolhido - O formato passa a representar explicitamente uma lista configurada com zero ocultas, usando um sentinel reservado e versionado pelo parser/serializer. - Exemplo conceitual: `municipios:__none__` significa “configurado; todas visíveis”. O sentinel nunca é exposto como column ID. - Ausência da entrada `municipios` significa “usar defaults atuais da lista”. - Defaults de Municípios: `['goalCoverage', 'lastSignal']`. - `Restaurar todas` persiste o estado explícito vazio; não volta aos defaults no refresh. - Cookies legados sem entrada de Municípios adotam o novo preset compacto uma vez. Após a primeira interação, o estado fica explícito. - As outras listas mantêm default vazio e comportamento existente. - O controle continua sendo preferência por dispositivo/browser, não por usuário autenticado. ## Objetivo e aceite - A tabela responde à largura do named container do painel de conteúdo, inclusive quando sidebar/chat abrem ou fecham sem mudar a viewport. - Não há barra de rolagem horizontal nem overflow do shell em nenhuma faixa de tabela. - A transição cards ↔ tabela é baseada no container em 48rem. - As colunas entram uma por vez na ordem C0–C6. - `name` continua sticky left e passa a ter largura máxima aproximada de 13rem; nome quebra em até duas linhas e território trunca em uma. - Headers podem quebrar apenas em whitespace; números e badges não truncam. - Território continua filtrável no omnibox; chips e URLs `?region=` permanecem intactos. - URLs legadas com `sort=region` continuam válidas. - `Nível` sem valor renderiza `—`. - Headers e labels usam singular; `2026` tem tooltip: “Estimativa de votos do candidato neste município em 2026. Ordena pelo cenário central, independente do cenário selecionado acima.” - Cobertura e Sinal começam ocultos nos defaults de Municípios. - `actions` não aparece no picker e só existe no DOM por ocultação manual de Tendência/Sinal. - Cada editor de Tendência/Sinal é montado no máximo uma vez por linha. - Cards mantêm conteúdo e interação atuais; somente o gatilho cards/tabela muda de media query para container query. - Sem migration, collection, Consent, server action ou mudança de contrato público de URL. ## Direção no codebase ### `MunicipalityList.tsx` - Envolver cards + tabela em `@container/municipality-list`. - Trocar `md:hidden` / `md:block` por variantes do named container. - Remover a definição `region`; mover `TerritoryLink` para a segunda linha de `name`. - Reordenar as definições conforme a ordem visual canônica. - Aplicar classes de container query simétricas ao `