Migrate Files surfaces to interface patterns

docs/INTERFACE_PATTERN_MIGRATION.md

@@ -0,0 +1,55 @@
+# Files Interface Pattern Migration
+
+This inventory records the Files-owned part of the GovOPlaN interface pattern
+language. Core owns the shell and shared components; Files owns the composition
+and consequences described here.
+
+## Surface inventory
+
+| Surface | Primary task | Archetype | Consequence | Pattern evidence |
+| --- | --- | --- | --- | --- |
+| `/files` space and folder panes | Browse managed and connected content without losing location | Directory/explorer | Low for navigation; medium for exposing filenames and provenance | Full-height two-pane workspace, bounded panes, stable selection and contextual Help Center link |
+| `/files` toolbar and property filters | Find and act on the current selection | Explorer actions and local filtering | Medium for upload, move, copy, share and synchronization; high for delete | Actions remain beside the affected list, disabled controls explain permission/state/selection blockers, destructive work uses `ConfirmDialog` |
+| Upload/archive, transfer, rename and connector-import dialogs | Supply and review one bounded change | Adaptive create/edit or guided import | Medium to high because files, paths and external bytes change | Shared `Dialog`, `FileDropZone`, validation, conflict review, unsaved inputs and explicit confirmation |
+| File share dialog | Inspect and change access | Review/decision | High because another actor gains access | Shared dialog, access explanation, stable row actions and destructive confirmation |
+| System/tenant/group/user connector surfaces | Compare connections, credentials and effective policy | Administration/configuration | High because endpoints, secrets and inherited policy control external access | Shared `ConnectionTree`, adaptive forms, `ActionBlockerHint`, policy provenance and contextual admin help |
+| Connection and credential editors | Create or edit one governed endpoint or secret | Adaptive create/edit | High because a saved change may enable remote access | Relevant fields only, typed credential controls, discovery/test, advanced compatibility section, unsaved-change guard and disabled-save reasons |
+| Connector policy card | Narrow inherited connector access | Effective-policy editor | High because deny/allow changes affect lower scopes | Typed reference selectors, deny precedence warning, effective source evidence and permission blocker |
+| `files.widget.spaces` | See available managed/connected spaces and open Files | Dashboard widget | Low; names and provider state may still be sensitive | Shared loading/alert/status components, bounded item count, permission-filtered contribution |
+| Files chooser capability used by another module | Select a managed snapshot without importing Files internals | Directory chooser | Medium because the exact selected version becomes another module's input | Shared dialog/confirmation, capability boundary and exact file/version evidence |
+
+## State and consequence contract
+
+- Loading, errors, success, empty results, access explanations and confirmation
+  use Core components. Files does not reproduce the application shell.
+- A connector that comes from deployment settings remains visible but read-only;
+  its action explains that bootstrap configuration and a restart are required.
+- Missing permission, target, selection, endpoint, or compatible provider is an
+  explained disabled state. It is not represented only by color or absence.
+- Provider metadata JSON is an expert compatibility escape hatch inside the
+  collapsed shared advanced-options component. Ordinary connector setup uses
+  typed provider, endpoint, credential, capability and policy controls.
+- Endpoint discovery and credential tests are explicit and report their result;
+  they do not save the draft. Save remains the only committing action.
+- Connector/profile disable and managed-file delete remain confirmed actions and
+  state their immediate effect. Soft deletion must not be described as purge.
+- External connector data, paths and credential references are rendered only in
+  already-authorized administration or explorer contexts. Secret values are
+  never returned for rendering.
+
+## Accessibility and responsive evidence
+
+Shared `Dialog` owns focus entry, Escape handling and focus return. Form and
+toolbar DOM order is the keyboard order; disabled-action tooltips are themselves
+focusable and expose the reason. The connector form uses semantic sections and
+labels, status is textual as well as colored, and result alerts are announced by
+the shared alert component. The explorer collapses to one column below 1050 px;
+connector forms and action rows collapse below 760 px while preserving source
+order. Long provider choices scroll inside the segmented control rather than
+expanding the page.
+
+The focused structural test guards these contracts, optional-module boundaries,
+confirmation, contextual help, advanced-only JSON and responsive rules. Core's
+TypeScript build, structural localization audit, module-permutation suite and
+full-product bundle check provide the integration gates.
+