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

package/docs/local-data-support-pr-package.md

@@ -0,0 +1,66 @@
+# Pacote de PR - Local Data Support + Gate Karma
+
+## Objetivo do pacote
+Consolidar o estado pronto para PR da trilha de suporte local/remote da `praxis-table`, com evidencias de validacao e operacao de testes no WSL/Windows.
+
+## Escopo consolidado
+1. `praxis-crud` com suporte a `metadata.data` sem `resource.path`, preservando precedencia remoto > local.
+2. Hardening da lane isolada da `praxis-table` no WSL (wrapper/probe Chromium).
+3. Runner de gate seguro (`tools/karma/run-safe-gate.sh`) com modo estrito WSL e opcao de suite full da `praxis-table`.
+4. Revalidacao final do gate com trilha primaria WSL e suites completas verdes.
+
+## Commits da etapa
+1. `7855fb9` feat(praxis-crud): suportar modo local via metadata.data sem resource.path
+2. `cc17ef8` test(praxis-crud): garantir precedencia resourcePath sobre metadata.data
+3. `99f5be9` docs(praxis-crud): alinhar contrato local/remote em metadata e hints
+4. `accf85b` test(praxis-crud): estabiliza specs para injeção e contrato de metadata
+5. `f9eac2c` docs(praxis-table): atualizar status do gate seguro de validacao
+6. `93d59dc` chore(karma): add safe gate runner for table+crud
+7. `0086e4c` test(praxis-table): estabiliza specs pendentes e fecha suíte
+8. `4e95076` test(praxis-table): expand shared TestBed provider coverage
+9. `e545355` docs(praxis-table): atualizar status de validacao pos-hardening
+10. `186e367` chore(karma): add WSL chromium probe wrapper for preimpl lane
+11. `3951fab` docs(praxis-table): registrar revalidacao do safe gate
+12. `73e7160` chore(karma): auto-configure WSL chromium wrapper in safe gate
+13. `7a8e0d4` test(praxis-crud): cobrir precedencia de resourcePath fallback
+14. `d84c49d` docs(praxis-table): registrar safe-gate com crud 32 success
+15. `5d0a335` docs(praxis-table): registrar full suite 372 success apos safe-gate
+16. `0c0f55a` chore(karma): auto-fallback to chromium wrapper in preimpl lane
+17. `f7fe073` chore(karma): log resolved real chromium in preimpl lane
+18. `1857a87` docs(praxis-table): registrar gate estrito com full suite verde
+19. `b7d6782` docs(karma): document strict WSL safe-gate modes
+
+## Validacoes executadas (gate operacional)
+1. `bash ./scripts/test-table-preimpl-lane.sh`
+   - Resultado: `TOTAL: 48 SUCCESS`.
+2. `bash tools/karma/run-safe-gate.sh`
+   - Resultado: `praxis-table lane PASS (48 SUCCESS)` e `praxis-crud full PASS (32 SUCCESS)`.
+3. `SAFE_GATE_STRICT_WSL_PRIMARY=true SAFE_GATE_INCLUDE_TABLE_FULL=true bash tools/karma/run-safe-gate.sh`
+   - Resultado: `praxis-table lane PASS (48 SUCCESS)`, `praxis-table lane path: wsl-primary`, `praxis-crud full PASS (32 SUCCESS)`, `praxis-table full PASS (372 SUCCESS)`.
+
+## Cobertura critica confirmada
+1. Preservacao de `pageSize` local (override do usuario)
+   - Spec: `projects/praxis-table/src/lib/praxis-table.local-runtime.spec.ts` (`preserves user-selected pageSize in local mode during data source sync`).
+2. Estabilidade de `fieldMetadata` em modo local
+   - Spec: `projects/praxis-table/src/lib/praxis-table.local-runtime.spec.ts` (`keeps local fieldMetadata reference stable when config is unchanged`).
+
+## Risco residual atual
+1. Sem bloqueador funcional imediato identificado no gate atual.
+2. Aviso nao bloqueante em build de testes: `baseline-browser-mapping` desatualizado.
+
+## Evidencia MCP (Angular CLI MCP)
+1. Ferramentas listadas via MCP smoke inline:
+   - `get_best_practices`
+   - `search_documentation`
+   - `list_projects`
+2. Recomendacoes aplicadas ao pacote:
+   - manter validacao focada e reproduzivel via `ng test` com `--include` por suite/arquivo;
+   - preferir setup de testes centralizado e reutilizavel (consolidacao de providers compartilhados no hardening dos integration tests);
+   - manter contratos e comportamento com regressao protegida por specs dedicadas (precedencia `resourcePath > data`, transicoes local/remote/empty);
+   - executar gate com comandos explicitos e deterministicos (modo estrito WSL + suite full opcional).
+3. Referencias oficiais retornadas por `search_documentation`:
+   - https://angular.dev/cli/test#options
+   - https://angular.dev/guide/testing/utility-apis
+
+## Nota operacional
+O workspace atual usa `npm run mcp:smoke` e `npm run mcp:tools` via `scripts/mcp-smoke.js` para validar o Angular CLI MCP. A trilha Chrome DevTools continua separada em `npm run mcp:devtools:*`. A validacao MCP tambem pode ser executada por cliente inline (`@modelcontextprotocol/sdk`) conectando em `npx -y @angular/cli mcp`.

package/docs/localization-persistence-merge.md

@@ -0,0 +1,22 @@
+# Localization and Persistence Merge
+
+`PraxisTable` hydrates persisted `table-config:*` snapshots by merging them on top of the current host `config`.
+
+This preserves newer host-provided fields that may not exist in older persisted snapshots, including:
+
+- `localization.locale`
+- `localization.dateTime`
+- `localization.currency`
+- `localization.number`
+
+Practical consequence:
+
+- a consumer can add localization settings in a newer release
+- older persisted table snapshots keep their saved preferences
+- missing localization fields are inherited from the current host input instead of being erased by the persisted snapshot
+
+This behavior is especially important for cross-host scenarios such as:
+
+- `praxis-crud` forwarding `metadata.table` into `praxis-table`
+- published playgrounds and examples that reuse older persisted table state
+- enterprise hosts with locale-specific number and currency conventions

package/docs/performance-hardening-v2-implementation-plan.md

@@ -0,0 +1,479 @@
+# Praxis Table Performance Hardening V2 Implementation Plan
+
+## Objective
+
+Execute the first two cuts of the `praxis-table` performance hardening plan without changing workspace configuration and without introducing public compatibility knobs too early.
+
+The immediate goal is to make the runtime safe for enterprise grids by:
+
+1. making the render path side-effect free;
+2. creating instrumentation that proves the current and improved behavior;
+3. preparing the table for on-demand contextual discovery without visual instability;
+4. keeping the correction in the canonical table runtime, not in host apps.
+
+This plan covers only:
+
+- `Cut 0`: observability and performance budgets
+- `Cut 1`: removing discovery side effects from the render path
+
+It intentionally does **not** yet implement:
+
+- a new public performance API;
+- scheduler/concurrency orchestration;
+- backend contract changes;
+- broad UX redesign of row actions.
+
+For clarity, this is an implementation-ready internal plan for the canonical table runtime.
+It is not yet a public consumer contract change.
+
+---
+
+## Executive Decision
+
+The canonical default direction for enterprise is:
+
+- collection-level capabilities remain eager;
+- item-level capabilities/actions move toward on-demand;
+- row/render code must not trigger network discovery;
+- layout stability and accessibility are first-class acceptance criteria, not follow-up polish.
+
+---
+
+## Current Runtime Problems
+
+The current table still mixes rendering and discovery:
+
+- `fetchData()` triggers `prefetchRowDiscovery(page.content)` in [praxis-table.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.ts)
+- `prefetchRowDiscovery()` loops through visible rows and calls `ensureRowDiscovery(row)`
+- `ensureRowDiscovery()` triggers item-level `capabilities` and `actions`
+- `getResolvedRowActions(row)` also calls `ensureRowDiscovery(row)` in the render path
+
+That creates three categories of cost:
+
+1. network fan-out for each visible row;
+2. change-detection churn because each completion calls `markForCheck()`;
+3. unstable runtime semantics because template reads can mutate runtime state.
+
+In enterprise scenarios this gets worse under:
+
+- pagination, filtering and sorting;
+- multiple grids on the same screen;
+- remote multi-tenant hosts;
+- slower networks and session-scoped permissions.
+
+---
+
+## Guiding Principles
+
+- Render-time getters must be pure.
+- Discovery must be event-driven or policy-driven, never template-driven.
+- Instrumentation comes before optimization guesses.
+- Layout must stay stable while contextual affordances are unresolved.
+- Accessibility states must distinguish `loading`, `blocked`, `error`, and `ready`.
+- Session cache and visual runtime state must be modeled separately.
+- No premature public flags. Stabilize canonical internal behavior first.
+
+---
+
+## Scope and Impact Map
+
+### Canonical subproject affected
+
+- [praxis-table](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table)
+
+### Consumers impacted
+
+- [praxis-crud](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-crud)
+- the remote host lab in [quickstart-remote-metadata-lab.page.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/src/app/features/quickstart-remote-metadata-lab/quickstart-remote-metadata-lab.page.ts)
+
+### Public docs potentially affected
+
+- [README.md](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/README.md)
+- [praxis-table.json-api.md](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.json-api.md)
+
+For Cuts 0 and 1, documentation updates are expected to stay in internal planning/test notes unless implementation changes observable runtime behavior.
+
+### Tests and validations minimally required
+
+- focused specs in `praxis-table`
+- focused regression in `praxis-crud` only if row action integration changes
+- `npm run build:praxis-table`
+- remote/browser proof only after the code cuts, not during planning
+
+### Breaking-change risk
+
+- low if changes remain internal and preserve current row actions behavior
+- medium if a hidden reliance on render-triggered discovery exists in current templates/integration tests
+
+---
+
+## Cut 0: Observability and Budgets
+
+## Goal
+
+Add instrumentation that makes current row discovery cost measurable before behavior is changed.
+
+## Required outcomes
+
+1. We can count item-level discovery requests per table session.
+2. We can distinguish:
+   - discovery requested
+   - discovery served from cache
+   - discovery completed
+   - discovery failed
+3. We can inspect row contextual runtime state without relying on network logs.
+4. We can define initial budgets and assert against them in tests.
+
+## Canonical budgets for Cut 0
+
+These are initial engineering budgets, not final SLAs:
+
+- no more than `1` discovery trigger per row/rel while an identical request is in flight
+- no more than `1` item-level discovery request per rel/href inside the freshness window
+- no implicit discovery from render-time getters
+- remote load of a page with 10 rows must not enqueue more discovery work than the current explicit policy allows
+
+These cuts must also define initial perception budgets for enterprise validation:
+
+- contextual row affordance must expose a visible `loading-context` state immediately when user-triggered discovery starts
+- row action area must remain layout-stable while contextual discovery is pending
+- row expansion/detail entry must distinguish `loading-context`, `blocked-semantic`, and `error-transient`
+- no focusable control may disappear from under keyboard focus during contextual resolution
+
+Budgets to measure and expose internally:
+
+- `rowDiscoveryRequestedCount`
+- `rowDiscoveryNetworkCount`
+- `rowDiscoveryCacheHitCount`
+- `rowDiscoveryFailureCount`
+- `rowDiscoveryInFlightCount`
+- `rowDiscoveryLastResolvedAt`
+- `rowDiscoveryPendingRowCount`
+- `rowDiscoveryUserTriggeredCount`
+- `rowDiscoveryPrefetchCount`
+
+Initial measurable thresholds to freeze for Cuts 0 and 1:
+
+- repeated evaluation of row-action getters for the same row must add `0` new network requests
+- a single explicit row interaction must start at most `1` capability request and `1` action-catalog request for that row/interaction cycle
+
+## Planned write set
+
+Primary files:
+
+- [praxis-table.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.ts)
+- [praxis-table.html](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.html) if instrumentation is surfaced through loading-state affordances used in focused tests
+- [praxis-table.remote-regression.spec.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.remote-regression.spec.ts)
+- potentially one new focused spec file near the table runtime if it improves isolation
+
+Optional if needed for test support:
+
+- [README.md](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/README.md)
+
+## Implementation tasks
+
+### 0.1 Introduce internal row discovery metrics state
+
+Add an internal structure in `PraxisTable` dedicated to diagnostics/observability for row discovery.
+
+It should capture at least:
+
+- total requested by rel
+- total served from cache by rel
+- total completed by rel
+- total failed by rel
+- current in-flight href count
+
+This must remain internal runtime state for now.
+
+### 0.2 Add explicit instrumentation points
+
+Instrument the following events:
+
+- prefetch scheduled
+- on-demand discovery scheduled
+- cache hit
+- request started
+- request resolved
+- request failed
+
+Instrumentation should attach enough context to debug:
+
+- `tableId`
+- `resourcePath`
+- `rel`
+- `href`
+- source:
+  - `prefetch`
+  - `row-action`
+  - `expansion`
+  - future sources can be added later
+
+### 0.3 Add a debug snapshot accessor
+
+Expose an internal/debug-friendly snapshot method or readonly getter on the component that tests can inspect.
+
+This is not a new public API for consumers. It is a runtime diagnostic surface for focused specs.
+
+Recommended contents:
+
+- metrics counters
+- current policy decisions
+- number of cached hrefs
+- number of pending hrefs
+
+Implementation constraint:
+
+- prefer a clearly internal debug accessor/helper used only by focused specs
+- do not export a new public symbol from `public-api.ts`
+- do not document this accessor as a supported consumer contract
+
+### 0.4 Encode the initial budgets in tests
+
+Focused specs should prove:
+
+- dedupe works while requests are in flight
+- repeated reads inside TTL count as cache hits rather than network hits
+- current explicit prefetch policy is visible in diagnostics
+- user-triggered discovery transitions the runtime into a distinct `loading-context` state
+- loading/blocked/error states are distinguishable in runtime diagnostics
+
+## Focused tests for Cut 0
+
+Primary:
+
+- add/update a focused spec around row discovery metrics in `praxis-table`
+- keep or extend [praxis-table.remote-regression.spec.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.remote-regression.spec.ts)
+
+Suggested test cases:
+
+1. `records a single network discovery for repeated same-href capability requests`
+2. `records cache hit for repeated row capability read inside TTL`
+3. `distinguishes prefetch and on-demand discovery sources`
+4. `does not increment network count when href is already in flight`
+5. `records pending contextual rows and loading-context transitions for user-triggered discovery`
+
+## Acceptance criteria for Cut 0
+
+- row discovery metrics are available in focused tests
+- dedupe and cache hit behavior are asserted by tests
+- runtime diagnostics distinguish `idle`, `loading-context`, `ready`, `blocked-semantic`, and `error-transient`
+- no workspace config changes
+- no public API contract is introduced yet
+
+---
+
+## Cut 1: Remove Side Effects From the Render Path
+
+## Goal
+
+Make render-time reads pure by removing discovery-triggering side effects from row action resolution.
+
+## Required outcomes
+
+1. Template-driven calls must no longer trigger network work.
+2. Row discovery must be triggered only from explicit runtime entrypoints.
+3. Existing visual affordances should continue to work, using already-resolved state.
+4. This cut should not yet force the final on-demand UX policy; it only removes the structural flaw.
+
+## Planned write set
+
+Primary files:
+
+- [praxis-table.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.ts)
+- [praxis-table.html](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.html)
+- [praxis-table.scss](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.scss) when needed to keep row affordance layout stable during unresolved contextual discovery
+- [praxis-table.remote-regression.spec.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.remote-regression.spec.ts)
+- [praxis-crud.component.spec.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-crud/src/lib/praxis-crud.component.spec.ts) only if host interaction assumptions change
+
+Potential supporting docs after implementation:
+
+- [README.md](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/README.md)
+
+## Implementation tasks
+
+### 1.1 Remove `ensureRowDiscovery(row)` from render-time action resolution
+
+Target the current call path rooted in `getResolvedRowActions(row)`.
+
+After this cut:
+
+- `getResolvedRowActions(row)` must only derive from current row runtime state
+- `getVisibleRowActions(row)`, `getInlineRowActions(row)`, `getOverflowRowActions(row)` must stay pure
+
+### 1.2 Introduce explicit runtime trigger points
+
+Create explicit discovery trigger methods with named intent, for example:
+
+- trigger discovery for row overflow-menu open intent
+- trigger discovery for explicit row workflow interaction only when the action is already surfaced by resolved runtime state
+- keep expansion-triggered discovery in expansion flow only
+
+These methods should become the only legal entrypoints for row item discovery until the scheduler cut.
+
+For avoidance of ambiguity, the expected concrete UI/runtime anchor points are:
+
+- row expansion trigger from the expander control rendered in [praxis-table.html](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.html) around the `_expander` column and its `aria-expanded` toggle
+- row overflow contextual actions from the overflow menu trigger rendered in the row actions cell in [praxis-table.html](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.html), currently using `matMenuTriggerFor` and the `more_vert` icon
+- runtime handlers must live in [praxis-table.ts](/D:/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.ts) rather than in template-side incidental calls
+
+For Cut 1, freeze the trigger policy explicitly:
+
+- allowed:
+  - expansion toggle in `hypermedia` mode
+  - row overflow menu open
+  - explicit workflow interaction when the row runtime already exposed that affordance
+- not allowed:
+  - plain row render
+  - repeated getter evaluation
+  - hover-only discovery
+  - passive focus traversal that is not an explicit user intent to inspect contextual actions
+
+These entrypoints must also set explicit runtime states that future UX can rely on:
+
+- `loading-context`
+- `ready`
+- `blocked-semantic`
+- `error-transient`
+
+### 1.3 Preserve current behavior using already-known state
+
+If row discovery has not run yet:
+
+- configured CRUD actions should still render according to existing fallback behavior
+- discovered workflow actions should only appear after explicit resolution
+- unresolved contextual affordances must keep a stable reserved area in the row action layout
+- unresolved contextual affordances must not masquerade as `no actions available`
+
+This prevents the cut from accidentally breaking baseline CRUD affordances while removing the side effect.
+
+### 1.4 Add temporary guardrails for accidental regressions
+
+Add a diagnostic assertion pattern in tests that proves repeated rendering/getter access does not change discovery counters.
+
+This is the key regression guard for the cut.
+
+Also add guardrails for UX/accessibility regressions:
+
+- keyboard focus remains on a stable trigger while discovery is pending
+- loading state is represented distinctly from semantic unavailability
+- row action area does not collapse/reflow when contextual state changes
+
+## Focused tests for Cut 1
+
+Suggested cases:
+
+1. `render-time row action getters do not trigger discovery`
+2. `opening contextual row affordance triggers discovery exactly once`
+3. `expansion hypermedia still resolves capabilities on demand when expanded`
+4. `configured CRUD row actions remain visible without implicit discovery`
+5. `discovered workflow row actions appear only after explicit contextual resolution`
+6. `row action area stays layout-stable while contextual discovery is pending`
+7. `contextual loading state is distinguishable from blocked or transient error states`
+
+If needed, split tests into:
+
+- pure table runtime spec
+- remote regression spec
+
+## Acceptance criteria for Cut 1
+
+- template/read getters are side-effect free
+- no discovery is triggered during plain render
+- explicit interaction still triggers discovery
+- expansion hypermedia behavior remains on-demand
+- focused tests prove the difference between render and interaction paths
+- row affordance area stays visually stable while contextual discovery is unresolved
+- contextual interaction exposes an explicit `loading-context` state
+- contextual failure does not silently degrade into `no actions`
+- no focusable affordance disappears from under keyboard focus during contextual resolution
+- render/getter re-evaluation alone adds `0` new discovery requests for the same row
+- a single overflow-menu open or expansion toggle does not fan out into repeated duplicate requests for the same row/rel while one is already in flight
+
+---
+
+## Design Constraints for Cuts 0 and 1
+
+These constraints must be respected now even if some of them are fully exercised only in later cuts.
+
+### Layout stability
+
+- do not make row action width depend on late-arriving discovery in a way that causes visible reflow
+- prefer existing configured actions plus later enrichment over inserting/removing controls unpredictably
+
+### Accessibility
+
+- do not make focusable controls disappear from under focus
+- if interaction-triggered loading is introduced in templates, it must be announced in the same implementation slice
+- do not conflate `loading` with `blocked`
+- degraded discovery states must remain perceivable for keyboard and assistive-tech users
+
+### Degraded UX contract
+
+- `loading-context`: user-triggered contextual resolution is pending
+- `blocked-semantic`: backend resolved the context and denied the affordance semantically
+- `error-transient`: contextual discovery failed or timed out and can be retried
+- `ready`: contextual discovery completed and affordances are stable
+
+These states must be explicit in runtime/test diagnostics even if the final UX chrome evolves later.
+
+### Cache semantics
+
+- do not redesign the full cache in Cut 1
+- but do not add new logic that further mixes:
+  - session cache
+  - current-page visual state
+  - in-flight requests
+
+### Future compatibility
+
+- Cut 1 must make it easier, not harder, to add:
+  - row runtime state materialization
+  - concurrency scheduler
+  - context-aware cache keys
+  - viewport-aware discovery
+
+---
+
+## Validation Strategy
+
+Minimal validation for implementation of these cuts:
+
+1. focused specs in `praxis-table`
+2. `npm run build:praxis-table`
+3. only if host integration changes are affected, focused specs in `praxis-crud`
+
+Not required for these cuts by default:
+
+- full workspace suite
+- remote browser proof
+- backend changes
+
+If validation is partial, the implementation handoff must state exactly which focused specs were run.
+
+Recommended escalation only if a focused regression becomes ambiguous:
+
+- one browser-level proof in the remote lab after Cut 1 to confirm row action/menu behavior did not drift visually
+
+---
+
+## Not In Scope Yet
+
+- scheduler with concurrency limit
+- visual skeleton redesign for row menus
+- context-aware cache key including tenant/principal/locale
+- backend aggregation of row affordances
+- new public config flags for prefetch policies
+
+These belong to later cuts after Cuts 0 and 1 are stable.
+
+---
+
+## Exit Condition
+
+This plan is ready to execute when:
+
+1. focused implementation starts in `praxis-table`;
+2. Cut 0 metrics are in place;
+3. Cut 1 removes render-path side effects without breaking baseline CRUD row affordances;
+4. the Cut 1 write set and tests explicitly cover runtime states, layout stability, and non-silent degraded UX.