@praxisui/table 8.0.0-beta.2 → 8.0.0-beta.20

package/docs/playground-scenario-second-opinion-review.md

@@ -0,0 +1,234 @@
+# Praxis Table Playground Scenario Second Opinion Review
+
+## Veredito executivo
+
+O plano está **forte, mas ainda um pouco largo e levemente enviesado para “capability completeness” em detrimento de “navegabilidade editorial”**.
+
+Em termos de diagnóstico, ele acerta quase tudo:
+
+- identifica corretamente a redundância do catálogo atual;
+- reposiciona o componente como plataforma governada, não só demo de regras;
+- respeita melhor os limites reais do runtime do que o catálogo existente.
+
+Mas o catálogo alvo ainda tem dois problemas:
+
+1. ele pode ficar grande demais para um playground principal;
+2. alguns cenários propostos estão muito próximos entre si do ponto de vista do usuário final.
+
+Minha leitura: o plano está correto como direção estratégica, mas precisa de uma camada final de poda editorial para não substituir “muitos demos redundantes” por “muitos demos corretos”.
+
+## Principais achados
+
+### 1. O diagnóstico do catálogo atual está correto e não superficial
+
+O ponto mais sólido do plano é reconhecer que o playground atual varia mais o domínio do que a capacidade.
+
+Isso é especialmente verdadeiro em:
+
+- fluxos operacionais;
+- demos de regras;
+- expansão genérica.
+
+Essa crítica é estruturalmente correta.
+
+### 2. O plano acerta ao tratar filtro dinâmico como cenário flagship
+
+Isso é talvez o melhor acerto do plano.
+
+Se `praxis-table` continuar sendo apresentado sem um showcase forte de filtro dinâmico, o playground vai seguir comunicando um produto menor do que a lib realmente é.
+
+`Dynamic Filter Workbench` não é acessório. É uma peça central da tese do componente.
+
+### 3. “Schema Reconciliation” está corretamente promovido de detalhe técnico para capability de produto
+
+Outro acerto forte.
+
+O mecanismo de ETag, banner, badge, snooze/ignore e reconciliação é diferencial de plataforma. Se isso não aparece no playground, o usuário conclui que a tabela é só mais uma grid configurável.
+
+### 4. O catálogo alvo ainda está amplo demais
+
+Onze cenários é melhor do que o catálogo atual, mas ainda parece alto para uma primeira superfície de playground.
+
+Se todos forem tratados como cenários principais e equivalentes, existe risco de:
+
+- fadiga de navegação;
+- dispersão cognitiva;
+- dificuldade de entender “por onde começar”.
+
+Minha recomendação é trabalhar com:
+
+- 6 cenários principais;
+- 2 ou 3 avançados;
+- variações extras via patches.
+
+### 5. “Renderer Gallery” e “Rules and DSL Playground” ainda estão parcialmente sobrepostos
+
+A separação conceitual faz sentido para quem conhece a arquitetura, mas não necessariamente para quem está explorando o playground.
+
+Hoje, um usuário pode perceber ambos como:
+
+- “cenários visuais com destaque condicional e células especiais”.
+
+Se mantidos separados, a tese de cada um precisa ser muito explícita:
+
+- `Renderer Gallery`: prova a superfície visual dos renderizadores
+- `Rules and DSL Playground`: prova lógica, critérios, condições e governança de regras
+
+Sem essa diferenciação forte, eles tendem a colapsar editorialmente.
+
+### 6. “Settings-Driven Authoring” é importante, mas não está claro se deve ser cenário flagship
+
+Aqui eu discordo parcialmente do plano.
+
+Esse tema é relevante, mas pode ser avançado demais para a primeira leitura do playground. Dependendo do público, ele funciona melhor como:
+
+- patch/aba de um cenário de reconciliação/governança; ou
+- cenário avançado, não um dos primeiros.
+
+Se virar cenário principal, precisa provar valor muito rapidamente. Caso contrário, vai parecer “editor interno do componente”, não capability consumível.
+
+### 7. “Virtualized High Volume” merece existir, mas com framing mais honesto e restrito
+
+Concordo com a criação, mas ele deve ser apresentado como:
+
+- cenário de performance e limites;
+- não cenário de feature breadth.
+
+O perigo aqui é o usuário entrar nesse cenário esperando combinação com expansão, governança rica, renderers pesados e tudo mais. A comunicação precisa enfatizar:
+
+- o que está validado;
+- o que é explicitamente limitado.
+
+### 8. Falta um cenário forte de “toolbar and action orchestration”
+
+O plano cobre isso parcialmente em `Selection and Bulk Operations` e `Remote CRUD Baseline`, mas ainda não há um cenário cujo foco explícito seja:
+
+- toolbar actions;
+- row actions;
+- confirm flows;
+- feedback states;
+- diferença entre ação emitida, ação automatizada e ação com side effect remoto.
+
+Talvez isso não exija um cenário extra, mas exige que um dos cenários existentes assuma essa tese com clareza.
+
+### 9. O plano poderia distinguir melhor “cenários de aprendizado” de “cenários de prova”
+
+Nem todo cenário serve ao mesmo propósito.
+
+Alguns deveriam ser:
+
+- “start here”
+- “power features”
+- “advanced governance”
+
+Hoje o plano lista um catálogo bom, mas ainda não hierarquiza o percurso.
+
+## Ajustes recomendados no catálogo
+
+### Manter como principais
+
+- `Remote CRUD Baseline`
+- `Dynamic Filter Workbench`
+- `Local Data Projection`
+- `Selection and Bulk Operations`
+- `Schema Reconciliation`
+- `Expansion Lab`
+
+### Manter, mas como avançados
+
+- `Column Governance`
+- `Virtualized High Volume`
+- `Settings-Driven Authoring`
+
+### Fundir ou recalibrar
+
+- `Renderer Gallery` + `Rules and DSL Playground`
+  Resultado recomendado:
+  - manter dois cenários apenas se a diferenciação ficar extremamente clara;
+  - caso contrário, fundir em `Renderers and Rules Lab`
+
+### Criar ou reforçar como tese dentro de cenário existente
+
+- `Action Orchestration`
+  Não precisa necessariamente ser cenário próprio.
+  Pode virar a tese explícita de `Selection and Bulk Operations`.
+
+### Remover do catálogo principal como cenários equivalentes
+
+- qualquer cenário operacional temático extra além de um baseline remoto
+- múltiplos presets de expansão genérica
+- múltiplos rules demos orientados por domínio
+
+## Riscos de comunicação
+
+### 1. Oversell de recursos schema-only
+
+O playground precisa marcar claramente o que é:
+
+- ativo no runtime;
+- parcial;
+- previsto no contrato, mas ainda não plenamente executado.
+
+Sem isso, o usuário lê o cenário e conclui maturidade falsa.
+
+### 2. Subestimar a dimensão “host integration”
+
+Se os cenários ficarem muito focados em visual/configuração local, o playground ainda pode esconder o caráter host-governed da tabela.
+
+Isso é especialmente importante para:
+
+- filtro dinâmico;
+- schema reconciliation;
+- settings-driven authoring.
+
+### 3. Tornar authoring/editor mais importante do que o uso normal
+
+Se `Settings-Driven Authoring` ganhar peso excessivo no catálogo principal, o playground pode parecer mais uma ferramenta de configuração interna do que um componente consumível de runtime.
+
+### 4. Misturar performance com amplitude funcional
+
+No cenário de virtualização, a mensagem precisa ser:
+
+- performance first;
+- limites explícitos.
+
+Não “modo turbo que faz tudo”.
+
+### 5. Confundir renderers com DSL
+
+Se a curadoria não explicar a diferença entre:
+
+- exibir conteúdo rico;
+- aplicar lógica/condições/regras;
+
+o usuário pode não entender o valor específico de cada trilha.
+
+## Catálogo final recomendado
+
+### Cenários principais
+
+1. `Remote CRUD Baseline`
+2. `Dynamic Filter Workbench`
+3. `Local Data Projection`
+4. `Selection and Bulk Operations`
+5. `Schema Reconciliation`
+6. `Expansion Lab`
+
+### Cenários avançados
+
+7. `Column Governance`
+8. `Renderers and Rules Lab`
+9. `Virtualized High Volume`
+10. `Settings-Driven Authoring`
+
+## Recomendação final
+
+Se o objetivo é um playground forte e legível, eu **não publicaria 11 cenários de primeira**.
+
+Eu publicaria:
+
+- 6 cenários principais na superfície inicial;
+- 3 ou 4 cenários avançados;
+- o restante como patches ou trilhas secundárias.
+
+Isso preserva a ambição do plano sem repetir o erro original em outra forma.

package/docs/release-notes-p1-hardening.md

@@ -0,0 +1,76 @@
+# @praxisui/table - Release Notes (P1 Hardening)
+
+Data de congelamento da baseline de docs: **2026-02-26**.
+
+## Escopo consolidado
+
+Nota historica: esta baseline e anterior a canonicalizacao de Json Logic. As referencias a DSL abaixo descrevem o estado de `2026-02-26`; para regras novas, use Json Logic canonico.
+
+- DSL runtime com helpers corporativos embutidos:
+  - `jsonType`, `coalesce`, `eqIgnoreCase`, `between`, `dateBetween`, `containsAny`, `containsAll`.
+  - Helpers anteriores mantidos (`jsonGet/jsonEq/jsonIn`, `isBlank`, `today/now`, `len*`, etc.).
+  - Normalização legada preservada para expressões antigas.
+  - Limitação documentada: parser atual não suporta comparação direta de retorno de função (`fn(...) == valor`).
+- `toolbar.actions.visibleWhen` com politica por ambiente:
+  - `prod/qa`: fail-closed.
+  - `dev/hml`: fail-open para diagnostico.
+- `shortcutScope` canonico com validacao (`toolbar|global`) e fallback seguro.
+- Guards schema-only para:
+  - `behavior.sorting.multiSort`
+  - `behavior.filtering.columnFilters.enabled`
+- `appearance.colors.*` com binding real no runtime:
+  - `background`, `hoverBackground`, `selectedBackground`, `textColor`, `states.*`.
+- `messages.actions.success/errors` por `actionId` em `rowAction`, `toolbarAction` e `bulkAction`.
+
+## Baseline de contrato/documentacao
+
+- Contrato principal alinhado em:
+  - `projects/praxis-table/src/lib/praxis-table.json-api.md`
+- Guia historico de remocao da DSL em:
+  - `projects/praxis-table/docs/DSL-Extensions-Guide.md`
+- README de uso atualizado em:
+  - `projects/praxis-table/README.md`
+- Changelog atualizado em:
+  - `projects/praxis-table/CHANGELOG.md`
+
+## Evidencia MCP (Angular CLI)
+
+- Ferramentas listadas:
+  - `get_best_practices`
+  - `search_documentation`
+  - `list_projects`
+- Recomendacoes aplicadas nesta release:
+  - bindings visuais via classe/style declarativos (evitando logica visual difusa em template).
+  - validacao via testes de DOM para classes e estilos efetivos (viewport/classes + cores).
+  - fluxo de testes async padronizado com ambiente `zone.js/testing` para specs com `fakeAsync`.
+  - manutencao de fallback seguro e comportamento previsivel no runtime/documentacao.
+  - helper DSL puros/deterministicos com tratamento explicito de nulos e tipos.
+- Referencias oficiais retornadas por `search_documentation`:
+  - `https://angular.dev/best-practices/security`
+  - `https://angular.dev/guide/testing/zone-js-testing-utilities`
+  - `https://angular.dev/guide/testing`
+
+## Checklist de compatibilidade (PR final)
+
+- [x] Sem quebra de retrocompatibilidade de payload dos eventos (`action`, `row/rows`, `actionConfig`).
+- [x] Fallbacks seguros para contrato invalido (`type` invalido, `shortcutScope` invalido, `visibleWhen` invalido).
+- [x] Features schema-only com bloqueio explicito no editor e guard no runtime.
+- [x] `appearance.colors.*` com precedencia documentada: custom > tokens > defaults.
+- [x] Matriz de limitações conhecida atualizada para refletir guards e status reais.
+- [x] Suite dirigida executada para runtime, toolbar, viewport, behavior editor e filtro.
+- [x] Suite de regras DSL atualizada para novos helpers corporativos e fuzzing deterministico.
+
+## Suite de regressao consolidada
+
+Comando base de fechamento:
+
+```bash
+node_modules/.bin/ng test praxis-table --watch=false --browsers=ChromeHeadless \
+  --polyfills=zone.js --polyfills=zone.js/testing \
+  --include=projects/praxis-table/src/lib/praxis-table.local-runtime.spec.ts \
+  --include=projects/praxis-table/src/lib/praxis-table-toolbar.spec.ts \
+  --include=projects/praxis-table/src/lib/praxis-table.viewport-classes.spec.ts \
+  --include=projects/praxis-table/src/lib/behavior-config-editor/behavior-config-editor.component.spec.ts \
+  --include=projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.spec.ts \
+  --include=projects/praxis-table/src/lib/components/praxis-filter/filter-form-dialog-host.component.spec.ts
+```

package/docs/table-authoring-document-completeness-checklist.md

@@ -0,0 +1,120 @@
+# Checklist de Completude: `TableAuthoringDocument`
+
+## Objetivo
+
+Este checklist existe para validar se o `TableAuthoringDocument` é realmente canônico.
+
+Regra central:
+
+> O documento persistível precisa carregar tudo que é semanticamente necessário para reconstruir o estado aplicado da tabela, sem depender do estado previamente aplicado do componente.
+
+Se qualquer item abaixo depender de fallback vindo do runtime anterior, o round-trip ainda está incompleto.
+
+## Critério de aceite
+
+O documento será considerado completo quando:
+
+1. editor visual e editor JSON produzirem o mesmo envelope persistível;
+2. `toCanonicalConfig(document, context)` for suficiente para reconstruir o estado aplicado;
+3. `buildApplyPlan(...)` não depender de `previousAppliedState` como mecanismo arquitetural;
+4. o runtime adapter apenas executar o plano, sem recompor semântica ausente.
+
+## Itens obrigatórios
+
+### 1. Envelope persistível
+
+- [ ] O JSON oficial de autoria é o envelope versionado (`kind`, `version`, `config`, `bindings`).
+- [ ] O editor JSON da tabela edita esse envelope, não `TableConfig` cru.
+- [ ] O editor visual devolve esse mesmo envelope.
+- [ ] O parser aceita payload legado `__resourcePath__`, `__idField__`, `__horizontalScroll__`, mas a serialização nova não escreve esses campos.
+
+### 2. Config principal
+
+- [ ] `config.columns` é emitido integralmente pelo documento.
+- [ ] `config.behavior` é emitido integralmente pelo documento.
+- [ ] `config.toolbar`, `config.actions`, `config.export`, `config.messages`, `config.dialogs` e demais áreas editáveis são emitidas integralmente pelo documento.
+- [ ] Nenhuma área semanticamente relevante depende de defaults implícitos não determinísticos do runtime.
+
+### 3. Bindings persistíveis
+
+- [ ] `resourcePath` tem representação canônica única em `bindings`.
+- [ ] `horizontalScroll` tem representação canônica única em `bindings`.
+- [ ] `idField` tem decisão provisória/documentada e não fica “metade bindings, metade meta” sem regra explícita.
+
+### 4. `advancedFilters.settings`
+
+- [ ] `advancedFilters.settings` é parte do documento quando semanticamente necessário.
+- [ ] O pipeline visual da tabela reemite `advancedFilters.settings` de forma completa.
+- [ ] `toCanonicalConfig()` não precisa buscar `advancedFilters.settings` no estado anterior do componente.
+- [ ] `applyTableConfig()` não depende mais de fallback implícito baseado no estado interno previamente aplicado.
+
+### 5. Coerções contextuais
+
+- [ ] Coerção de `pagination.strategy` e `sorting.strategy` em modo local acontece em `toCanonicalConfig()`, não em `normalizeDocument()`.
+- [ ] Essa coerção é puramente determinística e depende apenas de `document + projection context`.
+- [ ] A coerção não reescreve silenciosamente o documento persistível.
+
+### 6. Metadados de servidor
+
+- [ ] `serverIdField`, `schemaId`, `schemaHash` não fazem parte do documento persistível por padrão.
+- [ ] Divergências com servidor são tratadas como diagnóstico via contexto de validação.
+- [ ] Anexar `schemaId`/`schemaHash` ao config persistido, quando necessário, é decisão explícita do runtime adapter/save flow.
+
+### 7. Persistência paralela
+
+- [ ] O design considera explicitamente artefatos persistidos fora do `TableConfig`.
+- [ ] Overrides CRUD fora do `TableConfig` têm estratégia definida:
+  - ou entram no documento de autoria,
+  - ou permanecem explicitamente fora do escopo do piloto.
+- [ ] Dirty state do editor não depende de informação que o documento não consegue representar.
+
+## Itens de revisão arquitetural
+
+### Documento
+
+- [ ] O documento contém somente informação persistível e round-trippable.
+- [ ] Nada transitório do host/sessão é serializado no envelope.
+- [ ] A versão do documento está explícita e pronta para migração futura.
+
+### Contexto
+
+- [ ] Contexto de validação está separado de contexto de projeção.
+- [ ] Contexto de runtime está separado de autoria.
+- [ ] Nenhum dado transitório da execução vaza para o envelope persistível.
+
+### Apply plan
+
+- [ ] `buildApplyPlan(...)` produz um plano suficientemente explícito para o adapter não precisar recalcular a lógica principal.
+- [ ] O plano informa diff suficiente para decisões de runtime relevantes.
+- [ ] O adapter não recompõe semântica ausente do documento.
+
+## Itens de teste obrigatórios
+
+- [ ] `parseLegacyOrDocument()` migra corretamente payload legado.
+- [ ] `serializeDocument()` nunca escreve campos `__...__`.
+- [ ] `normalizeDocument()` é idempotente.
+- [ ] `validateDocument()` acusa inconsistências estruturais do envelope.
+- [ ] `toCanonicalConfig()` reconstrói config efetiva sem ler estado anterior do componente.
+- [ ] `buildApplyPlan()` gera plano consistente para:
+  - bind remoto
+  - bind local/sem `resourcePath`
+  - mudança de `horizontalScroll`
+  - mudança de `idField`
+  - mudança de `resourcePath`
+- [ ] Editor visual -> serialize -> parse -> canonicalize produz o mesmo resultado que editor JSON -> canonicalize.
+
+## Sinais de falha
+
+Se qualquer um dos itens abaixo acontecer, o documento ainda não é canônico:
+
+- o runtime precisa olhar para o estado anteriormente aplicado para “fechar” a configuração;
+- o editor visual perde informação que o editor JSON preserva;
+- o envelope persistido não basta para reproduzir o apply;
+- `idField` ou outro campo crítico muda de significado conforme a superfície de edição;
+- o adapter de runtime continua sendo o verdadeiro dono da inteligência semântica.
+
+## Decisão prática do piloto
+
+Antes de promover a arquitetura como padrão do ecossistema, este checklist deve estar majoritariamente verde no `praxis-table`.
+
+Enquanto houver dependência real de recomposição por estado anterior, especialmente em `advancedFilters.settings`, a arquitetura deve ser tratada como piloto e não como padrão fechado.