@praxisui/table 9.0.5-rc.8 → 9.0.5

package/README.md

@@ -11,8 +11,11 @@ the backend-authored refresh policy after success. Hosts should not recreate the
 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
+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
+collection command, remains selected after completion, and the lifecycle is emitted as a
+`toolbarAction` rather than a bulk operation. For selection-bound actions it enforces the published 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
@@ -137,6 +140,8 @@ Optional collection operations such as export are not implied by a base route. E
 
 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.
 
+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.
+
 ## Runtime Inputs And Outputs
 
 Common inputs:
@@ -216,6 +221,8 @@ Use `behavior.emptyState` for table-owned no-data copy and presentation. `messag
 
 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.
+
 ```ts
 const config: TableConfig = {
   behavior: {
@@ -244,6 +251,44 @@ const config: TableConfig = {
 };
 ```
 
+### Adaptive toolbar composition
+
+`PraxisTableToolbar` materializes the toolbar as semantic regions rather than one wrapping row:
+
+- **identity** — title, subtitle and table context;
+- **scope** — a small, mutually exclusive and removable set of governed quick filters;
+- **query** — always-visible dynamic filters and projected query shortcuts;
+- **commands** — collection/business actions, table utilities and authoring entrypoints.
+
+The runtime owns the responsive composition through container queries. This is important when a table
+is rendered inside a drawer, split pane or dashboard card: behavior follows the width actually available
+to the table, not only the browser viewport. At wide widths, identity and commands share the first band,
+while scope and query share a stable second band. At compact widths, the regions move as complete units and
+commands are consolidated under one localized `Mais ações` entrypoint without losing export, column or
+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.
+
+Authoring guidance:
+
+- use `toolbar.filters.quickFilters` for a small governed scope switch, not as a substitute for every filter;
+  one quick filter can be active at a time, and activating the current item again restores the previous criteria;
+- use `advancedFilters.settings.alwaysVisibleFields` for frequent editable criteria;
+- keep one clear collection/business action primary; export, columns and density are utilities;
+- project custom shortcuts through the toolbar slots, but do not target internal layout classes from the host;
+- validate the component container at `1440`, `1024`, `768`, `480` and `320` px, including long localized labels, zoom and keyboard focus.
+
+Adding supported filters or actions never requires a host breakpoint. When the command set grows, the compact
+menu preserves capability parity and keyboard order. Projected query shortcuts are grouped by the runtime,
+receive a bounded width budget and wrap as one semantic cluster; projected controls must remain intrinsically
+shrinkable and must not declare a fixed minimum width larger than their slot. Hosts must not rely on internal
+selectors to position them. The query region remains independently scroll-free at the page level.
+
+The existing `toolbar.layout` fields are materialized by the same runtime: `alignment` aligns the identity
+and command regions, `padding` and `backgroundColor` project governed chrome, `height` defines the minimum
+toolbar height, and `showSeparator` adds the boundary with the data surface. `toolbar.appearance.tokens.bg`
+remains the most specific background override, followed by `toolbar.layout.backgroundColor` and the legacy
+`actionsBackgroundColor` projection.
+
 ## Filtering And Row Actions
 
 The package exports both the table runtime and `PraxisFilter` integration surfaces.
@@ -256,6 +301,11 @@ The package exports both the table runtime and `PraxisFilter` integration surfac
   availability; transient errors and missing discovered operations fail closed. Actions with an
   explicit `globalAction` or `recordSurface` remain governed by that declared execution contract.
 - `visibleWhen` and `disabledWhen` use canonical JSON Logic.
+- Toolbar actions that are unavailable because of selection cardinality, `disabledWhen`, or an explicit
+  disabled state remain visually recognizable and keyboard focusable in the full toolbar. They expose
+  `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.
 - 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