# 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.