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