Eve library

V1-AWEB-099 — Modal & Drawer Pattern Spec

Spec

Revision 1

On this page

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.