An open source design system that's fully customizable and agent ready
TypeScript
feat(MobileNav): add XDSMobileNav drawer, useMediaQuery hook, and menu icon (#341)
Cindy Zhang904e6f7eba66
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsxindex 2183ef8f40..cb146eacd1 100644--- a/apps/storybook/stories/AppShell.stories.tsx+++ b/apps/storybook/stories/AppShell.stories.tsx@@ -6,6 +6,7 @@ import {XDSBadge} from '@xds/core/Badge';import {XDSButton} from '@xds/core/Button';import {XDSIcon} from '@xds/core/Icon';import {XDSText} from '@xds/core/Text';+import {XDSMobileNav} from '@xds/core/MobileNav';import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';import {XDSNavIcon} from '@xds/core/NavIcon';import {@@ -14,6 +15,7 @@ import {XDSSideNavItem,XDSSideNavSection,} from '@xds/core/SideNav';+import {useMediaQuery} from '@xds/core/hooks';import * as stylex from '@stylexjs/stylex';import {spacingVars} from '@xds/core/theme/tokens.stylex';import {@@ -479,3 +481,127 @@ export const WithBanner: Story = {</XDSAppShell>),};++/**+ * Responsive layout with mobile navigation drawer. Shows the recommended+ * pattern for apps that need to work across desktop and mobile:+ *+ * - Desktop (>768px): Standard AppShell with TopNav + inline SideNav+ * - Mobile (≤768px): SideNav hides, TopNav shows a hamburger button that+ * opens the `mobileNav` drawer (an XDSMobileNav rendered by AppShell)+ *+ * The nav sections are defined once and shared between `sideNav` and+ * `mobileNav`. AppShell handles rendering the XDSMobileNav internally —+ * you just pass the content and control open/close state.+ *+ * Resize the viewport or use Storybook's viewport addon to see the+ * transition between layouts.+ */+export const WithMobileNav: Story = {+ name: 'With Mobile Nav',+ render: function WithMobileNavStory() {+ const isMobile = useMediaQuery('(max-width: 768px)');+ const [mobileNavOpen, setMobileNavOpen] = useState(false);++ const navSections = (+ <>+ <XDSSideNavSection title="Main" isHeaderHidden>+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="#"+ />+ <XDSSideNavItem+ label="Analytics"+ icon={ChartBarIcon}+ selectedIcon={ChartBarIconSolid}+ href="#"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ selectedIcon={FolderIconSolid}+ href="#"+ endContent={<XDSBadge>12</XDSBadge>}+ />+ </XDSSideNavSection>+ <XDSSideNavSection title="Organization">+ <XDSSideNavItem+ label="Team"+ icon={UserGroupIcon}+ selectedIcon={UserGroupIconSolid}+ href="#"+ />+ <XDSSideNavItem+ label="Settings"+ icon={Cog6ToothIcon}+ selectedIcon={Cog6ToothIconSolid}+ href="#"+ />+ </XDSSideNavSection>+ </>+ );++ return (+ <XDSAppShell+ topNav={+ <XDSTopNav+ label="Main navigation"+ title={+ <XDSTopNavTitle+ title="Acme App"+ logo={+ <XDSNavIcon+ icon={<CubeIcon style={{width: 16, height: 16}} />}+ />+ }+ />+ }+ startContent={+ isMobile ? (+ <XDSButton+ label="Menu"+ variant="ghost"+ icon={<XDSIcon icon="menu" color="inherit" />}+ onClick={() => setMobileNavOpen(true)}+ />+ ) : (+ <>+ <XDSTopNavItem label="Home" href="#" isSelected />+ <XDSTopNavItem label="Products" href="#" />+ <XDSTopNavItem label="Docs" href="#" />+ </>+ )+ }+ endContent={+ <>+ <XDSButton+ label="Notifications"+ variant="ghost"+ icon={<BellIcon style={{width: 16, height: 16}} />}+ />+ <XDSButton+ label="Profile"+ variant="ghost"+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}+ />+ </>+ }+ />+ }+ sideNav={<XDSSideNav>{navSections}</XDSSideNav>}+ mobileNav={+ <XDSMobileNav+ isOpen={mobileNavOpen}+ onClose={() => setMobileNavOpen(false)}+ title="Acme App">+ {navSections}+ </XDSMobileNav>+ }>+ <MockContent />+ </XDSAppShell>+ );+ },+};diff --git a/apps/storybook/stories/MobileNav.stories.tsx b/apps/storybook/stories/MobileNav.stories.tsxnew file mode 100644index 0000000000..50b273d102--- /dev/null+++ b/apps/storybook/stories/MobileNav.stories.tsx@@ -0,0 +1,334 @@+import {useState} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {XDSMobileNav} from '@xds/core/MobileNav';+import {+ XDSSideNav,+ XDSSideNavHeader,+ XDSSideNavItem,+ XDSSideNavSection,+} from '@xds/core/SideNav';+import {XDSButton} from '@xds/core/Button';+import {XDSIcon} from '@xds/core/Icon';+import {XDSNavIcon} from '@xds/core/NavIcon';+import {useMediaQuery} from '@xds/core/hooks';+import {+ HomeIcon,+ FolderIcon,+ Cog6ToothIcon,+ ChartBarIcon,+ UserGroupIcon,+ CubeIcon,+} from '@heroicons/react/24/outline';+import {+ HomeIcon as HomeIconSolid,+ FolderIcon as FolderIconSolid,+} from '@heroicons/react/24/solid';++// =============================================================================+// Meta+// =============================================================================++const meta: Meta<typeof XDSMobileNav> = {+ title: 'Navigation/XDSMobileNav',+ component: XDSMobileNav,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+};++export default meta;+type Story = StoryObj<typeof XDSMobileNav>;++// =============================================================================+// Default+// =============================================================================++export const Default: Story = {+ render: () => {+ const [isOpen, setIsOpen] = useState(false);+ return (+ <>+ <XDSButton+ label="Open Navigation"+ icon={<XDSIcon icon="menu" color="inherit" />}+ variant="ghost"+ onClick={() => setIsOpen(true)}+ />+ <XDSMobileNav+ isOpen={isOpen}+ onClose={() => setIsOpen(false)}+ title="Navigation">+ <XDSSideNavSection title="Main">+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ selectedIcon={FolderIconSolid}+ href="/projects"+ />+ <XDSSideNavItem+ label="Analytics"+ icon={ChartBarIcon}+ href="/analytics"+ />+ </XDSSideNavSection>+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem+ label="General"+ icon={Cog6ToothIcon}+ href="/settings"+ />+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />+ </XDSSideNavSection>+ </XDSMobileNav>+ </>+ );+ },+};++// =============================================================================+// With SideNav Children+// =============================================================================++export const WithSideNavChildren: Story = {+ name: 'With SideNav Children',+ render: () => {+ const [isOpen, setIsOpen] = useState(false);++ const navSections = (+ <>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ selectedIcon={FolderIconSolid}+ href="/projects"+ />+ <XDSSideNavItem+ label="Analytics"+ icon={ChartBarIcon}+ href="/analytics"+ />+ </XDSSideNavSection>+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem+ label="General"+ icon={Cog6ToothIcon}+ href="/settings"+ />+ </XDSSideNavSection>+ </>+ );++ return (+ <>+ <XDSButton label="Open Drawer" onClick={() => setIsOpen(true)} />+ <XDSMobileNav+ isOpen={isOpen}+ onClose={() => setIsOpen(false)}+ title="My App">+ {navSections}+ </XDSMobileNav>+ </>+ );+ },+};++// =============================================================================+// Responsive Pattern+// =============================================================================++export const ResponsivePattern: Story = {+ name: 'Responsive Pattern',+ render: () => {+ const isMobile = useMediaQuery('(max-width: 768px)');+ const [drawerOpen, setDrawerOpen] = useState(false);++ const navSections = (+ <>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ selectedIcon={FolderIconSolid}+ href="/projects"+ />+ <XDSSideNavItem+ label="Analytics"+ icon={ChartBarIcon}+ href="/analytics"+ />+ </XDSSideNavSection>+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem+ label="General"+ icon={Cog6ToothIcon}+ href="/settings"+ />+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />+ </XDSSideNavSection>+ </>+ );++ if (isMobile) {+ return (+ <>+ <XDSButton+ label="Menu"+ icon={<XDSIcon icon="menu" color="inherit" />}+ variant="ghost"+ onClick={() => setDrawerOpen(true)}+ />+ <XDSMobileNav+ isOpen={drawerOpen}+ onClose={() => setDrawerOpen(false)}+ title="My App">+ {navSections}+ </XDSMobileNav>+ </>+ );+ }++ return (+ <div style={{width: 280, height: 600, border: '1px solid #e5e7eb'}}>+ <XDSSideNav+ header={+ <XDSSideNavHeader+ icon={+ <XDSNavIcon+ icon={<CubeIcon style={{width: 16, height: 16}} />}+ />+ }+ title="My App"+ titleHref="/"+ />+ }>+ {navSections}+ </XDSSideNav>+ </div>+ );+ },+};++// =============================================================================+// End Side+// =============================================================================++export const EndSide: Story = {+ name: 'End Side',+ render: () => {+ const [isOpen, setIsOpen] = useState(false);+ return (+ <>+ <XDSButton label="Open from Right" onClick={() => setIsOpen(true)} />+ <XDSMobileNav+ isOpen={isOpen}+ onClose={() => setIsOpen(false)}+ title="Settings"+ side="end">+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem+ label="General"+ icon={Cog6ToothIcon}+ href="/settings"+ />+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />+ </XDSSideNavSection>+ </XDSMobileNav>+ </>+ );+ },+};++// =============================================================================+// Custom Width+// =============================================================================++export const CustomWidth: Story = {+ name: 'Custom Width',+ render: () => {+ const [isOpen, setIsOpen] = useState(false);+ return (+ <>+ <XDSButton label="Open Wide Drawer" onClick={() => setIsOpen(true)} />+ <XDSMobileNav+ isOpen={isOpen}+ onClose={() => setIsOpen(false)}+ title="Wide Navigation"+ width={360}>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ href="/projects"+ />+ </XDSSideNavSection>+ </XDSMobileNav>+ </>+ );+ },+};++// =============================================================================+// Without Title+// =============================================================================++export const WithoutTitle: Story = {+ name: 'Without Title',+ render: () => {+ const [isOpen, setIsOpen] = useState(false);+ return (+ <>+ <XDSButton+ label="Open Navigation"+ icon={<XDSIcon icon="menu" color="inherit" />}+ variant="ghost"+ onClick={() => setIsOpen(true)}+ />+ <XDSMobileNav isOpen={isOpen} onClose={() => setIsOpen(false)}>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ href="/projects"+ />+ </XDSSideNavSection>+ </XDSMobileNav>+ </>+ );+ },+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 2e3b000e57..d957dfc75f 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -172,6 +172,12 @@"import": "./dist/List/index.mjs","require": "./dist/List/index.js"},+ "./MobileNav": {+ "source": "./src/MobileNav/index.ts",+ "types": "./dist/MobileNav/index.d.ts",+ "import": "./dist/MobileNav/index.mjs",+ "require": "./dist/MobileNav/index.js"+ },"./NavIcon": {"source": "./src/NavIcon/index.ts","types": "./dist/NavIcon/index.d.ts",diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.mdindex a0da331086..46f41aa524 100644--- a/packages/core/src/AppShell/README.md+++ b/packages/core/src/AppShell/README.md@@ -107,6 +107,52 @@ For landing pages or simple apps that don't need secondary navigation.</XDSAppShell>```+### Responsive: SideNav + MobileNav++For apps that need both desktop and mobile layouts, use the `mobileNav` slot.+On desktop the SideNav renders inline; on mobile AppShell hides the SideNav+(via `sideNavBreakpoint`) and the consumer shows an XDSMobileNav drawer instead.++Pass a fully composed `<XDSMobileNav>` — AppShell just renders it, same as+every other slot. All drawer props (`isOpen`, `onClose`, `title`) stay on+XDSMobileNav where they belong.++```tsx+const [mobileOpen, setMobileOpen] = useState(false);+const isMobile = useMediaQuery('(max-width: 768px)');++<XDSAppShell+ topNav={+ <XDSTopNav+ label="Navigation"+ title={<XDSTopNavTitle title="My App" />}+ startContent={+ isMobile ? (+ <XDSButton+ label="Menu"+ icon={<XDSIcon icon="menu" color="inherit" />}+ variant="ghost"+ onClick={() => setMobileOpen(true)}+ />+ ) : (+ <XDSTopNavItem label="Home" href="/" isSelected />+ )+ }+ />+ }+ sideNav={<XDSSideNav>{navSections}</XDSSideNav>}+ mobileNav={+ <XDSMobileNav+ isOpen={mobileOpen}+ onClose={() => setMobileOpen(false)}+ title="My App">+ {navSections}+ </XDSMobileNav>+ }>+ <Content />+</XDSAppShell>;+```+### Pattern Summary| Layout | TopNav | SideNav Header | When to use |@@ -150,6 +196,7 @@ For landing pages or simple apps that don't need secondary navigation.| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior || `isSideNavCollapsed` | `boolean` | — | Whether sideNav is collapsed (controlled) || `initialIsSideNavCollapsed` | `boolean` | `false` | Initial collapsed state (uncontrolled) |+| `mobileNav` | `ReactNode` | — | Mobile navigation (typically XDSMobileNav) || `onSideNavCollapsedChange` | `(isCollapsed: boolean) => void` | — | Collapse change callback || `sideNavBreakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Breakpoint for auto-collapse || `sideNavWidth` | `number` | `260` | SideNav width in pixels |diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsxindex 46c02b06cb..fa75e406da 100644--- a/packages/core/src/AppShell/XDSAppShell.test.tsx+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx@@ -7,9 +7,32 @@* SYNC: When XDSAppShell.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';+import {+ describe,+ it,+ expect,+ vi,+ beforeAll,+ beforeEach,+ afterEach,+} from 'vitest';import {render, screen, fireEvent, act} from '@testing-library/react';import {XDSAppShell} from './XDSAppShell';+import {XDSMobileNav} from '../MobileNav';++// 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');+ };+});// Mock ResizeObserverclass MockResizeObserver {@@ -270,10 +293,10 @@ describe('XDSAppShell', () => {});// ===========================================================================- // Mobile overlay+ // Mobile overlay (default XDSMobileNav wrapping sideNav)// ===========================================================================- it('shows overlay sideNav when below breakpoint and not collapsed', () => {+ it('shows default mobile nav when below breakpoint and not collapsed', () => {// Start below breakpoint with sideNav expandedmockMql = createMockMatchMedia(true);vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));@@ -287,13 +310,13 @@ describe('XDSAppShell', () => {</XDSAppShell>,);- // Should show backdrop- expect(screen.getByTestId('sidenav-backdrop')).toBeInTheDocument();- // Should show nav in overlay+ // Should show default mobile nav (XDSMobileNav wrapping sideNav)+ expect(screen.getByTestId('sidenav-mobile')).toBeInTheDocument();+ // Should show nav content inside the mobile navexpect(screen.getByText('Nav Items')).toBeInTheDocument();});- it('clicking backdrop calls onSideNavCollapsedChange', () => {+ it('default mobile nav calls onSideNavCollapsedChange on close', () => {mockMql = createMockMatchMedia(true);vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));@@ -307,25 +330,9 @@ describe('XDSAppShell', () => {</XDSAppShell>,);- fireEvent.click(screen.getByTestId('sidenav-backdrop'));- expect(onChange).toHaveBeenCalledWith(true);- });-- it('pressing Escape closes mobile overlay', () => {- mockMql = createMockMatchMedia(true);- vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));-- const onChange = vi.fn();- render(- <XDSAppShell- sideNav={<div>Nav</div>}- isSideNavCollapsed={false}- onSideNavCollapsedChange={onChange}>- <div>Content</div>- </XDSAppShell>,- );-- fireEvent.keyDown(document, {key: 'Escape'});+ // Click the close button inside the default mobile nav+ const closeButton = screen.getByRole('button', {name: /close/i});+ fireEvent.click(closeButton);expect(onChange).toHaveBeenCalledWith(true);});@@ -459,6 +466,85 @@ describe('XDSAppShell', () => {expect(observeSpy).not.toHaveBeenCalled();});+ // ===========================================================================+ // Mobile nav slot+ // ===========================================================================++ it('renders mobileNav slot content', () => {+ render(+ <XDSAppShell+ sideNav={<div>Side Nav</div>}+ mobileNav={+ <XDSMobileNav+ isOpen={true}+ onClose={() => {}}+ title="Test App"+ data-testid="appshell-mobile-nav">+ <div>Mobile Nav Content</div>+ </XDSMobileNav>+ }>+ <div>Content</div>+ </XDSAppShell>,+ );+ expect(screen.getByTestId('appshell-mobile-nav')).toBeInTheDocument();+ expect(screen.getByText('Mobile Nav Content')).toBeInTheDocument();+ });++ it('does not render mobileNav when not provided', () => {+ render(+ <XDSAppShell sideNav={<div>Side Nav</div>}>+ <div>Content</div>+ </XDSAppShell>,+ );+ expect(screen.queryByTestId('appshell-mobile-nav')).not.toBeInTheDocument();+ });++ it('uses explicit mobileNav instead of default when provided', () => {+ mockMql = createMockMatchMedia(true);+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));++ render(+ <XDSAppShell+ sideNav={<div>Side Nav</div>}+ mobileNav={+ <XDSMobileNav+ isOpen={false}+ onClose={() => {}}+ data-testid="appshell-mobile-nav">+ <div>Mobile Nav</div>+ </XDSMobileNav>+ }+ isSideNavCollapsed={false}+ onSideNavCollapsedChange={() => {}}>+ <div>Content</div>+ </XDSAppShell>,+ );+ // Default mobile nav should NOT appear+ expect(screen.queryByTestId('sidenav-mobile')).not.toBeInTheDocument();+ // Explicit mobileNav slot should be rendered+ expect(screen.getByTestId('appshell-mobile-nav')).toBeInTheDocument();+ });++ it('mobileNav onClose is called when close button is clicked', () => {+ const onClose = vi.fn();+ render(+ <XDSAppShell+ sideNav={<div>Side Nav</div>}+ mobileNav={+ <XDSMobileNav isOpen={true} onClose={onClose} title="Nav">+ <div>Mobile Nav</div>+ </XDSMobileNav>+ }>+ <div>Content</div>+ </XDSAppShell>,+ );+ const closeButton = screen.getByRole('button', {+ name: /close/i,+ });+ fireEvent.click(closeButton);+ expect(onClose).toHaveBeenCalled();+ });+// ===========================================================================// Ref forwarding// ===========================================================================diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsxindex cc296679f9..cae887c8fa 100644--- a/packages/core/src/AppShell/XDSAppShell.tsx+++ b/packages/core/src/AppShell/XDSAppShell.tsx@@ -28,6 +28,7 @@ import {XDSLayout} from '../Layout/XDSLayout';import {XDSLayoutHeader} from '../Layout/XDSLayoutHeader';import {XDSLayoutPanel} from '../Layout/XDSLayoutPanel';import {XDSLayoutContent} from '../Layout/XDSLayoutContent';+import {XDSMobileNav} from '../MobileNav/XDSMobileNav';// =============================================================================// Constants@@ -101,6 +102,18 @@ export interface XDSAppShellProps {*/isSideNavCollapsed?: boolean;+ /**+ * Mobile navigation — typically an XDSMobileNav.+ *+ * When provided, replaces the default mobile drawer that AppShell renders+ * for sideNav below the breakpoint. The consumer owns the XDSMobileNav+ * element and its open/close state, just like topNav and sideNav.+ *+ * When not provided, AppShell automatically wraps sideNav in an+ * XDSMobileNav for the mobile breakpoint.+ */+ mobileNav?: ReactNode;+/*** Callback when side nav collapsed state changes.*/@@ -211,29 +224,6 @@ const styles = stylex.create({banner: {flexShrink: 0,},- // Mobile overlay sideNav- overlay: {- position: 'fixed',- inset: 0,- zIndex: 100,- display: 'flex',- },- backdrop: {- position: 'fixed',- inset: 0,- backgroundColor: colorVars['--color-overlay'],- zIndex: 100,- },- overlaySideNav: {- position: 'relative',- zIndex: 101,- backgroundColor: colorVars['--color-surface'],- overflow: 'auto',- height: '100%',- borderInlineEndWidth: 1,- borderInlineEndStyle: 'solid',- borderInlineEndColor: colorVars['--color-divider'],- },hidden: {display: 'none',},@@ -252,12 +242,6 @@ const styles = stylex.create({},});-const dynamicStyles = stylex.create({- sideNavWidth: (width: number) => ({- width,- }),-});-// =============================================================================// Component// =============================================================================@@ -274,16 +258,14 @@ const dynamicStyles = stylex.create({* ```* <XDSAppShell* topNav={<XDSTopNav label="Navigation" title={<XDSTopNavTitle title="My App" />} />}- * sideNav={- * <XDSSideNav>- * <XDSSideNavSection title="Main" isHeaderHidden>- * <XDSSideNavItem label="Dashboard" isSelected href="/dashboard" />- * <XDSSideNavItem label="Analytics" href="/analytics" />- * </XDSSideNavSection>- * </XDSSideNav>+ * sideNav={<XDSSideNav>{navSections}</XDSSideNav>}+ * mobileNav={+ * <XDSMobileNav isOpen={mobileOpen} onClose={() => setMobileOpen(false)} title="My App">+ * {navSections}+ * </XDSMobileNav>* }* >- * <DashboardContent />+ * <Content />* </XDSAppShell>* ```*/@@ -297,6 +279,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(height = 'fill',initialIsSideNavCollapsed = false,isSideNavCollapsed: controlledCollapsed,+ mobileNav,onSideNavCollapsedChange,sideNav,sideNavBreakpoint = 'md',@@ -323,6 +306,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(const isFill = height === 'fill';const isAuto = height === 'auto';const hasSideNav = sideNav != null;+ const hasMobileNav = mobileNav != null;const hasTopNav = topNav != null;const hasBanner = banner != null;@@ -408,28 +392,15 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(onSideNavCollapsedChange?.(newValue);}, [isCollapsed, isControlled, onSideNavCollapsedChange]);- // =========================================================================- // Close mobile sideNav on Escape- // =========================================================================- useEffect(() => {- if (!isBelowBreakpoint || isCollapsed) return;-- const handleKeyDown = (e: KeyboardEvent) => {- if (e.key === 'Escape') {- e.preventDefault();- handleToggleCollapse();- }- };-- document.addEventListener('keydown', handleKeyDown);- return () => document.removeEventListener('keydown', handleKeyDown);- }, [isBelowBreakpoint, isCollapsed, handleToggleCollapse]);-// =========================================================================// Determine if sideNav should show as overlay (mobile) or inline// =========================================================================const showSideNavInline = hasSideNav && !isCollapsed && !isBelowBreakpoint;- const showSideNavOverlay = hasSideNav && !isCollapsed && isBelowBreakpoint;+ // Default mobile nav: when no explicit mobileNav is provided, AppShell+ // internally renders an XDSMobileNav wrapping the sideNav content.+ // This shares the same <dialog>-based behavior as explicit mobileNav.+ const useDefaultMobileNav =+ hasSideNav && !hasMobileNav && isBelowBreakpoint;// =========================================================================// Build header content (topNav + banner)@@ -525,24 +496,16 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(content={mainContent}/>- {/* Mobile overlay sideNav */}- {showSideNavOverlay && (- <>- <div- {...stylex.props(styles.backdrop)}- onClick={handleToggleCollapse}- data-testid="sidenav-backdrop"- aria-hidden="true"- />- <nav- aria-label="Application navigation"- {...stylex.props(- styles.overlaySideNav,- dynamicStyles.sideNavWidth(sideNavWidth),- )}>- {sideNav}- </nav>- </>+ {/* Mobile nav — either explicit mobileNav or default wrapping sideNav */}+ {mobileNav}+ {useDefaultMobileNav && (+ <XDSMobileNav+ isOpen={!isCollapsed}+ onClose={handleToggleCollapse}+ width={sideNavWidth}+ data-testid="sidenav-mobile">+ {sideNav}+ </XDSMobileNav>)}</div>);diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsxindex 62e8693038..2549c6d36d 100644--- a/packages/core/src/Icon/IconRegistry.tsx+++ b/packages/core/src/Icon/IconRegistry.tsx@@ -37,7 +37,8 @@ export type XDSIconName =| 'info'| 'calendar'| 'clock'- | 'externalLink';+ | 'externalLink'+ | 'menu';/*** Icon registry mapping semantic names to React nodes.diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsxindex ac40819e66..ab4ae4c61e 100644--- a/packages/core/src/Icon/defaultIcons.tsx+++ b/packages/core/src/Icon/defaultIcons.tsx@@ -153,4 +153,11 @@ export const defaultIcons: XDSIconRegistry = {<path d="M10 14L21 3" /></svg>),++ /** ☰ — hamburger menu (three horizontal lines) */+ menu: (+ <svg {...svgProps} strokeWidth={2}>+ <path d="M4 6h16M4 12h16M4 18h16" />+ </svg>+ ),};diff --git a/packages/core/src/MobileNav/README.md b/packages/core/src/MobileNav/README.mdnew file mode 100644index 0000000000..f125770b24--- /dev/null+++ b/packages/core/src/MobileNav/README.md@@ -0,0 +1,170 @@+# MobileNav++Slide-out drawer overlay for mobile navigation. The mobile counterpart to `XDSSideNav` — accepts the same children (`XDSSideNavSection`, `XDSSideNavItem`, or any ReactNode).++## Components++| Component | Description |+| -------------- | ----------------------------------------------------------------- |+| `XDSMobileNav` | Full-height drawer overlay with backdrop, close button, and title |++## Files++| File | Purpose |+| ----------------------- | ---------------- |+| `XDSMobileNav.tsx` | Drawer component |+| `XDSMobileNav.test.tsx` | Unit tests |+| `index.ts` | Public exports |++## Usage++```tsx+import {XDSMobileNav} from '@xds/core/MobileNav';+```++### Basic — hamburger menu with nav links++```tsx+const [isOpen, setIsOpen] = useState(false);++<XDSButton+ label="Menu"+ icon={<MenuIcon />}+ variant="ghost"+ onClick={() => setIsOpen(true)}+/>++<XDSMobileNav+ isOpen={isOpen}+ onClose={() => setIsOpen(false)}+ title="Navigation"+>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" href="/dashboard" isSelected />+ <XDSSideNavItem label="Analytics" href="/analytics" />+ <XDSSideNavItem label="Settings" href="/settings" />+ </XDSSideNavSection>+</XDSMobileNav>+```++### Responsive — sidebar on desktop, drawer on mobile++Use a media query to show `XDSSideNav` on desktop and `XDSMobileNav` on mobile. The same nav items work in both:++```tsx+const isMobile = useMediaQuery('(max-width: 768px)');+const [drawerOpen, setDrawerOpen] = useState(false);++const navSections = (+ <>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" href="/" isSelected />+ <XDSSideNavItem label="Projects" href="/projects" />+ </XDSSideNavSection>+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem label="General" href="/settings" />+ <XDSSideNavItem label="Security" href="/security" />+ </XDSSideNavSection>+ </>+);++{+ isMobile ? (+ <>+ <XDSButton+ label="Menu"+ icon={<MenuIcon />}+ variant="ghost"+ onClick={() => setDrawerOpen(true)}+ />+ <XDSMobileNav+ isOpen={drawerOpen}+ onClose={() => setDrawerOpen(false)}+ title="My App">+ {navSections}+ </XDSMobileNav>+ </>+ ) : (+ <XDSSideNav>{navSections}</XDSSideNav>+ );+}+```++### With top nav items moving to drawer++When top nav items need to collapse into the mobile drawer:++```tsx+const isMobile = useMediaQuery('(max-width: 768px)');+const [drawerOpen, setDrawerOpen] = useState(false);++<XDSTopNav+ title={<XDSTopNavTitle title="My App" />}+ startContent={+ isMobile ? (+ <XDSButton+ label="Menu"+ icon={<MenuIcon />}+ variant="ghost"+ onClick={() => setDrawerOpen(true)}+ />+ ) : (+ <>+ <XDSTopNavItem label="Home" href="/" isSelected />+ <XDSTopNavItem label="Products" href="/products" />+ <XDSTopNavItem label="Docs" href="/docs" />+ </>+ )+ }+/>++<XDSMobileNav isOpen={drawerOpen} onClose={() => setDrawerOpen(false)}>+ <XDSSideNavSection title="Navigation">+ <XDSSideNavItem label="Home" href="/" isSelected />+ <XDSSideNavItem label="Products" href="/products" />+ <XDSSideNavItem label="Docs" href="/docs" />+ </XDSSideNavSection>+</XDSMobileNav>+```++## Props++| Prop | Type | Default | Description |+| ------------- | ------------------ | ------- | ------------------------------------------------- |+| `isOpen` | `boolean` | — | Whether the drawer is open (required) |+| `onClose` | `() => void` | — | Called on backdrop click, escape, or close button |+| `children` | `ReactNode` | — | Drawer content (XDSSideNavSection, items, etc.) |+| `title` | `string` | — | Optional title at the top of the drawer |+| `width` | `number` | `280` | Drawer width in pixels (capped at 85vw) |+| `side` | `'start' \| 'end'` | `start` | Which side the drawer slides from |+| `data-testid` | `string` | — | Test ID for the root element |++## Accessibility++Uses the native `<dialog>` element with `showModal()` for top-layer rendering. The browser provides focus trapping, body scroll lock, and `::backdrop` — no manual z-index needed.++- Native `<dialog>` in top layer (no z-index stacking issues)+- `aria-label` set to title or "Navigation"+- Focus trapping via `showModal()` (browser-native)+- Escape key closes via native `cancel` event+- Backdrop click closes+- Body scroll locked while modal is open++## Composition with XDSSideNav++`XDSMobileNav` and `XDSSideNav` are designed to share children. Extract your nav sections into a variable and render them in both:++```tsx+const sections = (+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Home" href="/" />+ <XDSSideNavItem label="Settings" href="/settings" />+ </XDSSideNavSection>+);++// Desktop: sidebar+<XDSSideNav>{sections}</XDSSideNav>++// Mobile: drawer+<XDSMobileNav isOpen={open} onClose={close}>{sections}</XDSMobileNav>+```diff --git a/packages/core/src/MobileNav/XDSMobileNav.test.tsx b/packages/core/src/MobileNav/XDSMobileNav.test.tsxnew file mode 100644index 0000000000..0cee3c26e0--- /dev/null+++ b/packages/core/src/MobileNav/XDSMobileNav.test.tsx@@ -0,0 +1,191 @@+/**+ * @file XDSMobileNav.test.tsx+ * @input Uses vitest, @testing-library/react, XDSMobileNav component+ * @output Unit tests for XDSMobileNav component behavior+ * @position Testing; validates XDSMobileNav.tsx implementation+ *+ * SYNC: When XDSMobileNav.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi, beforeAll} from 'vitest';+import {render, screen, fireEvent} from '@testing-library/react';+import {XDSMobileNav} from './XDSMobileNav';++// 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');+ };+});++describe('XDSMobileNav', () => {+ it('renders when isOpen is true', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}}>+ <span>Nav content</span>+ </XDSMobileNav>,+ );+ expect(screen.getByRole('dialog')).toBeInTheDocument();+ expect(screen.getByText('Nav content')).toBeInTheDocument();+ });++ it('does not show dialog as open when isOpen is false', () => {+ render(+ <XDSMobileNav isOpen={false} onClose={() => {}} data-testid="mobile-nav">+ <span>Nav content</span>+ </XDSMobileNav>,+ );+ // The dialog element exists but is not open+ const dialog = screen.getByTestId('mobile-nav');+ expect(dialog).toBeInTheDocument();+ expect(dialog).not.toHaveAttribute('open');+ });++ it('calls onClose on native cancel event (Escape)', () => {+ const handleClose = vi.fn();+ render(+ <XDSMobileNav isOpen={true} onClose={handleClose}>+ <span>Content</span>+ </XDSMobileNav>,+ );++ // Native <dialog> fires a cancel event on Escape+ const dialog = screen.getByRole('dialog');+ const cancelEvent = new Event('cancel', {bubbles: false, cancelable: true});+ fireEvent(dialog, cancelEvent);+ expect(handleClose).toHaveBeenCalledTimes(1);+ });++ it('calls onClose on backdrop click (click on dialog itself)', () => {+ const handleClose = vi.fn();+ render(+ <XDSMobileNav+ isOpen={true}+ onClose={handleClose}+ data-testid="mobile-nav">+ <span>Content</span>+ </XDSMobileNav>,+ );++ // Click directly on the dialog element (the transparent overlay area)+ const dialog = screen.getByTestId('mobile-nav');+ fireEvent.click(dialog);+ expect(handleClose).toHaveBeenCalledTimes(1);+ });++ it('does not close on drawer content click', () => {+ const handleClose = vi.fn();+ render(+ <XDSMobileNav isOpen={true} onClose={handleClose}>+ <span>Content</span>+ </XDSMobileNav>,+ );++ fireEvent.click(screen.getByText('Content'));+ expect(handleClose).not.toHaveBeenCalled();+ });++ it('renders close button', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}}>+ <span>Content</span>+ </XDSMobileNav>,+ );++ const closeButton = screen.getByRole('button', {name: /close/i});+ expect(closeButton).toBeInTheDocument();+ });++ it('calls onClose when close button is clicked', () => {+ const handleClose = vi.fn();+ render(+ <XDSMobileNav isOpen={true} onClose={handleClose}>+ <span>Content</span>+ </XDSMobileNav>,+ );++ const closeButton = screen.getByRole('button', {name: /close/i});+ fireEvent.click(closeButton);+ expect(handleClose).toHaveBeenCalledTimes(1);+ });++ it('renders title when provided', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}} title="Navigation">+ <span>Content</span>+ </XDSMobileNav>,+ );++ expect(screen.getByText('Navigation')).toBeInTheDocument();+ });++ it('forwards data-testid', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}} data-testid="custom-nav">+ <span>Content</span>+ </XDSMobileNav>,+ );++ expect(screen.getByTestId('custom-nav')).toBeInTheDocument();+ });++ it('uses native dialog element', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}} data-testid="mobile-nav">+ <span>Content</span>+ </XDSMobileNav>,+ );++ const dialog = screen.getByTestId('mobile-nav');+ expect(dialog.tagName).toBe('DIALOG');+ });++ it('sets aria-label from title', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}} title="My Nav">+ <span>Content</span>+ </XDSMobileNav>,+ );++ expect(screen.getByRole('dialog')).toHaveAttribute('aria-label', 'My Nav');+ });++ it('defaults aria-label to Navigation when no title', () => {+ render(+ <XDSMobileNav isOpen={true} onClose={() => {}}>+ <span>Content</span>+ </XDSMobileNav>,+ );++ expect(screen.getByRole('dialog')).toHaveAttribute(+ 'aria-label',+ 'Navigation',+ );+ });++ it('opens dialog via showModal when isOpen becomes true', () => {+ const {rerender} = render(+ <XDSMobileNav isOpen={false} onClose={() => {}} data-testid="mobile-nav">+ <span>Content</span>+ </XDSMobileNav>,+ );++ const dialog = screen.getByTestId('mobile-nav');+ expect(dialog).not.toHaveAttribute('open');++ rerender(+ <XDSMobileNav isOpen={true} onClose={() => {}} data-testid="mobile-nav">+ <span>Content</span>+ </XDSMobileNav>,+ );++ expect(dialog).toHaveAttribute('open');+ });+});diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsxnew file mode 100644index 0000000000..66c4555750--- /dev/null+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx@@ -0,0 +1,371 @@+/**+ * @file XDSMobileNav.tsx+ * @input Uses React forwardRef, useEffect, useRef, useCallback, ReactNode, StyleX+ * @output Exports XDSMobileNav component and XDSMobileNavProps+ * @position Core implementation; consumed by index.ts+ *+ * Full-height slide-out drawer overlay for mobile navigation.+ * The mobile counterpart to XDSSideNav — accepts the same children+ * (XDSSideNavSection, XDSSideNavItem, or any ReactNode).+ *+ * Uses the native `<dialog>` element with `showModal()` for top-layer rendering.+ * This eliminates z-index stacking issues — the drawer renders above everything+ * without manual z-index management. The browser provides:+ * - Top layer promotion (no z-index needed)+ * - `::backdrop` pseudo-element+ * - Body scroll lock+ * - Focus trapping+ * - Escape key handling via `cancel` event+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/MobileNav/index.ts (exports if types change)+ */++'use client';++import {+ forwardRef,+ useCallback,+ useContext,+ useEffect,+ useRef,+ type ReactNode,+} from 'react';+import * as stylex from '@stylexjs/stylex';+import {colorVars, spacingVars} from '../theme/tokens.stylex';+import {ThemeContext} from '../theme/ThemeContext';+import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';+import {XDSButton} from '../Button';+import {XDSIcon} from '../Icon';+import {XDSHeading} from '../Text/XDSHeading';++// =============================================================================+// Styles+// =============================================================================++const SLIDE_DURATION = '0.25s';+const SLIDE_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';++const styles = stylex.create({+ dialog: {+ // Reset native <dialog> defaults+ position: 'fixed',+ margin: 0,+ padding: 0,+ border: 'none',+ maxWidth: 'none',+ maxHeight: 'none',+ // Full viewport overlay — the dialog itself is the full-screen container+ inset: 0,+ width: '100vw',+ height: '100dvh',+ backgroundColor: 'transparent',+ overflow: 'hidden',+ outline: 'none',+ // Native <dialog> uses display:none when closed — we preserve that+ // by only setting display when [open] via :where() selector.+ // This prevents the dialog from blocking pointer events when closed.+ display: {+ default: 'none',+ ':where([open])': 'flex',+ },+ },+ // ::backdrop is provided by the browser's top layer+ backdrop: {+ '::backdrop': {+ backgroundColor: colorVars['--color-overlay'],+ opacity: 0,+ transition: `opacity ${SLIDE_DURATION} ${SLIDE_EASING}`,+ },+ '@media (prefers-reduced-motion: reduce)': {+ '::backdrop': {+ transitionDuration: '0.01s',+ },+ },+ },+ backdropOpen: {+ '::backdrop': {+ opacity: 1,+ },+ },+ drawer: {+ position: 'absolute',+ top: 0,+ bottom: 0,+ display: 'flex',+ flexDirection: 'column',+ backgroundColor: colorVars['--color-surface'],+ boxSizing: 'border-box',+ overflow: 'hidden',+ transition: `transform ${SLIDE_DURATION} ${SLIDE_EASING}`,+ outline: 'none',+ '@media (prefers-reduced-motion: reduce)': {+ transitionDuration: '0.01s',+ },+ },+ drawerStart: {+ insetInlineStart: 0,+ borderInlineEndWidth: 1,+ borderInlineEndStyle: 'solid',+ borderInlineEndColor: colorVars['--color-divider'],+ transform: {+ default: 'translateX(-100%)',+ ':is([dir="rtl"] *)': 'translateX(100%)',+ },+ },+ drawerStartOpen: {+ transform: 'translateX(0)',+ },+ drawerEnd: {+ insetInlineEnd: 0,+ borderInlineStartWidth: 1,+ borderInlineStartStyle: 'solid',+ borderInlineStartColor: colorVars['--color-divider'],+ transform: {+ default: 'translateX(100%)',+ ':is([dir="rtl"] *)': 'translateX(-100%)',+ },+ },+ drawerEndOpen: {+ transform: 'translateX(0)',+ },+ header: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'space-between',+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-2'],+ flexShrink: 0,+ borderBlockEndWidth: 1,+ borderBlockEndStyle: 'solid',+ borderBlockEndColor: colorVars['--color-divider'],+ },+ headerNoTitle: {+ justifyContent: 'flex-end',+ },+ content: {+ flex: 1,+ overflowY: 'auto',+ overflowX: 'hidden',+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ },+});++const dynamicStyles = stylex.create({+ width: (w: number) => ({+ width: `${w}px`,+ maxWidth: '85vw',+ }),+});++// =============================================================================+// Module Augmentation+// =============================================================================++declare module '../theme/types' {+ interface ComponentStyles {+ mobileNav?: {+ /** Root dialog styles */+ root?: ThemeStyleXStyles;+ /** Drawer panel styles */+ drawer?: ThemeStyleXStyles;+ };+ }+}++// =============================================================================+// Types+// =============================================================================++export interface XDSMobileNavProps {+ /**+ * Whether the drawer is open.+ */+ isOpen: boolean;++ /**+ * Called when the drawer should close (backdrop click, escape, close button).+ */+ onClose: () => void;++ /**+ * Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.+ */+ children: ReactNode;++ /**+ * Optional title shown at the top of the drawer.+ */+ title?: string;++ /**+ * Width of the drawer in pixels.+ * @default 280+ */+ width?: number;++ /**+ * Which side the drawer slides from.+ * @default 'start'+ */+ side?: 'start' | 'end';++ /**+ * Test ID for the root element.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Component+// =============================================================================++/**+ * A slide-out drawer overlay for mobile navigation.+ *+ * The mobile counterpart to XDSSideNav. Renders a full-height drawer that slides+ * in from the start (left in LTR) or end (right in LTR) edge of the viewport,+ * with a semi-transparent backdrop behind it.+ *+ * Uses the native `<dialog>` element with `showModal()` for top-layer rendering,+ * which provides built-in focus trapping, body scroll lock, and `::backdrop`.+ * No manual z-index needed — the browser's top layer handles stacking.+ *+ * @example+ * ```tsx+ * const [isOpen, setIsOpen] = useState(false);+ *+ * <XDSButton label="Menu" onClick={() => setIsOpen(true)} />+ *+ * <XDSMobileNav+ * isOpen={isOpen}+ * onClose={() => setIsOpen(false)}+ * title="Navigation"+ * >+ * <XDSSideNavSection title="Main">+ * <XDSSideNavItem label="Home" icon={HomeIcon} isSelected href="/" />+ * <XDSSideNavItem label="Settings" icon={SettingsIcon} href="/settings" />+ * </XDSSideNavSection>+ * </XDSMobileNav>+ * ```+ */+export const XDSMobileNav = forwardRef<HTMLDialogElement, XDSMobileNavProps>(+ function XDSMobileNav(+ {+ isOpen,+ onClose,+ children,+ title,+ width = 280,+ side = 'start',+ 'data-testid': testId,+ },+ ref,+ ) {+ const dialogRef = useRef<HTMLDialogElement>(null);++ // Merge refs+ const setRefs = useCallback(+ (element: HTMLDialogElement | null) => {+ (+ dialogRef as React.MutableRefObject<HTMLDialogElement | null>+ ).current = element;+ if (typeof ref === 'function') {+ ref(element);+ } else if (ref) {+ ref.current = element;+ }+ },+ [ref],+ );++ // Open/close the dialog via showModal()/close()+ useEffect(() => {+ const dialog = dialogRef.current;+ if (!dialog) return;++ if (isOpen) {+ if (!dialog.open) {+ dialog.showModal();+ }+ } else {+ if (dialog.open) {+ dialog.close();+ }+ }+ }, [isOpen]);++ // Handle native cancel event (Escape key) — prevent default and route through onClose+ const handleCancel = useCallback(+ (event: React.SyntheticEvent<HTMLDialogElement>) => {+ event.preventDefault();+ onClose();+ },+ [onClose],+ );++ // Handle clicks on the dialog backdrop area (outside the drawer)+ const handleDialogClick = useCallback(+ (event: React.MouseEvent<HTMLDialogElement>) => {+ // Only close if click was directly on the dialog element (the transparent overlay),+ // not on the drawer or its children+ if (event.target === event.currentTarget) {+ onClose();+ }+ },+ [onClose],+ );++ // Get theme context for component-level overrides+ const themeContext = useContext(ThemeContext);+ const rootOverride = themeContext?.theme.components?.mobileNav?.root;+ const drawerOverride = themeContext?.theme.components?.mobileNav?.drawer;++ const isStart = side === 'start';++ return (+ <dialog+ ref={setRefs}+ data-testid={testId}+ aria-label={title ?? 'Navigation'}+ onClick={handleDialogClick}+ onCancel={handleCancel}+ {...stylex.props(+ styles.dialog,+ styles.backdrop,+ isOpen && styles.backdropOpen,+ rootOverride,+ )}>+ {/* Drawer panel */}+ <div+ {...stylex.props(+ styles.drawer,+ dynamicStyles.width(width),+ isStart && styles.drawerStart,+ isStart && isOpen && styles.drawerStartOpen,+ !isStart && styles.drawerEnd,+ !isStart && isOpen && styles.drawerEndOpen,+ drawerOverride,+ )}>+ {/* Header with optional title and close button */}+ <div {...stylex.props(styles.header, !title && styles.headerNoTitle)}>+ {title && <XDSHeading level={2}>{title}</XDSHeading>}+ <XDSButton+ variant="ghost"+ label="Close navigation"+ tooltip="Close"+ icon={<XDSIcon icon="close" color="inherit" />}+ onClick={onClose}+ />+ </div>++ {/* Scrollable content */}+ <div {...stylex.props(styles.content)}>{children}</div>+ </div>+ </dialog>+ );+ },+);++XDSMobileNav.displayName = 'XDSMobileNav';diff --git a/packages/core/src/MobileNav/index.ts b/packages/core/src/MobileNav/index.tsnew file mode 100644index 0000000000..1b01e7f7a7--- /dev/null+++ b/packages/core/src/MobileNav/index.ts@@ -0,0 +1,9 @@+/**+ * @file index.ts+ * @input Imports from XDSMobileNav.tsx+ * @output Re-exports XDSMobileNav component and XDSMobileNavProps type+ * @position Barrel export; consumed by packages/core/src/index.ts+ */++export {XDSMobileNav} from './XDSMobileNav';+export type {XDSMobileNavProps} from './XDSMobileNav';diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.tsindex bb6bd9d9b4..0de3772e86 100644--- a/packages/core/src/hooks/index.ts+++ b/packages/core/src/hooks/index.ts@@ -15,3 +15,5 @@ export type {UseGridFocusOptions, UseGridFocusReturn} from './useGridFocus';export {useListFocus} from './useListFocus';export type {UseListFocusOptions, UseListFocusReturn} from './useListFocus';++export {useMediaQuery} from './useMediaQuery';diff --git a/packages/core/src/hooks/useMediaQuery.test.ts b/packages/core/src/hooks/useMediaQuery.test.tsnew file mode 100644index 0000000000..5e89c662a0--- /dev/null+++ b/packages/core/src/hooks/useMediaQuery.test.ts@@ -0,0 +1,116 @@+/**+ * @file useMediaQuery.test.ts+ * @input Uses vitest, @testing-library/react, useMediaQuery hook+ * @output Unit tests for useMediaQuery hook+ * @position Testing; validates useMediaQuery.ts implementation+ *+ * SYNC: When useMediaQuery.ts changes, update tests to match new behavior+ */++import {describe, it, expect, vi, beforeEach} from 'vitest';+import {renderHook, act} from '@testing-library/react';+import {useMediaQuery} from './useMediaQuery';++// Mock matchMedia+function createMockMatchMedia(matches: boolean) {+ const listeners: Array<(e: MediaQueryListEvent) => void> = [];+ return {+ matches,+ media: '',+ onchange: null,+ addEventListener: vi.fn(+ (_event: string, handler: (e: MediaQueryListEvent) => void) => {+ listeners.push(handler);+ },+ ),+ removeEventListener: vi.fn(+ (_event: string, handler: (e: MediaQueryListEvent) => void) => {+ const index = listeners.indexOf(handler);+ if (index > -1) listeners.splice(index, 1);+ },+ ),+ dispatchEvent: vi.fn(),+ // Helper to simulate media query change+ _triggerChange(newMatches: boolean) {+ this.matches = newMatches;+ listeners.forEach(fn => fn({matches: newMatches} as MediaQueryListEvent));+ },+ _listeners: listeners,+ };+}++describe('useMediaQuery', () => {+ let mockMql: ReturnType<typeof createMockMatchMedia>;++ beforeEach(() => {+ mockMql = createMockMatchMedia(false);+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));+ });++ it('returns false on initial render (SSR-safe)', () => {+ const {result} = renderHook(() => useMediaQuery('(max-width: 768px)'));+ // Before the effect runs, should be false+ expect(result.current).toBe(false);+ });++ it('syncs with matchMedia on mount', () => {+ mockMql = createMockMatchMedia(true);+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));++ const {result} = renderHook(() => useMediaQuery('(max-width: 768px)'));+ // After effect, should match the mql state+ expect(result.current).toBe(true);+ });++ it('updates when media query changes', () => {+ const {result} = renderHook(() => useMediaQuery('(max-width: 768px)'));+ expect(result.current).toBe(false);++ act(() => {+ mockMql._triggerChange(true);+ });+ expect(result.current).toBe(true);++ act(() => {+ mockMql._triggerChange(false);+ });+ expect(result.current).toBe(false);+ });++ it('passes the query string to matchMedia', () => {+ renderHook(() => useMediaQuery('(min-width: 1024px)'));+ expect(window.matchMedia).toHaveBeenCalledWith('(min-width: 1024px)');+ });++ it('cleans up event listener on unmount', () => {+ const {unmount} = renderHook(() => useMediaQuery('(max-width: 768px)'));+ expect(mockMql.addEventListener).toHaveBeenCalledWith(+ 'change',+ expect.any(Function),+ );++ unmount();+ expect(mockMql.removeEventListener).toHaveBeenCalledWith(+ 'change',+ expect.any(Function),+ );+ });++ it('re-subscribes when query changes', () => {+ const mockMql2 = createMockMatchMedia(true);+ const matchMediaFn = vi.fn().mockReturnValue(mockMql);+ vi.stubGlobal('matchMedia', matchMediaFn);++ const {result, rerender} = renderHook(+ ({query}: {query: string}) => useMediaQuery(query),+ {initialProps: {query: '(max-width: 768px)'}},+ );+ expect(result.current).toBe(false);++ // Change query+ matchMediaFn.mockReturnValue(mockMql2);+ rerender({query: '(max-width: 1024px)'});+ expect(result.current).toBe(true);+ expect(matchMediaFn).toHaveBeenCalledWith('(max-width: 1024px)');+ });+});diff --git a/packages/core/src/hooks/useMediaQuery.ts b/packages/core/src/hooks/useMediaQuery.tsnew file mode 100644index 0000000000..500595f120--- /dev/null+++ b/packages/core/src/hooks/useMediaQuery.ts@@ -0,0 +1,37 @@+/**+ * @file useMediaQuery.ts+ * @input Uses React useState, useEffect+ * @output Exports useMediaQuery hook for responsive breakpoint detection+ * @position Core hook; used by consumers for responsive patterns+ *+ * SSR-safe media query hook that subscribes to window.matchMedia changes.+ *+ * SYNC: When modified, update:+ * - /packages/core/src/hooks/index.ts+ */++import {useState, useEffect} from 'react';++/**+ * SSR-safe media query hook.+ * Returns whether the given media query matches.+ *+ * @example+ * ```tsx+ * const isMobile = useMediaQuery('(max-width: 768px)');+ * const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');+ * ```+ */+export function useMediaQuery(query: string): boolean {+ const [matches, setMatches] = useState(false); // Always false on first render (SSR-safe)++ useEffect(() => {+ const mql = window.matchMedia(query);+ setMatches(mql.matches); // Sync on mount+ const handler = (e: MediaQueryListEvent) => setMatches(e.matches);+ mql.addEventListener('change', handler);+ return () => mql.removeEventListener('change', handler);+ }, [query]);++ return matches;+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 47e747d718..b171d9d86f 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -48,6 +48,7 @@ export * from './Dialog';export * from './DropdownMenu';export * from './TopNav';export * from './SideNav';+export * from './MobileNav';export * from './ProgressBar';// Layout utilities and components (includes XDSHStack, XDSVStack)diff --git a/packages/themes/default/src/icons.tsx b/packages/themes/default/src/icons.tsxindex 8849c85f3c..ca6e286100 100644--- a/packages/themes/default/src/icons.tsx+++ b/packages/themes/default/src/icons.tsx@@ -20,6 +20,7 @@ import {CalendarDaysIcon,ClockIcon,InformationCircleIcon,+ Bars3Icon,} from '@heroicons/react/24/outline';import {@@ -48,4 +49,5 @@ export const defaultIconRegistry: XDSIconRegistry = {calendar: <CalendarDaysIcon {...iconProps} />,clock: <ClockIcon {...iconProps} />,externalLink: <ArrowTopRightOnSquareIcon {...iconProps} />,+ menu: <Bars3Icon {...iconProps} />,};diff --git a/packages/themes/neutral/src/icons.tsx b/packages/themes/neutral/src/icons.tsxindex b9d3eb702f..eb7d65d1b9 100644--- a/packages/themes/neutral/src/icons.tsx+++ b/packages/themes/neutral/src/icons.tsx@@ -24,6 +24,7 @@ import {Calendar,Clock,ExternalLink,+ Menu,} from 'lucide-react';const iconProps = {@@ -44,4 +45,5 @@ export const neutralIconRegistry: XDSIconRegistry = {calendar: <Calendar {...iconProps} />,clock: <Clock {...iconProps} />,externalLink: <ExternalLink {...iconProps} />,+ menu: <Menu {...iconProps} />,};