Skip to content

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

TypeScript

fix(core): expose aria-expanded and aria-controls on MobileNav toggle (#3721)

Baraa Hamodid84a3539d874
diff --git a/.changeset/mobilenav-toggle-expanded.md b/.changeset/mobilenav-toggle-expanded.md
new file mode 100644
index 0000000000..69b24acdd9
--- /dev/null
+++ b/.changeset/mobilenav-toggle-expanded.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] MobileNav: the toggle button now exposes `aria-expanded` and references the nav drawer via `aria-controls`, so screen-reader users can tell whether the drawer is open and what the button controls. (#3721)
+@bhamodi
diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsx
index 628f744ce0..ffec53ea2e 100644
--- a/packages/core/src/AppShell/AppShell.tsx
+++ b/packages/core/src/AppShell/AppShell.tsx
@@ -24,6 +24,7 @@ import {
isValidElement,
useCallback,
useEffect,
+ useId,
useMemo,
useRef,
useState,
@@ -600,10 +601,14 @@ export function AppShell({
// =========================================================================
// Mobile context — shared with MobileNavToggle and future TopNav mobile
// =========================================================================
+ // Stable id shared by the drawer (applied as its `id`) and the toggle
+ // (referenced via `aria-controls`) so screen readers know what it controls.
+ const mobileNavId = useId();
const mobileContextValue = useMemo<AppShellMobileContextValue>(
() => ({
isMobile: isBelowBreakpoint,
isMobileNavOpen,
+ mobileNavId,
toggleMobileNav: () =>
mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
@@ -614,6 +619,7 @@ export function AppShell({
[
isBelowBreakpoint,
isMobileNavOpen,
+ mobileNavId,
setMobileNavOpen,
mobileNavEnabled,
mobileNavHasToggle,
diff --git a/packages/core/src/AppShell/AppShellMobileContext.tsx b/packages/core/src/AppShell/AppShellMobileContext.tsx
index 99d9dec125..077ebd798b 100644
--- a/packages/core/src/AppShell/AppShellMobileContext.tsx
+++ b/packages/core/src/AppShell/AppShellMobileContext.tsx
@@ -20,6 +20,14 @@ export interface AppShellMobileContextValue {
isMobile: boolean;
/** Whether the mobile nav drawer is currently open */
isMobileNavOpen: boolean;
+ /**
+ * DOM id of the mobile nav drawer. `AppShell` sets this so the toggle can
+ * point its `aria-controls` at the drawer and the drawer can apply it as its
+ * `id`. Optional: callers that construct this context by hand may omit it, in
+ * which case `MobileNav` falls back to a locally generated id and the toggle
+ * simply drops `aria-controls`.
+ */
+ mobileNavId?: string;
/** Toggle the mobile nav drawer open/closed */
toggleMobileNav: () => void;
/** Open the mobile nav drawer */
diff --git a/packages/core/src/AppShell/useAppShellMobile.doc.mjs b/packages/core/src/AppShell/useAppShellMobile.doc.mjs
index 8d86e8a779..16a910ef12 100644
--- a/packages/core/src/AppShell/useAppShellMobile.doc.mjs
+++ b/packages/core/src/AppShell/useAppShellMobile.doc.mjs
@@ -31,6 +31,12 @@ export const docs = {
description:
'Whether the AppShell-managed mobile navigation drawer is open.',
},
+ {
+ name: 'mobileNavId',
+ type: 'string | undefined',
+ description:
+ 'DOM id of the mobile navigation drawer, set by AppShell. Point aria-controls of a custom toggle at this so screen-reader users know which element the toggle expands. Undefined outside an AppShell that manages the drawer.',
+ },
{
name: 'toggleMobileNav',
type: '() => void',
@@ -111,6 +117,8 @@ export const docsDense = {
isMobile:
'viewport below AppShell mobile nav breakpoint? Use to sync AppShell-adjacent mobile UI',
isMobileNavOpen: 'AppShell-managed mobile nav drawer open?',
+ mobileNavId:
+ 'DOM id of the drawer; point custom toggle aria-controls at it',
toggleMobileNav: 'toggle drawer; no-op when mobile nav disabled',
openMobileNav: 'open drawer; no-op when mobile nav disabled',
closeMobileNav: 'close drawer',
diff --git a/packages/core/src/MobileNav/MobileNav.tsx b/packages/core/src/MobileNav/MobileNav.tsx
index 6686422587..12daba71aa 100644
--- a/packages/core/src/MobileNav/MobileNav.tsx
+++ b/packages/core/src/MobileNav/MobileNav.tsx
@@ -29,6 +29,7 @@
import {
useCallback,
useEffect,
+ useId,
useMemo,
useRef,
useState,
@@ -295,6 +296,10 @@ export function MobileNav({
// Read from AppShell context as fallback
const appShellMobile = useAppShellMobile();
const isOpen = isOpenProp ?? appShellMobile.isMobileNavOpen;
+ // Share the id from AppShell context so the toggle's aria-controls resolves to
+ // this drawer; fall back to a locally generated id when used standalone.
+ const fallbackId = useId();
+ const dialogId = appShellMobile.mobileNavId || fallbackId;
const onOpenChange = useMemo(
() =>
onOpenChangeProp ??
@@ -411,6 +416,7 @@ export function MobileNav({
return (
<dialog
ref={mergeRefs(ref, dialogRef)}
+ id={dialogId}
{...mergeProps(
themeProps('mobile-nav', {side: resolvedSide}),
stylex.props(
diff --git a/packages/core/src/MobileNav/MobileNavToggle.test.tsx b/packages/core/src/MobileNav/MobileNavToggle.test.tsx
new file mode 100644
index 0000000000..fb1bf4825b
--- /dev/null
+++ b/packages/core/src/MobileNav/MobileNavToggle.test.tsx
@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavToggle.test.tsx
+ * @input Uses vitest, @testing-library/react, AppShell + SideNav
+ * @output Unit tests for MobileNavToggle ARIA wiring
+ * @position Testing; validates MobileNavToggle.tsx exposes aria-expanded and
+ * aria-controls so screen-reader users know the drawer state and target.
+ *
+ * SYNC: When MobileNavToggle.tsx changes, update tests to match new behavior
+ */
+
+import {
+ describe,
+ it,
+ expect,
+ vi,
+ beforeAll,
+ beforeEach,
+ afterEach,
+} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {AppShell} from '../AppShell/AppShell';
+import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal =
+ HTMLDialogElement.prototype.showModal ||
+ function (this: HTMLDialogElement) {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close =
+ HTMLDialogElement.prototype.close ||
+ function (this: HTMLDialogElement) {
+ this.removeAttribute('open');
+ };
+});
+
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+vi.stubGlobal('ResizeObserver', MockResizeObserver);
+
+function createMockMatchMedia(matches: boolean) {
+ return {
+ matches,
+ media: '',
+ onchange: null,
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ addListener: vi.fn(),
+ removeListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ };
+}
+
+beforeEach(() => {
+ // Below the breakpoint so the mobile nav (and its toggle) render.
+ vi.stubGlobal(
+ 'matchMedia',
+ vi.fn().mockReturnValue(createMockMatchMedia(true)),
+ );
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+function TestShell() {
+ return (
+ <AppShell
+ sideNav={
+ <SideNav>
+ <SideNavSection title="Test" isHeaderHidden>
+ <SideNavItem label="Home" />
+ </SideNavSection>
+ </SideNav>
+ }
+ mobileNav={{breakpoint: 'md'}}>
+ <div>Content</div>
+ </AppShell>
+ );
+}
+
+describe('MobileNavToggle ARIA wiring', () => {
+ it('exposes aria-expanded="false" when the drawer is closed', () => {
+ render(<TestShell />);
+
+ const toggle = screen.getByRole('button', {name: /open navigation/i});
+ expect(toggle).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('exposes aria-expanded="true" after opening the drawer', () => {
+ render(<TestShell />);
+
+ const toggle = screen.getByRole('button', {name: /open navigation/i});
+ fireEvent.click(toggle);
+ expect(toggle).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('references the nav drawer via aria-controls that resolves to the dialog', () => {
+ render(<TestShell />);
+
+ const toggle = screen.getByRole('button', {name: /open navigation/i});
+ const controls = toggle.getAttribute('aria-controls');
+ expect(controls).toBeTruthy();
+
+ const target = document.getElementById(controls!);
+ expect(target).not.toBeNull();
+ expect(target).toBe(screen.getAllByRole('dialog', {hidden: true})[0]);
+ expect(target?.tagName).toBe('DIALOG');
+ });
+});
diff --git a/packages/core/src/MobileNav/MobileNavToggle.tsx b/packages/core/src/MobileNav/MobileNavToggle.tsx
index 6ed5a9c991..2a567ca1fc 100644
--- a/packages/core/src/MobileNav/MobileNavToggle.tsx
+++ b/packages/core/src/MobileNav/MobileNavToggle.tsx
@@ -69,7 +69,13 @@ export function MobileNavToggle({
}: MobileNavToggleProps) {
const t = useTranslator();
const label = labelFromProps ?? t('@astryx.mobileNav.toggle.open');
- const {isMobile, isMobileNavEnabled, toggleMobileNav} = useAppShellMobile();
+ const {
+ isMobile,
+ isMobileNavEnabled,
+ isMobileNavOpen,
+ mobileNavId,
+ toggleMobileNav,
+ } = useAppShellMobile();
// Don't render above the breakpoint or when mobile nav is disabled
if (!isMobile || !isMobileNavEnabled) {
@@ -83,6 +89,8 @@ export function MobileNavToggle({
label={label}
icon={children ?? <Icon icon="menu" color="inherit" />}
onClick={toggleMobileNav}
+ aria-expanded={isMobileNavOpen}
+ aria-controls={mobileNavId || undefined}
data-testid={testId ?? 'mobile-nav-toggle'}
xstyle={xstyle}
className={className}