a11y(2.4.3): inert-based focus containment + restore; drop trap from native dialogs by ardiewen · Pull Request #3598 · temporalio/ui

ardiewen · 2026-06-24T19:21:42Z

Alternative to #3536. Fixes WCAG 2.4.3 (Focus Order) using platform primitives instead of the hand-rolled keydown trap.

focus-trap.ts did two jobs — Tab containment + focus restoration — both of which have native equivalents:

<dialog> + showModal() (holocene/modal, command-palette/modal) already traps and restores focus natively → removed use:focusTrap entirely.
Non-dialog (drawer — no overlay, maximizable) needs help → the action now sets inert on background content (capturing/restoring focus around it). inert also blocks pointer + assistive-tech access, which the old keydown trap (first/last Tab only) did not.
maximizable additionally captures focus in the component before toggling, because maximizing re-renders CodeMirror and blurs to <body> before the action runs (the action alone — and a11y(2.4.3): focus-trap — capture and restore focus to the trigger element on close #3536 — would restore to <body>).

Net: −44 lines of trap machinery (keydown handlers, MutationObserver, first/last tracking).

Testing

Unit: +4 tests (inert on activate / clear on destroy, capture+restore, toggle lifecycle, preserve pre-existing inert). pnpm check clean, suite green.
Browser-verified end-to-end:
- Modal — outside-focus blocked natively, Esc restores focus to trigger (with focusTrap removed).
- Drawer — real inert blocks background focus; close → inert cleared + focus restored to trigger.
- Maximizable — real inert containment; focus restored to the maximize button via both Esc and the minimize button.
NVDA/VoiceOver pass (background unreachable while a drawer/maximized surface is open).

inert is Baseline (Chrome 102+/FF 112+/Safari 15.5+), same era as showModal().

A11y-Audit-Ref: 2.4.3-focus-restoration-on-close

🤖 Generated with Claude Code

…native dialogs Replaces the keydown-wrapping focus trap with an `inert`-based approach and removes the trap entirely from the two `<dialog>`+`showModal()` consumers, which already get focus containment and restoration natively. - `focus-trap.ts`: `inertBackground()` walks node→<body> marking sibling content `inert` (clearing only what it set), and the action now captures the pre-activation focus and restores it on deactivate. This delegates Tab containment to the platform — and `inert` also blocks pointer + assistive-tech access to the background, which the old keydown trap (first/last Tab only) did not, notably for `drawer.svelte`, which has no overlay. - `holocene/modal.svelte`, `command-palette/modal.svelte`: removed `use:focusTrap`. Native `<dialog>.showModal()`/`close()` already traps and restores focus. - Drawer and Maximizable (non-dialog) keep the action, now inert-based. Verified in-browser: Modal containment + Esc-restore via native dialog; Drawer and Maximizable inert containment (real focus-blocking) + restore via the action. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel · 2026-06-24T19:21:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
holocene	Ready	Preview, Comment	Jul 6, 2026 8:01pm

…-render) Maximizing re-renders the CodeMirror content, which blurs focus to <body> before the focus-trap action activates — so the action captured <body> and restored focus there on minimize instead of returning it to the trigger. Capture the focused element in maximizable.svelte before toggling `maximized`, and restore it after `tick()` on the minimize/Escape paths. Browser-verified: focus returns to the maximize button via both Escape and the minimize button; inert containment unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

laurakwhit · 2026-06-25T21:20:27Z

Could use:focusTrap potentially run before the portalElement is set? Maybe we could make portalElement $state() and add a null check to use:focusTrap just in case.

Verified: yes.

Went another direction here: removed the $effect entirely: maximize() now portals to <body> synchronously before setting maximized = true, so the node is already in place when use:focusTrap activates in the same flush. No more $effect phase ordering, so there's nothing to null-check.

laurakwhit · 2026-06-25T21:38:06Z

+    releaseBackground();
+    releaseBackground = () => {};
+
+    if (previouslyFocused && document.body.contains(previouslyFocused)) {


Should we provide a way to pass a fallback or default here? That way if whatever opened the focus trap re-renders (e.g. a CodeBlock) while the user is in it they won't be kicked back to <body>.

…-inert

The drawer is now a true modal (inert background), so clicking the main submit button while it is open no longer works. Values bind live to the form, so closing commits nothing. Also avoids a strict-mode double-match on the timeout error text (rendered in both the drawer and the form). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

laurakwhit

Two small comments that might be worth looking into, but otherwise 🚀

laurakwhit · 2026-07-07T22:49:50Z

+      if (
+        sibling !== current &&
+        sibling instanceof HTMLElement &&
+        !sibling.inert


Do we need to add a check for aria-live here as well? E.g. would a toast fired from within a drawer get inerted/unannounced?

Yes, this is a real concern. I'm going to address this as a follow up ticket (DT-4252)

laurakwhit · 2026-07-07T22:54:04Z

+    portalElement?.destroy();
+    portalElement = null;
+    if (wrapperEl && originalParent?.isConnected) {
+      originalParent.insertBefore(wrapperEl, originalNextSibling);


Might not hurt to add a check that originalNextSibling is still a child of originalParent here since Node.insertBefore might throw an exception if it isn't.

great catch, fixed!

The reference sibling captured at maximize time can be removed from the DOM while maximized (e.g. a re-render); insertBefore throws NotFoundError when the ref node is no longer a child of originalParent. Fall back to appending in that case. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…T-4252] The inert-based focus trap (#3598) inerts everything outside the trap up to <body>. The Toaster's aria-live region rendered inside the main app container, so it was inerted while a drawer/maximizable was open and toasts went unannounced to screen readers (still shown visually — an AT-only gap). Hoist the live region to <body> from within the Toaster and mark it data-inert-skip; inertBackground now skips live-region roots (matched on the element itself, so a container merely holding one is still inerted). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…T-4252] (#3654) * a11y(2.4.3): keep toast live region announcing during a focus trap [DT-4252] The inert-based focus trap (#3598) inerts everything outside the trap up to <body>. The Toaster's aria-live region rendered inside the main app container, so it was inerted while a drawer/maximizable was open and toasts went unannounced to screen readers (still shown visually — an AT-only gap). Hoist the live region to <body> from within the Toaster and mark it data-inert-skip; inertBackground now skips live-region roots (matched on the element itself, so a container merely holding one is still inerted). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(focus-trap): isolate data-inert-skip case from aria-live The data-inert-skip test also set aria-live, so it passed on the aria-live branch alone. Drop aria-live here so it exercises data-inert-skip only; aria-live has its own test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot added a11y Accessibility audit PR a11y:bucket-3 Bucket 3: engineer required a11y:sc-2.4.3 labels Jun 24, 2026

vercel Bot deployed to Preview June 24, 2026 19:22 View deployment

vercel Bot deployed to Preview June 24, 2026 19:44 View deployment

ardiewen marked this pull request as ready for review June 24, 2026 19:50

ardiewen requested a review from a team as a code owner June 24, 2026 19:50

ardiewen requested a review from laurakwhit June 24, 2026 19:51

ardiewen mentioned this pull request Jun 24, 2026

a11y(2.4.3): focus-trap — capture and restore focus to the trigger element on close #3536

Closed

9 tasks

laurakwhit reviewed Jun 25, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into wcag/2.4.3-focus-trap…

fc697a1

…-inert

vercel Bot deployed to Preview July 6, 2026 16:36 View deployment

ardiewen added 4 commits July 6, 2026 13:09

chore: add test coverage for nested inert focus traps

aee36d4

chore(nit): add tabindex="-1" for drawer and maximizable

e802e32

chore: add order of acitons comment to drawer component

3201645

fix: imperatively portal in maximize

7a21394

vercel Bot deployed to Preview July 6, 2026 17:43 View deployment

vercel Bot deployed to Preview July 6, 2026 20:01 View deployment

ardiewen requested a review from laurakwhit July 7, 2026 15:44

laurakwhit approved these changes Jul 7, 2026

View reviewed changes

ardiewen mentioned this pull request Jul 10, 2026

a11y(2.4.3): keep toast live region announcing during a focus trap [DT-4252] #3654

Merged

1 task

ardiewen merged commit b42b077 into main Jul 10, 2026
19 checks passed

ardiewen deleted the wcag/2.4.3-focus-trap-inert branch July 10, 2026 18:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

a11y(2.4.3): inert-based focus containment + restore; drop trap from native dialogs#3598

a11y(2.4.3): inert-based focus containment + restore; drop trap from native dialogs#3598
ardiewen merged 9 commits into
mainfrom
wcag/2.4.3-focus-trap-inert

ardiewen commented Jun 24, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

laurakwhit Jun 25, 2026

Uh oh!

ardiewen Jul 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

laurakwhit Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

laurakwhit left a comment

Uh oh!

laurakwhit Jul 7, 2026

Uh oh!

ardiewen Jul 10, 2026

Uh oh!

laurakwhit Jul 7, 2026

Uh oh!

ardiewen Jul 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ardiewen commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing

Uh oh!

vercel Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

laurakwhit Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

ardiewen Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

laurakwhit Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

laurakwhit left a comment

Choose a reason for hiding this comment

Uh oh!

laurakwhit Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

ardiewen Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

laurakwhit Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

ardiewen Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ardiewen commented Jun 24, 2026 •

edited

Loading

vercel Bot commented Jun 24, 2026 •

edited

Loading

ardiewen Jul 6, 2026 •

edited

Loading