govoplan-core/docs/INTERFACE_PATTERN_MIGRATION.md

Core Interface Pattern Migration

This document records the Core-owned part of the product-wide interface pattern-language rollout. The normative product grammar and complete route inventory live in the govoplan meta repository. Core owns reusable behavior; domain modules own their compositions.

Core Surfaces

Surface	Pattern	Consequence and provenance contract	Evidence
User settings	Two-zone settings workspace with typed controls and unsaved-change protection	Save actions distinguish busy, unchanged, and test-in-progress states; contextual help resolves through Docs or the hosted fallback	SettingsPage.tsx, test-core-interface-patterns.mjs
Reusable credentials	Repeated administration with an adaptive create/edit dialog, optional password generator, and destructive confirmation	Secret values are write-only; generated candidates use the browser cryptographic API without a weak fallback and do not replace the field until explicitly confirmed; scope/permission blockers name the required action, responsible actor, and destination; unavailable row actions remain keyboard-explainable	CredentialEnvelopeManager.tsx, shared PasswordField, PasswordGeneratorDialog, ActionBlockerHint, Button, TableActionGroup, and ConfirmDialog
Retention policy	Effective-policy editor with inherited source paths and typed, narrowing-only controls	Parent locks and missing write authority are explicit; the save action distinguishes locks, missing target, loading, clean draft, and active save	RetentionPolicyManagement.tsx, policy logic tests, test-core-interface-patterns.mjs
Module lifecycle	Guided operator projection over durable installer-queue evidence	Preflight, handoff, progress, stale evidence, recovery, and rollback consequences remain visible	Admin module lifecycle tests and the Core installer-queue contract
Shared page frame	Domain-neutral headed page layout used by Core and optional modules	Standalone, workspace, and embedded modes make inset and scroll ownership explicit; sticky heading, rich descriptions, route actions, notices, loading, narrow-layout collapse, and contextual-help identity are centralized; AdminPageLayout composes the same contract	PageLayout.tsx, page-layout.test.tsx, Core fallback dashboard, Dashboard module, Ops module, Campaign pages, and check-shared-webui-layouts.py
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, Campaign workspace, Campaign module workspace, Templates workspace, Approvals list/detail workspace, and check-shared-webui-layouts.py
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
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
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
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
Shared configuration primitives	Cross-module component contract	Dialog focus, blocker structure, disabled-action focus, route/page/field/action F1 help, unsaved changes, confirmation, loading, alerts, problem lists, and policy provenance are centralized	Core component tests, CONTEXTUAL_HELP_CONTRACT.md, and module-permutation build

Boundary

Files and Mail are the first two external consumers of the layered server/credential/policy pattern. Their own repositories retain provider discovery, transport behavior, authorization, and migration evidence. Remaining module surfaces are tracked by bounded module-owned issues under GovOPlaN #11; they are not reasons to add sibling-private behavior to Core.

Raw JSON remains permitted only for diagnostics, expert inspection, interchange, or conflict evidence. It is not a primary Core configuration editor.

Raw page-frame and full-canvas workspace debt is registered in the meta repository and may only decrease. New headed pages use PageLayout; pages inside WorkspaceLayout use its workspace mode so the pane owns scrolling while the page retains the standard inset. Module CSS continues to own domain content layout, never the shared page or workspace frame. Raw toolbar tags, retired generic grid and description-list classes, raw dialog-form wrappers, and module-local copies of the shared toolbar/grid/form-section/dialog-anatomy components 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.