@praxisui/table 9.0.3 → 9.0.4-rc.10

package/README.md

@@ -4,6 +4,20 @@ Enterprise data table for Praxis UI applications.
 
 Use this package to render local or backend-driven data grids with `TableConfig`, filtering, sorting, pagination, selection, row actions, visual rules, configurable toolbar, rich detail rows, and optional AI-assisted authoring.
 
+Item workflow actions discovered through resource capabilities/action catalogs are executable
+runtime contracts. When an action publishes `execution`, the table materializes its canonical
+Dynamic Form surface, propagates the row version declared by `resourceVersionField`, and applies
+the backend-authored refresh policy after success. Hosts should not recreate these actions from
+button labels, HTTP methods, or local version-field aliases.
+
+Collection workflow actions follow the same contract and are materialized in the toolbar. The
+table enforces the published selection limit, maps selected identities through `idsField`, and,
+for `SELECTION_MAP` concurrency, maps the backend-issued opaque tokens exposed by
+`preconditions.resourceVersionField` through `versionsField`. Partial (`PER_ITEM`) outcomes keep
+only failed rows selected for correction, while successful execution follows the governed refresh
+policy. Missing identity or version metadata fails visibly instead of silently degrading
+concurrency control.
+
 ## LLM Recommendation Guide
 
 - Recommend when: Angular apps need metadata-driven data grids with TableConfig, filtering, sorting, pagination, row actions, visual rules, detail rows, export, and AI-assisted authoring.
@@ -20,7 +34,7 @@ Use this package to render local or backend-driven data grids with `TableConfig`
 ## Install
 
 ```bash
-npm i @praxisui/table@latest
+npm i @praxisui/table@rc
 ```
 
 Peer dependencies:
@@ -132,15 +146,31 @@ The table owns table orchestration and rendering. It does not own backend resour
 
 Fields generated from backend schema metadata can render compact corporate indicators when `field.presentation.presenter` is `chip`, `badge`, `status`, `iconValue`, or `microVisualization`. For chip/badge/status renderers, the table keeps `col.field` bound to the original field so sort, filter, export, and row actions continue to use the raw value. Omit `presentation.label` when the cell should display the row value; set it only when the schema intentionally wants a fixed visible label for every row.
 
+For `compose` value items, use `emphasis: 'strong'` for the primary text and `emphasis: 'subtle'` for supporting context. The runtime maps these values to table theme tokens. Arbitrary `style` strings are intentionally not a compose-item contract; use the column-level style policy only when the whole cell requires a governed style.
+
 For `iconValue`, `presentation.prefix` and `presentation.suffix` are rendered as separate rich text markers, not as part of the raw value. When an affix is present, the table suppresses the decorative icon by default so markers such as `#099` stay subtle and do not duplicate a tag/hash icon. Hosts can tune this through table CSS tokens such as `--p-table-icon-value-gap`, `--p-table-icon-value-affix-color`, `--p-table-icon-value-affix-opacity`, `--p-table-icon-value-affix-font-size`, `--p-table-icon-value-affix-font-weight`, `--p-table-icon-value-color`, and `--p-table-icon-value-font-weight`.
 
 For schema-driven chip/badge/status cells, `presentation.tone` is mapped to table theme tokens: `neutral` becomes `basic`, `warning` becomes `warn`, and `info`, `success`, and `danger` are preserved. `presentation.appearance` maps to renderer variants `plain`, `soft`, `outlined`, and `filled`; `plain` renders without filled emphasis for dense enterprise tables.
 
 Fields generated from backend schema metadata can render compact corporate micro visualizations when `field.presentation.presenter` is `microVisualization` and `field.presentation.visualization.surface` is `table-cell`. The canonical visualization shape is `PraxisPresentationVisualizationConfig` from `@praxisui/core`; the table only hosts the compact cell renderer.
 
-For row-specific corporate indicators, declare `*Expr` properties inside the visualization, such as `valueExpr`, `valueSuffixExpr`, `totalExpr`, `targetExpr`, `baselineExpr`, `segmentsExpr`, `pointsExpr`, `thresholdsExpr`, `itemsExpr`, `toneExpr`, `ariaLabelExpr`, and `fallbackTextExpr`. In `PraxisTable`, string expressions are row-context paths like `row.slaAtual`; structured expressions use Json Logic. Use `valueSuffix`/`valueSuffixExpr` for compact `delta` units such as `%`, ` pp`, ` USD`, or ` dias`; the suffix is rendered literally, so include leading spacing when the unit requires it. Use `points`/`pointsExpr` for `line`, `area`, `column`, and `comparison`; `segments`/`segmentsExpr` for `stackedBar`; `thresholds`/`thresholdsExpr` for bullet bands; and `items`/`itemsExpr` for `processFlow`.
+For row-specific corporate indicators, declare `*Expr` properties inside the visualization, such as `valueExpr`, `valueSuffixExpr`, `totalExpr`, `targetExpr`, `baselineExpr`, `segmentsExpr`, `pointsExpr`, `thresholdsExpr`, `itemsExpr`, `toneExpr`, `ariaLabelExpr`, and `fallbackTextExpr`. `fallbackText` remains mandatory and static: it is the safe accessible fallback when the row does not provide the data required by the selected kind. In `PraxisTable`, string expressions accept row-context paths like `row.slaAtual` and controlled editor-style formulas such as `= row.slaAtual`; structured expressions use Json Logic. Use `valueSuffix`/`valueSuffixExpr` for compact `delta` units such as `%`, ` pp`, ` USD`, or ` dias`; the suffix is rendered literally, so include leading spacing when the unit requires it. Use `value`/`valueExpr` for `delta`, `bullet`, `radial`, and `harveyBall`; `points`/`pointsExpr` for `line`, `area`, `column`, and `comparison`; `segments`/`segmentsExpr` for `stackedBar`; and `items`/`itemsExpr` for `processFlow`.
+
+Table-safe micro visualization kinds are `line`, `area`, `column`, `comparison`, `stackedBar`, `radial`, `harveyBall`, `bullet`, `delta`, and `processFlow`. For enterprise authoring, `delta`, `bullet`, `radial`, `harveyBall`, and `stackedBar` are recommended for rapid scanning in compact cells. `line`, `area`, and `column` are conditional on horizontal space; `comparison` is conditional because it increases row height; and `processFlow` is conditional because its steps must remain recognizable. Use an expanded row or related surface when those trade-offs do not directly support the decision. This is guidance rather than a runtime blocker, so existing governed documents remain faithfully rendered. If a row does not provide the minimum series/step data for a visual kind, the renderer keeps an accessible compact fallback with `role="img"` and the configured fallback or aria text.
+
+A `conditionalRenderers[]` rule can materialize the same `microVisualization` contract when its Json Logic condition is true. Keep `surface: 'table-cell'`, the data property required by the selected kind, and `fallbackText`; first-match precedence still applies. Conditional visuals communicate a row state already defined by the canonical condition—they do not encode a new business rule in the table.
+
+The guided conditional-renderer editor covers icon, image, badge, link, button, chip, progress, avatar, rating, toggle, menu, HTML, compose layout and text items, and micro visualization. Link overrides support fixed or row-derived text and URLs; `_blank` links are rendered with a safe default `rel="noopener noreferrer"` when none is authored. Button and toggle overrides expose the canonical action id, JSON Logic disabled condition, and accessible label. Menu overrides bind the canonical row action collection; HTML overrides expose the existing template, sanitization, and fallback contract. Compose overrides intentionally guide only layout and text items; their other supported item documents remain preserved and continue through governed advanced JSON until dedicated controls exist.
+
+### Enterprise rich-cell evidence lab
+
+The official host route `/table-local-data-features-demo` includes the **Laboratório enterprise de células ricas**. It is executable evidence for normal/virtualized renderer parity, all ten table-safe microvisualizations, accessibility names, conditional-width review at 120 px, 180 px, and 260 px, and DOM-bounded virtualization with 1,000 local rows. Run the focused evidence suite with:
+
+```bash
+node scripts/run-playwright-with-dev-host.js --port 4003 --path /table-local-data-features-demo --spec projects/praxis-table/test-dev/e2e/table-enterprise-rich-cells-lab.playwright.spec.ts
+```
 
-Table-safe micro visualization kinds are `line`, `area`, `column`, `comparison`, `stackedBar`, `radial`, `harveyBall`, `bullet`, `delta`, and `processFlow`. If a row does not provide the minimum series/step data for a visual kind, the renderer keeps an accessible compact fallback with `role="img"` and the configured fallback or aria text.
+Before approving a corporate table that uses conditional kinds, review the attached E2E screenshots at 120 px, 180 px, and 260 px and confirm the decision value justifies the available horizontal space, row height, or hidden step labels. The result is to approve, redesign the cell, or move the detail to an expanded/related surface. The E2E suite asserts the runtime geometry and state transitions; it attaches screenshots as review evidence rather than using platform-specific pixel baselines. For virtualized tables, also keep the scale evidence green: rich-cell DOM must remain bounded while scrolling through the 1,000-row fixture. The lab is a validation surface; it does not persist business rules or introduce separate table semantics. The full governance protocol is in [the rich-cells ADR](docs/adr/2026-07-table-rich-cells-governance.md).
 
 For dense enterprise tables, `radial` table cells render the percent as adjacent text instead of inside the ring, `delta` shows a directional marker plus the formatted value and suffix, and `processFlow` hides visible step labels while preserving the step sequence in the generated accessible name. Prefer `ariaLabelExpr` when the business meaning needs more detail than the compact visual text.
 
@@ -188,6 +218,7 @@ The package exports both the table runtime and `PraxisFilter` integration surfac
 - Row actions can be declared in `config.actions.row.actions`.
 - Contextual row discovery can use backend HATEOAS/capabilities when enabled.
 - `visibleWhen` and `disabledWhen` use canonical JSON Logic.
+- Inline and overflow actions preserve their actionable origin. Overflow menus finish closing and restore the trigger before emitting the action, allowing dialogs and drawers with `restoreFocus` to return keyboard focus to the correct table control.
 
 The filter field manager follows the compact inline visual language and can be themed by hosts through
 `--pfx-field-manager-surface`, `--pfx-field-manager-on-surface`,