mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-20 01:33:05 +00:00
- Card denso (wireframe): posição de voto à direita, barra de cenários com marcador do ativo, chips classe/tendência/nível (label à esquerda), 3 grupos de avatares com wrap (um por entidade), rodapé Última atualização + chevron que expande revelando o último card de atualização + CTA registrar; sem atualização → CTA direto; prioridade = borda lateral direita 6px primary. - Controles ganham prop trigger/triggerClassName (precedente RelationChipCell); MunicipalityRelationAvatarStack ganha modo wrap. - C109 (sheet quebra ao abrir) corrigida: sessões do sheet host keyed por id (imune à identidade dos callbacks recriados por render) e footer customizado renderizado pelo host dentro da árvore do Drawer (portal perdia o Dialog context — reproduzido digitando no sheet). - Dado: MunicipalityListViewModel.lastUpdate (batch por página, scoped). - E2E novos (barra/votos, chip nível, borda prioridade, expansão/CTA vazio). Sem migration/access/Consent.
13 KiB
13 KiB
Impl: B193 — Card de município mobile: composição densa + edit-where-you-see + última atualização expandível
Status: aprovado Atualizado em: 2026-08-10 Issue: #542 Intenção: docs/plans/municipios-card-mobile-edit-where-you-see.md Appetite restante: herdado (~1–1,5 dia eng; recomposição de card + fiação de affordances sobre sheets existentes)
Leitura da intenção
- Outcome: no mobile (
md:hidden), o card de/campanha/municipiosvira composição densa na ordem do wireframe (cabeçalho nome+território com posição de voto 2022 à direita; barra de cenários com marcador do ativo; chips classe/tendência/nível; pilhas de avatares sem cap; rodapé última atualização com chevron) com edit-where-you-see em bottom sheets já existentes; toque atravessado abre o detalhe; prioritário ganha borda lateral direita ~6px; rodapé expande revelando o último card de atualização + CTA de registrar; sem atualização → CTA direto. - O que NÃO negociar: assimetria staff/leader (estimativas nunca para liderança — página já é
gate: noLeader); B13: classe nunca sem razão acessível; Salvador (linha agregada) read-only; desktop da lista e demais listas inalterados; não adicionar dado novo ao card; expansão ≠ feed completo; não recriar editors (reusar variantessheet). - O que reavaliar: (1) a intenção assume que os controles
variant="sheet"servem o card novo como estão — os triggers são internos a cada controle, e a composição densa exige trigger customizado por alvo (barra de cenários, chip com label à esquerda, pilha de avatares com wrap); (2) a intenção não diz de onde vem o "último card de atualização" — o view model da lista não carrega a última atualização (sólastUpdateAt/lastSignalAt), então é dado novo no load da página (não no card); (3) o rodapé hoje usa frescor (max atualização/pledge) — a expansão exige idade da atualização, não do sinal.
Abordagem recomendada
flowchart LR
page["municipios/page.tsx<br/>loadMunicipalityListPageBundle"] -->|"+ lastUpdate por página"| vm["MunicipalityListViewModel<br/>+ lastUpdate: MunicipalityUpdateViewModel | null"]
vm --> cards["MunicipalityListMobileCards (novo)"]
cards --> card["MunicipalityMobileCard (client, estado expandido)"]
card --> bar["ExpectedVotesControl + trigger barra (VoteEstimateScenarioStrip)"]
card --> chips["Trend/Level controls + trigger chip label-esquerda"]
card --> avatars["RelationEditor + trigger pilha wrap (3 grupos)"]
card --> footer["Rodapé: expande | CTA direto (UpdateControl)"]
Opções consideradas:
- A — Controles ganham prop
triggeropcional (recomendada). Cada controle de edição (MunicipalityListExpectedVotesControl,MunicipalityListLevelControl,MunicipalityListTrendControl,MunicipalityRelationEditor+ os 3 wrappers de relação) passa a aceitar umtriggercustomizado que substitui o interno; oCampaignCellEditOverlayjá tem oaria-labelque cobre a11y de qualquer conteúdo. O card compõe label+valor/barra/pilha dentro do botão, então o toque no label abre a sheet (aceite), e o trigger continuarelativeacima do overlayafter:inset-0(invariante B42 documentado no próprioCampaignCellEditOverlay). - B — Card posiciona label e trigger como irmãos, e o label abre a sheet via handler próprio. Duplica o estado de abertura do sheet (dois triggers para um overlay) e fura a maquinaria
openSheet/dismissSheetdo host compartilhado — o host guardaactiveOnOpenChangeRefe o segundo trigger entraria em conflito. Rejeitada: é a C109 que se descartou; quebraria a invariante "um control = um onOpenChange". - C — Recriar o editor no card (componentes novos de sheet). Rejeitada: rabbit hole "recriar editors" nomeado na intenção; anti-goal explícito.
- D — Barra/pilhas como affordances estáticas + navegação para a página de edição. Rejeitada: viola edit-where-you-see (editar "sem sair do card", aceite).
Decisões de engenharia:
- Dado da expansão — última atualização no view model (custo de reverter: médio — toca loader e tipo).
- Opções: (a)
lastUpdate: MunicipalityUpdateViewModel | nullnoMunicipalityListViewModel, carregado em batch por página; (b) fetch per-card no client (N+1, e o read precisa de access server-side); (c)lastUpdateAtsozinho (não dá o corpo/autoria do card). - Recomendação: (a) — um
payload.findemmunicipalityUpdatecomwhere: { municipality: { in: idsDaPágina } },sort: '-createdAt', select enxuto,overrideAccess: false(ocanReadMunicipalityUpdateescopa por portfólio), primeiro doc por município; nomes de autor vialoadCampaignUserNamesByIds(mesmo padrão deloadMunicipalityUpdatesFeed). Alternativas rejeitadas: (b) porque explode o número de reads por página e expõe o access no client; (c) porque o card expandido precisa de corpo/polaridade/autor (aceite). - Gatilho de revisitação (barato, não agora): se um município tiver centenas de updates, o batch puxa tudo —
DISTINCT ONvia drizzle quando houver medição (mesma política desupporterListOverviewAggregate).
- Opções: (a)
- Cobertura (conta da cadeira) sai do card mobile. O wireframe não a inclui; o card atual mostra "Cobertura" (goal coverage). Fica na tabela desktop e no detalhe. Sinalizo no gate como remoção de dado da superfície (não é "dado novo", é composição nova do wireframe).
- Rodapé passa a medir a idade da ATUALIZAÇÃO, não o frescor (update∨pledge).
- O wireframe é explícito ("Última atualização há X dias", "sem nenhuma atualização registrada → CTA direto") e o estado vazio é chaveado na existência de update, não de pledge. O
SignalAgeReadout/frescor continua na coluna desktop (lastSignal), intacto. A cor de "sinal frio" (estimate-pending) é mantida no rodapé quando a atualização está fria (≥21 dias), preservando o alerta da fila. - Sinalizo como divergência pequena de produto no gate (a intenção herda o vocabulário frescor; troco para update-only no card).
- O wireframe é explícito ("Última atualização há X dias", "sem nenhuma atualização registrada → CTA direto") e o estado vazio é chaveado na existência de update, não de pledge. O
- Borda de prioridade —
border-r-[6px] border-primaryno<article>quandoisPriority && isStaffView && !isCity, mantendo oborder-bseparador do B184. OMunicipalityPriorityIndicator(flag) sai do card mobile; a coluna desktop e o detalhe não mudam. - Pilha de avatares com wrap — estender
MunicipalityRelationAvatarStack(owner, não twin) com modo wrap:flex-wrap, sem cap (maxVisibleindefinido = todos), avatares densos (size-7); os três grupos (Assessores/Lideranças/Dobradinhas) são label + pilha dentro do trigger de cada relation editor via proptrigger(decisão A). - Chip de classe — mantém
TerritorialClassCardReadout(só o rótulo + tooltip com a razão;CampaignHoverTooltipjá abre no toque —openOnTouchdefault true, satisfaz "razão via tooltip/sheet" sem linha extra). Sem sheet nova. - Barra de cenários — trigger =
VoteEstimateScenarioStripcommarkerMode="active-only"+labelMode="all"(os três valores; ativo em destaque — igual ao canvas). Cenário ativo vem doMunicipalityEstimateScenarioProvider(já envolve a lista staff). Cidade: sem barra. - Expansão — estado
expandedpor card (MunicipalityMobileCardclient); rodapé é<button>comaria-expanded+ chevron rotacionando; conteúdo expandido = último card de atualização sem moldura (mesmo fundo; badges polaridade/urgente/adversário + corpo + autor · data — projeção enxuta doCampaignUpdatesFeedItemsem borda) + CTA "Registrar atualização" = trigger doMunicipalityListUpdateControl(sheet existente). Sem update → rodapé = trigger doMunicipalityListUpdateControlestilizado como CTA (sem chevron, sem expansão).
Componentes / mudanças
MunicipalityListViewModel(src/utilities/municipality/municipalityViewModels.ts): campo novolastUpdate: MunicipalityUpdateViewModel | null(server-only, staff; leader nunca chega à página).toMunicipalityListViewModelganha parâmetro com default.loadMunicipalityListPageBundle(src/utilities/municipality/municipalityPageData.ts): batch de última atualização dos ids da página (isStaff), mesmoPromise.alldas demais leituras.loadMunicipalityLastUpdates(novo, emmunicipalityUpdatePageData.ts— dono dos reads de update):Map<municipalityID, MunicipalityUpdateViewModel>compayload.find+overrideAccess: false+ nomes de autor.MunicipalityRelationEditor(src/components/campaign/shared/): prop opcionaltrigger?: (entries: MunicipalityRelationEntry[]) => ReactNode(default = avatar stack atual). Precedente:RelationChipCell.trigger.MunicipalityListAdvisorsControl/MunicipalityListLeadershipsControl/MunicipalityStateDeputyRelationCell: passthrough detrigger.MunicipalityListExpectedVotesControl/MunicipalityListLevelControl/MunicipalityListTrendControl: prop opcionaltrigger?: ReactNode(substitui o trigger interno).MunicipalityRelationAvatarStack: modo wrap (propwrap+maxVisible?: numbersem cap) — editar o owner.MunicipalityListMobileCards.tsx: recompõe o card; extraiMunicipalityMobileCard.tsx(client, estado de expansão). Mantémdata-view="mobile-cards"+<article>(contrato de e2e B42/B184).- Migration: sem migration (dado derivado; nenhum campo novo em collection).
- Access / Consent: nenhum;
canReadMunicipalityUpdatejá escopa por portfólio;overrideAccess: falseem tudo. - UI: Impeccable C — recomposição do card existente; tokens
data-theme='campaign'; reusa shells (CampaignCellEditOverlay, host de sheet compartilhado,VoteEstimateScenarioStrip, badges,Drawer); shape → craft → critique → polish.
Dados → forma (pergunta 3)
- Barra de cenários: forma = faixa com três valores + marcador do ativo (
VoteEstimateScenarioStripmarkerMode="active-only"labelMode="all"). Rejeitadas: % estadual absoluto (proibido pela intenção), barras empilhadas (custo de leitura alto para uma olhada), somente o valor do ativo (esconde o intervalo pessimista→otimista que a decisão desbloqueia — "a barra mostra onde a estimativa está no intervalo"). - Idade do rodapé: "há N dias" (padrão
formatMunicipalitySignalAgeLabelaplicado alastUpdate.createdAt), frio ≥21 dias. - Classe: só o rótulo (chip) + razão em tooltip que abre no toque — flexiona B13 sem linha extra.
Fases verificáveis
- Server/dados —
loadMunicipalityLastUpdates+ campo no view model + bundle;pnpm gate:fast(tsc/lint/unit). Sem migration. - Controles — prop
triggernos 4 controles +MunicipalityRelationEditor+ passthroughs; modo wrap na pilha. Unit onde o comportamento dos controles for tocado. - Card novo —
MunicipalityMobileCard+ recomposição da lista (cabeçalho/barra/chips/avatares/rodapé/expansão/CTA/prioridade/cidade). - E2E — atualizar B42 (alvo do tap-through: área não-control; trigger de tendência mantém nome), novos testes: expansão (último card + CTA abre sheet), sem-atualização → CTA direto, borda de prioridade, barra abre sheet de votos; rodar
pnpm test:e2eno spec de municípios + atualizações. - Gates finais —
pnpm gate:pushcompleto (incl. knip, cycles, format, build) + Aikido nos arquivos editados.
Rabbit holes / Não escopo (engenharia)
- Não mexer na maquinaria do sheet host /
CampaignCellEditOverlay(estado saudável — C109 descartado). - Não criar variante de card desktop nem tocar tabela/colunas (frescor desktop intacto).
- Não adicionar dado novo ao card (nada de meta da cadeira na barra, nada de contagem de apoios).
- Não otimizar o batch de updates com
DISTINCT ONsem medição (registrado como gatilho). - Não recriar o card de atualização do feed: projeção enxuta no card, feed completo fica em
/campanha/atualizacoes.
Riscos e mitigação
- Sobreposição de toque (overlay
after:inset-0× novos alvos): todo alvo novo passa pelo triggerrelativedoCampaignCellEditOverlayou receberelativeexplícito (rodapé, CTA); o tap-through do e2e cobre o contrato. aria-labelsubstitui conteúdo do trigger: os triggers mantêmtriggerLabelverbosos ("Editar tendência política em X — Favorável"); oVoteEstimateScenarioStripdentro do botão mantémrole="img"+ aria-label próprio (anuncio único, sem interativo aninhado).- E2E B42/B184 sensíveis a estrutura: manter
data-view="mobile-cards"+article+ bordasborder-b; o teste B42 de tap-through troca o alvo (label "Tendência" vira trigger — alvo novo: readout de posição de voto ou subtítulo, garantido não-control). - Rodapé muda de frescor para update-only: divergência pequena de produto — apresentada no gate; coluna desktop preserva frescor.
- Batch de updates grande: página = 25 municípios; updates são relatos de campo enxutos; select limita payload; gatilho de revisitação registrado.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (composição, edit-where-you-see, expansão, CTA vazio, borda de prioridade, cidade read-only, assimetria)
- Invariantes AGENTS/engineering-standards (nada de prod;
overrideAccess: false; sem migration; identificadores em inglês; copy pt-BR) - Testes previstos: e2e de expansão/CTA/borda/barra; tap-through re-verificado; unit onde controles mudam