mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-20 18:24:45 +00:00
F1: RelationChipCell ganha spec unitário (relationChipCellCollapse) que pina o colapso medido pelo layout real (16 chips → slice de 3 linhas = 12), expande pelo 'Ver mais…' e recolhe pelo 'Ver menos', com getBoundingClientRect stubado por índice — a lacuna que o B169 deixou (specs com measureOverflow:false ou 1 chip) não tinha regressão do comportamento de colapso após a mudança de timing. F2: medição PerformanceObserver no worktree confirma o resíduo pré-hidratação do B169 sem regressão material: load SSR→hidratação com shifts únicos [0.139, 0.043, 0.257] (fontes do shell, nenhuma célula de chips) e ordenação client-side com zero shifts novos; eliminá-lo exigiria estimativa de largura (rejeitada) ou mudança de layout/regra (anti-goal) → defer documentado. Sem migration, dados, access ou mudança visual.
8 KiB
8 KiB
Impl: B170 — Follow-up B169: contrato do colapso de chips (spec) + shift único no load SSR
Status: aprovado Atualizado em: 2026-08-09 Issue: #441 Intenção: docs/plans/estabilizar-lista-dobradinhas-followup.md Appetite restante: ~0,5–1 dia eng (herdado)
Leitura da intenção
- Outcome: (F1) um spec unitário pinando o contrato do colapso de chips (recolher para o slice de 3 linhas medido, "Ver mais…" expande, "Ver menos" recolhe) com
getBoundingClientRectstubado para múltiplos chips — cobrindo exatamente a lacuna que o B169 deixou (measureOverflow: falseou colapso para 1 chip nos specs atuais); (F2) avaliar o shift único do load SSR, com medição no browser, e deferi-lo documentado se aceitável — nunca reintroduzindo a estimativa de largura por label (anti-goal). - O que NÃO negociar: sem mudança de layout, regra de colapso (3 linhas), dados, access ou schema; sem estimativa de largura por label; F1 não deve quebrar os specs existentes das células (
relation*,municipalityPortfolioCell). - O que reavaliar: a intenção deixa F2 condicionada à evidência ("sem evidência de impacto, F2 é defer"). A medição do B169 já registra os números (0,13–0,26, único, pré-hidratação); este impl reproduz a medição no worktree e confirma ou refuta antes de deferir.
Abordagem recomendada
flowchart LR
A[F1: spec contrato do colapso<br/>RelationChipCell + rects stubados] --> B[Colapso 3 linhas / Ver mais / Ver menos<br/>pinned em jsdom]
C[F2: medição PerformanceObserver<br/>/campanha/dobradinhas no worktree] --> D{shift único pré-hidratação?}
D -->|sim ~0,13-0,26| E[Defer + CHANGELOG com medição]
D -->|regressão material nova| F[Investigar: precision, não estimar]
Opções consideradas:
- F1-A — renderizar
RelationChipCelldiretamente com fixture mínima (ownerId/ownerName/ids/buildChips/buildFormData/commitAction/copy) e stub global deElement.prototype.getBoundingClientRect(mesmo padrão descrollIntoView/ResizeObserver). Pina o contrato no dono do colapso, sem a indireção do wrapper. - F1-B — renderizar um wrapper (
LeadershipStateDeputyRelationCell/StateDeputyAdvisorRelationCell) commeasureOverflowdefault true. Props mais curtas, mas o contrato vive noRelationChipCellembutido — o spec passaria por um nível a mais e os fixtures dos wrappers já existem. - F2-A — medição no browser + defer documentado. Reproduz a medição
layout-shiftno worktree (porta 3270, DBteqo_wt170), confirma o shift único pré-hidratação (~0,13–0,26) e registra emdocs/CHANGELOG-AGENTS.mdcom os números; F2 vira "documentado". - F2-B — eliminar via estimativa de largura no servidor — reintroduz exatamente o que o dono evita; rejeitada pela intenção e pelo B169.
- F2-C — reserva de altura estável no estado medindo — já testada empiricamente no B169 (opção C:
max-hé teto, não piso; o slice colapsado é naturalmente mais baixo); não funciona. Rejeitada.
Recomendação: F1-A + F2-A.
- F1 no dono compartilhado, porque a lacuna é "nenhum spec cobra o colapso com layout real" no nível onde o colapso acontece.
- F2 mede e defer com documentação — a eliminação honesta não existe sem violar anti-goals (estimativa de largura ou mudança de layout/regra), e o segredo do useLayoutEffect já é "a primeira pintura chega colapsada" nas navegações; o resíduo é só a paint pré-hidratação do primeiro load.
Componentes / mudanças
tests/unit/relationChipCellCollapse.unit.spec.tsx(novo): renderizaRelationChipCelldireto commeasureOverflow: true(default), stub deResizeObservere deElement.prototype.getBoundingClientRectdevolvendo geometria determinística (4 chips/linha, 20px, gap 6 →COLLAPSED_CHIP_ROWS=3⇒ 12 chips no slice; 16 no total ⇒ 4 ocultos). Asserções: 12[data-relation-chip]no DOM colapsado; "Ver mais…" presente; clique → 16 chips + "Ver menos"; clique → volta a 12 + "Ver mais…"; caso tudo-cabe (8 chips) → sem toggle, todos visíveis. Reset do stub viaReflect.deletePropertynoafterAll(precedentemunicipalityStateDeputyRelationCell.unit.spec.tsx). Sem migration, sem production code.- F2 (medição + documentação): sem migração; registra entrada em
docs/CHANGELOG-AGENTS.md(B170) com os números medidos e a decisão de defer. - Access / Consent: toca nenhum.
- UI: Impeccable A — engenharia, sem mudança de superfície (intenção).
Dados → forma
- N/A — nenhum dado novo. Aceite F1 = spec verde; aceite F2 = medição registrada + decisão documentada no CHANGELOG.
Fases verificáveis
- F1 — spec —
tests/unit/relationChipCellCollapse.unit.spec.tsx; rodarpnpm test:unit(target do arquivo) até verde, e a suíte de células inteira (relation*,municipalityPortfolioCell) para provar que não regride. FEITO (4/4 verde; suíte completa 1451 verde). - F2 — medição — dev server do worktree (porta 3270,
teqo_wt170); login coordenador seed;PerformanceObserver('layout-shift')em/campanha/dobradinhas(load/reload,hadRecentInput=false); comparar com a linha de base do B169 (0,13–0,26 único). FEITO — mesmo worktree provisionado + dobradinhas sintética com 40 lideranças (célula colapsa). Resultados: load SSR→hidratação com shifts únicos0.139/0.043/0.257(fonteshadRecentInput:falsedo shell — sidebar/Drawer/main/col-resize — nenhuma célula de chips); linha da célula97px/42chips → 57px/0chipsnuma única transição pré-hidratação; ordenação client-side (RSC) → zero shifts novos (a única fila era replay buffer do load). Decisão: defer, conforme a intenção — sem evidência de regressão material; eliminar a paint pré-hidratação exigiria estimativa de largura por label (rejeitada) ou mudança de layout/regra (anti-goal); registrado no CHANGELOG. - Gates —
pnpm gate:fast;pnpm exec tsc --noEmit;pnpm lint;pnpm format:check;pnpm exec knip;pnpm check:cycles;pnpm test;pnpm buildlocal. Push viapnpm push.
Rabbit holes / Não escopo (engenharia)
- Tentativa de eliminar o shift SSR com estimativa de largura (F2-B) ou reserva de altura (F2-C).
- Redesign das células/da tabela; outras fontes de CLS (sidebar, Sollinha, agenda).
- Migration, schema, access, dados.
- Mudança de
COLLAPSED_CHIP_ROWS,max-h-18ou qualquer regra de colapso.
Riscos e mitigação
- Stub global de
getBoundingClientRectvaza para outros renders do spec: reset viabeforeAll/afterAllcomReflect.deleteProperty; fixtures isoladas porit. - O stub é frágil à geometria interna da medição (
lastVisibleTop, trailingtoggleWidth+inputWidth): manterrowRect.rightfolgado (ex. 500) para o loop trailing não encolher abaixo do slice esperado, e comentar a matemática no spec. useLayoutEffectem jsdom: roda sincronamente dentro doactdo RTL (render), então o estado colapsado já está no DOM apósrender(); asserções diretas, semwaitFor(se precisar,waitForcomo rede de segurança).- F2 sem dados de dobradinhas no worktree: se o seed local não tiver células com overflow, semear um dobradinha sintética com várias lideranças antes de medir; se a medição não reproduzir (regressão material), parar e investigar antes de deferir.
- Divergência da intenção: a intenção assume F2 defer com medição; se a medição mostrar shift materialmente maior que o registrado (nova fonte), tratar como correção, não como defer.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: F1 pina o contrato; F2 (se deferido) documentado com medição no CHANGELOG
- Invariantes AGENTS/engineering-standards: nada de schema/access/URLs; identificadores em inglês; pt-BR só em copy de teste
- Specs das células existentes continuam verdes (
relation*,municipalityPortfolioCell) - Testes de domínio previstos: novo spec verde + medição registrada no diff/entrega