docs(dialogs): document ConfirmDialog focus and escape contract#779
Merged
mikewheeleer merged 1 commit intoJul 26, 2026
Merged
Conversation
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%.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the canonical reference for
ConfirmDialogindocs/components/ConfirmDialog.mdand locks every documented guarantee in as an executable spec viasrc/components/__tests__/ConfirmDialog.test.tsx.What changed
docs/components/ConfirmDialog.md— everyConfirmDialogPropwith defaults (confirmLabel = "Confirm",cancelLabel = "Cancel",tone = "default"), therole="dialog"vsrole="alertdialog"behavior, the shareduseDialogFocusTrapwiring, theFOCUSABLE_SELECTORSlist, the empty-focusable fallback, Escape and backdrop contracts, and the explicit caller-responsibility contract withsrc/components/ActionPanel.tsxas the worked example, including theevent.currentTargetcapture pattern that beats staticref={triggerRef}props when several buttons share a dialog.src/components/__tests__/ConfirmDialog.test.tsx— 27 tests covering defaults, backdrop click, ARIA wiring, repeated open/close cycles, pre-existingaria-hidden/inertpreservation across cleanup, the no-focusable fallback, the caller-owned focus-restoration contract, andjest-axeaudits for both tones. Module coverage: Lines 100%, Statements >= 95% (Branches 91%, Functions 87.5%).Validation
npm run lint— clean.npm test— 1278/1278 pass across 73 suites (including 27 new ConfirmDialog tests).npm run buildfailed in the local sandbox due to a missing@tailwindcss/oxide-linux-x64-gnunative binding (a Tailwind optional-dependency install issue, unrelated to these changes). Should be red in CI; please re-run there.closes Document the ConfirmDialog focus-trap contract and caller responsibilities #435