@praxisui/table 9.0.5-rc.2 → 9.0.5-rc.20

package/README.md

@@ -216,6 +216,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 +246,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 +296,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