Define semantic page action layouts
This commit is contained in:
@@ -17,6 +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 |
|
||||
| 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 |
|
||||
|
||||
@@ -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.
|
||||
@@ -57,6 +57,7 @@ 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 |
|
||||
|
||||
## Confirmed Implementation Decisions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user