fix(MobileMenuToggle): trap keyboard focus inside the mobile menu (#3911)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>

Author: 3 people

.changeset/mobile-menu-focus-trap.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Keeps keyboard focus inside the mobile menu while it is open, preventing focus moving to hidden interactive elements in page content.

packages/starlight/__e2e__/basics.test.ts

@@ -772,6 +772,75 @@ test.describe('ToC highlighting', () => {
 	});
 });
 
+test.describe('mobile menu focus trap', () => {
+	test('traps focus within the mobile menu when open', async ({ page, getProdServer }) => {
+		const starlight = await getProdServer();
+		await page.setViewportSize({ width: 375, height: 667 });
+		await starlight.goto('/headings');
+
+		const currentFocus = page.locator('*:focus');
+
+		// Open the mobile menu.
+		const mobileMenuButton = page.getByRole('button', { name: 'Menu' });
+		await mobileMenuButton.click();
+		await expect(currentFocus).toHaveCount(1);
+
+		// Focus the theme selector, which is the last focusable element in the mobile menu.
+		const themeSelector = page.getByRole('navigation', { name: 'Main' }).getByLabel('Select theme');
+		await themeSelector.focus();
+		await expect(currentFocus).toHaveCount(1);
+
+		// Tab out of the menu.
+		await page.keyboard.press('Tab');
+
+		// Tabbing at the end of the mobile menu moves focus out of the viewport, so there should no
+		// longer be any focused element.
+		await expect(currentFocus).toHaveCount(0);
+
+		// Close the mobile menu.
+		await mobileMenuButton.click();
+
+		// The focus trap should be released and tabbing will focus the mobile table of contents button.
+		await page.keyboard.press('Tab');
+		await expect(currentFocus).toHaveText(/On this page/);
+	});
+
+	test('releases focus trap when the viewport resizes', async ({ page, getProdServer }) => {
+		const starlight = await getProdServer();
+		await page.setViewportSize({ width: 375, height: 667 });
+		await starlight.goto('/anchor-heading');
+
+		const currentFocus = page.locator('*:focus');
+		const anchorLinkAccessibleName = 'Section titled “An anchor heading”';
+		const anchorHeadingLink = page.getByRole('link', { name: anchorLinkAccessibleName });
+
+		// Focus the anchor heading link to check it is focusable.
+		await anchorHeadingLink.focus();
+		await expect(currentFocus).toHaveText(anchorLinkAccessibleName);
+
+		// Open the mobile menu.
+		const mobileMenuButton = page.getByRole('button', { name: 'Menu' });
+		await mobileMenuButton.click();
+		await expect(currentFocus).toHaveAccessibleName('Menu');
+
+		// Try to focus the anchor heading which should be prevented by the focus trap,
+		// keeping focus where it is.
+		await anchorHeadingLink.focus();
+		await expect(currentFocus).toHaveAccessibleName('Menu');
+
+		// Resize the viewport to a wider size, which should release the focus trap.
+		await page.setViewportSize({ width: 1280, height: 720 });
+
+		// The anchor heading link should be focusable again.
+		await anchorHeadingLink.focus();
+		await expect(currentFocus).toHaveText(anchorLinkAccessibleName);
+
+		// Resizing back to a smaller viewport should not re-enable the focus trap.
+		await page.setViewportSize({ width: 375, height: 667 });
+		await expect(currentFocus).toHaveText(anchorLinkAccessibleName);
+	});
+});
+
 /**
  * Loads the given `path` in a window of the specified `width` and `height` and checks that the
  * Starlight table of contents is highlighting an item with contents matching `pattern`.

packages/starlight/components/MobileMenuToggle.astro

@@ -28,11 +28,18 @@ import Icon from '../user-components/Icon.astro';
 			if (parentNav) {
 				parentNav.addEventListener('keyup', (e) => this.closeOnEscape(e));
 			}
+
+			// Reset menu state when the viewport toggles between mobile and desktop sizes.
+			matchMedia('(min-width: 50em)').addEventListener('change', () => this.setExpanded(false));
 		}
 
 		setExpanded(expanded: boolean) {
 			this.setAttribute('aria-expanded', String(expanded));
 			document.body.toggleAttribute('data-mobile-menu-expanded', expanded);
+			// Trap keyboard focus inside the header and menu when the menu is expanded.
+			document.querySelectorAll<HTMLElement>('.main-frame, .sl-skip-link').forEach((el) => {
+				el.toggleAttribute('inert', expanded);
+			});
 		}
 
 		toggleExpanded() {

packages/starlight/components/SkipLink.astro

@@ -2,7 +2,7 @@
 import { PAGE_TITLE_ID } from '../constants';
 ---
 
-<a href={`#${PAGE_TITLE_ID}`}>{Astro.locals.t('skipLink.label')}</a>
+<a class="sl-skip-link" href={`#${PAGE_TITLE_ID}`}>{Astro.locals.t('skipLink.label')}</a>
 
 <style>
 	@layer starlight.core {