Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): return focus to the opener when MobileNav closes (#4410)

AKc2463a6c22bb
diff --git a/.changeset/mobile-nav-focus-restore.md b/.changeset/mobile-nav-focus-restore.md
new file mode 100644
index 0000000000..13ef6e9cf0
--- /dev/null
+++ b/.changeset/mobile-nav-focus-restore.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] MobileNav: return focus to the element that opened the drawer when it closes. The drawer relied entirely on the browser's implicit `<dialog>` focus restore, which was reported failing in Safari 26.5.2: `document.activeElement` became `<body>` after close, stranding keyboard and screen-reader users at the top of the document. MobileNav now captures the opener before `showModal()` moves focus into the top layer and hands it back as soon as the native dialog has closed, matching what `Dialog` already does. The close is deferred until the slide-out has played, so the restore waits for it too; until then the rest of the document is inert and an earlier `focus()` would be silently dropped. The restore also covers the AppShell path, where the drawer is torn down by an `<Activity>` switching to `mode="hidden"` rather than by the close branch re-running. No API change. Focus is left untouched when there was no real opener (`activeElement` was `<body>`), when the opener has since left the DOM, or when the drawer is reopened before its pending close runs. (#3343)
+
+@AKnassa
diff --git a/packages/core/src/MobileNav/MobileNav.tsx b/packages/core/src/MobileNav/MobileNav.tsx
index c6c41c92f7..1ffcbf6d24 100644
--- a/packages/core/src/MobileNav/MobileNav.tsx
+++ b/packages/core/src/MobileNav/MobileNav.tsx
@@ -25,6 +25,13 @@
* closes. The native `cancel` event still handles the dismissals the browser
* starts itself, such as the Android back gesture.
*
+ * Focus RESTORATION is not delegated to the browser. The drawer captures the
+ * element that opened it and refocuses it once the native dialog has closed,
+ * mirroring Dialog: the implicit `<dialog>` restore has been observed dropping
+ * focus to `<body>`. The close itself is deferred past the slide-out, and the
+ * restore has to follow it. Until close() runs the rest of the document is
+ * inert and focus() on the opener is silently dropped.
+ *
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/MobileNav/index.ts (exports if types change)
* - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
@@ -40,6 +47,7 @@ import {
useRef,
useState,
type ReactNode,
+ type RefObject,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
@@ -317,6 +325,34 @@ function resolveCloseDelay(dialog: HTMLDialogElement): number {
return hold <= 0 ? 0 : Math.min(cap, hold * CLOSE_WITHIN_HOLD);
}
+/**
+ * Close the native dialog, then return focus to the element that opened it.
+ *
+ * Browsers are supposed to restore focus themselves when a modal <dialog>
+ * closes, but that has been observed to fail (focus lands on <body>), so the
+ * drawer does it explicitly, as Dialog does. The order is load-bearing: while
+ * the modal dialog holds the top layer the rest of the document is inert and
+ * focus() on the opener is silently dropped. So the restore rides on the close
+ * itself, wherever that happens (the delayed timer, or the unmount teardown),
+ * not on the `isOpen` flip that only schedules it.
+ *
+ * Focus is left alone when there was no real opener (activeElement was <body>)
+ * or the opener has since left the DOM: focusing <body> would blur whatever a
+ * router moved focus to, and a detached node cannot take focus.
+ */
+function closeAndRestoreFocus(
+ dialog: HTMLDialogElement,
+ openerRef: RefObject<HTMLElement | null>,
+): void {
+ dialog.close();
+ const opener = openerRef.current;
+ openerRef.current = null;
+ if (!opener || opener === document.body || !opener.isConnected) {
+ return;
+ }
+ opener.focus();
+}
+
// =============================================================================
// Types
// =============================================================================
@@ -449,6 +485,9 @@ export function MobileNav({
const dialogRef = useRef<HTMLDialogElement>(null);
const closeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+ // Element that was focused when the drawer opened; focus goes back to it
+ // once the native dialog has closed (see closeAndRestoreFocus).
+ const triggerElementRef = useRef<HTMLElement | null>(null);
const gutterRef = useRef<ScrollbarGutterHold | null>(null);
// Gives back the gutter held open in place of the hidden scrollbar.
@@ -505,6 +544,12 @@ export function MobileNav({
gutterRef.current ??= holdScrollbarGutter(document.documentElement);
if (!dialog.open) {
+ // Capture the opener before showModal() pulls focus into the top
+ // layer. Only on the transition into open: a reopen while the delayed
+ // close is still pending finds the dialog open, and must keep the
+ // original opener rather than whatever is focused inside the drawer.
+ triggerElementRef.current =
+ document.activeElement as HTMLElement | null;
dialog.showModal();
}
// Prevent background scrolling and iOS pull-to-refresh.
@@ -517,7 +562,7 @@ export function MobileNav({
releaseGutter();
closeTimeoutRef.current = setTimeout(() => {
- dialog.close();
+ closeAndRestoreFocus(dialog, triggerElementRef);
}, resolveCloseDelay(dialog));
}
@@ -541,11 +586,14 @@ export function MobileNav({
// This must be a separate unmount-only effect: putting it in the open/close
// effect above would close the dialog on every isOpen flip and cut off the
// delayed slide-out close.
+ //
+ // Inside AppShell this teardown is the only close the drawer ever gets, so
+ // it is also where focus goes back to the toggle.
useEffect(() => {
const dialog = dialogRef.current;
return () => {
if (dialog?.open) {
- dialog.close();
+ closeAndRestoreFocus(dialog, triggerElementRef);
}
};
}, []);
diff --git a/packages/core/src/MobileNav/MobileNavFocus.test.tsx b/packages/core/src/MobileNav/MobileNavFocus.test.tsx
new file mode 100644
index 0000000000..109ff32579
--- /dev/null
+++ b/packages/core/src/MobileNav/MobileNavFocus.test.tsx
@@ -0,0 +1,553 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavFocus.test.tsx
+ * @input Uses vitest, @testing-library/react, MobileNav + AppShell + SideNav
+ * @output Regression tests for focus restoration when the drawer closes
+ * @position Testing; validates the focus restore in MobileNav.tsx
+ *
+ * Repro for the umbrella accessibility issue (#3343): closing the drawer
+ * dropped focus to `<body>` instead of returning it to the element that
+ * opened the drawer.
+ *
+ * jsdom has NO `<dialog>` implementation at all — `HTMLDialogElement.prototype`
+ * exposes only `open`, with no `show`/`showModal`/`close` (verified on
+ * jsdom 27.4.0). The other MobileNav suites polyfill those two methods as
+ * plain attribute toggles, which means focus never moves in the first place
+ * and the defect is invisible.
+ *
+ * These tests model the two halves of real browser behaviour explicitly:
+ * - `showModal()` runs the dialog focusing steps, so focus moves INTO the
+ * drawer. Without this the bug cannot reproduce.
+ * - `close()` does NOT hand focus back. That is the behaviour reported
+ * against Safari 26.5.2, and it is what the component must not depend on.
+ *
+ * The native close is deferred past the slide-out (#4290), and the restore has
+ * to follow it: while a modal <dialog> holds the top layer the rest of the
+ * document is inert, so `focus()` on the opener is silently dropped. jsdom has
+ * no top layer and cannot reproduce that, so these tests pin the call order
+ * and the timing directly instead.
+ *
+ * SYNC: When MobileNav.tsx's focus handling changes, update these tests.
+ */
+
+import {
+ describe,
+ it,
+ expect,
+ vi,
+ beforeAll,
+ beforeEach,
+ afterEach,
+} from 'vitest';
+import {useState} from 'react';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import {MobileNav} from './MobileNav';
+import {AppShell} from '../AppShell/AppShell';
+import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
+import {stubMatchMedia} from '../__tests__/stubMatchMedia';
+
+beforeAll(() => {
+ // Model the dialog focusing steps: showModal() moves focus into the dialog.
+ HTMLDialogElement.prototype.showModal = function (this: HTMLDialogElement) {
+ this.setAttribute('open', '');
+ const target = this.querySelector<HTMLElement>('[tabindex]');
+ target?.focus();
+ };
+ // Deliberately does NOT restore focus — mirrors the reported Safari
+ // behaviour the component must not rely on.
+ HTMLDialogElement.prototype.close = function (this: HTMLDialogElement) {
+ this.removeAttribute('open');
+ };
+});
+
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+// AppShell needs its breakpoint query to match, but a blanket `matches: true`
+// would also match `prefers-reduced-motion`, which caps the close delay at 0.
+// The restore has to wait for that delay, so keep the real one in play.
+beforeEach(() => {
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+ stubMatchMedia({reduceMotion: false});
+});
+
+afterEach(() => {
+ document.documentElement.style.overflow = '';
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+});
+
+/** Controlled standalone harness with a real trigger button. */
+function StandaloneHarness({onMounted}: {onMounted?: () => void} = {}) {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <button
+ type="button"
+ data-testid="trigger"
+ onClick={() => {
+ onMounted?.();
+ setIsOpen(true);
+ }}>
+ Open nav
+ </button>
+ <MobileNav
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ side="start"
+ data-testid="nav">
+ <a href="/home" data-testid="nav-link">
+ Home
+ </a>
+ </MobileNav>
+ </>
+ );
+}
+
+/** Standalone harness whose whole subtree — trigger included — can unmount. */
+function UnmountHarness() {
+ const [isMounted, setIsMounted] = useState(true);
+ return (
+ <>
+ <button
+ type="button"
+ data-testid="unmount"
+ onClick={() => setIsMounted(false)}>
+ Unmount
+ </button>
+ {isMounted ? <StandaloneHarness /> : null}
+ </>
+ );
+}
+
+/** The drawer alone can unmount; the trigger stays in the document. */
+function DrawerUnmountHarness() {
+ const [isOpen, setIsOpen] = useState(false);
+ const [hasDrawer, setHasDrawer] = useState(true);
+ return (
+ <>
+ <button
+ type="button"
+ data-testid="trigger"
+ onClick={() => setIsOpen(true)}>
+ Open nav
+ </button>
+ <button
+ type="button"
+ data-testid="unmount-drawer"
+ onClick={() => setHasDrawer(false)}>
+ Unmount drawer
+ </button>
+ {hasDrawer ? (
+ <MobileNav
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ side="start"
+ data-testid="nav">
+ <span>Content</span>
+ </MobileNav>
+ ) : null}
+ </>
+ );
+}
+
+/** Removes the trigger from the DOM in the same commit that closes the drawer. */
+function DetachHarness() {
+ const [isOpen, setIsOpen] = useState(false);
+ const [hasTrigger, setHasTrigger] = useState(true);
+ return (
+ <>
+ {hasTrigger ? (
+ <button
+ type="button"
+ data-testid="trigger"
+ onClick={() => setIsOpen(true)}>
+ Open nav
+ </button>
+ ) : null}
+ <button
+ type="button"
+ data-testid="detach"
+ onClick={() => {
+ setHasTrigger(false);
+ setIsOpen(false);
+ }}>
+ Detach
+ </button>
+ <MobileNav isOpen={isOpen} onOpenChange={setIsOpen} side="start">
+ <span>Content</span>
+ </MobileNav>
+ </>
+ );
+}
+
+/** Opens the drawer without ever focusing the button that opens it. */
+function BodyHarness() {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <button
+ type="button"
+ data-testid="programmatic"
+ onClick={() => setIsOpen(v => !v)}>
+ Toggle
+ </button>
+ <MobileNav isOpen={isOpen} onOpenChange={setIsOpen} side="start">
+ <span>Content</span>
+ </MobileNav>
+ </>
+ );
+}
+
+function AppShellHarness() {
+ return (
+ <AppShell
+ sideNav={
+ <SideNav>
+ <SideNavSection title="Test" isHeaderHidden>
+ <SideNavItem label="Home" />
+ </SideNavSection>
+ </SideNav>
+ }
+ mobileNav={{breakpoint: 'md'}}>
+ <div>Content</div>
+ </AppShell>
+ );
+}
+
+/** Opens the standalone drawer from a focused trigger and returns the trigger. */
+function openFromTrigger(): HTMLElement {
+ const trigger = screen.getByTestId('trigger');
+ trigger.focus();
+ fireEvent.click(trigger);
+ // showModal() pulled focus into the drawer.
+ expect(trigger).not.toHaveFocus();
+ return trigger;
+}
+
+function clickDrawerClose() {
+ fireEvent.click(screen.getByRole('button', {name: /close navigation/i}));
+}
+
+describe('MobileNav focus restoration', () => {
+ it('returns focus to the trigger when the drawer closes (standalone)', () => {
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(trigger).toHaveFocus();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('returns focus to the hamburger toggle when the AppShell drawer closes', () => {
+ vi.useFakeTimers();
+ try {
+ render(<AppShellHarness />);
+
+ const toggle = screen.getByRole('button', {name: /open navigation/i});
+ toggle.focus();
+ fireEvent.click(toggle);
+
+ expect(toggle).not.toHaveFocus();
+
+ // Inside AppShell the drawer sits in an <Activity> that hides on close,
+ // so the native close is the unmount-style teardown, not the delayed
+ // timer. Focus still has to come back, and still only after close().
+ const closeSpy = vi.spyOn(HTMLDialogElement.prototype, 'close');
+ const focusSpy = vi.spyOn(toggle, 'focus');
+
+ fireEvent.click(screen.getByRole('button', {name: /close navigation/i}));
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(document.activeElement).not.toBe(document.body);
+ expect(toggle).toHaveFocus();
+ expect(closeSpy).toHaveBeenCalled();
+ expect(focusSpy.mock.invocationCallOrder[0]).toBeGreaterThan(
+ closeSpy.mock.invocationCallOrder[0],
+ );
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('restores focus only after the native dialog has closed', () => {
+ // Load-bearing ordering contract. Browsers hold the rest of the document
+ // inert while a modal <dialog> is open, so focusing the trigger before
+ // close() would be silently dropped — the exact class of failure this fix
+ // exists to remove. jsdom has no top layer and cannot reproduce that, so
+ // assert the call order directly instead. Restoring when `isOpen` flips
+ // (in an effect or its cleanup) instead of after the deferred close()
+ // breaks this.
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+
+ const closeSpy = vi.spyOn(HTMLDialogElement.prototype, 'close');
+ const focusSpy = vi.spyOn(trigger, 'focus');
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(closeSpy).toHaveBeenCalled();
+ expect(focusSpy).toHaveBeenCalled();
+ expect(focusSpy.mock.invocationCallOrder[0]).toBeGreaterThan(
+ closeSpy.mock.invocationCallOrder[0],
+ );
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('waits for the delayed close before restoring focus', () => {
+ // The close is deferred so the slide-out can play (250ms cap outside
+ // reduced motion). Until it runs the dialog is still modal and the trigger
+ // is inert, so an early restore would be a silent no-op in a browser.
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+ const closeSpy = vi.spyOn(HTMLDialogElement.prototype, 'close');
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(200);
+ });
+
+ expect(closeSpy).not.toHaveBeenCalled();
+ expect(screen.getByTestId('nav')).toHaveAttribute('open');
+ expect(trigger).not.toHaveFocus();
+
+ act(() => {
+ vi.advanceTimersByTime(100);
+ });
+
+ expect(closeSpy).toHaveBeenCalledTimes(1);
+ expect(trigger).toHaveFocus();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('keeps focus in the drawer when it is reopened before the delayed close', () => {
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+ const focusSpy = vi.spyOn(trigger, 'focus');
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(100);
+ });
+ // Reopened while the close was still pending: the dialog never closed,
+ // so there is nothing to hand focus back from.
+ fireEvent.click(trigger);
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(screen.getByTestId('nav')).toHaveAttribute('open');
+ expect(focusSpy).not.toHaveBeenCalled();
+ expect(trigger).not.toHaveFocus();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('returns focus to the original opener after a reopen interrupted the close', () => {
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(100);
+ });
+ // The reopen happens with focus inside the drawer. That element must
+ // not replace the opener the drawer captured on the way in.
+ fireEvent.click(trigger);
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+ expect(trigger).not.toHaveFocus();
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(screen.getByTestId('nav')).not.toHaveAttribute('open');
+ expect(trigger).toHaveFocus();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('restores focus when the drawer unmounts while its delayed close is pending', () => {
+ vi.useFakeTimers();
+ try {
+ render(<DrawerUnmountHarness />);
+ const trigger = openFromTrigger();
+ const closeSpy = vi.spyOn(HTMLDialogElement.prototype, 'close');
+ const focusSpy = vi.spyOn(trigger, 'focus');
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(100);
+ });
+ expect(closeSpy).not.toHaveBeenCalled();
+
+ // Unmounting cancels the timer and closes the dialog on the spot. Focus
+ // goes back to the trigger from that close, and only after it.
+ fireEvent.click(screen.getByTestId('unmount-drawer'));
+
+ expect(screen.queryByTestId('nav')).toBeNull();
+ expect(closeSpy).toHaveBeenCalledTimes(1);
+ expect(trigger).toHaveFocus();
+ expect(focusSpy.mock.invocationCallOrder[0]).toBeGreaterThan(
+ closeSpy.mock.invocationCallOrder[0],
+ );
+
+ // The cancelled timer must not fire a second close later.
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+ expect(closeSpy).toHaveBeenCalledTimes(1);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('returns focus to the trigger even when focus moved inside the drawer first', () => {
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+
+ // User tabs to a link inside the drawer before dismissing it.
+ const link = screen.getByTestId('nav-link');
+ link.focus();
+ expect(link).toHaveFocus();
+
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(trigger).toHaveFocus();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('restores focus when the drawer is closed via Escape', () => {
+ vi.useFakeTimers();
+ try {
+ render(<StandaloneHarness />);
+ const trigger = openFromTrigger();
+
+ const dialog = screen.getByTestId('nav');
+ fireEvent(
+ dialog,
+ new Event('cancel', {bubbles: false, cancelable: true}),
+ );
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(trigger).toHaveFocus();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('does not throw when the drawer unmounts while still open', () => {
+ vi.useFakeTimers();
+ try {
+ render(<UnmountHarness />);
+ openFromTrigger();
+
+ // Unmounting the whole drawer subtree also takes the trigger with it —
+ // the restore must not throw and must not force focus onto a detached
+ // node.
+ expect(() => {
+ fireEvent.click(screen.getByTestId('unmount'));
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+ }).not.toThrow();
+ expect(document.activeElement).toBe(document.body);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('does not throw when the trigger is removed before the drawer closes', () => {
+ vi.useFakeTimers();
+ try {
+ render(<DetachHarness />);
+ const trigger = openFromTrigger();
+
+ // jsdom silently ignores focus() on a detached node, so assert the call
+ // is never made rather than assert on activeElement.
+ const triggerFocus = vi.spyOn(trigger, 'focus');
+ expect(() => {
+ fireEvent.click(screen.getByTestId('detach'));
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+ }).not.toThrow();
+ expect(screen.queryByTestId('trigger')).toBeNull();
+ expect(triggerFocus).not.toHaveBeenCalled();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('leaves focus alone when nothing was focused before opening', () => {
+ vi.useFakeTimers();
+ try {
+ render(<BodyHarness />);
+
+ // fireEvent.click does not focus, so <body> is the "trigger" the drawer
+ // sees when it opens — there is nothing meaningful to restore to.
+ expect(document.activeElement).toBe(document.body);
+ fireEvent.click(screen.getByTestId('programmatic'));
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ // jsdom treats <body> as a non-focusable area, so body.focus() is a
+ // silent no-op there and an activeElement assertion cannot tell the two
+ // implementations apart. Spy on the call itself — in a real browser
+ // body.focus() DOES blur whatever is focused.
+ const bodyFocus = vi.spyOn(document.body, 'focus');
+ clickDrawerClose();
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+
+ expect(bodyFocus).not.toHaveBeenCalled();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});