govoplan-mail/docs/INTERFACE_PATTERN_MIGRATION.md

Mail Interface Pattern Migration

This inventory records the Mail-owned part of the GovOPlaN interface pattern language. Core owns the shell and shared components; Mail owns the transport, mailbox, policy, and delivery-evidence consequences described here.

Surface inventory

Surface	Primary task	Archetype	Consequence	Pattern evidence
/mail folder, message, and preview panes	Browse and inspect an authorized mailbox without changing provider state	Directory/explorer	Medium because message metadata and content are private, although navigation is read-only	Full-height three-pane workspace, bounded paging, stable keyboard selection, contextual Help Center link, explicit no-profile blocker
/mail toolbar, page filter, and pagination	Select a profile, refresh the current bounded mailbox context, and find a message	Explorer actions and local filtering	Low for refresh; medium for provider access	Persistent WorkspaceFrame/WorkspaceActionBar keeps one right-aligned Reload; shared FormField profile selection; labelled Mailbox tools Dialog groups targeted refreshes and related diagnostics through FormSection; loading/profile/folder/permission blockers remain visible
System/tenant/group/user/campaign profile surfaces	Compare profiles, protocol servers, reusable credentials, status, and scope	Administration/configuration	High because endpoints, credentials, and inheritance control external communication	Shared ConnectionTree, stable row actions, textual status, permission/target blockers, and contextual admin help
Profile creation and focused profile/server/credential editors	Create a governed transport identity or edit one hierarchy object	Guided setup plus adaptive create/edit	High because saving may enable provider access or replace encrypted credentials	Shared Dialog and StageRail for multi-object setup; focused edit modes show only the selected hierarchy object; field help, connection tests, unsaved-draft guard, and disabled-save reasons
Mail profile policy card	Narrow visible profiles, lower-scope definitions, hosts, senders, and recipients	Effective-policy editor	High because inherited allow/deny rules govern delivery and lower scopes	Shared policy rows, typed selectors, source path, locked/read-only blocker, dirty-save state, and contextual policy help
/mail/bounces watcher table	Configure bounded IMAP evidence sources and run an explicit scan	Operational administration	High because it accesses a provider mailbox and changes durable evidence cursors	Shared PageLayout, ContentGrid, DataGrid, status, loading/error feedback, field help, actionable no-profile blocker, and stable row actions
/mail/bounces observation table	Inspect correlated or unmatched delivery-status evidence	Evidence/reporting	Medium because recipient and diagnostic data may be sensitive	Bounded sanitized rows, textual status, filters, correlation state, and no raw bounce body
Bounce watcher removal	Stop future scans while retaining evidence	Destructive confirmation	Medium and reversible by recreating the watcher; observations are retained	Shared ConfirmDialog states the immediate consequence and retained evidence
mail.profiles and credential-reference capabilities	Let another module select or validate Mail-owned transport without receiving secrets	Governed capability composition	High because the selected identity can perform external effects	Stable references and Core capability boundaries; no sibling-private WebUI import; authorization and credential resolution remain Mail-owned

State and consequence contract

• Loading, success, error, empty results, permission blockers, and destructive confirmation use Core components. Mail does not reproduce the shell.
• Bounce processing now delegates its page inset, sticky responsive heading, route actions, alert regions, loading boundary, scrolling, and help audience to Core PageLayout; Mail retains only watcher and evidence semantics.
• A target-dependent profile surface cannot load until a concrete user, group, or campaign is selected. The blocker identifies the responsible actor and destination instead of silently hiding the editor.
• Profile, server, credential, policy, mailbox refresh, connection-test, and bounce actions remain visible when structurally relevant. Missing authority, required input, or an in-progress operation is exposed through a focusable disabled-action explanation.
• Connection tests never save the draft and explicitly require the relevant hostname. Save remains the committing action. Policy save is unavailable until a local change exists.
• Effective policy keeps inherited source/provenance visible. A locked parent limit or governed workflow cannot be represented as an editable local value.
• Removing a bounce watcher retains observations and delivery evidence. Profile/server deactivation and credential unlinking use confirmations whose copy distinguishes retained reusable credentials from scrubbed owned secrets.
• Mailbox browsing is read-only. Listing or previewing must not mark messages read, move, delete, reply, or expose unbounded content.
• The mailbox Reload rechecks authorized profiles and refreshes the current catalogue, bounded page, and still-selected message. IMAP retains its page; JMAP refresh starts a new cursor chain while keeping the search. Selecting a synthetic grouping refreshes only the catalogue. Refresh failures retain usable data and a retry; request identities reject previous-profile/tenant results. Folder expansion is independent of labels and refreshes. Advanced targeted reads and bounce diagnostics remain in the labelled tools dialog, not a second persistent toolbar. Escape in that dialog leaves message selection intact.

Accessibility, responsive, and privacy evidence

Shared Dialog owns focus entry, Escape handling, focus containment, and focus return. Toolbar and form DOM order is keyboard order; mailbox rows support Enter and Space, arrow navigation is bounded to the visible page, and disabled reasons are keyboard-focusable. Status always has text in addition to color. Contextual links identify their destination to assistive technology.

Profile/policy grids collapse to one column below 900 px. The mailbox changes from three panes to two below 1280 px and to single-column message rows below 760 px while preserving source order and independent scroll regions. Core owns toolbar wrapping, with Reload right-aligned even on narrow screens. The two-row mailbox layout shares the available height between list and preview instead of reserving a fixed preview minimum that can squeeze message rows to zero height. Narrow screens stack compact folders, a usable message index, and the preview within a vertically scrollable bounded workspace. The action header never scrolls away, and each pane retains its own bounded scroll region. Long identities and transport summaries wrap or ellipsize inside stable bounds.

Profile and mailbox APIs return non-secret transport metadata and bounded message content only. Passwords are write-only and rendered only as a saved state marker. Bounce observations contain bounded sanitized diagnostics and a raw digest, not the raw provider message. Optional Campaign, Addresses, Audit, Calendar, and Notifications integrations remain capability-driven; Mail WebUI does not import their private packages.

The focused structural test guards shared components, contextual help, actionable blockers, confirmation, optional-module boundaries, responsive rules, and the absence of browser-native confirmation. Mail backend tests, Core component tests, manifest-shape checks, module permutations, structural localization audit, theme contract, and bundle budgets provide integration evidence.