Define semantic page archetypes

docs/INTERFACE_PATTERN_MIGRATION.md

@@ -17,7 +17,7 @@ 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 action bar | Named collection, detail, and editor action placement composed over the responsive toolbar | Reload stays leading; collection Create, editor Save, and detail consequences occupy stable trailing slots; read-only pages do not invent Save; modules retain wording, permissions, blockers, and effects | `PageActionBar.tsx`, `PAGE_LAYOUT_USAGE_GUIDELINES.md`, `layout-primitives.test.tsx`, Payments, 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` |
 | 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 |

docs/PAGE_LAYOUT_USAGE_GUIDELINES.md

@@ -7,6 +7,8 @@ wording, authorization, consequences, and data state.
 ## Required Page Frame
 
 - Use `PageLayout` for every headed standalone, workspace, or embedded page.
+- Declare exactly one semantic `archetype`; do not infer page intent from the
+  `mode`, which controls geometry and scroll ownership only.
 - Use `WorkspaceFrame` for a full-height module surface and
   `WorkspaceLayout` only where navigation/content or list/detail panes are
   genuinely part of the interaction.
@@ -16,7 +18,22 @@ wording, authorization, consequences, and data state.
 - Do not reproduce shared page padding, heading, toolbar, form-grid, section,
   table, dialog, or breakpoint CSS in a module.
 
-## Page Action Archetypes
+## Semantic Page Archetypes
+
+| Archetype | Use when |
+| --- | --- |
+| `overview` | The page summarizes health, metrics, or several peer areas without owning one primary collection or draft. |
+| `collection` | The primary object is a searchable/listable collection and Create, when available, applies to that collection. |
+| `detail` | The page primarily presents one record, report, or immutable projection. |
+| `editor` | The page owns one explicit draft with Save and Discard behavior. |
+| `workspace` | The page coordinates several panes, stages, or task-local operations that cannot honestly be reduced to one record or draft. |
+
+The archetype remains stable for the current interaction. A page may switch
+from `overview` to `editor` when the user explicitly enters configuration
+mode. It must not call a page an editor merely because a dialog or an inline
+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
@@ -24,17 +41,36 @@ across modules.
 
 | Page kind | Leading group | Trailing group |
 | --- | --- | --- |
-| Collection | Reload, then collection context such as export | Help, then Create at the far right |
-| Detail | Reload, then object context | Help, ordinary primary actions, then consequential actions |
-| Editor | Reload, then editor context such as preview | Help, Discard, then Save at the far right |
+| Overview | Reload when refreshable, then context | Help, then ordinary primary actions |
+| Collection | Reload when refreshable, then collection context such as export | Help, then Create at the far right |
+| Detail | Reload when refreshable, then object context | Help, ordinary primary actions, then a separated destructive group |
+| Editor | Reload only when refresh is a distinct safe operation, then context | Dirty state, Help, ordinary primary actions, separated destructive actions, Discard, then Save at the far right |
+| Workspace | Reload when the coordinated projection can become stale, then task context | Help, ordinary primary actions, then a separated destructive group |
 
-Reload means re-fetch or re-evaluate the current surface. It remains present
-when the page can become stale. Create is a collection-wide action and is not
-duplicated in a 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.
+Reload means re-fetch or re-evaluate the current surface. A page declaring
+`refreshable` must provide it, and a non-refreshable page must not use Reload as
+a synonym for Cancel, Reset, or Discard. Reload never silently destroys a dirty
+draft. Create is a collection-wide action and is not duplicated in a
+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.
 
-`PageActionBar` controls placement only. Actions continue to use central
+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.
+
+Destructive page actions use `destructiveActions`; never put a danger action in
+`contextActions` or the ordinary primary group. Core renders a persistent
+visual and semantic boundary before this group. In an editor it precedes the
+Discard/Save pair, keeping Save in the final keyboard and visual position.
+
+`PageActionBar` controls non-editor placement and owns the standard editor
+persistence buttons. Other actions continue to use central
 `Button`, `IconButton`, or `TableActionGroup` components. When an action is
 visible but unavailable because of permission, target, policy, state, or
 validation, keep it in its stable slot and supply `disabledReason`. Do not
@@ -65,8 +101,11 @@ silently hide a normally applicable action.
 
 ## Review Evidence
 
-Every new or changed page should have structural evidence for its page frame,
-semantic action archetype and slot order, shared component usage, stable
-disabled actions, and module-owned help identity. Keyboard and narrow-layout
-checks must confirm that all commands remain reachable in DOM order and that
-the trailing group stays visually trailing after wrapping.
+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.

docs/UI_UX_DECISION_LEDGER.md

@@ -57,7 +57,8 @@ contestability, responsibility, and traceability at the point of action.
 | UX-031 | Public controls and extension contributions use stable, module-namespaced interface identities. Shared controls expose `interfaceId` and `helpTopicId`; generated source anchors are inventory evidence, not a substitute for an explicit ID when documentation, policy, or automation refers to the control. | Accepted | Core and module WebUIs |
 | UX-032 | `F1` resolves help from the focused field or action, then its dialog/section/page and registered route. Focused contexts retain the page fallback; Docs applies audience and permission filtering and falls back to visible module documentation. | Accepted | Core shell, Docs, and all module WebUIs |
 | UX-033 | Global search is the left-most titlebar command, immediately before language selection. Its icon, `F3`, and `Ctrl`/`Cmd`+`K` all open the same permission-aware search overlay; the titlebar does not reserve a persistent query field. | Accepted | Core shell and Search WebUI |
-| UX-034 | Headed pages use the semantic `PageActionBar` slots instead of arranging primary page actions ad hoc. Collections place Reload in the leading group and Create at the far right; details place Reload first and contextual, primary, then consequential actions in stable groups; editors place Reload first and Discard immediately before the far-right Save. Read-only pages do not invent a meaningless Save action, and unavailable actions retain shared actionable blocker explanations. | Accepted | Core and all module WebUIs |
+| UX-034 | Every headed `PageLayout` declares one of `overview`, `collection`, `detail`, `editor`, or `workspace` independently from its standalone/workspace/embedded geometry. Its actions use the matching semantic `PageActionBar`: a refreshable page must provide Reload in the leading slot; collections keep Create far right; read-only pages do not invent Save. | Accepted | Core and all module WebUIs |
+| UX-035 | Editor action bars expose clean, dirty, and saving state; always retain Discard immediately before the far-right Save; centrally disable both while clean or saving; and participate in the unsaved-change navigation guard. Danger actions occupy the explicit separated destructive group after ordinary actions and before editor persistence. | Accepted | Core and all module WebUIs |
 
 ## Confirmed Implementation Decisions