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

package/docs/playground-scenario-curation-plan.md

@@ -0,0 +1,482 @@
+# Praxis Table Playground Scenario Curation Plan
+
+## Objective
+
+Replace the current table playground catalog with a smaller, capability-driven set of scenarios that demonstrates the real power of `@praxisui/table` without repeating the same runtime grammar across multiple domain skins.
+
+This plan is based on:
+
+- public contract in `@praxisui/core` (`TableConfigV2`, `TableBehaviorConfig`)
+- runtime implementation in `projects/praxis-table/src/lib/praxis-table.ts`
+- template/runtime surface in `projects/praxis-table/src/lib/praxis-table.html`
+- authoring/settings flow in `projects/praxis-table/src/lib/table-editor-capability.ts`
+- AI metadata in `projects/praxis-table/src/lib/ai/*.ts`
+- specialized docs for filter, DSL, local-data and expansion
+
+## Executive Summary
+
+The current playground over-indexes on:
+
+- rule styling
+- domain variation
+- small narrative changes over the same base runtime
+
+It under-represents:
+
+- remote vs local data mode
+- dynamic filter as a first-class feature
+- selection and bulk operations
+- schema reconciliation
+- settings-driven authoring
+- column governance
+- virtualization
+
+The result is breadth by theme, not by capability.
+
+After the second-opinion review, one more rule became explicit:
+
+- the target catalog must optimize for editorial navigation, not only for capability completeness.
+
+Because of that, the final structure distinguishes:
+
+- main scenarios
+- advanced scenarios
+- patches and secondary variants
+
+## Current Catalog Problems
+
+### 1. Operational flows are mostly the same demo
+
+Current scenarios:
+
+- `minimal`
+- `financial`
+- `crm`
+- `sla`
+- `backoffice`
+
+All five reuse the same metadata factory and nearly the same runtime grammar:
+
+- same core columns
+- same toolbar shape
+- same conditional style baseline
+- same interaction model
+
+They should not exist as five equal-weight presets.
+
+### 2. Rules demos are over-fragmented
+
+Current scenarios:
+
+- `rules-full`
+- `rules-funcionarios`
+- `rules-simple`
+- `rules-eventos-folha`
+- `rules-cargos`
+
+Most of them prove the same category of value:
+
+- conditional row emphasis
+- typed columns
+- small domain-specific patch set
+
+This should be consolidated into fewer, sharper demos.
+
+### 3. Expansion is duplicated as presets instead of being modeled as one lab
+
+Current scenarios:
+
+- `expansion-inline-basic`
+- `expansion-inline-tabs`
+- `expansion-advanced-nodes`
+- `expansion-funcionarios`
+
+The first three are variants of the same idea and should become one scenario with patches. Only the employee case clearly justifies a separate business-oriented example.
+
+### 4. Some documented features are absent or underplayed
+
+The runtime and docs show meaningful capabilities that are not properly showcased today:
+
+- dynamic filter pipeline
+- local data mode precedence
+- schema freshness / reconciliation
+- settings panel + canonical authoring document
+- selection and bulk delete flows
+- column reorder with keyboard/undo/persistence
+- virtualization as a governed mode
+
+### 5. Documentation drift must shape the examples
+
+The README still contains old event examples that do not match the runtime outputs. The playground should be curated against runtime truth, not outdated prose.
+
+## Runtime Truth to Preserve
+
+Examples should explicitly reflect these runtime facts:
+
+- `behavior.sorting.multiSort` is currently schema-only in runtime
+- `behavior.filtering.columnFilters.enabled` is currently schema-only in runtime
+- `behavior.dragging.rows` is currently schema-only in runtime
+- row expansion is blocked when virtualization is active in the current runtime policy
+- export is visible in toolbar config, but should not be oversold as a complete end-to-end runtime story unless the host flow is implemented
+
+## Curation Principles
+
+### Principle 1. Organize by capability, not by domain
+
+Use business framing only when it proves a capability better than an abstract demo.
+
+### Principle 2. Keep one scenario per real question
+
+Each scenario should answer one primary question, for example:
+
+- how do I connect remote data?
+- how does the dynamic filter work?
+- how do row actions and bulk actions behave?
+- how does schema reconciliation look in practice?
+
+### Principle 3. Use patches for variants, not new presets
+
+If the only difference is layout mode, emphasis rule or business skin, prefer patches.
+
+### Principle 4. Be explicit about maturity
+
+Do not create demos that imply runtime support for features that are still schema-only or partially rolled out.
+
+## Proposed Target Catalog
+
+The catalog should not ship as 11 equal-weight scenarios.
+
+Recommended publication model:
+
+- 6 main scenarios on the primary surface
+- 4 advanced scenarios behind a secondary grouping
+- patches for domain/layout variants
+
+### 1. Remote CRUD Baseline
+
+Primary goal:
+
+- prove remote mode with schema bootstrap and data fetching
+
+Should demonstrate:
+
+- `resourcePath`
+- server-driven pagination and sorting
+- row click and row actions
+- schema-derived columns
+- loading / error / empty state transitions
+
+Can absorb parts of:
+
+- `minimal`
+- `financial`
+- `crm`
+
+### 2. Dynamic Filter Workbench
+
+Primary goal:
+
+- prove that filtering is a full feature pipeline, not a toolbar extra
+
+Should demonstrate:
+
+- `praxis-filter`
+- always-visible fields
+- advanced filter settings
+- submit/change/clear behavior
+- remote request contract
+- DTO persistence
+- inline control variety
+
+Should become one of the flagship scenarios.
+
+### 3. Local Data Projection
+
+Primary goal:
+
+- prove local mode as a first-class operational path
+
+Should demonstrate:
+
+- `[data]`
+- precedence against `resourcePath`
+- client-side sorting and pagination projection
+- local filtering
+- no backend dependency
+
+This should be explicit because local mode is a meaningful contract decision.
+
+### 4. Selection and Bulk Operations
+
+Primary goal:
+
+- prove enterprise action orchestration instead of only read-only tables
+
+Should demonstrate:
+
+- single/multiple selection
+- select all
+- bulk action toolbar
+- bulk delete with confirmation
+- remote vs local behavior difference
+- action feedback states
+- clear distinction between row action, toolbar action, emitted action and automatic destructive flow
+
+This scenario should explicitly own the action-orchestration thesis.
+
+### 5. Schema Reconciliation
+
+Primary goal:
+
+- prove schema freshness as a product capability
+
+Should demonstrate:
+
+- ETag verification
+- `schemaStatusChange`
+- outdated badge
+- inline banner
+- snooze / ignore
+- reconcile via settings panel
+
+This scenario is strategically important because it differentiates Praxis from generic grids.
+
+### 6. Expansion Lab
+
+Primary goal:
+
+- prove row expansion in its real current maturity level
+
+Base scenario should demonstrate:
+
+- non-virtualized detail row
+- identity rules
+- a11y expansion trigger
+- row vs icon trigger
+- single vs multiple open
+
+Patches should switch between:
+
+- stack detail
+- tabs detail
+- advanced node set
+
+Keep one separate business scenario only if needed:
+
+- `Employee expansion`
+
+## Advanced Catalog
+
+These scenarios should exist, but not as first-surface peers of the six main scenarios.
+
+### A1. Column Governance
+
+Primary goal:
+
+- prove that the table supports governed column management
+
+Should demonstrate:
+
+- sticky columns
+- width control
+- reorder by drag
+- reorder by keyboard
+- drop-zone policy
+- undo
+- persisted preference behavior
+
+This should be framed as governance, not just “drag columns around”.
+
+### A2. Renderers and Rules Lab
+
+Primary goal:
+
+- prove the combination of rich renderer surface and conditional rule logic without splitting the story too early
+
+Should demonstrate:
+
+- badge
+- progress
+- button
+- menu
+- toggle
+- avatar
+- image
+- html
+- compose
+- rating
+- rowConditionalStyles
+- column conditional styles
+- JSON helpers
+- date/time helpers
+- list helpers
+- rule preview/test mindset
+
+Can absorb parts of:
+
+- `rules-incidentes`
+- `rules-perfil-heroi`
+- `rules-ranking-reputacao`
+- `rules-complex`
+- `rules-full`
+- `rules-funcionarios`
+- `rules-simple`
+- `rules-eventos-folha`
+- `rules-cargos`
+
+If this scenario later becomes too dense, split it again only with explicit thesis labels:
+
+- `Renderer Gallery`
+- `Rules and DSL Playground`
+
+### A3. Virtualized High Volume
+
+Primary goal:
+
+- prove performance mode with honest constraints
+
+Should demonstrate:
+
+- fixed-height virtualization
+- high row volume
+- scroll behavior
+- compatible renderer set
+- explicit note that expansion is blocked under current policy
+
+This scenario must not imply unsupported expansion + virtualization parity.
+
+### A4. Settings-Driven Authoring
+
+Primary goal:
+
+- prove the table as an authorable runtime surface
+
+Should demonstrate:
+
+- opening `PraxisTableConfigEditor`
+- canonical `praxis.table.editor` document
+- bindings such as `resourcePath`, `idField`, `horizontalScroll`
+- `buildTableApplyPlan`
+- diagnostics and projection rules
+
+This scenario should communicate that the table is governable by document, but it should live in the advanced track so the playground does not look like an internal editor first.
+
+## Current-to-Target Mapping
+
+### Keep as concept, but redesign heavily
+
+- `minimal` -> `Remote CRUD Baseline`
+- `rules-full` -> `Renderers and Rules Lab`
+- `expansion-funcionarios` -> optional business-specific `Employee expansion`
+
+### Merge into other scenarios
+
+- `financial` -> merge into `Remote CRUD Baseline` as patch or dataset variant
+- `crm` -> merge into `Remote CRUD Baseline`
+- `sla` -> merge into `Remote CRUD Baseline`
+- `backoffice` -> merge into `Remote CRUD Baseline`
+- `rules-funcionarios` -> merge into `Renderers and Rules Lab`
+- `rules-simple` -> merge into `Renderers and Rules Lab`
+- `rules-eventos-folha` -> merge into `Renderers and Rules Lab`
+- `rules-cargos` -> merge into `Renderers and Rules Lab`
+- `rules-incidentes` -> merge into `Renderers and Rules Lab`
+- `rules-perfil-heroi` -> merge into `Renderers and Rules Lab`
+- `rules-ranking-reputacao` -> merge into `Renderers and Rules Lab`
+- `rules-complex` -> merge into `Renderers and Rules Lab`
+- `expansion-inline-basic` -> merge into `Expansion Lab`
+- `expansion-inline-tabs` -> merge into `Expansion Lab`
+- `expansion-advanced-nodes` -> merge into `Expansion Lab`
+
+### Create from scratch
+
+- `Dynamic Filter Workbench`
+- `Local Data Projection`
+- `Selection and Bulk Operations`
+- `Column Governance`
+- `Schema Reconciliation`
+- `Settings-Driven Authoring`
+- `Virtualized High Volume`
+
+## Recommended Final Scenario Count
+
+Recommended stable catalog:
+
+- 6 main scenarios
+- 4 advanced scenarios
+- 1 optional business-specific expansion example
+
+This is enough to communicate breadth without turning the playground into a demo graveyard.
+
+## Recommended Grouping
+
+### Main scenarios
+
+- Remote CRUD Baseline
+- Dynamic Filter Workbench
+- Local Data Projection
+- Selection and Bulk Operations
+- Schema Reconciliation
+- Expansion Lab
+
+### Advanced scenarios
+
+- Column Governance
+- Renderers and Rules Lab
+- Virtualized High Volume
+- Settings-Driven Authoring
+
+## Implementation Sequence
+
+### Phase 1. Remove catalog noise
+
+- merge operational flow variants
+- merge renderer/rules variants
+- fold generic expansion presets into one lab
+
+### Phase 2. Add missing flagship scenarios
+
+- Dynamic Filter Workbench
+- Selection and Bulk Operations
+- Schema Reconciliation
+
+### Phase 3. Add advanced platform scenarios
+
+- Local Data Projection
+- Column Governance
+- Renderers and Rules Lab
+- Settings-Driven Authoring
+- Virtualized High Volume
+
+### Phase 4. Documentation alignment
+
+- update README event examples to match runtime outputs
+- mark schema-only capabilities clearly
+- align playground copy with current maturity of expansion and export
+
+## Editorial Path
+
+The first-surface sequence should feel intentional:
+
+1. start with connection and CRUD reality
+2. move into filtering
+3. prove local mode
+4. prove actions and orchestration
+5. prove schema governance
+6. prove expansion
+
+Only after that should the user enter advanced tracks for:
+
+- column governance
+- renderer/rules breadth
+- virtualization
+- authoring
+
+## Definition of Done for the New Catalog
+
+- each scenario has one primary capability thesis
+- no two first-surface scenarios share the same interaction grammar without a strong reason
+- schema-only capabilities are not presented as fully active runtime features
+- at least one scenario proves each strategic capability of the component
+- the primary surface stays within 6 scenarios
+- advanced scenarios are clearly labeled as deeper capability tracks
+- the catalog explains why `praxis-table` is a governed runtime platform, not just a configurable grid

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

@@ -0,0 +1,121 @@
+# Praxis Table Playground Second-Opinion Prompt
+
+Faça uma análise criteriosa e independente da estratégia de curadoria dos cenários do playground de `@praxisui/table`.
+
+Seu papel aqui não é apenas concordar com o plano. Você deve atuar como uma segunda opinião técnica/editorial exigente, procurando:
+
+- pontos cegos;
+- simplificações perigosas;
+- capacidades subestimadas ou superestimadas;
+- cenários redundantes;
+- cenários ausentes;
+- riscos de comunicação errada sobre a maturidade real do componente.
+
+## Contexto
+
+O componente `@praxisui/table` é mais do que uma grid configurável. Pela leitura do código-fonte e da documentação da lib, ele já combina:
+
+- modo remoto com bootstrap por schema;
+- modo local com precedência formal de fonte de dados;
+- filtro dinâmico como feature transversal, com `praxis-filter`, metadata, persistência local e contrato backend;
+- renderers ricos, inclusive `compose`;
+- seleção, row actions e bulk actions;
+- governança de colunas com reorder, teclado, undo e persistência;
+- verificação de schema via ETag com reconciliação;
+- settings/editor com documento canônico autorável;
+- DSL de regras com helpers nativos de JSON, tempo, listas e texto;
+- expansão de linhas com contrato tipado e restrições explícitas de virtualização;
+- virtualização como modo governado.
+
+Ao mesmo tempo, a investigação também encontrou limites importantes no runtime atual:
+
+- `behavior.sorting.multiSort` ainda é `schema-only`;
+- `behavior.filtering.columnFilters.enabled` ainda é `schema-only`;
+- `behavior.dragging.rows` ainda é `schema-only`;
+- expansão é bloqueada quando virtualização está ativa na política atual;
+- export aparece como affordance de toolbar, mas não deve ser tratado automaticamente como fluxo end-to-end completo;
+- a README ainda contém exemplos de eventos/API desatualizados em relação ao runtime real.
+
+## Problema Atual do Playground
+
+A curadoria atual do playground da tabela parece excessivamente orientada por domínio e pouco orientada por capacidade.
+
+Exemplos do problema:
+
+- cinco cenários operacionais (`minimal`, `financial`, `crm`, `sla`, `backoffice`) reaproveitam a mesma gramática de runtime com datasets e copy diferentes;
+- vários demos de regras parecem fragmentos do mesmo showcase, com pouca diferenciação real de interação;
+- os três exemplos genéricos de expansão parecem variantes de layout empacotadas como presets separados, quando poderiam ser um único laboratório com patches;
+- recursos fortes do componente, como filtro dinâmico, modo local, schema reconciliation, settings-driven authoring, seleção/bulk e governança de colunas, estão sub-representados ou praticamente ausentes;
+- a vitrine atual comunica bem “rules styling”, mas comunica mal a ideia de plataforma governada para dados enterprise.
+
+## Objetivo do Plano
+
+O plano proposto tenta substituir a vitrine atual por um catálogo menor, mais claro e mais honesto, organizado por capacidade.
+
+Catálogo alvo proposto:
+
+1. `Remote CRUD Baseline`
+2. `Dynamic Filter Workbench`
+3. `Local Data Projection`
+4. `Renderer Gallery`
+5. `Rules and DSL Playground`
+6. `Selection and Bulk Operations`
+7. `Column Governance`
+8. `Schema Reconciliation`
+9. `Settings-Driven Authoring`
+10. `Expansion Lab`
+11. `Virtualized High Volume`
+
+Racional do plano:
+
+- reduzir redundância entre cenários orientados por domínio;
+- usar patches para variantes, em vez de multiplicar presets quase iguais;
+- destacar capacidades estratégicas e diferenciais reais da tabela;
+- evitar que o playground prometa maturidade maior que a do runtime;
+- reposicionar `praxis-table` como superfície governada de dados, não só como demo de badges/regras.
+
+## Documento-base do plano
+
+Use como referência principal o documento:
+
+- `projects/praxis-table/docs/playground-scenario-curation-plan.md`
+
+## O que eu quero da sua resposta
+
+Quero uma revisão crítica de verdade, não um resumo.
+
+Avalie:
+
+1. Se o diagnóstico do catálogo atual está correto ou superficial.
+2. Se o catálogo alvo realmente cobre o poder do componente.
+3. Se algum cenário proposto está abstrato demais ou genérico demais.
+4. Se falta algum cenário essencial para provar valor enterprise.
+5. Se algum cenário proposto deveria ser fundido, renomeado, quebrado ou removido.
+6. Se a separação entre “Renderer Gallery” e “Rules and DSL Playground” está boa ou artificial.
+7. Se “Settings-Driven Authoring” merece mesmo ser um cenário flagship ou deveria ser incorporado a outro.
+8. Se “Schema Reconciliation” está sendo tratado com a importância correta.
+9. Se “Virtualized High Volume” deve ser cenário próprio ou apenas patch de outro.
+10. Se a proposta respeita bem os limites atuais do runtime e evita oversell.
+
+## Formato esperado da resposta
+
+Responda com:
+
+1. `Veredito executivo`
+   - diga se o plano está forte, incompleto, enviesado ou mal calibrado.
+
+2. `Principais achados`
+   - liste os problemas ou acertos mais importantes, em ordem de impacto.
+
+3. `Ajustes recomendados no catálogo`
+   - diga exatamente o que manter, fundir, criar, remover ou renomear.
+
+4. `Riscos de comunicação`
+   - destaque onde o playground ainda pode induzir interpretação errada sobre o componente.
+
+5. `Catálogo final recomendado`
+   - proponha sua própria versão final, se diferente.
+
+## Instrução final
+
+Se você discordar do plano, seja explícito. Prefiro uma crítica dura e útil a uma validação diplomática.