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.mdnew file mode 100644index 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)+@bhamodidiff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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 fallbackconst 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 (<dialogref={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.tsxnew file mode 100644index 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.tsxindex 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 disabledif (!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}