@praxisui/table 9.0.66 → 9.0.68-rc.0

package/README.md

@@ -2,14 +2,77 @@
 
 Enterprise data table for Praxis UI applications.
 
+Opt-in responsive record cards (`appearance.responsive.mobile.cardMode`) adapt to
+the narrower of the viewport and the table host, including resized desktop widgets.
+The existing mobile breakpoint is reused; virtualization and horizontal-scroll
+policy are unchanged. At up to 480 px of internal width, labels stack above values.
+Selection decoration does not replace field labels. No column is removed by this
+adaptation. The config editor no longer displays an informational version banner
+over actionable diagnostics.
+
+In card mode, an intentionally empty action-column heading does not reserve a
+label row or extra vertical padding. Explicit action headings remain visible,
+and the action buttons retain their configured dimensions. Selection keeps its
+own accessible control area; this refinement does not reorder business fields.
+
+The checked row-selection radio inherits `--p-table-row-selected-fg` in its normal,
+hover, focus and pressed states, including responsive cards. Disabled and unselected
+radios keep Material's state tokens. Custom themes must maintain sufficient contrast
+between the selected-row foreground and background; the built-in light/dark themes
+are covered by a real-backend regression with a minimum 3:1 indicator contrast.
+
+Table action authoring projects session availability out of `toolbar.actions`,
+`actions.row.actions`, `actions.bulk.actions` and nested action `children` before
+editor normalization and portable persistence. Internal `__praxis*` action fields
+are runtime-only; business payloads remain intact. Collection availability preserves
+an explicit host `disabled: true`, and a temporary denial does not become an authored
+restriction when a label or order changes. Older snapshots with an ambiguous denial
+retain `disabled: true`; raw-document validation reports
+`table.action.disabled.origin.unknown`, and portable runtime projection logs that
+diagnostic. Review those older settings explicitly instead of inferring permission.
+See [the implementation evidence](test-dev/action-authoring-projection-result-2026-09-08.md).
+The toolbar editor also compares its initial and edited projections before emitting
+configuration: changing an action label must not materialize export, row-action or
+layout defaults. Untouched host settings remain inherited, while explicit control
+changes retain their derived behavior (for example, hybrid row-action display).
+The [live authoring journey](test-dev/action-authoring-live-roundtrip-2026-09-08.md)
+records the persisted-page comparison and validation.
+Action editor text belongs to the `praxisTableEditor` namespace: quick-add and selected
+action inputs have distinct label keys, and target/selection-limit controls have pt-BR
+and en-US translations. Host translators can override this chrome without changing
+the authored business action label. See [copy validation](test-dev/action-authoring-copy-2026-09-08.md).
+The JSON tab follows visual edits while its text is an untouched projection. Pending
+manual JSON, including incomplete or empty text, is preserved on document updates;
+after applying it and receiving the host acknowledgement, visual synchronization
+resumes. See the [selection-to-surface journey and regression proof](test-dev/view-action-surface-journey-2026-09-08.md).
+
 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.
 
+On remote pagination, selection is cleared and the existing `selectionChange`
+event is emitted before requesting the new page when both
+`behavior.selection.persistSelection` and `persistOnDataUpdate` are disabled
+(or omitted). Connected detail views therefore leave the previous record context
+during loading, including when that request later fails or is cancelled. Enabling
+either policy preserves the selection during loading: `persistSelection` retains
+cross-page selection, while `persistOnDataUpdate` reconciles it against the rows
+returned by the new page. Local pagination keeps its synchronous reconciliation.
+This timing change is specific to pagination; it does not redefine filter or
+sort transitions, permissions, or action availability.
+
 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.
 
+In a standalone table, the discovered native `view`/`byId` capability opens a readonly
+Dynamic Form through `surface.open`, using the canonical item read and response schema.
+Named record surfaces retain their declared identity, path and schema. Inside a CRUD host,
+native view continues to delegate through `rowAction`; explicit global actions keep precedence.
+The host must provide the surface runtime/drawer bridge and authorize the declared item and
+schema reads. The table forwards its originating injector and trigger focus only in ephemeral
+runtime context, never in authored configuration or API payloads.
+
 Collection workflow actions follow the same contract and are materialized in the toolbar. The
 table requires a row selection only when the action publishes `selection.idsField` or uses
 `SELECTION_MAP`; an unrelated current selection is never injected into a selection-independent
@@ -87,6 +150,14 @@ export class LocalTableComponent {
 
 ## Minimum Remote Runtime
 
+For discovered standalone collection create, Table suppresses disabled/denied
+actions and coalesces concurrent opening attempts for the same resource and
+surface while opening is pending. The guard is released after success or failure;
+it does not implement HTTP idempotency or prevent a later deliberate opening.
+A selected surface failure shows localized feedback and never emits a second
+toolbar action as a fallback. CRUD-hosted tables retain CRUD ownership. Diagnostics
+keep correlation and the error type, not arbitrary provider exception messages.
+
 Use `resourcePath` when the host wants the table to enter backend schema/data mode.
 
 ```html
@@ -144,6 +215,14 @@ When the collection response exposes `_links.create` or a collection `capabiliti
 
 Selector and lookup surfaces can keep the same remote `resourcePath`, schema, pagination and read capabilities while opting out of collection action materialization with `actions.collection.discovery.enabled = false`. The policy suppresses only collection actions discovered from HATEOAS/capabilities, including canonical create and collection workflows. Explicit toolbar actions and configured row actions remain unchanged. Omission preserves the default enabled behavior.
 
+## Configuration ownership in Page Builder
+
+Use the **Tabela da página** catalog preset when the page owns the table configuration. It sets the existing `configPersistenceStrategy: 'input-first'`, so an older saved `table-config` does not replace the authored input on reload. In **Configurar conteúdo**, the configuration source selector makes this choice explicit; filter edits in its **Filtros** tab belong to `config.behavior.filtering.advancedFilters.settings` and are saved with the widget/page.
+
+The runtime default remains `local-first`, which loads saved table preferences. `volatile` is intended for temporary surfaces that neither load nor save persistent table configuration. `input-first` prioritizes the input for table configuration hydration; it does not mean every independent runtime preference is disabled.
+
+The native filter **Preferências do Filtro** panel uses its own `filter-config` preference lane. Its saved always-visible order does not override a nonempty `alwaysVisibleFields` supplied by the page. Use the Page Builder content editor to author the page's filters. Editing a field opens a child settings panel and preserves the parent draft; save the child, then its parent and the page to persist authored changes.
+
 ## Runtime Inputs And Outputs
 
 Common inputs:
@@ -195,6 +274,11 @@ When row selection is enabled with `mode: "row"` or `mode: "both"`, selectable
 rows use a single roving keyboard stop. `ArrowUp`, `ArrowDown`, `Home`, and `End`
 move focus without changing the selection; `Enter` and `Space` activate the
 focused row through the same `selectionChange` contract used by pointer input.
+For the single-selection radio, native input, label and enlarged touch-target
+activation all select through Material's `change` event and emit one canonical
+selection update. Re-clicking the checked radio retains the selection. The
+existing Space shortcut on the radio can still select or clear it; checkbox and
+explicit row-toggle paths retain their own toggle behavior.
 Navigation is resolved against the table data model rather than the rows currently
 mounted in the DOM. In virtualized tables, `Home` and `End` therefore reach the
 first and last logical records and scroll the viewport before restoring focus.
@@ -266,6 +350,13 @@ Use `config.ai.assistant.enabled = false` when a host needs to disable the embed
 
 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.
 
+The no-data region follows its content height. It delegates alignment, variant,
+density and internal spacing to the shared `praxis-empty-state-card`, without
+forcing a centered transparent card or reserving viewport-based height. Existing
+`--pdx-empty-state-*` theme tokens remain available for the card; the surrounding
+table surface uses the table background and border tokens. The default
+presentation remains centered, compact and transparent.
+
 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.
 
 For related resources, the generated empty state is informational and does not repeat the capability-governed CREATE action already kept stable in the toolbar. Declare `behavior.emptyState.actions` only when the journey intentionally needs a distinct contextual action; explicit host actions are preserved. Empty-state and toolbar actions share the public `--praxis-action-control-*` geometry, while `toolbar.appearance.tokens.actionSize` and `actionRadius` remain the stronger per-table overrides.
@@ -286,6 +377,16 @@ const config: TableConfig = {
 
 ## Toolbar Appearance
 
+When a containing Widget Shell already owns the title and resource identity, omit
+the table's `toolbar.title`, `toolbar.subtitle`, and `toolbar.icon` and keep
+`toolbar: { visible: true }`. The toolbar can render commands without its identity
+block. Do not use `visible: false` to deduplicate headings: resource discovery may
+materialize a capability-governed CREATE action and make the toolbar visible.
+Preserve those actions, their availability, and their accessible disabled reasons.
+For nested compositions, bind the shell identity to the propagated canonical
+resource identity and verify it after selection changes and in fullscreen; matching
+configuration alone does not prove that the correct record is presented.
+
 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
@@ -315,6 +416,11 @@ commands are consolidated under one localized `Mais ações` entrypoint without
 density controls. At narrow widths the first band preserves identity and commands before the scope and
 query bands, so keyboard focus follows the same reading order presented visually.
 
+At up to 540 px of toolbar width, identity and the compact command menu share a
+row when no scope region is present; query controls keep their full-width row.
+With scope present, the existing separate bands remain. Long identities retain
+the existing truncation/tooltip behavior rather than overlapping the menu.
+
 Authoring guidance:
 
 - use `toolbar.filters.quickFilters` for a small governed scope switch, not as a substitute for every filter;
@@ -353,6 +459,11 @@ The package exports both the table runtime and `PraxisFilter` integration surfac
   `aria-disabled="true"`, keep execution fail-closed, and announce the contextual disabled reason before
   the configured operation tooltip. In the compact overflow menu, the same reason is rendered inline so
   understanding the unavailable command never depends on hovering or focusing a native disabled menu item.
+- When runtime discovery publishes a denied capability, workflow action or surface, toolbar explanations
+  use its canonical availability reason from Core’s `resourceDiscovery` translations. Authentication and
+  permission denials take precedence over selection guidance. Table locale and host translation overrides
+  remain supported; unknown codes use the generic canonical message rather than exposing internal codes.
+  An available form surface does not override a denied create operation. This copy does not grant permission.
 - 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
@@ -375,14 +486,18 @@ control when the operating system displays the thumb. Because the manager render
 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
+default to the Portuguese runtime labels. The trigger count includes fixed and selected filters.
+Inside the manager, **Campos fixos**, **Campos selecionados** and **Campos disponíveis** state the
+three distinct roles; the selected-section summary counts only the customizable selection. Its
+`selectedFieldsCount` and `selectedFieldsCountSingular` text remains overridable through the same
+i18n input. 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
+had when the draft began. Checkbox state, the selected-field summary, 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`,
@@ -415,6 +530,25 @@ const config: TableConfig = {
 
 Use `PraxisTableConfigEditor` or the table settings surfaces when `enableCustomization` is true.
 
+For `surface.open` actions, invalid input/context JSON remains an unsaved draft:
+the owning editor combines the subeditor's `validationChange` with its other
+validation sources and blocks Apply/Save. Switching tabs preserves the draft;
+correct it or use Cancel/discard before switching or replacing actions. Raw invalid
+text is never included in the settings document. See the
+[Core validation evidence and rollout boundary](../praxis-core/docs/surface-invalid-drafts-validation-2026-09-08.md).
+
+In **Overview and behavior → Narrow screens** (Portuguese: **Visão geral e
+comportamento → Telas estreitas**), choose **Cards** and set the maximum width in
+pixels. The native editor and the Page Builder content editor use the existing
+`appearance.responsive.mobile.cardMode` and `appearance.responsive.breakpoints.mobile`
+properties. Missing width defaults to 768 px. The control accepts positive whole
+numbers; invalid drafts block apply/save without replacing the last valid document.
+Switching back to Table keeps other responsive preferences and column priorities.
+Cards retain visible fields, row selection and actions; virtualization keeps the
+standard table renderer. Selection still follows the authored connections and does
+not implicitly navigate to an offscreen detail widget.
+
+
 Main authoring areas include:
 
 - columns
@@ -426,6 +560,8 @@ Main authoring areas include:
 - value mapping
 - JSON config editing
 
+The runtime loads `PraxisTableConfigEditor` only when `openTableSettings()` reaches the native table authoring flow. Rendering a table does not eagerly materialize the editor chunk; delegated CRUD authoring also returns before that chunk is requested.
+
 The package exports separate governed contracts for the two authoring documents: `PRAXIS_TABLE_AUTHORING_MANIFEST` owns `TableConfig`, including embedded filtering under `behavior.filtering`, while `PRAXIS_FILTER_AUTHORING_MANIFEST` owns the standalone `FilterConfig`. The standalone manifest never persists the controlled `value` DTO and does not expose Table query-builder operations or the nominal `submit` alias. `TABLE_AI_CAPABILITIES` / `TABLE_COMPONENT_AI_CAPABILITIES` remain the component capability discovery surface for the Table aggregate.
 
 Canonical table refinements preserve business meaning across preview, persistence, reopen and runtime rendering:
@@ -482,3 +618,55 @@ Main exports:
 - 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.
+
+### Authoring de tabela e filtro no Page Builder
+
+O editor de conteúdo da tabela recebe a configuração efetiva em contexto transitório. Ao salvar, aplica apenas as mudanças autoradas, preservando paginação e renderizadores derivados do schema. Essa projeção não é copiada integralmente para o documento.
+
+O editor do filtro permite selecionar o recurso e carregar seus campos pelo schema de filtro canônico. `resourcePath` e preferências visuais são persistidos; os metadados carregados permanecem derivados da API.
+
+Ao receber novos `filterCriteria` ou `queryContext` de outro widget, a consulta remota reinicia na página zero. Para um recurso paginado, selecione estratégia de paginação `server` no editor; a estratégia cliente continua sendo uma opção explícita para dados locais.
+
+## Filter heading and advanced-action presentation
+
+Tables and standalone filters share Core `FilterPresentationConfig`. Configure an optional heading above or inline with the filters and present the advanced action as icon, text, or both. Heading visibility is opt-in; omitting presentation preserves the existing appearance. Action placement stays within the auxiliary controls group. It does not move table actions or change filter values.
+
+For tables use `config.behavior.filtering.advancedFilters.settings.presentation`; for standalone filters use `FilterConfig.presentation` (runtime input `presentation`). The guided editor exposes semantic choices, while the optional nine `--pfx-filter-*` tokens support theme customization. See [the canonical JSON API](src/lib/praxis-table.json-api.md#filter-presentation) for the exact fields, defaults and token list.
+
+When filter persistence is enabled, a presentation acknowledged by **Save and close** is restored over the authored page baseline for the same component identity. **Apply** changes only the current preview. Set `disablePersistence` when the host must always materialize the authored input and must not read or write user filter preferences.
+
+The preferences editor carries the complete effective filter document through Apply and Save. Editing presentation, layout or behavior therefore preserves `selectedFieldIds` and metadata overrides owned by the same preference record.
+
+
+## Ciclo de vida dos editores do filtro
+
+Os painéis de preferências e de metadados são vinculados ao `DestroyRef` da origem
+pelo contrato `owner` do Settings Panel. Remover a origem encerra seus painéis e
+as assinaturas de Apply/Save. Um carregamento lazy concluído após a destruição
+do pai não abre um editor filho. O host deve destruir efetivamente o componente
+quando sua origem deixa de existir, em vez de apenas ocultá-lo por CSS.
+
+Salvar metadados no editor filho altera o rascunho do pai; a gravação da configuração
+continua pertencendo ao fluxo de Save do filtro. Destruir a origem não inicia Save
+e não implica cancelar requisições de gravação já iniciadas legitimamente.
+
+
+### Confirmação de Save nas preferências do filtro
+
+O painel aguarda a conclusão do storage antes de fechar. Apply permanece uma
+prévia sem gravação; erros de Save mantêm o rascunho aberto para nova tentativa.
+Conflitos 409/412 não são sobrescritos automaticamente. Alterações feitas durante
+uma requisição também permanecem abertas após a confirmação da versão enviada.
+O cache local de FilterConfigService é atualizado ou removido somente após sucesso
+de Save/Clear. A garantia corresponde ao storage configurado: o adapter local não
+constitui confirmação de gravação no backend.
+
+
+### Navegação em painéis estreitos
+
+A adaptação de authoring considera a largura do contêiner, inclusive quando o
+painel é estreito em uma janela desktop. Table e Dynamic Form exibem “Seção do
+editor” até 768px de largura disponível, mantendo a mesma seleção e os conteúdos
+das abas. Acima desse limite, reaparece a navegação por abas. O Settings Panel
+organiza título, expandir e fechar em uma grade até 599px; a prévia, quando
+suportada, ocupa a linha seguinte. Nenhum documento ou protocolo de Save é alterado.