@praxisui/table 9.0.3 → 9.0.4-rc.2

package/docs/adr/2026-07-table-rich-cells-governance.md

@@ -0,0 +1,80 @@
+---
+title: "ADR - Governança de células ricas em tabelas"
+slug: "adr-table-rich-cells-governance-2026-07"
+description: "Decisão de governança para microvisualizações em células compactas, com evidência executável de legibilidade, acessibilidade e escala virtualizada."
+doc_type: "adr"
+document_kind: "adr-record"
+category: "architecture"
+level: "advanced"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+status: "implemented"
+owner: "praxis-ui"
+tags:
+  - "table"
+  - "rich-cells"
+  - "micro-visualization"
+  - "accessibility"
+  - "virtualization"
+toc: true
+sidebar: true
+last_updated: "2026-07-30"
+---
+
+# ADR: Governança de células ricas em tabelas
+
+## Status
+
+`implemented`
+
+## Context
+
+A PraxisTable suporta células compostas, indicadores, avaliação, toggle e dez tipos de microvisualização. A adoção corporativa exige distinguir suporte de runtime de adequação para uma célula compacta.
+
+O laboratório executável comprova paridade normal/virtualizada, nomes acessíveis, presença geométrica dos elementos compactos nas larguras de 120 px, 180 px e 260 px, e reciclagem de DOM para 1.000 linhas. A aprovação visual continua uma revisão humana: a evidência anexa capturada pela E2E não é um baseline de pixels dependente de plataforma.
+
+## Decision
+
+Todos os tipos table-safe continuam suportados. `delta`, `bullet`, `radial`, `harveyBall` e `stackedBar` são recomendados. `line`, `area` e `column` exigem espaço horizontal; `comparison` aumenta a altura da linha; `processFlow` exige etapas reconhecíveis.
+
+Essas condições são diagnóstico de authoring e grounding de IA, não bloqueio de runtime. Não será introduzido limite numérico rígido sem evidência de produto recorrente.
+
+Itens `compose` do tipo `value` expressam a hierarquia de leitura por `emphasis: 'strong' | 'subtle'`. O runtime materializa essa decisão por tokens do tema; CSS arbitrário por item não integra o contrato público de documentos governados.
+
+Uma regra `conditionalRenderers[]` pode materializar a mesma microvisualização quando sua condição Json Logic vencer. A regra usa `surface: 'table-cell'`, mantém o fallback acessível e respeita a precedência de primeira regra aplicável; ela não introduz uma segunda regra de negócio na tabela.
+
+## Corporate Review Protocol
+
+Antes de aprovar um tipo condicional em uma tabela corporativa, a revisão deve registrar evidência do laboratório nas larguras de 120 px, 180 px e 260 px e responder:
+
+- o visual acelera uma decisão que a coluna precisa suportar, em vez de apenas decorar a linha;
+- `line`, `area` e `column` permanecem interpretáveis na largura reservada; caso contrário, a informação deve migrar para detalhe expandido ou outra superfície;
+- `comparison` justifica a altura adicional da linha; `processFlow` mantém a sequência compreensível mesmo quando os rótulos visíveis são reduzidos;
+- nome acessível, fallback de dados ausentes e contraste preservam o mesmo significado da representação visual;
+- na tabela virtualizada, a rolagem mantém a célula materializada sem crescimento proporcional do DOM.
+
+O resultado deve ser **aprovar**, **redesenhar a célula** ou **mover o detalhe para outra superfície**. O protocolo governa a decisão de UX e não persiste regras de negócio na `TableConfig`.
+
+## Consequences
+
+- documentos existentes continuam carregáveis; valores legados de `compose.items[].style` são descartados no próximo salvamento pelo editor e não recebem CSS no runtime;
+- editor e IA explicam o trade-off de cada tipo;
+- o laboratório fornece evidência reproduzível antes de aprovar uma tabela corporativa;
+- uma futura regra mandatória exigirá evidência de recorrência e revisão de produto.
+
+## Acceptance Criteria
+
+- E2E prova todos os tipos, fallback para dados ausentes, acessibilidade e geometria da largura condicional;
+- E2E prova microvisualizações após rolagem em 1.000 linhas virtualizadas;
+- documentação pública aponta para a evidência e os trade-offs;
+- compose usa hierarquia semântica materializada por tokens, sem CSS arbitrário por item;
+- nenhuma regra de negócio é persistida na configuração da tabela.
+
+## Source References
+
+- `projects/praxis-core/src/lib/models/presentation-visualization.model.ts`
+- `projects/praxis-table/src/lib/columns-config-editor/columns-config-editor.component.ts`
+- `src/app/features/table-enterprise-rich-cells-lab/`
+- `projects/praxis-table/test-dev/e2e/table-enterprise-rich-cells-lab.playwright.spec.ts`