@praxisui/table 9.0.0-beta.9 → 9.0.0-beta.90

package/README.md

@@ -26,7 +26,7 @@ npm i @praxisui/table@latest
 Peer dependencies:
 
 - `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/cdk`, `@angular/material`, `@angular/router` `^21.0.0`
-- `@praxisui/ai`, `@praxisui/core`, `@praxisui/dialog`, `@praxisui/dynamic-fields`, `@praxisui/dynamic-form`, `@praxisui/metadata-editor`, `@praxisui/rich-content`, `@praxisui/settings-panel`, `@praxisui/table-rule-builder` `^9.0.0-beta.4`
+- `@praxisui/ai`, `@praxisui/core`, `@praxisui/dialog`, `@praxisui/dynamic-fields`, `@praxisui/dynamic-form`, `@praxisui/metadata-editor`, `@praxisui/rich-content`, `@praxisui/settings-panel`, `@praxisui/table-rule-builder` `^9.0.0-beta.12`
 - `rxjs` `~7.8.0`
 
 ## Minimum Local Runtime
@@ -87,6 +87,8 @@ Use `resourcePath` when the host wants the table to enter backend schema/data mo
 
 Optional collection operations such as export are not implied by a base route. Expose them only when backend capabilities or HATEOAS links prove that the operation is available.
 
+When the collection response exposes `_links.create` or a collection `capabilities` snapshot with create support, `PraxisTable` can materialize the canonical `create` toolbar action without requiring each host screen to duplicate labels, disabled state, schema URLs, or submit URLs. If the host provides `surface.open`, the action opens the create form as a governed collection surface; otherwise the table emits `toolbarAction` with the enriched action metadata for the composed host to handle.
+
 ## Runtime Inputs And Outputs
 
 Common inputs:
@@ -116,12 +118,68 @@ Common outputs:
 - `loadingStateChange`, `collectionLinksChange`
 - `widgetEvent`
 
+Row, selection and action events can include the read-only `resourceIdentity`
+materialized from the response schema. A valid explicit identity is preferred;
+otherwise a valid `idField` can produce a diagnostic key-only fallback. This
+context is for list/detail continuity and must not be copied into command
+controls or persistence payloads.
+
 ## TableConfig Boundaries
 
 `TableConfig` comes from `@praxisui/core` and is the public table configuration contract. It covers columns, behavior, appearance, toolbar, messages, filtering, selection, expansion, export configuration, conditional styles/renderers, and other table semantics.
 
 The table owns table orchestration and rendering. It does not own backend resource semantics, form payloads, page composition, or business rules outside the table contract.
 
+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 `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`.
+
+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.
+
+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.
+
+Use `config.ai.assistant.enabled = false` when a host needs to disable the embedded AI assistant entrypoint for a table instance. The default is enabled, so existing AI-enabled tables keep the current behavior without extra config. When the value changes to `false`, the component closes the assistant and removes the table assistant session from the shared assistant registry.
+
+## Empty State
+
+Use `behavior.emptyState` for table-owned no-data copy and presentation. `message` remains the required backward-compatible text. When `title` is omitted, `message` is used as the empty-state title. When `title` is provided, `message` is rendered as the description unless `description` is explicitly set.
+
+When the host does not provide `behavior.emptyState` or legacy `messages.states` copy, the table uses localized runtime defaults for the initial empty collection and for the filtered/search no-results state. Context-specific entries in `behavior.emptyState.contexts.initial`, `behavior.emptyState.contexts.filtered`, and `behavior.emptyState.contexts.searched` still override the base empty state for those modes.
+
+```ts
+const config: TableConfig = {
+  behavior: {
+    emptyState: {
+      title: 'Sem documentos legais',
+      message: 'Inclua um documento legal para registrar a base normativa deste código.',
+      icon: 'gavel',
+      density: 'compact',
+      variant: 'inline',
+    },
+  },
+};
+```
+
+## Toolbar Appearance
+
+Use `toolbar.appearance` for governed toolbar chrome instead of host CSS targeting internal classes. The built-in preset `table-integrated` composes toolbar and table as one operational block using public tokens for background, border, radius, shadow, spacing, and density.
+
+```ts
+const config: TableConfig = {
+  toolbar: {
+    visible: true,
+    position: 'top',
+    appearance: { preset: 'table-integrated' },
+  },
+};
+```
+
 ## Filtering And Row Actions
 
 The package exports both the table runtime and `PraxisFilter` integration surfaces.
@@ -131,6 +189,43 @@ The package exports both the table runtime and `PraxisFilter` integration surfac
 - Contextual row discovery can use backend HATEOAS/capabilities when enabled.
 - `visibleWhen` and `disabledWhen` use canonical JSON Logic.
 
+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`,
+`--pfx-field-manager-on-surface-muted`, `--pfx-field-manager-outline`,
+`--pfx-field-manager-focus-outline`, `--pfx-field-manager-search-surface`,
+`--pfx-field-manager-search-on-surface`, `--pfx-field-manager-search-placeholder`,
+`--pfx-field-manager-search-height`, `--pfx-field-manager-search-radius`,
+`--pfx-field-manager-search-font-size`, `--pfx-field-manager-search-line-height`,
+`--pfx-field-manager-search-font-weight`, `--pfx-field-manager-search-icon-size`,
+`--pfx-field-manager-scrollbar-thumb`, `--pfx-field-manager-scrollbar-thumb-hover`,
+`--pfx-field-manager-scrollbar-track`, and `--pfx-field-manager-scrollbar-size`. Their defaults inherit
+the corresponding `--pdx-inline-*` tokens when available, then the semantic `--praxis-theme-*` roles,
+and finally Material system
+tokens; `--pfx-field-manager-search-radius` intentionally defaults to Material's full corner radius so
+the search focus ring and field share the same pill geometry. The runtime resolves every public
+`--pfx-field-manager-*` token from the host before applying its private fallback, so overrides take
+effect without CSS specificity workarounds. The scrollable field list reserves a stable scrollbar gutter
+and derives a contrasting thumb from the manager surface and on-surface roles, so its overflow affordance
+does not depend on application-global scrollbar styles. Native scrollbar auto-hide preferences can still
+control when the operating system displays the thumb. Because the manager renders in a CDK overlay, define host overrides on a global theme scope
+such as `html`, `body`, or the application theme class rather than only on the `praxis-filter` element.
+When using the `PraxisFilter` i18n input, `selectedFieldsSectionTitle` and
+`availableFieldsSectionTitle` customize the grouped field-manager headings; both are optional and
+default to the Portuguese runtime labels. Each manageable field preserves its authored
+`FieldMetadata.description` (falling back to its explicit tooltip/help metadata) as an information
+tooltip on hover and keyboard focus. This lets operators distinguish semantically different filters
+with similar labels—such as a single date, a date range, and a relative period—without the table
+runtime fabricating domain guidance.
+
+While the field manager is open, its selected and available sections preserve the composition they
+had when the draft began. Checkbox state, the displayed-field count, pending-change badges, and the
+Apply count update immediately, but rows are regrouped only after Apply closes the overlay or when it
+is opened again. This keeps pointer position, keyboard focus, and scroll anchoring stable. Optional
+`PraxisFilter.i18n` entries `fieldPendingAddition`, `fieldPendingRemoval`,
+`fieldAddedAnnouncement`, `fieldRemovedAnnouncement`, and
+`fieldSelectionSummaryAnnouncement` customize the pending-state badges and polite live-region
+feedback; announcement templates accept `{field}` and `{summary}` placeholders.
+
 ```ts
 const config: TableConfig = {
   columns: [{ field: 'name', header: 'Name' }],
@@ -174,6 +269,10 @@ The package also exports `PRAXIS_TABLE_AUTHORING_MANIFEST` for governed AI edits
 The table can materialize analytic table projections produced by the canonical `x-ui.analytics` decision in `@praxisui/core`. Services such as `AnalyticsTableContractService` help hosts resolve analytic table contracts and data without reimplementing that projection.
 
 Detail rows can host governed rich content surfaces. Rich content semantics belong to the shared rich content/core contracts; the table provides the row-detail shell and host-mediated dispatch.
+Governed embed nodes (`formRef`, `tableRef`, `chartRef`, `templateRef`, `diagramEmbed`) default to `renderMode: "reference"` when the field is omitted.
+`renderMode: "inline"` is an explicit intent for an owning runtime/provider to materialize the referenced surface inside the detail row; hosts must still keep the reference shell as the accessible fallback when the provider, data, or capability is unavailable.
+For charts, use `chartDocumentRef` or a governed `chartDocument` payload that follows the canonical `x-ui.chart` contract; do not place raw chart-engine options directly inside the table detail schema.
+Hosts can register `PRAXIS_TABLE_DETAIL_INLINE_NODE_RESOLVERS` to resolve lightweight references such as `chartDocumentRef` into governed runtime inputs before the inline renderer runs, keeping persisted detail schemas small and auditable.
 
 ## Public API
 
@@ -199,6 +298,8 @@ Main exports:
 
 - Separate local data mode from backend resource mode before deciding the minimum setup.
 - `enableCustomization` is opt-in and gates settings/authoring surfaces; it does not change the data mode.
+- `authoringCapability` optionally requires an exact capability from `EnterpriseRuntimeContext.capabilities` before those authoring surfaces are materialized. Use it for governed configuration; do not derive authorization from client-side usernames or roles.
 - Treat export as a governed optional operation, not as automatic support implied by `resourcePath`.
+- When `excel` is enabled in `export.formats`, the toolbar also exposes a current-page Excel export that downloads only the rows currently loaded in the table runtime with visible columns and formatted cell values. Full filtered exports continue to use the configured collection export provider.
 - Theme the table through Material/Praxis tokens instead of targeting internal descendants.
 - Use the official documentation for full recipes on filters, rich detail rows, rules, formatting, AI authoring, and backend capabilities.