An open source design system that's fully customizable and agent ready
TypeScript
fix(MobileNav): the drawer's content region is a navigation landmark named like the dialog (#10130)
Cindy Zhangd67a7848eeda
diff --git a/.changeset/mobilenav-navigation-landmark.md b/.changeset/mobilenav-navigation-landmark.mdnew file mode 100644index 0000000000..1be3e1427d--- /dev/null+++ b/.changeset/mobilenav-navigation-landmark.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] MobileNav: the drawer's content region is now a navigation landmark (`<nav>`) named like the drawer's dialog, so someone moving by landmarks on a phone finds the drawer's links, as they find SideNav's on a wide screen. SideNav items and a TopNav's drawer content both sit inside that one landmark.++@cixzhangdiff --git a/docs/specs/components/MobileNav/MobileNav.spec.md b/docs/specs/components/MobileNav/MobileNav.spec.mdindex bef16b81c4..f44bfb7a02 100644--- a/docs/specs/components/MobileNav/MobileNav.spec.md+++ b/docs/specs/components/MobileNav/MobileNav.spec.md@@ -48,15 +48,15 @@ system_specs: [spec:AST-094/FR13, spec:AST-094/FR35]## Contract at a glance-| Area | Contract |-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | `MobileNav` with `isOpen`, `onOpenChange`, `header`, `width` (320), `side` (`start`, `end`, `auto`; default `auto`), `label`, and `children`; target `mobile-nav` with a `side` state; `MobileNavToggle` with `label` and `children`. |-| Behavior | A modal native dialog with a drawer that slides in from one inline edge, a header with a Close button, and a scrolling content region. Escape, the backdrop, and Close request closing; the dialog stays open while the drawer starts sliding out and closes within the slide-out (FR5), then focus returns to the opener. |-| End-user impact | Phone users open navigation in a drawer that contains focus, lock the page behind it, close it any usual way, and land back on the control that opened it. |-| Builder impact | None. |-| Compatibility/readiness | Records shipped behavior; no public change. Seven implementation gaps: automatic side selection uses physical position, reduced motion still animates, its own top layer, close hold, and backdrop, a caller `id` disconnects the Toggle, a caller `aria-label` and `onCancel` are dropped, and the drawer has no navigation landmark (see Current-state impact). |-| Review checks | Reject a non-modal drawer, a close that hides the drawer before its slide-out runs, focus not returned to a connected opener, a backdrop click inside the drawer that closes it, or a Toggle rendered outside an enabled AppShell mobile layout. |-| Governing rules | `family:overlay-dismissal`; `architecture:layer-runtime` INV14; `component:AppShell` FR10–FR13; `design:bidirectionality` DR7; `design:reduced-motion` DR1–DR3; `architecture:public-component-api` INV5, INV7; `architecture:component-theming-surface`. |+| Area | Contract |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `MobileNav` with `isOpen`, `onOpenChange`, `header`, `width` (320), `side` (`start`, `end`, `auto`; default `auto`), `label`, and `children`; target `mobile-nav` with a `side` state; `MobileNavToggle` with `label` and `children`. |+| Behavior | A modal native dialog with a drawer that slides in from one inline edge, a header with a Close button, and a scrolling content region. Escape, the backdrop, and Close request closing; the dialog stays open while the drawer starts sliding out and closes within the slide-out (FR5), then focus returns to the opener. |+| End-user impact | Phone users open navigation in a drawer that contains focus, lock the page behind it, close it any usual way, and land back on the control that opened it. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps: automatic side selection uses physical position, reduced motion still animates, its own top layer, close hold, and backdrop, a caller `id` disconnects the Toggle, and a caller `aria-label` and `onCancel` are dropped (see Current-state impact). |+| Review checks | Reject a non-modal drawer, a close that hides the drawer before its slide-out runs, focus not returned to a connected opener, a backdrop click inside the drawer that closes it, or a Toggle rendered outside an enabled AppShell mobile layout. |+| Governing rules | `family:overlay-dismissal`; `architecture:layer-runtime` INV14; `component:AppShell` FR10–FR13; `design:bidirectionality` DR7; `design:reduced-motion` DR1–DR3; `architecture:public-component-api` INV5, INV7; `architecture:component-theming-surface`. |This table is a review projection; the body below is authoritative.@@ -106,10 +106,6 @@ Consumer migration instructions belong in consumer docs and release notes.the backdrop's fade still run, for 0.01 s, rather than changing at once for afine pointer or cross-fading for touch. `design:reduced-motion` DR2 and DR3allow no travel and, for a fine pointer, no animated property.-- **The drawer has no navigation landmark.** The Content region is a plain- element inside the modal dialog, which is not a landmark, so landmark- navigation on a phone finds no navigation. FR14 makes the Content region a- navigation landmark named like the dialog.## Ownership boundarydiff --git a/packages/core/src/MobileNav/MobileNav.test.tsx b/packages/core/src/MobileNav/MobileNav.test.tsxindex 591abf58df..c007056356 100644--- a/packages/core/src/MobileNav/MobileNav.test.tsx+++ b/packages/core/src/MobileNav/MobileNav.test.tsx@@ -10,7 +10,7 @@*/import {describe, it, expect, vi, beforeAll} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {render, screen, within, fireEvent} from '@testing-library/react';import {MobileNav} from './MobileNav';import {declaredValue} from '../__tests__/stylexDeclarations';@@ -247,6 +247,67 @@ describe('MobileNav', () => {);});+ it('puts the drawer content in a navigation landmark named like the dialog', () => {+ const {rerender} = render(+ <MobileNav isOpen={true} onOpenChange={() => {}} header="My Nav">+ <a href="/home">Home</a>+ </MobileNav>,+ );+ const dialog = screen.getByRole('dialog', {name: 'My Nav'});+ const navigation = within(dialog).getByRole('navigation', {+ name: 'My Nav',+ });+ expect(navigation).toContainElement(+ screen.getByRole('link', {name: 'Home'}),+ );+ expect(within(dialog).getAllByRole('navigation')).toHaveLength(1);++ rerender(+ <MobileNav isOpen={true} onOpenChange={() => {}}>+ <a href="/home">Home</a>+ </MobileNav>,+ );+ expect(+ within(screen.getByRole('dialog')).getByRole('navigation', {+ name: 'Navigation',+ }),+ ).toBeInTheDocument();+ });++ it("names the landmark by the caller's aria-labelledby, as the dialog is", () => {+ render(+ <>+ <h2 id="drawer-title">Workspace</h2>+ <MobileNav+ isOpen={true}+ onOpenChange={() => {}}+ aria-labelledby="drawer-title">+ <a href="/home">Home</a>+ </MobileNav>+ </>,+ );+ const dialog = screen.getByRole('dialog', {name: 'Workspace'});+ expect(+ within(dialog).getByRole('navigation', {name: 'Workspace'}),+ ).toBeInTheDocument();+ });++ it("falls back to the dialog's own name when the caller's aria-labelledby resolves to nothing", () => {+ render(+ <MobileNav+ isOpen={true}+ onOpenChange={() => {}}+ header="My Nav"+ aria-labelledby="missing-id">+ <a href="/home">Home</a>+ </MobileNav>,+ );+ const dialog = screen.getByRole('dialog', {name: 'My Nav'});+ expect(+ within(dialog).getByRole('navigation', {name: 'My Nav'}),+ ).toBeInTheDocument();+ });+it('opens dialog via showModal when isOpen becomes true', () => {const {rerender} = render(<MobileNavdiff --git a/packages/core/src/MobileNav/MobileNav.tsx b/packages/core/src/MobileNav/MobileNav.tsxindex 9592be734c..897895d05c 100644--- a/packages/core/src/MobileNav/MobileNav.tsx+++ b/packages/core/src/MobileNav/MobileNav.tsx@@ -701,6 +701,9 @@ export function MobileNav({);const isStart = resolvedSide === 'start';+ const navigationLabel =+ label ??+ (typeof header === 'string' ? header : t('@astryx.mobileNav.navigation'));return (<dialog@@ -723,12 +726,7 @@ export function MobileNav({)}{...rest}data-testid={testId}- aria-label={- label ??- (typeof header === 'string'- ? header- : t('@astryx.mobileNav.navigation'))- }+ aria-label={navigationLabel}// Presses inside the navigation do not reach handlers around where it// is written.{...layerClickBoundary({@@ -773,8 +771,16 @@ export function MobileNav({/></div>- {/* Scrollable content */}- <div {...stylex.props(styles.content)}>{children}</div>+ {/* Scrollable content, the drawer's navigation landmark: a+ modal dialog is not a landmark. */}+ <nav+ // Named as the dialog is: by the caller's aria-labelledby when+ // it resolves, else by the dialog's own label.+ aria-labelledby={rest['aria-labelledby']}+ aria-label={navigationLabel}+ {...stylex.props(styles.content)}>+ {children}+ </nav></div></LayerContentBoundary></LayerDepthProvider>diff --git a/packages/core/src/MobileNav/__tests__/MobileNavLandmark.a11y.chromium.spec.ts b/packages/core/src/MobileNav/__tests__/MobileNavLandmark.a11y.chromium.spec.tsnew file mode 100644index 0000000000..1770ea6276--- /dev/null+++ b/packages/core/src/MobileNav/__tests__/MobileNavLandmark.a11y.chromium.spec.ts@@ -0,0 +1,146 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y scope ^(packages/core/src/(MobileNav|SideNav|TopNav|AppShell)/|apps/storybook/stories/(MobileNav|AppShell)\.stories)++/**+ * @file MobileNavLandmark.a11y.chromium.spec.ts+ * @input Built MobileNav and AppShell stories, real Chromium, and its+ * accessibility tree (CDP)+ * @output Evidence that the open drawer exposes exactly one navigation+ * landmark, named like its dialog, holding the drawer's links, for SideNav+ * items and for a TopNav's drawer content+ * @position Real-engine proof for component:MobileNav FR14; computed role and+ * name need accessibility-tree evidence+ */++import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++let storybook: StaticServer;+test.beforeAll(async () => {+ storybook = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+});+test.afterAll(async () => {+ await storybook?.close();+});++interface AXNode {+ readonly nodeId: string;+ readonly parentId?: string;+ readonly role?: {readonly value?: string};+ readonly name?: {readonly value?: string};+ readonly ignored?: boolean;+}++/** The open dialog's navigation landmarks, from Chromium's own tree. */+async function drawerLandmarks(page: Page) {+ const cdp = await page.context().newCDPSession(page);+ const {nodes} = (await cdp.send('Accessibility.getFullAXTree')) as {+ nodes: AXNode[];+ };+ const byId = new Map(nodes.map(node => [node.nodeId, node]));+ const dialog = nodes.find(+ node => !node.ignored && node.role?.value === 'dialog',+ );+ if (dialog == null) {+ throw new Error('No open dialog in the accessibility tree');+ }+ const insideDialog = (node: AXNode) => {+ for (+ let parent = node.parentId != null ? byId.get(node.parentId) : undefined;+ parent != null;+ parent = parent.parentId != null ? byId.get(parent.parentId) : undefined+ ) {+ if (parent.nodeId === dialog.nodeId) {+ return true;+ }+ }+ return false;+ };+ const landmarks = nodes.filter(+ node =>+ !node.ignored && node.role?.value === 'navigation' && insideDialog(node),+ );+ const linksIn = (landmark: AXNode) =>+ nodes.filter(node => {+ if (node.ignored || node.role?.value !== 'link') {+ return false;+ }+ for (+ let parent =+ node.parentId != null ? byId.get(node.parentId) : undefined;+ parent != null;+ parent = parent.parentId != null ? byId.get(parent.parentId) : undefined+ ) {+ if (parent.nodeId === landmark.nodeId) {+ return true;+ }+ }+ return false;+ }).length;+ return {+ dialogName: dialog.name?.value ?? '',+ landmarks: landmarks.map(node => ({+ name: node.name?.value ?? '',+ links: linksIn(node),+ })),+ };+}++test.describe('MobileNav navigation landmark (Chromium)', () => {+ test('a drawer of SideNav items exposes one navigation landmark named like the dialog', async ({+ page,+ }) => {+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-mobilenav--with-side-nav-children&viewMode=story`,+ );+ await page.getByRole('button', {name: 'Open Drawer'}).click();+ await expect(page.getByRole('dialog')).toBeVisible();+ const {dialogName, landmarks} = await drawerLandmarks(page);+ expect(dialogName).toBe('My App');+ expect(landmarks).toHaveLength(1);+ expect(landmarks[0].name).toBe(dialogName);+ expect(landmarks[0].links).toBeGreaterThan(0);+ });++ test("SideNav's drawer mode in an AppShell on a phone exposes one navigation landmark named like the dialog", async ({+ page,+ }) => {+ await page.setViewportSize({width: 390, height: 844});+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-appshell--side-nav-only&viewMode=story`,+ );+ await page+ .getByRole('button', {name: /navigation|menu/i})+ .first()+ .click();+ await expect(page.getByRole('dialog')).toBeVisible();+ const {dialogName, landmarks} = await drawerLandmarks(page);+ expect(landmarks).toHaveLength(1);+ expect(landmarks[0].name).toBe(dialogName);+ expect(landmarks[0].links).toBeGreaterThan(0);+ });++ test("a TopNav's drawer content on a phone sits inside one navigation landmark named like the dialog", async ({+ page,+ }) => {+ await page.setViewportSize({width: 390, height: 844});+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-appshell--top-nav-with-side-nav&viewMode=story`,+ );+ await page+ .getByRole('button', {name: /navigation|menu/i})+ .first()+ .click();+ await expect(page.getByRole('dialog')).toBeVisible();+ const {dialogName, landmarks} = await drawerLandmarks(page);+ expect(landmarks).toHaveLength(1);+ expect(landmarks[0].name).toBe(dialogName);+ expect(landmarks[0].links).toBeGreaterThan(0);+ });+});