feat(webui): govern actions, quick access, and metrics

Refs #264, #285, #289

docs/INTERFACE_PATTERN_MIGRATION.md

@@ -17,12 +17,12 @@ domain modules own their compositions.
 | Full-canvas workspace | Navigation/content and list/detail canvases that own pane geometry and scrolling | Navigation and split variants, primary-pane width, pane-owned or contained scrolling, responsive stacking or navigation collapse, pane labels, and contextual-help identity are centralized without encoding domain navigation | `WorkspaceLayout.tsx`, `workspace-layout.test.tsx`, Core Settings, Access administration, Docs, Organizations, Campaign, Templates, Approvals, and `check-shared-webui-layouts.py`; the raw-workspace exception baseline is empty |
 | Full-height module frame | Outer module landmark and viewport/container sizing | `WorkspaceFrame` centralizes surface, overflow, box sizing, accessible naming, help identity, and application-viewport height so modules do not copy the `100vh - shell` frame | `WorkspaceFrame.tsx`, `layout-primitives.test.tsx`, Dataflow, Workflow, Datasources, Distribution Lists, Notifications, Tasks, Scheduling, Forms, Portal, Projects, Records, and Reporting |
 | Responsive action toolbar | Domain-neutral action and filter grouping for pages, workspaces, editors, and overlays | Density, surface, grouping, flexible space, accessible naming, toolbar help identity, and responsive wrapping are centralized while modules retain action wording, authority, and consequence | `ActionToolbar.tsx`, `layout-primitives.test.tsx`, WYSIWYG, Calendar, Files, Forms, Templates, and the product-wide primitive check |
-| Semantic page archetypes and action bar | Overview, collection, detail, editor, and workspace intent declared independently from frame geometry and composed over the responsive toolbar | Refreshable pages require leading Reload; editor persistence owns clean/dirty/saving feedback, guarded Discard and far-right Save; destructive actions occupy an explicit separated slot; read-only pages do not invent Save | `PageLayout.tsx`, `PageActionBar.tsx`, `PAGE_LAYOUT_USAGE_GUIDELINES.md`, component and browser conformance, every headed product page, and `check-shared-webui-layouts.py` |
+| Semantic page and pane action bars | Overview, collection, detail, editor, and workspace intent declared independently from frame geometry; full-canvas panes add workspace/collection/detail/editor scope | Core renders leading Reload from a guarded descriptor; editor persistence owns clean, dirty, invalid, saving, failed, and conflict feedback plus guarded Discard and far-right Save; destructive actions occupy an explicit named boundary; read-only surfaces do not invent Save | `PageActionBar.tsx`, `WorkspaceActionBar.tsx`, `PAGE_LAYOUT_USAGE_GUIDELINES.md`, component and browser conformance, every headed page and full-canvas workspace, and the discovery-based `check-shared-webui-layouts.py` |
 | Catalogue and state composition | Search/filter bars, selectable navigation lists, count badges, and empty/blocked/error panels | Width, surface, wrap, selection geometry, title/description truncation, numeric emphasis, state sizing, tone and action placement are centralized; modules retain query behavior, object state and consequences | `FilterBar.tsx`, `SelectionList.tsx`, `CountBadge.tsx`, `StatePanel.tsx`, `layout-primitives.test.tsx`, and list/detail modules across Cases, Committee, Dataflow, Forms, Notifications, Portal, Postbox, Projects, Records, Reporting, Tasks, Templates, and Workflow |
 | Content and form grids | Equal-column content, field, and native-form geometry | Explicit 1–4 columns, standard gaps, item spans, alignment, and named narrow/workspace/standard/wide collapse points replace generic and module-prefixed copies; unequal domain tracks remain local | `ContentGrid.tsx`, `layout-primitives.test.tsx`, Core dashboard/settings/mail, Calendar dialogs, Forms editor, Datasources, Postbox, Campaign, administration surfaces, and the product-wide primitive check |
 | Content sections | Repeated editor/detail section surfaces | Border, surface, compact/default density, stacked flow and block rhythm are centralized without encoding section contents | `ContentSection.tsx`, `layout-primitives.test.tsx`, Datasources, Distribution Lists, Templates, Dataflow, and Workflow |
 | Form sections | Reusable heading/description/action/content grouping inside forms | Plain, separated, and panel variants centralize hierarchy and narrow action placement without moving validation, permissions, values, or domain wording into Core | `FormSection.tsx`, `layout-primitives.test.tsx`, Addresses contact editing, and Quick Access preferences |
-| Metric groups | Reusable responsive grouping around metric cards | Fixed one-to-five and auto-fit columns, minimum card widths, density, block/inset/zero spacing, and named collapse points replace the product-wide `metric-grid` class and cross-module dashboard overrides | `MetricGrid.tsx`, `MetricCard.tsx`, `layout-primitives.test.tsx`, Core and Dashboard summaries, administration, Campaign, Ops, Files, Search, and dashboard widgets |
+| Metric groups and drill-downs | Reusable responsive grouping around metric cards with an explicit optional detail affordance | Fixed one-to-five and auto-fit columns, minimum card widths, density, block/inset/zero spacing, and named collapse points replace the product-wide `metric-grid` class and cross-module dashboard overrides; typed link or in-page drill-downs name their destination while summary-only, non-enumerable, derived, or privacy-suppressed values remain inert | `MetricGrid.tsx`, `MetricCard.tsx`, `metric-card.test.tsx`, `layout-primitives.test.tsx`, Core and Dashboard summaries, administration, Campaign, Ops, Files, Search, and dashboard widgets |
 | Description lists | Semantic property and fact presentation | Stacked and inline variants, one-to-five list columns, density, term width, wrapping, and responsive collapse replace both `admin-details-grid` and `detail-list`; `DescriptionItem` preserves native `dt`/`dd` anatomy | `DescriptionList.tsx`, `layout-primitives.test.tsx`, Access and Tenancy administration, Audit, Policy, Campaign reports/imports, Docs, Settings, Ops, and Reporting |
 | Dialog anatomy | Shared outer dialog plus composable body and footer regions | Size and administration variants, body padding, descriptions, notices, fixed action wrapping, native form flow, and section grouping are centralized; focus trapping and stack lifecycle remain unchanged | `Dialog.tsx`, `DialogAnatomy.tsx`, `dialog-focus.test.tsx`, `layout-primitives.test.tsx`, Addresses, Calendar, Records, Datasources, Distribution Lists, Files, and Templates |
 | Definition-editor visuals | Reusable graph palette, canvas chrome, node icon/port geometry, empty overlay and floating activity state | Core owns visual and responsive anatomy while node/edge types, validation, execution, provenance and workflow semantics remain in Dataflow or Workflow | `DefinitionPalette.tsx`, `DefinitionNodeIcon.tsx`, `FloatingStatus.tsx`, shared definition styles, Dataflow and Workflow structure/build checks |
@@ -48,4 +48,6 @@ chrome. Retired copies and module-local component definitions are rejected by
 `check-shared-webui-primitives.py`. That check also requires standard dialog
 widths to use `Dialog size` and keeps every remaining domain-specific width in
 a reviewed, decrease-only exception baseline. The companion layout check now
-has zero raw page-frame and zero raw workspace exceptions.
+has zero raw page-frame and zero raw workspace exceptions, discovers semantic
+consumers without a hand-maintained route list, requires semantic action bars
+on `WorkspaceFrame` routes, and rejects ad-hoc panel-header toolbars.

docs/PAGE_LAYOUT_USAGE_GUIDELINES.md

@@ -35,9 +35,13 @@ filter is editable.
 
 ## Page Action Rules
 
-Pass one `PageActionBar` to the `PageLayout` `actions` slot. The variant makes
-the page's intent inspectable and preserves the same keyboard and visual order
-across modules.
+Pass one `PageActionBar` to the `PageLayout` `actions` slot. Full-canvas
+workspaces use the same contract through `WorkspaceActionBar`, with an explicit
+`workspace`, `collection-pane`, `detail-pane`, or `editor-pane` scope. The
+variant makes the surface's intent inspectable and preserves the same keyboard
+and visual order across modules. `ActionToolbar` remains the lower-level
+component for section-local controls; it is not a substitute for a semantic
+page or pane action bar.
 
 | Page kind | Leading group | Trailing group |
 | --- | --- | --- |
@@ -55,14 +59,24 @@ persistent side panel. Save is present only where the page owns an editable
 draft; a read-only detail page must not display a disabled or inert Save merely
 to fill the slot.
 
-Editor bars always keep Discard and Save visible. They expose `clean`, `dirty`,
-and `saving` status through a live status label. In the clean or saving state,
-the central component disables both persistence actions and supplies the
-standard explanation. A module may add a more specific validation, policy, or
-permission blocker while the draft is dirty. The editor must register its
-draft with `useUnsavedDraftGuard` (or a shared hook that uses the same
-registration contract), so browser unload, route navigation, section changes,
-and the explicit Discard path cannot silently lose work.
+Editor bars always keep Discard and Save visible. Their required `state`
+projection is one of `clean`, `dirty`, `invalid`, `saving`, `save-failed`, or
+`conflict`, and the central component announces it through a live status label.
+Clean and saving states disable both persistence actions; invalid disables Save
+while retaining Discard. Failed saves and conflicts keep the draft recoverable
+and allow an authorized retry after the module has shown the owning error or
+conflict evidence. A module may add a more specific validation, policy, or
+permission blocker. The editor must register its draft with
+`useUnsavedDraftGuard` (or a shared hook that uses the same registration
+contract), so browser unload, route navigation, section changes, Reload, and
+the explicit Discard path cannot silently lose work.
+
+Reload is rendered by Core from a descriptor rather than passed as arbitrary
+button markup. It can project `current`, `stale`, `reloading`, or
+`reload-failed`; `loading` is the shorthand for `reloading`. A failed refresh
+must preserve usable loaded data, expose its stale/failure state, and leave
+Reload available for recovery. Reload goes through the same unsaved-navigation
+guard as route changes.
 
 Destructive page actions use `destructiveActions`; never put a danger action in
 `contextActions` or the ordinary primary group. Core renders a persistent
@@ -95,17 +109,26 @@ silently hide a normally applicable action.
 - Use `MetricGrid`/`MetricCard` for summary measures, `Card` or
   `ContentSection` for logical sections, and `DescriptionList` for labelled
   facts.
+- Add a `MetricCard.drilldown` only when the displayed measure has a useful,
+  authorized underlying collection or detail. Name the destination explicitly
+  (for example, “Review failed deliveries”) and preserve the current scope and
+  filters in its `href` or action. The card itself remains non-interactive so
+  the action is visible and keyboard-predictable. Derived, privacy-suppressed,
+  non-enumerable, or purely informational aggregates remain plain metrics;
+  when an ordinarily available drill-down is temporarily blocked, keep its
+  action and provide `disabledReason`.
 - Preserve loaded data after a refresh failure and mark it stale; offer Reload
   as the recovery action. Distinguish initial loading, empty, unavailable,
   permission-blocked, conflict, success, and retry states.
 
 ## Review Evidence
 
-Every new or changed page must have structural evidence for its page frame,
-semantic archetype and slot order, refresh declaration, shared component
-usage, stable disabled actions, dirty guard, destructive boundary, and
-module-owned help identity. Type checks enforce conditional Reload and editor
-persistence props. Product checks reject undeclared archetypes and ad-hoc
-headed action fragments. Browser conformance confirms keyboard order, live
-dirty-state changes, accessibility, destructive separation, narrow wrapping,
-and screenshot geometry.
+Every new or changed page or workspace pane must have structural evidence for
+its frame, semantic archetype/scope and slot order, refresh declaration, shared
+component usage, stable disabled actions, dirty guard, destructive boundary,
+and module-owned help identity. Type checks enforce conditional Reload and
+editor persistence props. The product check discovers all consumers, rejects
+undeclared archetypes and `ActionToolbar` panel-header copies, and requires
+semantic actions for every `WorkspaceFrame` route. Browser conformance confirms
+keyboard order, lifecycle changes, accessibility, destructive separation,
+narrow wrapping, and screenshot geometry.