ui-conflict-resolution-modal

Component contract

• open: boolean — controlled. Parent opens when their save returns 409.
• conflictKind: ConflictKind — "version-mismatch" | "publish-in-progress" | "session-expired" | "edit-lock-held"
• yourChanges: ChangeSet — labeled diff of what the user did (added/changed/removed fields with values)
• serverState: ChangeSet — current server state for the same fields
• onChoose: (decision) => Promise<void> — fires with decision: "discard-mine" | "overwrite" | "refresh-and-merge"
• onCancel: () => void — closes the modal without choosing; user returns to their stale-form state to re-evaluate
• otherActorName?: string — when known, "Bob also edited this 30 seconds ago"; when not, "Another user changed this server-side"
• contextLabel: string — human-readable identifier of what's in conflict ("Event 'Acme Conference' settings", "Access type 'VIP'")
• allowOverwrite?: boolean — defaults to true; some surfaces (audit-critical) set false to force discard-or-merge only

Composition

• ui-modal — focus-trap + esc-cancel + focus-returns-to-trigger
• ui-data-table — for the diff display (your-value | server-value per field row)
• ui-status-pill — labels each row with "Changed by you" / "Changed by [other]" / "You didn't change"
• ui-destructive-confirmation — wraps the "overwrite" action because it discards another user's work
• ui-toast — confirms the chosen action ("Refreshed and merged your changes")

Interaction surface

1. Modal opens after parent's save returns 409.

   Title reflects conflictKind: "Someone else edited this" / "Publish in progress" / "Your session expired" / "Another organizer is editing." Body header: contextLabel + otherActorName context.

2. Diff table renders.

   Per row: field name + your-value + server-value + status pill. Rows where your value matches server (no actual conflict) are hidden by default, expandable via "Show unchanged fields." Diff is field-level (not whole-document) to make decisions tractable.

3. Three primary actions.

   "Discard my changes" (safe, default focus on this), "Refresh and merge" (loads server state into the form, lets user re-apply their changes manually), "Overwrite with my changes" (uses ui-destructive-confirmation; explicitly discards other user's work).

4. Cancel returns to stale form.

   User can close modal to inspect their form state more carefully, then reopen the diff via parent's "Re-check conflict" CTA. This is for situations where the user wants to manually copy specific values before merging.

5. Edit-lock-held variant.

   When conflictKind=edit-lock-held, the modal is mostly informational: "Bob is currently editing this. Your changes are saved as a draft and will sync when the lock releases." Diff hidden. Single CTA: "Got it" (closes modal, parent enters draft-saved state).

Failure modes

Accessibility

• Inherits ui-modal: role=dialog, aria-modal=true, focus-trap, esc-closes, focus-returns-to-trigger.
• Title is the modal's aria-labelledby target.
• Body description is the aria-describedby target.
• Diff table inherits ui-data-table a11y.
• Action buttons have descriptive aria-labels including the consequence ("Discard my changes to access type 'VIP'").
• Color contrast: status pills inherit ui-status-pill registry contrast.
• axe-clean ≥ serious across all conflictKind variants.

Stable test attributes

Agent test plan

- default-focus-on-discard: open modal, activeElement = ui-conflict-resolution-discard-button
- overwrite-uses-destructive-confirmation: click overwrite, ui-destructive-confirmation visible
- diff-field-level-not-blob: stub 47 fields with 3 conflicts, only 3 rows visible by default
- show-unchanged-expander: click expander, all 47 rows visible
- other-actor-displayed-when-known: stub otherActorName, displayed
- other-actor-fallback: stub null, "Another user" fallback
- edit-lock-held-minimal-ui: kind=edit-lock-held, no diff table, only got-it
- session-expired-signin-only: kind=session-expired, only signin CTA
- allow-overwrite-false-hides: allowOverwrite=false, overwrite hidden
- refresh-merge-refetches: click refresh, parent fetch fires
- recheck-via-parent-reopens: cancel + re-check parent CTA, modal reopens with fresh diff
- audit-row-per-decision: each of 3 decisions, 3 audit rows
- ui-lock-during-modal-open: parent submit disabled while open
- color-contrast-status-pill: ≥ 4.5:1
- axe-clean-across-kinds: every conflictKind passes axe ≥ serious

Current consumers