# V1-AWEB-099 — Modal & Drawer Pattern Spec

Implementation spec for the Phase 17.10 reduction of modal and drawer overuse.
Goal: **define preferred patterns for inline review, side-panel inspection, and
staged confirmation**.

## Reference: as-is

The admin app today opens a modal or drawer for almost any action with
side-effects. Surveyed surfaces (per the V1-AWEB-092 inventory):

- Modal-driven: `ReviewHighRiskApprovalPanel` (high-risk confirmation),
  `RetentionManagementPanel` (legal-hold release), several trust-safety lists
  (offender history dialog, appeal context), `PolicyBundleEditorPanel` (deploy
  confirmation), `IncidentRunbookPostmortemPanel` (close postmortem dialog).
- Drawer-driven: `UnifiedInboxPanel` (row inspection),
  `ResearchIntegrityCopilotPanel` (suggestion details),
  `CitationValidationWorkspacePanel` (citation drawer), `AvatarPackReviewPanel`
  (gate detail drawer).
- Inline expansion: `ResearchSourceReviewPanel` (per-citation re-review form
  expands inline), `ResearchComparativePromotionPanel` (per-card forms inline),
  `ResearchReportPolicyGatingPanel` (3-form grid inline),
  `PrivacyConsentAuditPanel` (per-card forms inline).

### As-is pain points

1. **Operators lose context on modal open.** A modal blanks the queue; the
   operator's place in the list is lost.
2. **Drawers compete with the action rail (V1-AWEB-094).** A row drawer + a
   sticky right-edge action rail occupy the same screen real estate.
3. **Confirmation modals stack.** Some flows trigger modal → confirm → second
   modal; operators report "modal fatigue".
4. **Inline forms scale with row count.** A 60-row queue with inline forms can
   render 60 expanded forms simultaneously (depending on panel logic).
5. **No consistent close affordance.** Some modals close on Esc, some on
   backdrop click, some only on explicit `Cancel`.

## Pattern decisions

The redesign formalises **three** action-affordance patterns with strict
applicability rules.

### 1. Inline review (preferred)

Use when: the action is reversible, low-risk, single-step, and self-contained on
the row's data (no second screen needed).

Examples to keep inline: V1-AWEB-085 comparative-text verdict, V1-AWEB-086
hallucination review, V1-AWEB-087 consent review, V1-AWEB-089 conversation note.
All four already follow the inline pattern.

Render rule: the form expands beneath the row card, never beside it. Only one
inline form is open at a time per panel (opening another collapses the
previous).

### 2. Side-panel inspection (preferred for inspection)

Use when: the operator needs to read more context than the row shows, but the
action set is the same as the row's inline actions.

Examples to migrate: `UnifiedInboxPanel` row drawer (already a side panel),
`CitationValidationWorkspacePanel` citation drawer.

Render rule: the side panel is the right column of the master-detail split
(V1-AWEB-094). Opening a row updates the URL hash; closing returns the operator
to the queue with the hash cleared. Side panel does NOT trap focus; operators
can keep `j/k`-navigating the queue with the side panel open.

### 3. Staged confirmation (modal — only for irreversible)

Use when: the action is irreversible, destructive, or requires elevated
confirmation (high-risk approval, legal hold release, deploy to production,
force-close incident).

Render rule: a single modal layer with three required sub- sections:

1. **Action summary** — what will happen.
2. **Reversibility note** — what cannot be undone.
3. **Confirmation control** — typed confirmation (e.g., type the case id) for
   the most destructive actions; otherwise an explicit `Confirm` button with a
   keyboard-required `Tab + Enter` to activate (no auto- focus on the confirm
   button).

The modal closes on Esc, backdrop click, or explicit `Cancel`. The modal does
NOT auto-focus the destructive button.

## Anti-patterns (banned by the spec)

- Modal that opens a second modal.
- Drawer that opens a modal that opens a drawer.
- Inline form that simultaneously renders for >1 row in the same panel.
- Modals that auto-focus the destructive action.
- Drawers that trap focus, preventing keyboard queue navigation.

## Implementation deliverables

1. `apps/oshun/admin/src/components/AdminConfirmationModal.tsx`
   - `.module.css` — canonical modal with the three required subsections +
     typed-confirmation prop.
2. Audit + migration of every existing modal usage:
   - `ReviewHighRiskApprovalPanel` → adopt typed confirmation.
   - `RetentionManagementPanel` legal-hold release → adopt typed confirmation.
   - `PolicyBundleEditorPanel` deploy → adopt typed confirmation.
   - `IncidentRunbookPostmortemPanel` close → adopt typed confirmation.
   - Trust-safety modals → migrate offender-history / appeal-context modals to
     side panels (Pattern 2).
3. Audit + migration of every existing drawer usage:
   - `UnifiedInboxPanel` drawer → migrate to master-detail side panel
     (V1-AWEB-094).
   - `ResearchIntegrityCopilotPanel` suggestion drawer → migrate to side panel.
   - `CitationValidationWorkspacePanel` citation drawer → migrate to side panel.
   - `AvatarPackReviewPanel` gate-detail drawer → migrate to side panel.
4. Inline form audit: confirm only one inline form is open per panel at a time
   across all V1-AWEB-085/086/087/088/089 panels.
5. Tests: confirmation modal component test (typed confirmation flow),
   Playwright `admin-modal-drawer.spec.ts` covering Esc / backdrop close, no
   auto-focus on destructive, drawer-doesn't-trap-focus.

## Acceptance criteria

- Every existing modal in the admin app falls into Pattern 3 (staged
  confirmation) or has been migrated to Pattern 1 / 2.
- No modal opens another modal; no drawer opens a modal.
- Side-panel drawers do NOT trap focus; the operator can `j/k`-navigate the
  queue while the drawer is open.
- Confirmation modals do NOT auto-focus the destructive button; they require an
  explicit `Tab + Enter`.
- Per-panel inline form rule: only one open at a time.
- Confirmation modal component test + Playwright spec pass.
