Define semantic page action layouts

2026-08-19 13:33:51 +02:00
parent 5a2e99f496
commit c042244da8
18 changed files with 306 additions and 10 deletions
@@ -0,0 +1,72 @@
+# Page Layout and Action Guidelines
+
+This document defines the binding composition grammar for headed GovOPlaN
+pages. Core owns the reusable anatomy; each module owns its domain actions,
+wording, authorization, consequences, and data state.
+
+## Required Page Frame
+
+- Use `PageLayout` for every headed standalone, workspace, or embedded page.
+- Use `WorkspaceFrame` for a full-height module surface and
+  `WorkspaceLayout` only where navigation/content or list/detail panes are
+  genuinely part of the interaction.
+- Put page-wide feedback in `PageLayout` notices. Use `DismissibleAlert` for a
+  recoverable warning or failure and `StatePanel` when the entire surface is
+  loading, empty, unavailable, or blocked.
+- Do not reproduce shared page padding, heading, toolbar, form-grid, section,
+  table, dialog, or breakpoint CSS in a module.
+
+## Page Action Archetypes
+
+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.
+
+| 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 |
+
+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.
+
+`PageActionBar` controls placement only. 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
+silently hide a normally applicable action.
+
+## Forms and Dialogs
+
+- Compose forms from `FormLayout`/`FormGrid`, `FormSection`, and `FormField`.
+- Use `FieldLabel` through `FormField` for every field that is not genuinely
+  self-explanatory; record justified omissions in the owning UI ledger.
+- Use `Dialog`, `DialogForm`, `DialogSection`, and `DialogActions` for modal
+  work. A dialog can be domain-specific while its anatomy remains central.
+- Use `useUnsavedDraftGuard` for explicit Discard and guarded navigation on an
+  editable page or dialog.
+- Explain irreversible or operationally consequential actions before the
+  commit button, including reversibility and durable evidence.
+
+## Collections and Details
+
+- Use `FilterBar` for collection query controls and `DataGrid` for tabular
+  collections. Keep a single ordered `TableActionGroup` action set per table.
+- Use `MetricGrid`/`MetricCard` for summary measures, `Card` or
+  `ContentSection` for logical sections, and `DescriptionList` for labelled
+  facts.
+- 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 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.