Refactor mobile menu to use Popover API

.changeset/clean-flies-start.md

@@ -0,0 +1,23 @@
+---
+'@astrojs/starlight': minor
+---
+
+Simplifies markup for Starlight’s mobile menu toggle
+
+**⚠️ Potentially breaking change:** If you use a theme plugin, custom styles, or component overrides targeting the `MobileMenuToggle` button or `PageFrame` components, you may need to adjust these for the new markup. The button is no longer wrapped in a `<starlight-menu-button>` custom element and no longer uses the `aria-expanded` attribute. Instead, you can use the `.sl-menu-button` class name to target the button and the `:popover-open` pseudo-class to style the menu open state specifically.
+
+In the following example, custom styles for the menu button are updated for the new approach:
+
+```diff
+- starlight-menu-button button {
++ .sl-menu-button {
+  color: var(--sl-color-text);
+}
+
+- starlight-menu-button[aria-expanded='true'] button {
++ .sl-menu-button:has(~ :popover-open) {
+  color: var(--sl-color-text-accent-high);
+}
+```
+
+See [`MobileMenuToggle.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/MobileMenuToggle.astro) and [`PageFrame.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageFrame.astro) on GitHub for the full source code of the updated components.

.changeset/long-jokes-post.md

@@ -0,0 +1,18 @@
+---
+'@astrojs/starlight': minor
+---
+
+Refactors Starlight’s mobile menu toggle to work when JavaScript fails or is disabled
+
+⚠️ **BREAKING CHANGE:** This release drops official support for Chromium-based browsers prior to version 116 (released August 2023), Safari-based browsers prior to version 17.0 (released September 2023), and Firefox prior to version 125 (released April 2024). You can find a list of currently supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+116%2C+Edge+%3E%3D+116%2C+Firefox+%3E%3D+125%2C+Safari+%3E%3D+17.0%2C+iOS+%3E%3D+17.0%2C+not+op_mini+all).
+
+This change also removes the `data-mobile-menu-expanded` attribute, which was previously added to `<body>` while the mobile menu is open. If you have custom code that was depending on this attribute, you will need to update it to use a new selector to check if the mobile menu is open.
+
+In the following example, a custom background colour for the site header while the menu is open is updated for the new approach:
+
+```diff
+- [data-mobile-menu-expanded] header {
++ body:has(sl-sidebar-pane:popover-open) header {
+  background-color: var(--sl-color-bg);
+}
+```

CONTRIBUTING.md

@@ -289,7 +289,7 @@ To add a language, you will need its BCP-47 tag and a label. See [“Adding a ne
 
 - Components that require client-side JavaScript or CSS should use JavaScript/CSS features that are well-supported by browsers.
 
-  You can find a list of supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+111%2C+Edge+%3E%3D+111%2C+Firefox+%3E%3D+121%2C+Safari+%3E%3D+16.4%2C+iOS+%3E%3D+16.4%2C+not+op_mini+all). To check whether or not a feature is supported, you can visit the [Can I use](https://caniuse.com) website and search for the feature.
+  You can find a list of supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+116%2C+Edge+%3E%3D+116%2C+Firefox+%3E%3D+125%2C+Safari+%3E%3D+17.0%2C+iOS+%3E%3D+17.0%2C+not+op_mini+all). To check whether or not a feature is supported, you can visit the [Can I use](https://caniuse.com) website and search for the feature.
 
 [discord]: https://astro.build/chat
 [issues]: https://github.com/withastro/starlight/issues

packages/starlight/__e2e__/basics.test.ts

@@ -779,11 +779,13 @@ test.describe('mobile menu focus trap', () => {
 		await starlight.goto('/headings');
 
 		const currentFocus = page.locator('*:focus');
+		const mainFrame = page.locator('.main-frame');
 
 		// Open the mobile menu.
 		const mobileMenuButton = page.getByRole('button', { name: 'Menu' });
 		await mobileMenuButton.click();
 		await expect(currentFocus).toHaveCount(1);
+		await expect(mainFrame).toHaveAttribute('inert', '');
 
 		// Focus the theme selector, which is the last focusable element in the mobile menu.
 		const themeSelector = page.getByRole('navigation', { name: 'Main' }).getByLabel('Select theme');
@@ -801,6 +803,7 @@ test.describe('mobile menu focus trap', () => {
 		await mobileMenuButton.click();
 
 		// The focus trap should be released and tabbing will focus the mobile table of contents button.
+		await expect(mainFrame).not.toHaveAttribute('inert', '');
 		await page.keyboard.press('Tab');
 		await expect(currentFocus).toHaveText(/On this page/);
 	});
@@ -811,6 +814,7 @@ test.describe('mobile menu focus trap', () => {
 		await starlight.goto('/anchor-heading');
 
 		const currentFocus = page.locator('*:focus');
+		const mainFrame = page.locator('.main-frame');
 		const anchorLinkAccessibleName = 'Section titled “An anchor heading”';
 		const anchorHeadingLink = page.getByRole('link', { name: anchorLinkAccessibleName });
 
@@ -822,6 +826,7 @@ test.describe('mobile menu focus trap', () => {
 		const mobileMenuButton = page.getByRole('button', { name: 'Menu' });
 		await mobileMenuButton.click();
 		await expect(currentFocus).toHaveAccessibleName('Menu');
+		await expect(mainFrame).toHaveAttribute('inert', '');
 
 		// Try to focus the anchor heading which should be prevented by the focus trap,
 		// keeping focus where it is.
@@ -832,11 +837,14 @@ test.describe('mobile menu focus trap', () => {
 		await page.setViewportSize({ width: 1280, height: 720 });
 
 		// The anchor heading link should be focusable again.
+		await expect(mainFrame).not.toHaveAttribute('inert', '');
 		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(mainFrame).not.toHaveAttribute('inert', '');
+		await expect(page.locator('.sidebar-pane:popover-open')).toHaveCount(0);
 		await expect(currentFocus).toHaveText(anchorLinkAccessibleName);
 	});
 });

packages/starlight/src/components/MobileMenuToggle.astro

@@ -2,60 +2,11 @@
 import Icon from '../user-components/Icon.astro';
 ---
 
-<starlight-menu-button class="print:hidden">
-	<button
-		aria-expanded="false"
-		aria-label={Astro.locals.t('menuButton.accessibleLabel')}
-		aria-controls="starlight__sidebar"
-		class="sl-flex md:sl-hidden"
-	>
-		<Icon name="bars" class="open-menu" />
-		<Icon name="close" class="close-menu" />
-	</button>
-</starlight-menu-button>
-
-<script>
-	class StarlightMenuButton extends HTMLElement {
-		btn = this.querySelector('button')!;
-
-		constructor() {
-			super();
-			// Toggle `aria-expanded` state when a user clicks the button.
-			this.btn.addEventListener('click', () => this.toggleExpanded());
-
-			// Close the menu when a user presses the escape key.
-			const parentNav = this.closest('nav');
-			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() {
-			this.setExpanded(this.getAttribute('aria-expanded') !== 'true');
-		}
-
-		closeOnEscape(e: KeyboardEvent) {
-			if (e.code === 'Escape') {
-				this.setExpanded(false);
-				this.btn.focus();
-			}
-		}
-	}
-
-	customElements.define('starlight-menu-button', StarlightMenuButton);
-</script>
+<button popovertarget="starlight__sidebar" class="sl-menu-button sl-flex md:sl-hidden print:hidden">
+	<Icon name="bars" class="open-menu" />
+	<Icon name="close" class="close-menu" />
+	<span class="sr-only">{Astro.locals.t('menuButton.accessibleLabel')}</span>
+</button>
 
 <style>
 	@layer starlight.core {
@@ -75,16 +26,16 @@ import Icon from '../user-components/Icon.astro';
 			cursor: pointer;
 		}
 
-		[aria-expanded='true'] button {
+		button:has(~ :popover-open) {
 			background-color: var(--sl-color-gray-2);
 			box-shadow: none;
 		}
 
-		[aria-expanded='true'] button .open-menu {
+		button:has(~ :popover-open) .open-menu {
 			display: none;
 		}
 
-		:not([aria-expanded='true']) button .close-menu {
+		button:not(:has(~ :popover-open)) .close-menu {
 			display: none;
 		}
 
@@ -93,20 +44,20 @@ import Icon from '../user-components/Icon.astro';
 			color: var(--sl-color-white);
 		}
 
-		:global([data-theme='light']) [aria-expanded='true'] button {
+		:global([data-theme='light']) button:has(~ :popover-open) {
 			background-color: var(--sl-color-gray-5);
 		}
 	}
 </style>
 
 <style is:global>
 	@layer starlight.core {
-		[data-mobile-menu-expanded] {
+		body:has(#starlight__sidebar:popover-open) {
 			overflow: hidden;
 		}
 
 		@media (min-width: 50rem) {
-			[data-mobile-menu-expanded] {
+			body:has(#starlight__sidebar:popover-open) {
 				overflow: auto;
 			}
 		}

packages/starlight/src/components/PageFrame.astro

@@ -10,11 +10,33 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 		hasSidebar && (
 			<nav class="sidebar print:hidden" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
 				<MobileMenuToggle />
-				<div id="starlight__sidebar" class="sidebar-pane">
+				<script>
+					// The mobile menu uses the popover API to open and close without JavaScript. We enhance this
+					// behaviour with focus trapping while the menu is open.
+					class StarlightSidebarPane extends HTMLElement {
+						constructor() {
+							super();
+
+							// Close the menu when the viewport is resized between mobile and desktop sizes.
+							matchMedia('(min-width: 50em)').addEventListener('change', () => this.hidePopover());
+
+							// Update the menu state when the sidebar popover is toggled.
+							this.addEventListener('toggle', ({ newState }) => this.trapFocus(newState === 'open'));
+						}
+						/** Trap keyboard focus inside the header and menu when the menu is expanded. */
+						trapFocus(shouldTrap: boolean) {
+							document.querySelectorAll<HTMLElement>('.main-frame, .sl-skip-link').forEach((el) => {
+								el.toggleAttribute('inert', shouldTrap);
+							});
+						}
+					}
+					customElements.define('sl-sidebar-pane', StarlightSidebarPane);
+				</script>
+				<sl-sidebar-pane popover="" id="starlight__sidebar" class="sidebar-pane">
 					<div class="sidebar-content sl-flex">
 						<slot name="sidebar" />
 					</div>
-				</div>
+				</sl-sidebar-pane>
 			</nav>
 		)
 	}
@@ -48,7 +70,12 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 		}
 
 		.sidebar-pane {
-			visibility: var(--sl-sidebar-visibility, hidden);
+			/* By default, user agents apply some opinionated styles to popovers, which we don’t want. */
+			border: unset;
+			padding: unset;
+			height: unset;
+			color: unset;
+
 			position: fixed;
 			z-index: var(--sl-z-index-menu);
 			inset-block: var(--sl-nav-height) 0;
@@ -59,10 +86,6 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 			scrollbar-gutter: stable;
 		}
 
-		:global([aria-expanded='true']) ~ .sidebar-pane {
-			--sl-sidebar-visibility: visible;
-		}
-
 		.sidebar-content {
 			height: 100%;
 			min-height: max-content;
@@ -88,7 +111,8 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 				padding-inline-end: var(--sl-nav-pad-x);
 			}
 			.sidebar-pane {
-				--sl-sidebar-visibility: visible;
+				/* Make the sidebar visible on larger screens instead of deferring to popover state. */
+				display: block;
 				width: var(--sl-sidebar-width);
 				background-color: var(--sl-color-bg-sidebar);
 				border-inline-end: 1px solid var(--sl-color-hairline-shade);