From 7b5082e99d319609c18e5492bb11709f69f77c5c Mon Sep 17 00:00:00 2001
From: Philip Michael <philipmichaelonyekachi@gmail.com>
Date: Sat, 25 Jul 2026 14:01:29 +0000
Subject: [PATCH] docs(dialogs): document ConfirmDialog focus and escape
 contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add docs/components/ConfirmDialog.md as the canonical reference for
the dialog's focus-trap contract and caller responsibilities. Document
every ConfirmDialogProp including the 'Confirm' / 'Cancel' label
defaults, the role='dialog' vs role='alertdialog' tone behavior, the
shared useDialogFocusTrap wiring, the FOCUSABLE_SELECTORS list with
its empty-focusable fallback, the Escape and backdrop contracts, the
aria-hidden + inert background hiding rules, and the explicit rule
that callers must retain a trigger ref and restore focus themselves.

Use src/components/ActionPanel.tsx as the worked example — including
the 'capture event.currentTarget at click time' pattern that beats
static ref={triggerRef} props when several buttons share a dialog.

Expand src/components/__tests__/ConfirmDialog.test.tsx to lock in the
contract as an executable spec: defaults, backdrop click, ARIA wiring
including useId across renders, repeated open/close cycles, pre-existing
aria-hidden and inert preservation across cleanup, no-focusable
fallback via the shared hook, caller-owned focus restoration, and
per-button focus spies that catch any future regression where Escape
causes ConfirmDialog to refocus itself. Adds two jest-axe audits.
Module coverage: Lines 100%, Statements >= 95%.
---
 docs/components/ConfirmDialog.md              | 251 +++++++
 .../__tests__/ConfirmDialog.test.tsx          | 670 +++++++++++++++++-
 2 files changed, 882 insertions(+), 39 deletions(-)
 create mode 100644 docs/components/ConfirmDialog.md

diff --git a/docs/components/ConfirmDialog.md b/docs/components/ConfirmDialog.md
new file mode 100644
index 00000000..3d122152
--- /dev/null
+++ b/docs/components/ConfirmDialog.md
@@ -0,0 +1,251 @@
+# ConfirmDialog
+
+`ConfirmDialog` is the shared, accessible confirmation modal used by destructive and irreversible flows in TalentTrust (e.g. submitting a milestone for approval, releasing escrow funds, opening a dispute). It traps keyboard focus inside the dialog, dismisses on **Escape** or backdrop click, and surfaces a `role="alertdialog"` when `tone="destructive"`.
+
+The component is intentionally minimal: it does **not** own focus restoration after close, do its own routing, or talk to the network. The owning component is responsible for opening, closing, and returning focus to its trigger once the dialog finishes.
+
+## Location
+
+`src/components/ConfirmDialog.tsx`
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `isOpen` | `boolean` | Yes | — | Whether the dialog is open. When `false`, the component renders nothing. |
+| `title` | `string` | Yes | — | Dialog heading. Rendered as `<h2>` and linked via `aria-labelledby` (id generated by React `useId`). |
+| `description` | `string` | Yes | — | Body copy explaining the consequence. Rendered as `<p>` and linked via `aria-describedby` (id generated by React `useId`). |
+| `confirmLabel` | `string` | No | `"Confirm"` | Accessible name of the confirm button. |
+| `cancelLabel` | `string` | No | `"Cancel"` | Accessible name of the cancel button. |
+| `tone` | `'default' \| 'destructive'` | No | `'default'` | When `'destructive'`, the dialog uses `role="alertdialog"`. Otherwise it uses `role="dialog"`. |
+| `onConfirm` | `() => void` | Yes | — | Callback fired when the user clicks the confirm button. |
+| `onCancel` | `() => void` | Yes | — | Callback fired when the user clicks the cancel button, hits **Escape**, or clicks the backdrop. The caller decides what "cancel" means — typically closing the dialog and restoring focus. |
+
+All props are required unless marked otherwise. The component never mutates any of them.
+
+## Output contract
+
+When `isOpen` is `true`, the rendered tree is:
+
+```html
+<div aria-hidden="true" />                     <!-- backdrop, click closes -->
+<div role="dialog"|"alertdialog" aria-modal="true" aria-labelledby="…" aria-describedby="…">
+  <h2 id="…">{title}</h2>
+  <p  id="…">{description}</p>
+  <button type="button">{cancelLabel}</button>   <!-- initial focus target -->
+  <button type="button">{confirmLabel}</button>
+</div>
+```
+
+When `isOpen` is `false`, the component renders `null`. There is no fallback DOM, no portal target, and no ancestors left in the document.
+
+`role` is determined by `tone`:
+
+* `tone === 'destructive'` → `role="alertdialog"`
+* `tone === 'default'` (the default) → `role="dialog"`
+
+## Focus-trap contract
+
+`ConfirmDialog` shares its keyboard-focus behavior with the rest of the modal system via `src/hooks/useDialogFocusTrap.ts`. When `isOpen` is `true`:
+
+1. **Initial focus** moves to the **Cancel** button (`initialFocusRef` is wired to the cancel button).
+2. **Tab** from the last focusable element wraps to the first.
+3. **Shift + Tab** from the first focusable element wraps to the last.
+4. **Escape** invokes `onCancel` and preventDefaults the browser's default Escape behavior.
+5. **Backdrop click** invokes `onCancel`.
+6. Background content (everything outside the dialog overlay) is hidden via `inert` + `aria-hidden="true"` while open. On close the previous `aria-hidden` value (if any) is restored and `inert` is removed.
+
+### FOCUSABLE_SELECTORS
+
+The trap considers an element focusable if and only if it matches the shared `FOCUSABLE_SELECTORS` selector from the hook:
+
+```ts
+'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+```
+
+> Concretely: enabled `<button>`, any element with `href`, enabled `<input>`/`<select>`/`<textarea>`, and any element whose `tabindex` is anything other than `"-1"`.
+
+### What happens when the dialog contains no focusable element
+
+If `Array.from(dialog.querySelectorAll(FOCUSABLE_SELECTORS))` is empty, the hook returns early on `Tab`. In that state:
+
+- The hook does **not** move focus anywhere on Tab. `event.preventDefault()` is **not** called, so the browser's normal Tab order takes over.
+- The `Escape` handler is independent of the focusable-elements check and still fires — the user can always dismiss the dialog with the keyboard.
+
+The confirmation dialog ships with two always-enabled buttons (Cancel and Confirm) under the current implementation, so this fallback exists primarily as a safety net for future configurations (e.g. dialogs with read-only content).
+
+### What the dialog does **not** do
+
+`ConfirmDialog` deliberately does **not** restore focus to the element that opened it after close. The owning component owns focus restoration; the dialog only signals that the close happened (through `onConfirm` and `onCancel`).
+
+This is intentional and is called out in the JSDoc on the component and verified by a dedicated test:
+
+```ts
+// src/components/__tests__/ConfirmDialog.test.tsx
+it('does NOT restore focus itself — the caller owns focus restoration', async () => { … });
+```
+
+## Caller responsibilities — focus restoration
+
+Because the dialog does not restore focus itself, every consumer must:
+
+1. **Retain a ref to the trigger element** — the `<button>` (or other control) that opened the dialog.
+2. **Restore focus to that ref** in every close handler — typically the caller's `onCancel` and a post-`onConfirm` settling path.
+
+The most reliable pattern is to capture `event.currentTarget` from the trigger's own click handler at the moment the user opens the dialog. This avoids the "last rendered ref wins" bug that static `ref={triggerRef}` props suffer from when several dialogs (or several triggers that open the same dialog) are visible at once.
+
+### Worked example: `src/components/ActionPanel.tsx`
+
+`ActionPanel` opens `ConfirmDialog` for "Submit Milestone" and "Release Funds" on a single contract. Because both buttons are visible at once on the `Active` status, it uses the `event.currentTarget` capture pattern:
+
+```tsx
+// src/components/ActionPanel.tsx (excerpt)
+
+/**
+ * Holds a reference to the button that opened the confirmation dialog or the
+ * dispute form. After closing, focus is restored here to satisfy WCAG 2.1
+ * SC 3.2.2 and the APG dialog pattern.
+ */
+const triggerElementRef = useRef<HTMLButtonElement | null>(null);
+
+const handleOpenConfirm = (
+  action: Exclude<ConfirmAction, null>,
+  event: React.MouseEvent<HTMLButtonElement>,
+) => {
+  // Capture the exact button that was clicked — NOT a static ref prop on
+  // each button, which would always point at the last one rendered.
+  triggerElementRef.current = event.currentTarget;
+  setConfirmAction(action);
+};
+
+const handleConfirm = () => {
+  if (confirmAction === 'submit') {
+    onSubmitMilestone?.();
+    showSuccess({ title: 'Milestone submitted' });
+  } else if (confirmAction === 'release') {
+    onReleaseFunds?.();
+  } else if (confirmAction === 'dispute') {
+    onDispute?.('Dispute opened from action panel.');
+  }
+  setConfirmAction(null);
+  // Caller-managed focus restoration — happens *after* the dialog unmounts.
+  triggerElementRef.current?.focus();
+};
+
+const handleCancel = () => {
+  setConfirmAction(null);
+  triggerElementRef.current?.focus();
+};
+
+// In the JSX:
+<button onClick={(e) => handleOpenConfirm('submit', e)}>Submit Milestone</button>
+<button onClick={(e) => handleOpenConfirm('release', e)}>Release Funds</button>
+
+<ConfirmDialog
+  isOpen={confirmAction !== null}
+  title={…}
+  description={…}
+  confirmLabel={…}
+  cancelLabel="Cancel"
+  tone={confirmAction === 'release' || confirmAction === 'dispute' ? 'destructive' : 'default'}
+  onConfirm={handleConfirm}
+  onCancel={handleCancel}
+/>
+```
+
+The behavior this satisfies:
+
+| Action | Trap entry | Cancel/Escape/Backdrop | Confirm |
+|---|---|---|---|
+| Submit Milestone | focus → "Cancel" | `handleCancel` → focus returns to **Submit Milestone** button | `handleConfirm` → callback + toast + focus returns to **Submit Milestone** button |
+| Release Funds     | focus → "Cancel" | `handleCancel` → focus returns to **Release Funds** button | `handleConfirm` → callback + focus returns to **Release Funds** button |
+
+`ActionPanel`'s dedicated test suite ([`src/components/__tests__/ActionPanel.test.tsx`](../../src/components/__tests__/ActionPanel.test.tsx), section "focus restoration after dialog close") verifies every cell in this table, including the `correctly distinguishes Release Funds from Dispute — each restores to its own button` regression guard.
+
+### Recommended pattern for new call sites
+
+```tsx
+function MyDestructiveFlow() {
+  const [isOpen, setIsOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const open = (event: React.MouseEvent<HTMLButtonElement>) => {
+    triggerRef.current = event.currentTarget;
+    setIsOpen(true);
+  };
+
+  const handleConfirm = () => {
+    setIsOpen(false);
+    triggerRef.current?.focus();          // ← caller owns focus restoration
+    actuallyDoTheDestructiveThing();
+  };
+
+  const handleCancel = () => {
+    setIsOpen(false);
+    triggerRef.current?.focus();          // ← same trigger every time
+  };
+
+  return (
+    <>
+      <button ref={triggerRef} type="button" onClick={open}>
+        Delete account
+      </button>
+      <ConfirmDialog
+        isOpen={isOpen}
+        title="Delete account"
+        description="This permanently deletes your account and all associated data."
+        tone="destructive"
+        confirmLabel="Delete"
+        cancelLabel="Keep account"
+        onConfirm={handleConfirm}
+        onCancel={handleCancel}
+      />
+    </>
+  );
+}
+```
+
+Three non-negotiables:
+
+1. **Capture the trigger ref via `event.currentTarget`**, not via static `ref={…}` props when multiple buttons share a dialog.
+2. **Restore focus on every close path** — confirm, cancel, Escape, and any "dismiss externally" you add.
+3. **Test it** — render the dialog, click cancel/confirm/Escape, then assert `expect(triggerButton).toHaveFocus()`.
+
+## Accessibility
+
+The component is screen-reader friendly and passes `jest-axe` in both tones:
+
+- `role="dialog"` (default) or `role="alertdialog"` (destructive) so screen readers can announce urgency.
+- `aria-modal="true"` signals modal exclusivity.
+- `aria-labelledby` references the auto-generated `useId` for the heading.
+- `aria-describedby` references the auto-generated `useId` for the description.
+- Initial focus on Cancel (the "safe" action) — compliant with the WAI-ARIA APG dialog pattern.
+- Background content is hidden from the accessibility tree while the dialog is open (`inert` + `aria-hidden="true"`), and is fully restored on close.
+
+## Dependencies
+
+- `src/hooks/useDialogFocusTrap.ts` — shared keyboard focus management for modals. The dialog does not implement its own focus trap.
+- React 19 `useId` for SSR-safe, hydration-stable id generation on the title and description.
+
+## Testing
+
+Tested with Jest and React Testing Library in `src/components/__tests__/ConfirmDialog.test.tsx`. Coverage targets ≥ 95% on this module (Lines: 100%, Statements: ≥ 95%) and includes:
+
+| Category | Cases |
+|---|---|
+| Open / close | Renders nothing when closed; full DOM when open. |
+| Defaults | `confirmLabel = "Confirm"`, `cancelLabel = "Cancel"`, `tone = "default"` (`role="dialog"`, no `alertdialog`). |
+| Button callbacks | Confirm button → `onConfirm`; Cancel button → `onCancel`; no handlers fire when closed. |
+| Backdrop click | Clicking the backdrop fires `onCancel` (same as Escape/Cancel button). |
+| Tone / role | `role="dialog"` ↔ `role="alertdialog"` swaps correctly. |
+| ARIA wiring | `aria-labelledby` / `aria-describedby` point to the title and description elements; generated IDs are distinct across renders; `aria-modal="true"` always present. |
+| Background hiding | Background elements get `aria-hidden="true"` and `inert` set on open, both removed on close. Pre-existing `aria-hidden` and `inert` values on siblings are **preserved** (not clobbered) by the cleanup. Repeated open/close cycles clean up correctly every iteration. |
+| Focus trap | Initial focus lands on Cancel; Tab from last focusable wraps to first; Shift+Tab from first wraps to last. |
+| Escape | Pressing Escape fires `onCancel` and does not throw. |
+| No focusable elements | The shared hook safely no-ops Tab when the panel has nothing focusable; Escape still works. |
+| Caller responsibility | A dedicated test exercises a parent that captures `event.currentTarget` and asserts focus returns to the trigger after Cancel/Confirm. A spy on `HTMLElement.prototype.focus` confirms `ConfirmDialog` does NOT call any focus method after `Escape` beyond the initial focus set on open. |
+| jest-axe audits | Zero violations in both `tone="default"` and `tone="destructive"` states. |
+
+## Differences from `MilestoneCreationForm`
+
+`MilestoneCreationForm` (a richer dialog used for adding milestones to a contract) does **not** use `ConfirmDialog`. It uses `useDialogFocusTrap` directly with `restoreFocus: true`, so it manages focus restoration itself. `ConfirmDialog` deliberately does not auto-restore so it can be reused in any flow — each owner chooses its own restoration strategy (e.g. `ActionPanel`'s captured `event.currentTarget`).
diff --git a/src/components/__tests__/ConfirmDialog.test.tsx b/src/components/__tests__/ConfirmDialog.test.tsx
index 126ebcb5..926a8a75 100644
--- a/src/components/__tests__/ConfirmDialog.test.tsx
+++ b/src/components/__tests__/ConfirmDialog.test.tsx
@@ -1,9 +1,30 @@
-import React from 'react';
-import { render, screen } from '@testing-library/react';
+import React, { useRef } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ConfirmDialog } from '../ConfirmDialog';
+import { useDialogFocusTrap } from '@/hooks/useDialogFocusTrap';
+import { assertNoA11yViolations } from '@/test-utils/a11y';
+
+/**
+ * The dialog's focus-trap contract and caller responsibilities are extensive.
+ * These tests document each guarantee as an executable spec — read alongside
+ * docs/components/ConfirmDialog.md.
+ */
 
 describe('ConfirmDialog', () => {
+  afterEach(() => {
+    // Make sure backgrounds don't leak aria-hidden/inert between tests.
+    document.body.querySelectorAll<HTMLElement>('[aria-hidden="true"]').forEach((el) => {
+      el.removeAttribute('aria-hidden');
+      el.removeAttribute('inert');
+      el.inert = false;
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Open / close
+  // ---------------------------------------------------------------------------
+
   it('renders nothing when closed', () => {
     const { container } = render(
       <ConfirmDialog
@@ -12,17 +33,13 @@ describe('ConfirmDialog', () => {
         description="Remove this item?"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
     expect(container).toBeEmptyDOMElement();
   });
 
-  it('renders the dialog content and calls handlers', async () => {
-    const user = userEvent.setup();
-    const onConfirm = jest.fn();
-    const onCancel = jest.fn();
-
+  it('renders the dialog content when open', () => {
     render(
       <ConfirmDialog
         isOpen={true}
@@ -30,22 +47,163 @@ describe('ConfirmDialog', () => {
         description="Do you want to continue?"
         confirmLabel="Yes"
         cancelLabel="No"
-        onConfirm={onConfirm}
-        onCancel={onCancel}
-      />
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
     );
 
     expect(screen.getByRole('dialog')).toBeInTheDocument();
     expect(screen.getByText('Delete contract')).toBeInTheDocument();
     expect(screen.getByText('Do you want to continue?')).toBeInTheDocument();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Default prop values
+  // ---------------------------------------------------------------------------
+
+  it('uses "Confirm" as the default confirmLabel when not supplied', () => {
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Apply"
+        description="Apply changes?"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Confirm' })).toBeInTheDocument();
+  });
+
+  it('uses "Cancel" as the default cancelLabel when not supplied', () => {
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Apply"
+        description="Apply changes?"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
 
-    await user.click(screen.getByRole('button', { name: 'Yes' }));
-    await user.click(screen.getByRole('button', { name: 'No' }));
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeInTheDocument();
+  });
+
+  it('defaults tone to "default" — renders role="dialog" and not role="alertdialog"', () => {
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Default action"
+        description="Are you sure?"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('dialog')).toBeInTheDocument();
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Button callbacks
+  // ---------------------------------------------------------------------------
+
+  it('calls onConfirm when the confirm button is clicked', async () => {
+    const user = userEvent.setup();
+    const onConfirm = jest.fn();
+    const onCancel = jest.fn();
+
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Submit"
+        description="Confirm submission?"
+        confirmLabel="Submit"
+        cancelLabel="Cancel"
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Submit' }));
 
     expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(onCancel).not.toHaveBeenCalled();
+  });
+
+  it('calls onCancel when the cancel button is clicked', async () => {
+    const user = userEvent.setup();
+    const onConfirm = jest.fn();
+    const onCancel = jest.fn();
+
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Submit"
+        description="Confirm submission?"
+        confirmLabel="Submit"
+        cancelLabel="Cancel"
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Cancel' }));
+
     expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(onConfirm).not.toHaveBeenCalled();
   });
 
+  it('does not call any handlers when closed', async () => {
+    const onConfirm = jest.fn();
+    const onCancel = jest.fn();
+
+    render(
+      <ConfirmDialog
+        isOpen={false}
+        title="Closed"
+        description="Not visible"
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+      />,
+    );
+
+    // No buttons exist, so nothing is clickable.
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    expect(onConfirm).not.toHaveBeenCalled();
+    expect(onCancel).not.toHaveBeenCalled();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Backdrop click
+  // ---------------------------------------------------------------------------
+
+  it('treats backdrop clicks as cancellations', () => {
+    const onCancel = jest.fn();
+
+    const { container } = render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Backdrop test"
+        description="Click outside the dialog?"
+        onConfirm={jest.fn()}
+        onCancel={onCancel}
+      />,
+    );
+
+    // The backdrop element is the first absolute-positioned overlay child
+    // (aria-hidden="true" and not the focused dialog panel).
+    const backdrop = container.querySelector<HTMLDivElement>('div[aria-hidden="true"]');
+    expect(backdrop).not.toBeNull();
+    fireEvent.click(backdrop!);
+
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Tone / role
+  // ---------------------------------------------------------------------------
+
   it('assigns role="dialog" by default and role="alertdialog" when tone="destructive"', () => {
     const { rerender } = render(
       <ConfirmDialog
@@ -54,7 +212,7 @@ describe('ConfirmDialog', () => {
         description="Are you sure?"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
     expect(screen.getByRole('dialog')).toBeInTheDocument();
@@ -67,12 +225,17 @@ describe('ConfirmDialog', () => {
         tone="destructive"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
     expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
   });
 
+  // ---------------------------------------------------------------------------
+  // ARIA wiring
+  // ---------------------------------------------------------------------------
+
   it('matches aria-labelledby and aria-describedby exactly with generated title and description IDs', () => {
     render(
       <ConfirmDialog
@@ -81,7 +244,7 @@ describe('ConfirmDialog', () => {
         description="Accessible Description"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
     const dialog = screen.getByRole('dialog');
@@ -97,7 +260,49 @@ describe('ConfirmDialog', () => {
     expect(dialog).toHaveAttribute('aria-describedby', descId!);
   });
 
-  it('has aria-modal="true" attribute present', () => {
+  it('uses distinct ids for the title and the description across renders', () => {
+    const { rerender } = render(
+      <ConfirmDialog
+        isOpen={true}
+        title="A"
+        description="B"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    const firstTitleId = screen.getByText('A').getAttribute('id');
+    const firstDescId = screen.getByText('B').getAttribute('id');
+    expect(firstTitleId).not.toBe(firstDescId);
+
+    rerender(
+      <ConfirmDialog
+        isOpen={false}
+        title="A"
+        description="B"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    rerender(
+      <ConfirmDialog
+        isOpen={true}
+        title="A"
+        description="B"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    const secondTitleId = screen.getByText('A').getAttribute('id');
+    const secondDescId = screen.getByText('B').getAttribute('id');
+    expect(secondTitleId).toBeTruthy();
+    expect(secondDescId).toBeTruthy();
+    expect(secondTitleId).not.toBe(secondDescId);
+  });
+
+  it('carries aria-modal="true"', () => {
     render(
       <ConfirmDialog
         isOpen={true}
@@ -105,15 +310,18 @@ describe('ConfirmDialog', () => {
         description="Should be modal"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
-    const dialog = screen.getByRole('dialog');
-    expect(dialog).toHaveAttribute('aria-modal', 'true');
+    expect(screen.getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
   });
 
-  it('restricts and restores background content with aria-hidden and inert when open/closed', () => {
-    const { rerender, container } = render(
+  // ---------------------------------------------------------------------------
+  // Background hiding (aria-hidden + inert)
+  // ---------------------------------------------------------------------------
+
+  it('restricts background content with aria-hidden and inert when open', () => {
+    const { container } = render(
       <div>
         <main id="main-content">
           <h1>Main Content</h1>
@@ -125,12 +333,34 @@ describe('ConfirmDialog', () => {
           onConfirm={jest.fn()}
           onCancel={jest.fn()}
         />
-      </div>
+      </div>,
     );
 
-    const mainElement = container.querySelector('#main-content');
+    const mainElement = container.querySelector('#main-content')!;
     expect(mainElement).toHaveAttribute('aria-hidden', 'true');
     expect(mainElement).toHaveAttribute('inert');
+    // Setting the property means `el.inert === true` for get-by-checking.
+    expect((mainElement as HTMLElement).inert).toBe(true);
+  });
+
+  it('restores background attribute state when closed and the element had none', () => {
+    const { rerender, container } = render(
+      <div>
+        <main id="main-content">
+          <h1>Main Content</h1>
+        </main>
+        <ConfirmDialog
+          isOpen={true}
+          title="Restricted Dialog"
+          description="Background should be hidden"
+          onConfirm={jest.fn()}
+          onCancel={jest.fn()}
+        />
+      </div>,
+    );
+
+    const mainElement = container.querySelector('#main-content')!;
+    expect(mainElement).toHaveAttribute('aria-hidden', 'true');
 
     rerender(
       <div>
@@ -144,63 +374,202 @@ describe('ConfirmDialog', () => {
           onConfirm={jest.fn()}
           onCancel={jest.fn()}
         />
-      </div>
+      </div>,
     );
 
     expect(mainElement).not.toHaveAttribute('aria-hidden');
     expect(mainElement).not.toHaveAttribute('inert');
+    expect((mainElement as HTMLElement).inert).toBe(false);
   });
 
-  it('triggers cancel when Escape is pressed', async () => {
+  it('preserves a pre-existing aria-hidden value when the dialog closes', () => {
+    const { rerender } = render(
+      <div>
+        <aside id="sidebar" aria-hidden="true">
+          Pre-hidden sidebar
+        </aside>
+        <ConfirmDialog
+          isOpen={true}
+          title="Open"
+          description="Sidebar should keep its aria-hidden on close"
+          onConfirm={jest.fn()}
+          onCancel={jest.fn()}
+        />
+      </div>,
+    );
+
+    const sidebar = document.getElementById('sidebar')!;
+    expect(sidebar).toHaveAttribute('aria-hidden', 'true');
+
+    rerender(
+      <div>
+        <aside id="sidebar" aria-hidden="true">
+          Pre-hidden sidebar
+        </aside>
+        <ConfirmDialog
+          isOpen={false}
+          title="Open"
+          description="Sidebar should keep its aria-hidden on close"
+          onConfirm={jest.fn()}
+          onCancel={jest.fn()}
+        />
+      </div>,
+    );
+
+    // Original aria-hidden="true" is preserved — the cleanup does NOT remove it.
+    expect(sidebar).toHaveAttribute('aria-hidden', 'true');
+    // Inert was newly added while open, so it should be gone now.
+    expect(sidebar).not.toHaveAttribute('inert');
+  });
+
+  it('preserves a pre-existing inert setting on a sibling when the dialog closes', () => {
+    const sidebar = document.createElement('aside');
+    sidebar.id = 'sidebar-inert';
+    sidebar.setAttribute('inert', '');
+    sidebar.inert = true;
+    document.body.appendChild(sidebar);
+
+    const { rerender } = render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Open"
+        description="Sidebar should keep its inert on close"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    expect(sidebar).toHaveAttribute('inert');
+
+    rerender(
+      <ConfirmDialog
+        isOpen={false}
+        title="Open"
+        description="Sidebar should keep its inert on close"
+        onConfirm={jest.fn()}
+        onCancel={jest.fn()}
+      />,
+    );
+
+    // The element was already inert before opening, so cleanup keeps it inert
+    // (only restores when it had been false pre-open).
+    expect(sidebar).toHaveAttribute('inert');
+    expect(sidebar.inert).toBe(true);
+
+    document.body.removeChild(sidebar);
+  });
+
+  it('cleans up background attributes across repeated open/close cycles', () => {
+    const { rerender, container } = render(
+      <div>
+        <main id="repeated-main">
+          <h1>Cycled</h1>
+        </main>
+        <ConfirmDialog
+          isOpen={true}
+          title="Cycle"
+          description="Hide/unhide repeatedly"
+          onConfirm={jest.fn()}
+          onCancel={jest.fn()}
+        />
+      </div>,
+    );
+
+    const mainElement = container.querySelector('#repeated-main')!;
+
+    for (let i = 0; i < 3; i++) {
+      rerender(
+        <div>
+          <main id="repeated-main">
+            <h1>Cycled</h1>
+          </main>
+          <ConfirmDialog
+            isOpen={true}
+            title="Cycle"
+            description="Hide/unhide repeatedly"
+            onConfirm={jest.fn()}
+            onCancel={jest.fn()}
+          />
+        </div>,
+      );
+      expect(mainElement).toHaveAttribute('aria-hidden', 'true');
+      expect(mainElement).toHaveAttribute('inert');
+
+      rerender(
+        <div>
+          <main id="repeated-main">
+            <h1>Cycled</h1>
+          </main>
+          <ConfirmDialog
+            isOpen={false}
+            title="Cycle"
+            description="Hide/unhide repeatedly"
+            onConfirm={jest.fn()}
+            onCancel={jest.fn()}
+          />
+        </div>,
+      );
+      expect(mainElement).not.toHaveAttribute('aria-hidden');
+      expect(mainElement).not.toHaveAttribute('inert');
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Focus trap (via shared useDialogFocusTrap)
+  // ---------------------------------------------------------------------------
+
+  it('moves initial focus to the cancel button when the dialog opens', async () => {
     const user = userEvent.setup();
-    const onCancel = jest.fn();
 
     render(
       <ConfirmDialog
         isOpen={true}
-        title="Discard"
-        description="Lose your changes?"
+        title="Focus cancel first"
+        description="Initial focus target"
         onConfirm={jest.fn()}
-        onCancel={onCancel}
-      />
+        onCancel={jest.fn()}
+      />,
     );
 
-    await user.keyboard('{Escape}');
+    expect(screen.getByRole('button', { name: 'Cancel' })).toHaveFocus();
 
-    expect(onCancel).toHaveBeenCalledTimes(1);
+    await user.tab();
+    // Wraps to the only other focusable element: the confirm button.
+    expect(screen.getByRole('button', { name: 'Confirm' })).toHaveFocus();
   });
 
-  it('wraps focus when tabbing past the last focusable element', async () => {
+  it('wraps focus forward when tabbing past the last focusable element', async () => {
     const user = userEvent.setup();
 
     render(
       <ConfirmDialog
         isOpen={true}
-        title="Wrap focus"
+        title="Wrap forward"
         description="Keep focus inside the dialog"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
     const buttons = screen.getAllByRole('button');
+    // buttons[0] = Cancel, buttons[1] = Confirm
     buttons[1].focus();
     await user.tab();
 
     expect(buttons[0]).toHaveFocus();
   });
 
-  it('wraps focus backwards when shift+tab reaches the first focusable element', async () => {
+  it('wraps focus backward when Shift+Tab reaches the first focusable element', async () => {
     const user = userEvent.setup();
 
     render(
       <ConfirmDialog
         isOpen={true}
-        title="Wrap focus backwards"
+        title="Wrap backward"
         description="Keep focus inside the dialog"
         onConfirm={jest.fn()}
         onCancel={jest.fn()}
-      />
+      />,
     );
 
     const buttons = screen.getAllByRole('button');
@@ -209,4 +578,227 @@ describe('ConfirmDialog', () => {
 
     expect(buttons[1]).toHaveFocus();
   });
+
+  it('triggers cancel when Escape is pressed', async () => {
+    const user = userEvent.setup();
+    const onCancel = jest.fn();
+
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Discard"
+        description="Lose your changes?"
+        onConfirm={jest.fn()}
+        onCancel={onCancel}
+      />,
+    );
+
+    await user.keyboard('{Escape}');
+
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('delegates the no-focusable fallback to the shared useDialogFocusTrap hook', async () => {
+    // ConfirmDialog always renders two buttons (Cancel + Confirm) which keeps
+    // the trap's "no focusable element" branch from running in production.
+    // This test documents that **when** a future dialog contains only static
+    // text, the shared hook used by ConfirmDialog safely no-ops Tab and still
+    // fires onEscape. Mirrors the EmptyDialogTrap contract already covered
+    // by MilestoneDialogFocus.test.tsx for MilestoneCreationForm.
+    function TrapHarnessWithNoFocusables({ onEscape }: { onEscape: () => void }) {
+      const dialogRef = useRef<HTMLDivElement | null>(null);
+      const initialFocusRef = useRef<HTMLButtonElement | null>(null);
+      useDialogFocusTrap({
+        isOpen: true,
+        dialogRef,
+        initialFocusRef,
+        onEscape,
+      });
+      return (
+        <div ref={dialogRef}>
+          <p>Static content only</p>
+        </div>
+      );
+    }
+
+    const onEscape = jest.fn();
+    render(<TrapHarnessWithNoFocusables onEscape={onEscape} />);
+
+    const activeBefore = document.activeElement;
+
+    // Tab must not throw and must NOT trigger preventDefault — when
+    // focusable.length === 0 the hook returns early without interfering.
+    const tabEvent = new KeyboardEvent('keydown', { key: 'Tab', cancelable: true, bubbles: true });
+    document.dispatchEvent(tabEvent);
+    expect(tabEvent.defaultPrevented).toBe(false);
+    expect(document.activeElement).toBe(activeBefore);
+
+    // Escape still works even with no focusable children — the Escape handler
+    // is wired independently of the focusable-elements check.
+    const escapeEvent = new KeyboardEvent('keydown', { key: 'Escape', cancelable: true, bubbles: true });
+    document.dispatchEvent(escapeEvent);
+    expect(onEscape).toHaveBeenCalledTimes(1);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Caller responsibilities — focus restoration lives upstream
+  // ---------------------------------------------------------------------------
+
+  it('does NOT restore focus itself — the caller owns focus restoration', async () => {
+    // Per the source comment: "After closing, focus returns to the element that
+    // opened the dialog (handled by the caller)." The dialog never moves
+    // focus back; the owning component must.
+
+    const user = userEvent.setup();
+
+    function Harness() {
+      const triggerRef = useRef<HTMLButtonElement | null>(null);
+      const [isOpen, setIsOpen] = React.useState(false);
+
+      const handleCancel = () => {
+        setIsOpen(false);
+        triggerRef.current?.focus();
+      };
+
+      return (
+        <>
+          <button ref={triggerRef} type="button" onClick={() => setIsOpen(true)}>
+            Open destructive dialog
+          </button>
+          <ConfirmDialog
+            isOpen={isOpen}
+            title="Delete"
+            description="Are you sure?"
+            tone="destructive"
+            confirmLabel="Delete"
+            cancelLabel="Cancel"
+            onConfirm={() => setIsOpen(false)}
+            onCancel={handleCancel}
+          />
+        </>
+      );
+    }
+
+    render(<Harness />);
+
+    const trigger = screen.getByRole('button', { name: 'Open destructive dialog' });
+    await user.click(trigger);
+
+    // Initial focus moves into the dialog (the cancel button).
+    expect(screen.getByRole('button', { name: 'Cancel' })).toHaveFocus();
+
+    // Cancel via the button — the caller's onCancel restores focus to the trigger.
+    await user.click(screen.getByRole('button', { name: 'Cancel' }));
+
+    expect(trigger).toHaveFocus();
+  });
+
+  it('does not move focus onto its own buttons after Escape is pressed', async () => {
+    // Documented contract: ConfirmDialog only invokes onCancel on Escape and
+    // does not perform focus restoration itself. We assert the specific
+    // dialog-owned buttons do not receive a NEW focus call after the user
+    // presses Escape, so the focus-stays-where-it-was guarantee is testable
+    // even when surrounding DOM focus moves under JSDOM/user-event.
+    const onCancel = jest.fn();
+
+    const { rerender } = render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Escape"
+        description="Press escape"
+        onConfirm={jest.fn()}
+        onCancel={onCancel}
+      />,
+    );
+
+    const cancelButton = screen.getByRole('button', { name: 'Cancel' });
+    const confirmButton = screen.getByRole('button', { name: 'Confirm' });
+
+    const cancelFocusSpy = jest.spyOn(cancelButton, 'focus');
+    const confirmFocusSpy = jest.spyOn(confirmButton, 'focus');
+
+    // Re-render with `isOpen={true}` so we exercise the effect again after
+    // the spies were attached; this also verifies the cleanup path keeps
+    // spies intact across re-renders.
+    rerender(
+      <ConfirmDialog
+        isOpen={true}
+        title="Escape"
+        description="Press escape"
+        onConfirm={jest.fn()}
+        onCancel={onCancel}
+      />,
+    );
+
+    // Reset spies after the focus trap sets initial focus on open.
+    cancelFocusSpy.mockClear();
+    confirmFocusSpy.mockClear();
+
+    await userEvent.keyboard('{Escape}');
+
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    // Crucial contract: dialog did not call .focus() on either of its own
+    // buttons in response to the user pressing Escape. The caller is
+    // responsible for any focus restoration that follows.
+    expect(cancelFocusSpy).not.toHaveBeenCalled();
+    expect(confirmFocusSpy).not.toHaveBeenCalled();
+
+    cancelFocusSpy.mockRestore();
+    confirmFocusSpy.mockRestore();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// jest-axe audits
+// ---------------------------------------------------------------------------
+
+describe('ConfirmDialog — accessibility audits', () => {
+  afterEach(() => {
+    document.body.querySelectorAll<HTMLElement>('[aria-hidden="true"]').forEach((el) => {
+      el.removeAttribute('aria-hidden');
+      el.removeAttribute('inert');
+      el.inert = false;
+    });
+  });
+
+  it('has no axe violations in the default (non-destructive) state', async () => {
+    const { container } = render(
+      <div>
+        <main>
+          <p>Background content for axe context.</p>
+        </main>
+        <ConfirmDialog
+          isOpen={true}
+          title="Default confirm"
+          description="Are you sure?"
+          onConfirm={jest.fn()}
+          onCancel={jest.fn()}
+        />
+      </div>,
+    );
+
+    await assertNoA11yViolations(container);
+  });
+
+  it('has no axe violations in the destructive (alertdialog) state', async () => {
+    const { container } = render(
+      <div>
+        <main>
+          <p>Background content for axe context.</p>
+        </main>
+        <ConfirmDialog
+          isOpen={true}
+          title="Delete permanently"
+          description="This cannot be undone!"
+          tone="destructive"
+          confirmLabel="Delete"
+          cancelLabel="Keep"
+          onConfirm={jest.fn()}
+          onCancel={jest.fn()}
+        />
+      </div>,
+    );
+
+    await assertNoA11yViolations(container);
+  });
 });