V9 — Modals + AgentPicker (NewIssue, EditIssue, Diff, AgentPicker)

[Luis85]

Parent epic: #326 · Depends on: F2, F3, F4 (ModalShell + Dropdown atoms), F5 · Stories: US-003, US-018, US-020, US-021, US-023, US-026, US-028

Problem

The workspace has four cross-cutting overlay surfaces. They are referenced from V1, V3, V4, V5 — but the surfaces themselves are V9's responsibility so the verticals can dispatch a single open event and not own the overlay implementation.

Solution

NewIssueModal.vue

• Fields: Title (required) · Type (feat | fix | research | chore | docs | req) · Scope (free text with suggestions: plugin-shell | tooling | ui | infra | …) · Description (textarea) · Assign Agent (optional, populated from useLiveStreamStore.agents)
• Submit → CreateIssueUseCase (calls GitHubPort.createIssue) → on success: inject IssueRow at top of sidebar list (via useEntitiesStore.insertIssue); numbered toast "Issue #N created" (US-003)
• Esc / ✕ closes without creating
• Empty title → submit disabled; inline validation hint

EditIssueModal.vue

• Pre-fills all fields from current issue + a "Context & Notes" textarea (acceptance criteria, constraints) — US-017, US-018
• Submit → UpdateIssueUseCase (calls GitHubPort.updateIssue); re-renders IssueHeader on success
• Same Esc / ✕ behaviour

DiffModal.vue

• Wide (~660px), centered
• File header: kind badge + path + line counts
• Line-numbered diff body using DiffViewer atom (F4); hunk header in blue
• Two variants:
  • Proposal: footer has Accept / Reject buttons; dispatch AcceptProposalUseCase / RejectProposalUseCase (US-020, US-021)
  • PR file: footer has Close + branch info (no actions) (US-026, US-028)
• Esc closes

AgentPicker.vue

• Fixed-position dropdown (not modal — must position relative to the trigger element)
• Lists all agents with gradient avatar + Name + Role + status dot (green/amber)
• Click an agent → resolves the dispatching promise with the agent id; consumer dispatches AssignTaskToAgentUseCase
• Outside-click dismisses (use useEventListener('click', …, { once: true }) or capture-phase listener; respect z-index)
• Esc dismisses

Cross-cutting modal infrastructure

• Modals open via a useModalStack() composable (built on the ModalShell atom from F4): LIFO Esc handling, single overlay, focus trap, restore focus on close
• All four overlays expose a typed promise-returning API:

  await openNewIssueModal()   // resolves to Issue | undefined
  await openEditIssueModal(issue)
  await openDiffModal(source) // source: { kind: 'proposal'; proposal } | { kind: 'pr-file'; pr; file }
  await openAgentPicker({ anchorEl })

Acceptance criteria

• All four overlays render via ModalShell (modals) or Dropdown (picker)
• LIFO Esc closes only the topmost overlay
• Focus trapped while modal open; restored to trigger on close
• NewIssueModal: required-title validation; success injects IssueRow; numbered toast (US-003)
• EditIssueModal: pre-fills correctly; Context & Notes field saves to issue.context (US-017, US-018)
• DiffModal proposal variant: Accept/Reject buttons dispatch correct use case + close (US-020, US-021)
• DiffModal PR-file variant: read-only with branch info footer (US-026, US-028)
• AgentPicker positions to the trigger; outside click closes; selection resolves with agent id
• PageObject tests cover all flows + LIFO Esc + focus restore
• Storybook stories for each modal in open state (with realistic content)
• A11y: role="dialog" + aria-modal="true" + aria-labelledby for modals; focusable trigger / restorable focus
• npm run typecheck, npm run lint, npm run test, npm run test:storybook pass

Out of scope

• "Assign Agent" field in NewIssueModal actually assigning (note as TODO; defer to Phase 2 since agent assignment is its own use case)
• Diff syntax highlighting language selection (just pass through code tokens from F4's DiffViewer)

Affected files

File	Action
src/ui/components/modals/NewIssueModal.vue	New
src/ui/components/modals/EditIssueModal.vue	New
src/ui/components/modals/DiffModal.vue	New
src/ui/components/modals/AgentPicker.vue	New
src/ui/composables/useModalStack.ts	New
src/application/issue/CreateIssueUseCase.ts	New
src/application/issue/UpdateIssueUseCase.ts	New
tests/ui/components/modals/*.test.ts + .po.ts	New
tests/application/issue/*.test.ts	New
stories/modals/*.stories.ts	New

References

• inputs/specorator-mvp-design-2026-05/Specorator_Design_Brief.html §"Modals & Overlays"
• inputs/specorator-mvp-design-2026-05/Specorator_Handoff.html §"Modals & Overlays" table
• User stories US-003, US-018, US-020, US-021, US-023, US-026, US-028

[Luis85]

Cross-cutting review (V9) — readiness: M, headline finding: modal-stack semantics, AgentPicker anchor strategy, and the "Vue overlay vs. Obsidian Modal" decision need to be nailed down before F4 ships the ModalShell atom.

Review findings

1. LIFO Esc + focus trap correctness. useModalStack must be a single source of truth — a module-level reactive stack: Ref<ModalEntry[]> plus exactly one document-level keydown listener attached on first push and detached on empty. Per-modal Esc listeners will mis-fire when stacked (both top and parent dismiss). Each entry stores { id, triggerEl, restoreFocus: boolean } so pop() calls triggerEl?.focus(). Focus trap must use :focus-visible-safe sentinel elements (two zero-size tabindex=0 nodes wrapping the trap) rather than swallowing Tab globally — otherwise screen-reader virtual cursors break.

2. AgentPicker positioning. Don't roll an ad-hoc fixed-position calc — Obsidian's iframe-like leaf can be scrolled/resized at any time. Either (a) use Floating UI (@floating-ui/dom, ~8KB) with autoUpdate for anchor-relative placement, or (b) port the prototype's getBoundingClientRect() math but recompute on scroll/resize of the nearest scrollable ancestor. Option (a) is the safer default; either way the picker must be position: fixed, not absolute (Tasks Panel scroll container will clip it).

3. DiffModal — one component or two? Recommend one component with a discriminated-union source prop, not two siblings. The two variants differ only in footer (Accept/Reject vs. branch info + Close), not in header/body/scrolling. Splitting duplicates the diff-rendering scaffolding. Use a <slot name="footer"> or v-if on source.kind to swap footers.

4. Obsidian Modal vs. Vue overlay. CLAUDE.md §DOM construction bans window.confirm/alert/prompt and v-html/innerHTML. It does not mandate Obsidian's Modal subclass for in-view overlays — those overlays render inside the Vue tree under the plugin's leaf. Use Vue-native ModalShell (teleported to body via <Teleport to="body">) so focus trap, scroll lock, and z-index are all owned by the Vue layer. Reserve the Obsidian Modal subclass for out-of-leaf confirmation flows (e.g. plugin settings).

5. useEventListener('click', …, { once: true }) is wrong for outside-click. The trigger's own click event will bubble through and fire the handler on the same tick. Use a capture-phase mousedown listener installed on the next microtask (queueMicrotask) with explicit target containment check against the picker's root element. Also handle Escape and blur for keyboard parity.

EARS requirements

• REQ-MVP-V9-001 — When a modal is open and the user presses Esc, the system shall dismiss only the topmost modal and return focus to its triggering element.
• REQ-MVP-V9-002 — While any modal is open, the system shall trap keyboard focus within the modal's interactive descendants.
• REQ-MVP-V9-003 — When NewIssueModal is submitted with an empty Title, the system shall prevent submission and surface an inline validation message; the submit button remains disabled until Title is non-empty.
• REQ-MVP-V9-004 — When AcceptProposalUseCase resolves successfully from DiffModal, the system shall close the modal and emit a numbered success toast referencing the proposal id.
• REQ-MVP-V9-005 — When AgentPicker is open and the user clicks outside its bounds or presses Esc, the system shall dismiss the picker without selecting an agent (the awaiting consumer promise resolves to undefined).
• REQ-MVP-V9-006 — While a DiffModal is shown for a PR file, the system shall render the footer in read-only mode (no Accept/Reject controls) and expose the branch name in an aria-describedby association.

Acceptance-criteria additions

• useModalStack is module-singleton; verified by a test that pushes from two unrelated components and observes shared depth.
• <Teleport to="body"> used for ModalShell; verified the modal renders outside the workspace leaf's scroll container.
• AgentPicker recomputes position on scroll + resize of nearest scrollable ancestor (or via Floating UI autoUpdate).
• Outside-click handler uses capture-phase mousedown, not bubbled click with { once: true }.
• DiffModal is a single component with a discriminated-union source prop ({ kind: 'proposal' | 'pr-file', … }).
• Storybook a11y addon shows zero violations on all four overlay stories (open state).
• PageObject covers: stacked-modal LIFO Esc, focus restore after each close, AgentPicker resolves with undefined on dismiss.
• Reduced-motion media query disables modal enter/exit transitions.

Dependency cross-check

Depends on: F2, F3, F4, F5 — accurate. F4's ModalShell and Dropdown atoms are real prerequisites. F5 (auth) is only needed because CreateIssueUseCase/UpdateIssueUseCase hit GitHubPort; mock adapter unblocks dev/test paths so V9 can land before F5 ships if the use cases are written against the port.

Test strategy

• Unit: useModalStack (push/pop/LIFO Esc/focus restore) — no DOM library needed; use happy-dom + a fake document.activeElement.
• Component (PO-based, Vitest): each modal in isolation with a fake trigger; assert ARIA contract.
• Storybook: open-state stories for each + an "all stacked" story to exercise LIFO.
• a11y addon: WCAG 2.1 AA on every story (handed off to X2 for the end-to-end gate, but every story should pass at land time).

Risks / unknowns (need decisions before implementation)

• Floating UI dependency — adds ~8KB gz; ok? If not, document the manual positioning approach in the PR.
• AgentPicker "live" status dot semantics — green/amber thresholds aren't defined here; defer to V7 (Agents Panel) for the canonical source.
• "Assign Agent" in NewIssueModal already noted as TODO — confirm with PM that the field is visible-but-noop or hidden entirely for MVP.

---

Generated by Claude Code