16 KiB
Impl: C95 — Agenda: seletor de modo de visualização no header do app
Status: aprovado Atualizado em: 2026-08-09 Issue: #439 Intenção: docs/plans/c95-agenda-seletor-modo-visualizacao.md Appetite restante: ~0,5–1 dia eng (herdado); sem ajuste
Leitura da intenção
- Outcome: um seletor único de modo de visualização (Dia/Semana/Mês/Lista) no header do app —
CampaignDesktopHeaderno desktop,CampaignMobileTopBarno mobile — agenda-contextual (só/campanha/agenda), compacto (não crescemin-h-11/min-h-14), substituindo os 4 botões de modo do FullCalendar (headerToolbar.end). A escolha persiste por sessão/reload (estado da tela, junto do filtro — que já vive na URL), respeita o recorte do filtro e vence a lógica responsiva de resize (semana↔dia) que hoje existe. - O que NÃO negociar: navegação prev/next/"Hoje" permanece no FullCalendar; criação inline (C91) intacta; leader lockdown intacto; demais telas
/campanhasem o seletor; header sem segunda linha e sem aumento de altura; escolha do usuário não é trocada por resize. - O que reavaliar (hipóteses da intenção):
- "estado de vista eventualmente junto ao
ActivityAgendaState/URL" → confirmado:viewentra no contrato URL deActivityAgendaState(mesmo mecanismo dos filtros — canônico, fail-closed, share/reload consistentes). - "conectar o seletor ao
changeViewviacalendarRef" → via URL: o seletor navega (useCampaignListFilterNavigation), oActivityAgendareage aostate.viewcom um effect que chamachangeView— sem ref compartilhado entre header e página. - A lógica responsiva de resize precisa reconciliar com a escolha do usuário — gate simples: com
viewna URL, o auto-switch semana↔dia desliga; semview, comportamento atual permanece.
- "estado de vista eventualmente junto ao
Abordagem recomendada
flowchart LR
subgraph AGENDA_PAGE[AGENDA PAGE · server]
S[searchParams] --> R[resolveActivityAgendaUrl + restrict → state com view?]
end
R -->|state| VC[AgendaViewChrome · client]
VC -->|registra| H[SetCampaignHeaderAction id=agenda-view]
H -->|lê| DH[CampaignDesktopHeader · cluster direito]
H -->|lê| MB[CampaignMobileTopBar · junto ao sino]
VC -->|opções navegam| NAV[useCampaignListFilterNavigation → buildActivityAgendaHref]
NAV -->|router.replace view=X| R
R -->|novo state.view| AG[ActivityAgenda]
AG -->|effect state.view → changeView| FC[FullCalendar · headerToolbar sem end]
Opções consideradas (estado da vista): A) URL param view no ActivityAgendaState | B) contexto React compartilhado header↔página | C) localStorage/sessionStorage + estado local.
Recomendação: A — "edit the owner": o filtro da agenda já é estado de tela na URL (municipality/deputyPresent/tag); a vista é a mesma classe de estado. Ganha canonicalização/redirect fail-closed de graça (resolveActivityAgendaUrl), persistência reload/share consistente, e o seletor no header não precisa de bridge para o calendarRef — o FullCalendar reage a state.view como já reage a qualquer filtro.
Rejeitadas: B (o node de header é renderizado pelo shell, fora da árvore da página — provider por-página não o envolve; exigiria contexto no layout, vazamento de domínio de agenda para o shell); C (perde URL canônica/share; dois sources of truth; contraria "junto do filtro").
Opções consideradas (controle do seletor): A) Popover + botão-ghost compacto com rótulo do modo atual + ▾ | B) NativeSelect compacto | C) ToggleGroup com 4 ícones.
Recomendação: A — é o "Semana ▾" do esboço da intenção; adapta por superfície como o sino (text-primary-foreground no top bar escuro mobile vs md:text-foreground no header claro desktop); um único controle compacto na linha existente (não cresce o header). Opções com check do modo ativo.
Rejeitadas: B (usa tokens --field-* claros — destoa do bg-primary do top bar mobile; sem trigger customizável); C (4 segmentos não cabem na linha única — anti-goal explícito da intenção).
Opções consideradas (reconciliação com o resize): A) gate !state.view no auto-switch existente (com escolha → nada muda no resize; sem escolha → comportamento atual) | B) remover o auto-switch e deixar só initialView por viewport | C) canonicalizar o auto-switch na URL (vira escolha).
Recomendação: A — mudança mínima, preserva o default responsivo atual e faz a escolha vencer; "só o default muda por viewport" da intenção permanece verdadeiro.
Rejeitadas: B (muda comportamento de C15 além do pedido — o resize continuaria flipando hoje); C (torna o default "escolha" — depois do primeiro resize o usuário ficaria preso no modo auto-escrito; contradiz "só o default muda por viewport").
Opções consideradas (mobile): A) renderizar o mapa headerActions no CampaignMobileTopBar (o slot C94/C95 compartilhado passa a renderizar nos dois bars; o botão do feed já se auto-esconde com hidden md:inline-flex) | B) registro separado mobile-only.
Recomendação: A — o slot foi construído como "C94/C95 shared slot"; o feed já controla a própria visibilidade por viewport; o seletor nasce visível nos dois. Uma única fonte de registro.
Rejeitadas: B (duplica o mecanismo de registro que C94 entregou para exatamente isso).
Opções consideradas (valores de URL): A) códigos curtos view=week|day|month|list + mapa puro p/ FC ids | B) FC ids diretos view=timeGridWeek.
Recomendação: A — URL curta e estável (independe de internals do FullCalendar); o mapa é 3 linhas testáveis em activityUi.ts.
Rejeitadas: B (URL verbosa acoplada ao FullCalendar; renomear vista no FC vazaria para a URL).
Decisão registrada (label do seletor sem view): o label reflete o modo efetivo — state.view se presente, senão o default responsivo do viewport (window.innerWidth < 640 → "Dia", senão "Semana"), medido com matchMedia + settle de hidratação (useNarrowMeasured em hooks/use-mobile.ts). A janela residual (viewport 640–~680 sem sidebar e 768–896 com sidebar 16rem aberta, onde o card do calendário cruza 640 antes do viewport) é cosmética e só ocorre sem escolha explícita — aceita, sem bridge header↔página para o estado efetivo do FC.
Componentes / mudanças
src/utilities/activityUi.ts(extender):activityAgendaViews = ['week','day','month','list'],ActivityAgendaViewtype,activityAgendaViewLabels(Semana/Dia/Mês/Lista),activityAgendaViewFcId(week→timeGridWeek, day→timeGridDay, month→dayGridMonth, list→listMonth),isActivityAgendaViewguard.parseActivityAgendaParamsganhaview(fail-closed: valor desconhecido → undefined → redirect canônico);buildActivityAgendaSearchParamsserializaviewao final (ordem canônicamunicipality,deputyPresent,tag,view);activityAgendaParamNames+=view;restrictActivityAgendaStaterepassaview(sem restrição de acesso — é estado de UI, não recorte de dados);parseActivityAgendaReturnHrefpreservaviewno round-trip do create.ActivityAgendaFilters.tsx(1 linha): "Limpar" preservaview(limpa filtros, não o modo de visualização —setDraft/navigatemantêmviewatual).AgendaViewSelector.tsx(novo, client,components/campaign/activity/): Popover compacto — triggerButtonghosth-9 gap-1 px-2com label do modo efetivo +ChevronDown, classes adaptativastext-primary-foreground hover:bg-primary-foreground/10 md:text-foreground md:hover:bg-muted(padrão do sino);aria-label="Modo de visualização",aria-expanded/aria-haspopup. PopoverContent com 4 opções (role="menu"/menuitemradio+aria-checked, check do ativo); cada opção navega{...state, view}viauseCampaignListFilterNavigation(mesmo hook dos filtros → dim do pending boundary na troca). Label fallback semview:matchMedia('(max-width: 639px)')com settle de hidratação.AgendaViewChrome.tsx(novo, client, espelho deAgendaFeedChrome): recebestateda página; renderiza<SetCampaignHeaderAction id="agenda-view">{selector memoizado}</SetCampaignHeaderAction>. Montado na página antes de<AgendaFeedChrome>→ ordem de inserção no mapa garante cluster[Semana ▾][Link de import][Notificações][IA](gate da intenção).agenda/page.tsx: renderiza<AgendaViewChrome state={state} />antes do<AgendaFeedChrome />.CampaignMobileTopBar.tsx(extender): renderizaObject.entries(headerActions)entre título e sino (<div className="ml-auto flex shrink-0 items-center gap-1">), espelhando o cluster do desktop; wizard-mode inalterado (early return).ActivityAgenda.tsx:headerToolbar.endremovido (fica{ start: 'prev,next today', center: 'title' });initialView={state.view ? activityAgendaViewFcId[state.view] : 'timeGridWeek'}; effect[state.view]→calendarRef.current?.getApi().changeView(...)(skip se já é a vista atual;datesSetdispara reload da janela como hoje);applyResponsiveViewsó flips quandostate.viewausente (mantémisNarrowpara o inline create C91).- Migration: sem migration (nenhuma mudança de schema).
- Access / Consent: nenhuma mudança — agenda segue
gate: 'staff'; sem opt-in novo. - UI: Impeccable B — encaixe no header global existente, controle compacto, sem redesign. Shape → craft → critique → polish leve; tokens
data-theme='campaign'.
Dados → forma (se aplicável)
- Não apresento dados novos (vista = estado de tela/navegação, mesma classe do filtro). Forma do controle: dropdown compacto (decisão A acima), espelhando o padrão visual do cluster direito do header.
Fases verificáveis
- Contrato URL (traço dominante) —
activityUi.ts(views/labels/mapa/parse/serialize/restrict/returnHref) + unit tests emactivityUi.unit.spec.ts(parse fail-closed, serialização canônica comview, restrict repassa, returnHref preserva, mapa FC).ActivityAgendaFilters"Limpar" preserva view. Verificar: URLs canônicas existentes inalteradas para estados semview. - Seletor + wiring do header —
AgendaViewSelector(Popover compacto + navegação),AgendaViewChrome(registro), página (ordem),CampaignMobileTopBar(slot no mobile);ActivityAgenda(headerToolbar semend, initialView, effect changeView, gate do responsive). - Gates — e2e da agenda atualizado (os asserts
getByRole('tab', /semana|mês|lista/i)morrem com a remoção doend— reescrever para o seletor do header, desktop e mobile);pnpm gate:fastna iteração;pnpm pushno fechamento.
Rabbit holes / Não escopo (engenharia)
- Mover prev/next/"Hoje" para o header (fica no FullCalendar — corte da intenção).
- Persistência entre dispositivos/contas (só URL/tela).
- Bridge de estado efetivo do FC para o header (label fallback usa viewport; janela cosmética aceita).
- Extrair
useNarrowcompartilhado calendário/seletor (2 call sites com alvos de medição diferentes; DRY <3). - Redesign do FullCalendar (C15) e do slot de header (C94).
Riscos e mitigação
- E2E: os asserts de
role="tab"do FullCalendar quebram ao removerend— reescrever para o seletor (labelModo de visualização+ opções), cobrindo desktop e mobile, e adicionar: troca de vista → URLview=...→ reload persiste → escolha vence resize. useCampaignListFilterNavigationno header: o node renderiza no header, dentro deCampaignListPendingBoundarydo layout (verificado) — transição compartilhada funciona;router.replacecomscroll: false.SetCampaignHeaderActionre-registra em re-render: node memoizado (useMemoem[state]), padrão C94.- Eventos ao trocar vista:
changeView→datesSet→visibleRangemuda → reload da janela (mesmo caminho dos botões atuais do FC; sem regressão). - Estado com
viewna action do servidor:loadActivityAgendaEvents({...state})ganhaview— zodactivityAgendaRequestSchema(non-strict) descarta chaves desconhecidas; sem mudança de schema (verificado). - Flake pré-existente (
gridcell.nth(1)): os testes de slot do calendário (cria inline,Mais detalhes) flakavam com "Element is not attached to the DOM" noscrollIntoViewIfNeeded— o grid do FullCalendar pinta vazio e substitui os gridcells quando os events chegam, então o scroll corria contra o re-render. Estabilizado nesta entrega: esperarCarregando compromissos…sumir (toHaveCount(0)) antes de interagir nos 2 testes de slot (mesmo padrão de waits do C94, agora antes da ação). SuítecampaignActivity.e2e.spec.tscompleta verde (6/6) com o rebase em main. O QueryErrorendAt cannot be queriedapareceu 1×/9 runs (intermitente, em run sem relação com os testes que falharam; não reproduzido após o rebase).
Pós-/simplify (reviewers paralelos)
- P1 corrigido (desync URL→calendário): o effect de
changeViewsó sincronizava quandostate.viewestava presente; navegar para/campanha/agendasem query (link da sidebar, back/forward) deixava o FullCalendar numa vista órfã (ex: mês) que o seletor não reivindicava. Agora o effect normaliza também na ausência: volta ao default responsivo (narrow →timeGridDay, senãotimeGridWeek) — mesma regra do label do seletor. E2E cobre o caso (goto semview→ "Dia" + grid de dia). - P1 corrigido (e2e só provava o label): os asserts do teste C95 agora verificam o calendário de fato — o
aria-labeldo botão "Hoje" ("Esta semana"/"Este mês"/"Hoje" — o FullCalendar v7 classic hasheia as classes de view) + presença/ausência de[role="grid"](month tem grid, list não). Coberto após troca, após reload, após resize (escolha vence) e após navegação semview. - P2 corrigido (teclado do menu):
nav[role="menu"]ganhouonKeyDowncom ArrowUp/ArrowDown/ArrowRight/ArrowLeft/Home/End movendo o foco entre osmenuitemradio(roving focus mínimo; Escape/foco de volta já vêm do Radix Popover). - P2 corrigido (3ª cópia do hook de viewport):
use-mobile.tsganhouuseNarrowMeasured(breakpoint)(mesmo settle de hidratação deuseIsMobileMeasured); o seletor usauseNarrowMeasured(640)em vez de reimplementar matchMedia.MOBILE_BREAKPOINTvoltou a ser const interna (knip). - P2 corrigido (labels sem assert unit):
activityAgendaViewLabelspinado em unit test (typo "Mêes" falharia); parse deview=day|listcoberto. - P3 (banda de divergência): corrigida a estimativa no doc — com sidebar de 16rem a janela real é 768–896px (não 640–680).
- P3 (Limpar sem cobertura): e2e do "abre a semana" ganhou assert — após "Limpar", a URL mantém
view=list(filtros vão, vista fica).
Débitos deferidos (gatilho de revisitação)
| Débito | Gatilho |
|---|---|
menuitemradio sem typeahead; anchor híbrido mantém ctrl/middle-click abrindo href (comportamento de link, não de radio) |
Próxima Issue que tocar a11y do menu do header |
Sem caminho de UI para "voltar ao modo automático" (uma vez escolhida, view fica na URL; "Limpar" preserva de propósito) |
Se produto pedir default responsivo restaurado por um gesto |
useNarrowViewport do seletor (viewport 640) vs applyResponsiveView do calendário (container 640) — banda residual documentada (768–896 com sidebar) |
Se o seletor e o calendário precisarem concordar sempre (mudar o probe do calendário para viewport) |
Aceite de engenharia
- Aceite de produto da intenção coberto (seletor único no header desktop+mobile, agenda-contextual, compacto; botões FC removidos; persistência junto do filtro; escolha vence resize; sem regressão de navegação/inline/lockdown)
- Invariantes AGENTS/engineering-standards (URL canônica, staff gate, sem Consent novo, sem migration)
- Testes de domínio: unit do contrato URL (
viewparse/serialize/restrict/returnHref/mapa); e2e da agenda reescrito no seletor + persistência + escolha-vence-resize pnpm gate:fast, tsc, lint, prettier, knip, check:cycles verdes