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.mdnew file mode 100644index 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)++@AKnassadiff --git a/packages/core/src/MobileNav/MobileNav.tsx b/packages/core/src/MobileNav/MobileNav.tsxindex 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.tsxnew file mode 100644index 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();+ }+ });+});