An open source design system that's fully customizable and agent ready
TypeScript
feat(PageNav): add XDSPageNav component with header, items, and sections (#251)
Cindy Zhangc2e3266c3855
diff --git a/apps/storybook/stories/PageNav.stories.tsx b/apps/storybook/stories/PageNav.stories.tsxnew file mode 100644index 0000000000..57bca33983--- /dev/null+++ b/apps/storybook/stories/PageNav.stories.tsx@@ -0,0 +1,356 @@+import type {Meta, StoryObj} from '@storybook/react';+import {+ XDSPageNav,+ XDSPageNavHeader,+ XDSPageNavItem,+ XDSPageNavSection,+} from '@xds/core/PageNav';+import {XDSBadge} from '@xds/core/Badge';+import {XDSButton} from '@xds/core/Button';+import {XDSDivider} from '@xds/core/Divider';+import {XDSIcon} from '@xds/core/Icon';+import {XDSText} from '@xds/core/Text';+import {XDSVStack} from '@xds/core/Stack';+import {+ HomeIcon,+ FolderIcon,+ Cog6ToothIcon,+ ChartBarIcon,+ UserGroupIcon,+ BellIcon,+ QuestionMarkCircleIcon,+ DocumentTextIcon,+ CubeIcon,+ BuildingOfficeIcon,+ UserIcon,+ PlusIcon,+ ArrowRightStartOnRectangleIcon,+} from '@heroicons/react/24/outline';+import {+ HomeIcon as HomeIconSolid,+ FolderIcon as FolderIconSolid,+} from '@heroicons/react/24/solid';++const meta: Meta<typeof XDSPageNav> = {+ title: 'Navigation/XDSPageNav',+ component: XDSPageNav,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+ decorators: [+ Story => (+ <div style={{width: 280, height: 600, border: '1px solid #e5e7eb'}}>+ <Story />+ </div>+ ),+ ],+};++export default meta;+type Story = StoryObj<typeof XDSPageNav>;++// =============================================================================+// Basic+// =============================================================================++export const Default: Story = {+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ title="My App"+ titleHref="/"+ />+ }>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ />+ <XDSPageNavItem+ label="Projects"+ icon={FolderIcon}+ selectedIcon={FolderIconSolid}+ href="/projects"+ endContent={<XDSBadge label="3" />}+ />+ <XDSPageNavItem+ label="Analytics"+ icon={ChartBarIcon}+ href="/analytics"+ />+ <XDSPageNavItem label="Team" icon={UserGroupIcon} href="/team" />+ </XDSPageNavSection>+ <XDSPageNavSection title="Documents">+ <XDSPageNavItem+ label="All Documents"+ icon={DocumentTextIcon}+ href="/documents"+ />+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};++// =============================================================================+// With Header Menu+// =============================================================================++export const WithHeaderMenu: Story = {+ name: 'Header with Menu',+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ title="Product Name"+ subtitle="Business Account"+ menu={+ <div style={{padding: 12}}>+ <XDSVStack gap="space2">+ <XDSText type="supporting" color="secondary">+ Switch account+ </XDSText>+ <XDSButton+ label="Personal Account"+ icon={<XDSIcon icon={UserIcon} size="sm" />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Acme Corp"+ icon={<XDSIcon icon={BuildingOfficeIcon} size="sm" />}+ variant="ghost"+ size="sm"+ />+ <XDSDivider />+ <XDSButton+ label="Add account"+ icon={<XDSIcon icon={PlusIcon} size="sm" />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Sign out"+ icon={+ <XDSIcon icon={ArrowRightStartOnRectangleIcon} size="sm" />+ }+ variant="ghost"+ size="sm"+ />+ </XDSVStack>+ </div>+ }+ />+ }>+ <XDSPageNavSection title="Navigation">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ />+ <XDSPageNavItem label="Settings" icon={Cog6ToothIcon} />+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};++// =============================================================================+// Suite Header+// =============================================================================++export const SuiteHeader: Story = {+ name: 'Suite with Independent Links',+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ supertitle="Suite Name"+ supertitleHref="/suite"+ title="Product Name"+ titleHref="/product"+ menu={+ <div style={{padding: 12}}>+ <XDSVStack gap="space1">+ <XDSText type="supporting" color="secondary">+ Switch product+ </XDSText>+ <XDSButton+ label="Analytics"+ icon={<XDSIcon icon={ChartBarIcon} size="sm" />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Commerce"+ icon={<XDSIcon icon={CubeIcon} size="sm" />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Team Hub"+ icon={<XDSIcon icon={UserGroupIcon} size="sm" />}+ variant="ghost"+ size="sm"+ />+ </XDSVStack>+ </div>+ }+ />+ }>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ />+ <XDSPageNavItem label="Projects" icon={FolderIcon} />+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};++// =============================================================================+// Nested Items+// =============================================================================++export const NestedItems: Story = {+ name: 'Nested Items',+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ title="My App"+ />+ }>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ />+ <XDSPageNavItem label="Settings" icon={Cog6ToothIcon}>+ <XDSPageNavItem label="General" href="/settings/general" />+ <XDSPageNavItem label="Security" href="/settings/security" />+ <XDSPageNavItem+ label="Notifications"+ href="/settings/notifications"+ />+ </XDSPageNavItem>+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};++// =============================================================================+// With Footer+// =============================================================================++export const WithFooter: Story = {+ name: 'With Footer Icons',+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ title="My App"+ />+ }+ footerIcons={+ <>+ <XDSButton+ label="Help"+ icon={<XDSIcon icon={QuestionMarkCircleIcon} size="md" />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Notifications"+ icon={<XDSIcon icon={BellIcon} size="md" />}+ variant="ghost"+ size="sm"+ />+ </>+ }>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ />+ <XDSPageNavItem label="Projects" icon={FolderIcon} />+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};++// =============================================================================+// Disabled Item+// =============================================================================++export const DisabledItem: Story = {+ name: 'Disabled Items',+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ title="My App"+ />+ }>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ />+ <XDSPageNavItem label="Projects" icon={FolderIcon} />+ <XDSPageNavItem+ label="Analytics (Coming Soon)"+ icon={ChartBarIcon}+ isDisabled+ />+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};++// =============================================================================+// Hidden Section Header+// =============================================================================++export const HiddenSectionHeader: Story = {+ name: 'Hidden Section Header',+ render: () => (+ <XDSPageNav+ header={+ <XDSPageNavHeader+ icon={<XDSIcon icon={CubeIcon} size="lg" />}+ title="My App"+ />+ }>+ <XDSPageNavSection title="Main navigation" isHeaderHidden>+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ />+ <XDSPageNavItem label="Projects" icon={FolderIcon} />+ <XDSPageNavItem label="Analytics" icon={ChartBarIcon} />+ </XDSPageNavSection>+ </XDSPageNav>+ ),+};diff --git a/packages/core/src/PageNav/README.md b/packages/core/src/PageNav/README.mdnew file mode 100644index 0000000000..c7269c1602--- /dev/null+++ b/packages/core/src/PageNav/README.md@@ -0,0 +1,81 @@+# PageNav++Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.++## Components++| Component | Description |+| ------------------- | ----------------------------------------------------------------------------------------- |+| `XDSPageNav` | Container with five zones: header, topContent, children (scrollable), footer, footerIcons |+| `XDSPageNavHeader` | Product/suite/account header with smart interaction boundary logic |+| `XDSPageNavItem` | Navigation item with icon, selected state, and nesting |+| `XDSPageNavSection` | Section grouping with optional title and end content |++## Files++| File | Purpose |+| ----------------------- | ------------------------------------------ |+| `XDSPageNav.tsx` | Container component |+| `XDSPageNavHeader.tsx` | Header component with popover menu support |+| `XDSPageNavItem.tsx` | Navigation item component |+| `XDSPageNavSection.tsx` | Section grouping component |+| `XDSPageNav.test.tsx` | Unit tests |+| `index.ts` | Public exports |++## Usage++```tsx+import {+ XDSPageNav,+ XDSPageNavHeader,+ XDSPageNavItem,+ XDSPageNavSection,+} from '@xds/core/PageNav';++<XDSPageNav+ header={<XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}+ topContent={<XDSButton label="Create new" variant="primary" />}+ footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ />+ <XDSPageNavItem+ label="Projects"+ icon={FolderIcon}+ href="/projects"+ endContent={<XDSBadge label="3" />}+ />+ </XDSPageNavSection>++ <XDSPageNavSection title="Settings">+ <XDSPageNavItem label="General" href="/settings/general" />+ <XDSPageNavItem label="Security" href="/settings/security" />+ </XDSPageNavSection>+</XDSPageNav>;+```++## Header Interaction Model++| Props provided | Behavior |+| --------------------------------------- | -------------------------------------------------------------- |+| `titleHref` only, no menu | Whole header is one link |+| `titleHref` + `supertitleHref`, no menu | Each text is an independent link |+| `menu` only, no hrefs | Whole header is the popover trigger |+| `menu` + hrefs | Links are independent `<a>`, chevron/remaining area is trigger |++## Accessibility++- `<nav aria-label="Page navigation">`+- `aria-current="page"` on selected item+- Sections: `role="group"` with `aria-labelledby`+- Keyboard: Tab through items, Enter/Space to activate++## Dependencies++- `useXDSPopover` — for header menu popover+- `XDSIcon` — for rendering icon components in nav itemsdiff --git a/packages/core/src/PageNav/XDSPageNav.test.tsx b/packages/core/src/PageNav/XDSPageNav.test.tsxnew file mode 100644index 0000000000..f440e81116--- /dev/null+++ b/packages/core/src/PageNav/XDSPageNav.test.tsx@@ -0,0 +1,388 @@+/**+ * @file XDSPageNav.test.tsx+ * @input Uses vitest, @testing-library/react, PageNav components+ * @output Unit tests for XDSPageNav component suite+ * @position Testing; validates PageNav implementations+ *+ * SYNC: When PageNav components change, update tests to match new behavior+ */++import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSPageNav} from './XDSPageNav';+import {XDSPageNavHeader} from './XDSPageNavHeader';+import {XDSPageNavItem} from './XDSPageNavItem';+import {XDSPageNavSection} from './XDSPageNavSection';++// =============================================================================+// XDSPageNav+// =============================================================================++describe('XDSPageNav', () => {+ it('renders with navigation role', () => {+ render(<XDSPageNav>Content</XDSPageNav>);+ expect(screen.getByRole('navigation')).toBeInTheDocument();+ });++ it('renders aria-label for page navigation', () => {+ render(<XDSPageNav>Content</XDSPageNav>);+ expect(screen.getByRole('navigation')).toHaveAttribute(+ 'aria-label',+ 'Page navigation',+ );+ });++ it('renders children in scrollable area', () => {+ render(+ <XDSPageNav>+ <span data-testid="nav-content">Nav items</span>+ </XDSPageNav>,+ );+ expect(screen.getByTestId('nav-content')).toBeInTheDocument();+ });++ it('renders header slot', () => {+ render(+ <XDSPageNav header={<span data-testid="header">Header</span>}>+ Content+ </XDSPageNav>,+ );+ expect(screen.getByTestId('header')).toBeInTheDocument();+ });++ it('renders topContent slot', () => {+ render(+ <XDSPageNav topContent={<span data-testid="sticky">Sticky</span>}>+ Content+ </XDSPageNav>,+ );+ expect(screen.getByTestId('sticky')).toBeInTheDocument();+ });++ it('renders footer slot', () => {+ render(+ <XDSPageNav footer={<span data-testid="footer">Footer</span>}>+ Content+ </XDSPageNav>,+ );+ expect(screen.getByTestId('footer')).toBeInTheDocument();+ });++ it('renders footerIcons slot', () => {+ render(+ <XDSPageNav footerIcons={<span data-testid="footer-icons">Icons</span>}>+ Content+ </XDSPageNav>,+ );+ expect(screen.getByTestId('footer-icons')).toBeInTheDocument();+ });++ it('renders all slots together', () => {+ render(+ <XDSPageNav+ header={<span data-testid="header">Header</span>}+ topContent={<span data-testid="sticky">Sticky</span>}+ footer={<span data-testid="footer">Footer</span>}+ footerIcons={<span data-testid="icons">Icons</span>}>+ <span data-testid="content">Content</span>+ </XDSPageNav>,+ );+ expect(screen.getByTestId('header')).toBeInTheDocument();+ expect(screen.getByTestId('sticky')).toBeInTheDocument();+ expect(screen.getByTestId('content')).toBeInTheDocument();+ expect(screen.getByTestId('footer')).toBeInTheDocument();+ expect(screen.getByTestId('icons')).toBeInTheDocument();+ });++ it('forwards ref correctly', () => {+ const ref = vi.fn();+ render(<XDSPageNav ref={ref}>Content</XDSPageNav>);+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));+ });++ it('passes data-testid to root', () => {+ render(<XDSPageNav data-testid="page-nav">Content</XDSPageNav>);+ expect(screen.getByTestId('page-nav')).toBeInTheDocument();+ });+});++// =============================================================================+// XDSPageNavHeader+// =============================================================================++describe('XDSPageNavHeader', () => {+ it('renders title text', () => {+ render(<XDSPageNavHeader title="My App" />);+ expect(screen.getByText('My App')).toBeInTheDocument();+ });++ it('renders icon', () => {+ render(+ <XDSPageNavHeader+ title="My App"+ icon={<span data-testid="app-icon">🏠</span>}+ />,+ );+ expect(screen.getByTestId('app-icon')).toBeInTheDocument();+ });++ it('renders supertitle', () => {+ render(<XDSPageNavHeader title="Product" supertitle="Suite Name" />);+ expect(screen.getByText('Suite Name')).toBeInTheDocument();+ });++ it('renders subtitle', () => {+ render(<XDSPageNavHeader title="Product" subtitle="Account" />);+ expect(screen.getByText('Account')).toBeInTheDocument();+ });++ it('renders as link when titleHref is provided without menu', () => {+ render(<XDSPageNavHeader title="My App" titleHref="/home" />);+ const link = screen.getByRole('link');+ expect(link).toHaveAttribute('href', '/home');+ expect(link).toHaveTextContent('My App');+ });++ it('renders independent links when titleHref and supertitleHref are provided', () => {+ render(+ <XDSPageNavHeader+ title="Product"+ titleHref="/product"+ supertitle="Suite"+ supertitleHref="/suite"+ />,+ );+ const links = screen.getAllByRole('link');+ expect(links).toHaveLength(2);+ expect(links[0]).toHaveAttribute('href', '/suite');+ expect(links[1]).toHaveAttribute('href', '/product');+ });++ it('shows chevron when menu is provided', () => {+ render(<XDSPageNavHeader title="My App" menu={<div>Menu content</div>} />);+ // The chevron SVG should be rendered+ const button = screen.getByRole('button');+ expect(button).toBeInTheDocument();+ });++ it('does not show chevron without menu', () => {+ const {container} = render(<XDSPageNavHeader title="My App" />);+ const svg = container.querySelector('svg');+ expect(svg).not.toBeInTheDocument();+ });++ it('whole header is popover trigger when menu provided without hrefs', () => {+ render(<XDSPageNavHeader title="My App" menu={<div>Menu</div>} />);+ const button = screen.getByRole('button');+ expect(button).toHaveAttribute('aria-haspopup', 'dialog');+ expect(button).toHaveAttribute('aria-expanded', 'false');+ });++ it('toggles popover on click when menu is provided', async () => {+ const user = userEvent.setup();+ render(+ <XDSPageNavHeader+ title="My App"+ menu={<div data-testid="menu-content">Menu</div>}+ />,+ );+ const button = screen.getByRole('button');+ await user.click(button);+ expect(button).toHaveAttribute('aria-expanded', 'true');+ });++ it('renders chevron as separate trigger when menu and hrefs are provided', () => {+ render(+ <XDSPageNavHeader+ title="Product"+ titleHref="/product"+ menu={<div>Menu</div>}+ />,+ );+ const button = screen.getByRole('button', {name: 'Open menu'});+ expect(button).toHaveAttribute('aria-haspopup', 'dialog');+ });++ it('passes data-testid', () => {+ render(<XDSPageNavHeader title="My App" data-testid="nav-header" />);+ expect(screen.getByTestId('nav-header')).toBeInTheDocument();+ });+});++// =============================================================================+// XDSPageNavItem+// =============================================================================++describe('XDSPageNavItem', () => {+ it('renders label text', () => {+ render(<XDSPageNavItem label="Dashboard" />);+ expect(screen.getByText('Dashboard')).toBeInTheDocument();+ });++ it('renders as link when href is provided', () => {+ render(<XDSPageNavItem label="Dashboard" href="/dashboard" />);+ const link = screen.getByRole('link');+ expect(link).toHaveAttribute('href', '/dashboard');+ });++ it('renders as button when no href', () => {+ render(<XDSPageNavItem label="Dashboard" />);+ expect(screen.getByRole('button')).toBeInTheDocument();+ });++ it('sets aria-current="page" when selected', () => {+ render(<XDSPageNavItem label="Dashboard" isSelected />);+ const button = screen.getByRole('button');+ expect(button).toHaveAttribute('aria-current', 'page');+ });++ it('does not set aria-current when not selected', () => {+ render(<XDSPageNavItem label="Dashboard" />);+ const button = screen.getByRole('button');+ expect(button).not.toHaveAttribute('aria-current');+ });++ it('disables the button when isDisabled', () => {+ render(<XDSPageNavItem label="Dashboard" isDisabled />);+ const button = screen.getByRole('button');+ expect(button).toBeDisabled();+ });++ it('calls onClick handler', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(<XDSPageNavItem label="Dashboard" onClick={handleClick} />);+ await user.click(screen.getByRole('button'));+ expect(handleClick).toHaveBeenCalledTimes(1);+ });++ it('renders endContent', () => {+ render(+ <XDSPageNavItem+ label="Projects"+ endContent={<span data-testid="badge">3</span>}+ />,+ );+ expect(screen.getByTestId('badge')).toBeInTheDocument();+ });++ it('renders nested children', () => {+ render(+ <XDSPageNavItem label="Settings">+ <XDSPageNavItem label="General" />+ <XDSPageNavItem label="Security" />+ </XDSPageNavItem>,+ );+ expect(screen.getByText('General')).toBeInTheDocument();+ expect(screen.getByText('Security')).toBeInTheDocument();+ });++ it('passes data-testid', () => {+ render(<XDSPageNavItem label="Dashboard" data-testid="nav-item" />);+ expect(screen.getByTestId('nav-item')).toBeInTheDocument();+ });++ it('renders with selected link', () => {+ render(<XDSPageNavItem label="Dashboard" href="/dashboard" isSelected />);+ const link = screen.getByRole('link');+ expect(link).toHaveAttribute('aria-current', 'page');+ });+});++// =============================================================================+// XDSPageNavSection+// =============================================================================++describe('XDSPageNavSection', () => {+ it('renders with group role', () => {+ render(+ <XDSPageNavSection title="Main">+ <XDSPageNavItem label="Dashboard" />+ </XDSPageNavSection>,+ );+ expect(screen.getByRole('group')).toBeInTheDocument();+ });++ it('renders title text', () => {+ render(+ <XDSPageNavSection title="Main">+ <XDSPageNavItem label="Dashboard" />+ </XDSPageNavSection>,+ );+ expect(screen.getByText('Main')).toBeInTheDocument();+ });++ it('uses aria-labelledby to link title to group', () => {+ render(+ <XDSPageNavSection title="Main">+ <XDSPageNavItem label="Dashboard" />+ </XDSPageNavSection>,+ );+ const group = screen.getByRole('group');+ const labelId = group.getAttribute('aria-labelledby');+ expect(labelId).toBeTruthy();+ const label = document.getElementById(labelId!);+ expect(label).toHaveTextContent('Main');+ });++ it('renders subtitle', () => {+ render(+ <XDSPageNavSection title="Main" subtitle="Primary navigation">+ <XDSPageNavItem label="Dashboard" />+ </XDSPageNavSection>,+ );+ expect(screen.getByText('Primary navigation')).toBeInTheDocument();+ });++ it('renders endContent', () => {+ render(+ <XDSPageNavSection+ title="Main"+ endContent={<span data-testid="section-action">+</span>}>+ <XDSPageNavItem label="Dashboard" />+ </XDSPageNavSection>,+ );+ expect(screen.getByTestId('section-action')).toBeInTheDocument();+ });++ it('passes data-testid', () => {+ render(+ <XDSPageNavSection title="Main" data-testid="nav-section">+ <XDSPageNavItem label="Dashboard" />+ </XDSPageNavSection>,+ );+ expect(screen.getByTestId('nav-section')).toBeInTheDocument();+ });+});++// =============================================================================+// Integration+// =============================================================================++describe('PageNav integration', () => {+ it('renders a complete page nav', () => {+ render(+ <XDSPageNav+ header={<XDSPageNavHeader title="My App" />}+ topContent={<button>Create</button>}+ footer={<div data-testid="promo">Promo</div>}+ footerIcons={<button>Help</button>}>+ <XDSPageNavSection title="Main">+ <XDSPageNavItem label="Dashboard" isSelected />+ <XDSPageNavItem label="Projects" />+ </XDSPageNavSection>+ <XDSPageNavSection title="Settings">+ <XDSPageNavItem label="General" />+ </XDSPageNavSection>+ </XDSPageNav>,+ );++ expect(screen.getByRole('navigation')).toBeInTheDocument();+ expect(screen.getByText('My App')).toBeInTheDocument();+ expect(screen.getByText('Dashboard')).toBeInTheDocument();+ expect(screen.getByText('Projects')).toBeInTheDocument();+ expect(screen.getByText('General')).toBeInTheDocument();+ expect(screen.getByTestId('promo')).toBeInTheDocument();+ });+});diff --git a/packages/core/src/PageNav/XDSPageNav.tsx b/packages/core/src/PageNav/XDSPageNav.tsxnew file mode 100644index 0000000000..d7510286fc--- /dev/null+++ b/packages/core/src/PageNav/XDSPageNav.tsx@@ -0,0 +1,210 @@+/**+ * @file XDSPageNav.tsx+ * @input Uses React forwardRef, HTMLAttributes, ReactNode, StyleX+ * @output Exports XDSPageNav component and XDSPageNavProps+ * @position Core implementation; consumed by index.ts, tested by XDSPageNav.test.tsx+ *+ * Sidebar navigation container with five zones: header + topContent (sticky together),+ * children (scrollable), footer, and footerIcons (sticky bottom).+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/PageNav/README.md+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx+ * - /packages/core/src/PageNav/index.ts+ * - /apps/storybook/stories/PageNav.stories.tsx+ */++'use client';++import {+ forwardRef,+ useContext,+ type HTMLAttributes,+ type ReactNode,+} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {colorVars, spacingVars} from '../theme/tokens.stylex';+import {ThemeContext} from '../theme/ThemeContext';+import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ flexDirection: 'column',+ height: '100%',+ backgroundColor: colorVars['--color-surface'],+ boxSizing: 'border-box',+ overflow: 'hidden',+ },+ stickyTop: {+ display: 'flex',+ flexDirection: 'column',+ flexShrink: 0,+ position: 'sticky',+ top: 0,+ zIndex: 1,+ backgroundColor: colorVars['--color-surface'],+ },+ topContent: {+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ },+ scrollable: {+ flex: 1,+ overflowY: 'auto',+ overflowX: 'hidden',+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ },+ stickyBottom: {+ flexShrink: 0,+ marginTop: 'auto',+ position: 'sticky',+ bottom: 0,+ backgroundColor: colorVars['--color-surface'],+ },+ footer: {+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-2'],+ },+ footerIcons: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-2'],+ borderBlockStart: `1px solid ${colorVars['--color-divider']}`,+ },+});++// =============================================================================+// Module Augmentation+// =============================================================================++declare module '../theme/types' {+ interface ComponentStyles {+ pageNav?: {+ /** Root container styles */+ root?: ThemeStyleXStyles;+ };+ }+}++// =============================================================================+// Types+// =============================================================================++export interface XDSPageNavProps extends Omit<+ HTMLAttributes<HTMLElement>,+ 'style' | 'className'+> {+ /**+ * Header area — typically XDSPageNavHeader. Sticky at top.+ */+ header?: ReactNode;+ /**+ * Content pinned below header (e.g., create button, top-level items). Sticky.+ */+ topContent?: ReactNode;+ /**+ * Navigation sections and items. Scrollable.+ */+ children: ReactNode;+ /**+ * Footer area above icon bar (e.g., promo cards).+ */+ footer?: ReactNode;+ /**+ * Footer icon bar (e.g., help, notifications, avatar).+ */+ footerIcons?: ReactNode;+ /**+ * StyleX overrides for the root container.+ */+ xstyle?: StyleXStyles;+ /**+ * Test ID for the root element.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Component+// =============================================================================++/**+ * Sidebar navigation container for application pages.+ *+ * Provides five zones stacked vertically: a sticky header + action area (stuck together),+ * scrollable nav content, and a sticky bottom footer + footer icon bar.+ *+ * @example+ * ```tsx+ * <XDSPageNav+ * header={<XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}+ * topContent={<XDSButton label="Create new" variant="primary" />}+ * footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}+ * >+ * <XDSPageNavSection title="Main">+ * <XDSPageNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />+ * <XDSPageNavItem label="Projects" icon={FolderIcon} href="/projects" />+ * </XDSPageNavSection>+ * </XDSPageNav>+ * ```+ */+export const XDSPageNav = forwardRef<HTMLElement, XDSPageNavProps>(+ function XDSPageNav(+ {+ header,+ topContent,+ children,+ footer,+ footerIcons,+ xstyle,+ 'data-testid': testId,+ ...props+ },+ ref,+ ) {+ const themeContext = useContext(ThemeContext);+ const rootOverride = themeContext?.theme.components?.pageNav?.root;++ const hasStickyTop = !!(header || topContent);+ const hasStickyBottom = !!(footer || footerIcons);++ return (+ <nav+ ref={ref}+ role="navigation"+ aria-label="Page navigation"+ data-testid={testId}+ {...stylex.props(styles.root, rootOverride, xstyle)}+ {...props}>+ {hasStickyTop && (+ <div {...stylex.props(styles.stickyTop)}>+ {header}+ {topContent && (+ <div {...stylex.props(styles.topContent)}>{topContent}</div>+ )}+ </div>+ )}+ <div {...stylex.props(styles.scrollable)}>{children}</div>+ {hasStickyBottom && (+ <div {...stylex.props(styles.stickyBottom)}>+ {footer && <div {...stylex.props(styles.footer)}>{footer}</div>}+ {footerIcons && (+ <div {...stylex.props(styles.footerIcons)}>{footerIcons}</div>+ )}+ </div>+ )}+ </nav>+ );+ },+);++XDSPageNav.displayName = 'XDSPageNav';diff --git a/packages/core/src/PageNav/XDSPageNavHeader.tsx b/packages/core/src/PageNav/XDSPageNavHeader.tsxnew file mode 100644index 0000000000..796cea676d--- /dev/null+++ b/packages/core/src/PageNav/XDSPageNavHeader.tsx@@ -0,0 +1,506 @@+/**+ * @file XDSPageNavHeader.tsx+ * @input Uses React forwardRef, useRef, useCallback, ReactNode, StyleX, useXDSPopover+ * @output Exports XDSPageNavHeader component and XDSPageNavHeaderProps+ * @position Core implementation; used inside XDSPageNav header slot+ *+ * Product/suite/account header with smart interaction boundary logic.+ * Composes useXDSPopover internally when menu prop is provided.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/PageNav/README.md+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx+ * - /packages/core/src/PageNav/index.ts+ * - /apps/storybook/stories/PageNav.stories.tsx+ */++'use client';++import {forwardRef, useCallback, useRef, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ textSizeVars,+ fontWeightVars,+ lineHeightVars,+ radiusVars,+} from '../theme/tokens.stylex';+// TODO(#264): Lazy-load useXDSPopover so the popover/layer bundle is not+// eagerly imported when `menu` is not provided. See XDSText for an example+// of lazy loading layer resources.+import {useXDSPopover} from '../Layer/useXDSPopover';+import {XDSLink} from '../Link';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ paddingBlock: spacingVars['--spacing-3'],+ boxSizing: 'border-box',+ textDecoration: 'none',+ color: 'inherit',+ cursor: 'default',+ },+ interactive: {+ cursor: 'pointer',+ borderRadius: radiusVars['--radius-element'],+ borderWidth: 0,+ borderStyle: 'none',+ backgroundColor: 'transparent',+ fontFamily: 'inherit',+ fontSize: 'inherit',+ textAlign: 'start',+ ':hover': {+ backgroundColor: colorVars['--color-hover-overlay'],+ },+ },+ interactiveInset: {+ marginInline: spacingVars['--spacing-1'],+ marginBlock: spacingVars['--spacing-1'],+ },+ icon: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ width: spacingVars['--spacing-8'],+ height: spacingVars['--spacing-8'],+ },+ textContainer: {+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minWidth: 0,+ },+ supertitle: {+ fontSize: textSizeVars['--text-xsm'],+ lineHeight: lineHeightVars['--leading-snug'],+ color: colorVars['--color-text-secondary'],+ textDecoration: 'none',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ title: {+ fontSize: textSizeVars['--text-base'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ lineHeight: lineHeightVars['--leading-snug'],+ color: colorVars['--color-text-primary'],+ textDecoration: 'none',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ subtitle: {+ fontSize: textSizeVars['--text-xsm'],+ lineHeight: lineHeightVars['--leading-snug'],+ color: colorVars['--color-text-secondary'],+ textDecoration: 'none',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ chevron: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ width: 16,+ height: 16,+ color: colorVars['--color-icon-secondary'],+ },+ popoverContent: {+ borderRadius: radiusVars['--radius-element'],+ backgroundColor: colorVars['--color-surface'],+ boxShadow: `0 4px 12px ${colorVars['--color-shadow-elevation']}`,+ overflow: 'hidden',+ },+ popover: {+ minWidth: 'anchor-size(width)',+ marginBlockStart: spacingVars['--spacing-1'],+ },+});++// =============================================================================+// Types+// =============================================================================++export interface XDSPageNavHeaderProps {+ /**+ * Product/app icon.+ */+ icon?: ReactNode;+ /**+ * Product/app name.+ */+ title: string;+ /**+ * Link for the title (e.g., product home).+ */+ titleHref?: string;+ /**+ * Text above the title (e.g., suite name).+ */+ supertitle?: string;+ /**+ * Link for the supertitle (e.g., suite home).+ */+ supertitleHref?: string;+ /**+ * Text below the title (e.g., account context).+ */+ subtitle?: string;+ /**+ * Link for the subtitle.+ */+ subtitleHref?: string;+ /**+ * Menu content shown in a popover. When provided, the header composes+ * useXDSPopover internally and shows a dropdown chevron. The trigger+ * boundary is determined automatically:+ * - No hrefs → whole header is the trigger+ * - With hrefs → links are independent, chevron/remaining area is the trigger+ */+ menu?: ReactNode;+ /**+ * StyleX overrides.+ */+ xstyle?: StyleXStyles;+ /**+ * Test ID for the root element.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Chevron SVG+// =============================================================================++function ChevronDownIcon() {+ return (+ <svg+ width="16"+ height="16"+ viewBox="0 0 16 16"+ fill="none"+ aria-hidden="true">+ <path+ d="M4 6L8 10L12 6"+ stroke="currentColor"+ strokeWidth="1.5"+ strokeLinecap="round"+ strokeLinejoin="round"+ />+ </svg>+ );+}++// =============================================================================+// Component+// =============================================================================++/**+ * Product/suite/account header for XDSPageNav.+ *+ * Supports smart interaction boundary logic:+ * - No hrefs + menu → whole header is the popover trigger+ * - titleHref only, no menu → whole header is one link+ * - titleHref + supertitleHref, no menu → each is an independent link+ * - menu + hrefs → links are independent, chevron/remaining area is the trigger+ *+ * The chevron indicator is automatically shown when `menu` is provided.+ *+ * @example+ * ```tsx+ * // Single product+ * <XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />+ *+ * // Suite with menu+ * <XDSPageNavHeader+ * icon={<SuiteIcon />}+ * supertitle="Suite Name"+ * supertitleHref="/suite"+ * title="Product Name"+ * titleHref="/product"+ * menu={<ProductSwitcher />}+ * />+ *+ * // Account context with menu+ * <XDSPageNavHeader+ * icon={<AppIcon />}+ * title="Product Name"+ * subtitle="Business Account"+ * menu={<AccountSwitcher />}+ * />+ * ```+ */+export const XDSPageNavHeader = forwardRef<+ HTMLDivElement,+ XDSPageNavHeaderProps+>(function XDSPageNavHeader(+ {+ icon,+ title,+ titleHref,+ supertitle,+ supertitleHref,+ subtitle,+ subtitleHref,+ menu,+ xstyle,+ 'data-testid': testId,+ ...props+ },+ ref,+) {+ const rootRef = useRef<HTMLDivElement>(null);++ const popover = useXDSPopover({+ dialogLabel: 'Navigation menu',+ });++ const showChevron = !!menu;+ const hasAnyHref = !!(titleHref || supertitleHref || subtitleHref);++ // Determine interaction mode+ const isWholeHeaderTrigger = !!menu && !hasAnyHref;+ const isWholeHeaderLink =+ !!titleHref && !menu && !supertitleHref && !subtitleHref;++ const handleToggle = useCallback(() => {+ popover.toggle();+ }, [popover]);++ // Combine refs — always anchor popover to the full header element+ // so the popover appears in the same position regardless of whether+ // links are present (mixed mode) or not (whole-header trigger mode).+ const setRef = useCallback(+ (el: HTMLDivElement | null) => {+ (rootRef as React.MutableRefObject<HTMLDivElement | null>).current = el;+ if (typeof ref === 'function') {+ ref(el);+ } else if (ref) {+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = el;+ }+ if (menu) {+ popover.triggerRef(el);+ }+ },+ [ref, popover, menu],+ );++ // Render text content+ const renderTextContent = () => (+ <span {...stylex.props(styles.textContainer)}>+ {supertitle &&+ (hasAnyHref && supertitleHref && menu ? (+ <XDSLink+ label={supertitle}+ href={supertitleHref}+ color="secondary"+ size="xsm">+ {supertitle}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.supertitle)}>{supertitle}</span>+ ))}+ {hasAnyHref && titleHref && menu ? (+ <XDSLink+ label={title}+ href={titleHref}+ color="primary"+ weight="semibold">+ {title}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.title)}>{title}</span>+ )}+ {subtitle &&+ (hasAnyHref && subtitleHref && menu ? (+ <XDSLink+ label={subtitle}+ href={subtitleHref}+ color="secondary"+ size="xsm">+ {subtitle}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.subtitle)}>{subtitle}</span>+ ))}+ </span>+ );++ const chevronElement = showChevron && (+ <span {...stylex.props(styles.chevron)}>+ <ChevronDownIcon />+ </span>+ );++ // Whole header is a link (no menu, single titleHref)+ if (isWholeHeaderLink) {+ return (+ <a+ ref={ref as React.Ref<HTMLAnchorElement>}+ href={titleHref}+ data-testid={testId}+ {...stylex.props(+ styles.root,+ styles.interactive,+ styles.interactiveInset,+ xstyle,+ )}+ {...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)}>+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}+ {renderTextContent()}+ {chevronElement}+ </a>+ );+ }++ // Whole header is the popover trigger (menu, no hrefs)+ if (isWholeHeaderTrigger) {+ return (+ <>+ <button+ ref={setRef as React.Ref<HTMLButtonElement>}+ type="button"+ onClick={handleToggle}+ data-testid={testId}+ {...popover.triggerProps}+ {...stylex.props(+ styles.root,+ styles.interactive,+ styles.interactiveInset,+ xstyle,+ )}>+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}+ {renderTextContent()}+ {chevronElement}+ </button>+ {popover.render(+ <div {...stylex.props(styles.popoverContent)}>{menu}</div>,+ {placement: 'below', alignment: 'start', xstyle: styles.popover},+ )}+ </>+ );+ }++ // Mixed mode: independent links + chevron trigger for menu+ // Popover anchors to the full header div, not the chevron, so it+ // appears in the same position as the no-links case.+ if (menu && hasAnyHref) {+ return (+ <>+ <div+ ref={setRef}+ data-testid={testId}+ {...stylex.props(styles.root, xstyle)}>+ {icon &&+ (titleHref ? (+ <a href={titleHref} {...stylex.props(styles.icon)}>+ {icon}+ </a>+ ) : (+ <span {...stylex.props(styles.icon)}>{icon}</span>+ ))}+ {renderTextContent()}+ {showChevron && (+ <button+ type="button"+ onClick={handleToggle}+ aria-label="Open menu"+ {...popover.triggerProps}+ {...stylex.props(styles.chevron, styles.interactive)}>+ <ChevronDownIcon />+ </button>+ )}+ </div>+ {popover.render(+ <div {...stylex.props(styles.popoverContent)}>{menu}</div>,+ {placement: 'below', alignment: 'start', xstyle: styles.popover},+ )}+ </>+ );+ }++ // Static header with independent links (no menu)+ if (hasAnyHref && !isWholeHeaderLink) {+ return (+ <div+ ref={ref}+ data-testid={testId}+ {...stylex.props(styles.root, xstyle)}+ {...props}>+ {icon &&+ (titleHref ? (+ <a href={titleHref} {...stylex.props(styles.icon)}>+ {icon}+ </a>+ ) : (+ <span {...stylex.props(styles.icon)}>{icon}</span>+ ))}+ <span {...stylex.props(styles.textContainer)}>+ {supertitle &&+ (supertitleHref ? (+ <XDSLink+ label={supertitle}+ href={supertitleHref}+ color="secondary"+ size="xsm">+ {supertitle}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.supertitle)}>{supertitle}</span>+ ))}+ {titleHref ? (+ <XDSLink+ label={title}+ href={titleHref}+ color="primary"+ weight="semibold">+ {title}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.title)}>{title}</span>+ )}+ {subtitle &&+ (subtitleHref ? (+ <XDSLink+ label={subtitle}+ href={subtitleHref}+ color="secondary"+ size="xsm">+ {subtitle}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.subtitle)}>{subtitle}</span>+ ))}+ </span>+ {chevronElement}+ </div>+ );+ }++ // Default: static header, no links, no menu+ return (+ <div+ ref={ref}+ data-testid={testId}+ {...stylex.props(styles.root, xstyle)}+ {...props}>+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}+ {renderTextContent()}+ {chevronElement}+ </div>+ );+});++XDSPageNavHeader.displayName = 'XDSPageNavHeader';diff --git a/packages/core/src/PageNav/XDSPageNavItem.tsx b/packages/core/src/PageNav/XDSPageNavItem.tsxnew file mode 100644index 0000000000..621292dc3b--- /dev/null+++ b/packages/core/src/PageNav/XDSPageNavItem.tsx@@ -0,0 +1,270 @@+/**+ * @file XDSPageNavItem.tsx+ * @input Uses React forwardRef, ReactNode, StyleX, XDSIcon, XDSIconType+ * @output Exports XDSPageNavItem component and XDSPageNavItemProps+ * @position Core implementation; used inside XDSPageNav children+ *+ * Navigation item with icon, selected state, and nesting.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/PageNav/README.md+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx+ * - /packages/core/src/PageNav/index.ts+ * - /apps/storybook/stories/PageNav.stories.tsx+ */++'use client';++import {forwardRef, useId, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ radiusVars,+ textSizeVars,+ fontWeightVars,+ lineHeightVars,+} from '../theme/tokens.stylex';+import {XDSIcon} from '../Icon';+import type {XDSIconType} from '../Icon';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ flexDirection: 'column',+ width: '100%',+ },+ item: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ width: '100%',+ paddingInline: spacingVars['--spacing-3'],+ paddingBlock: spacingVars['--spacing-2'],+ borderRadius: radiusVars['--radius-element'],+ borderWidth: 0,+ borderStyle: 'none',+ backgroundColor: 'transparent',+ color: colorVars['--color-text-primary'],+ textDecoration: 'none',+ cursor: 'pointer',+ fontFamily: 'inherit',+ fontSize: textSizeVars['--text-base'],+ fontWeight: fontWeightVars['--font-weight-normal'],+ lineHeight: lineHeightVars['--leading-base'],+ textAlign: 'start',+ boxSizing: 'border-box',+ ':hover': {+ backgroundColor: colorVars['--color-hover-overlay'],+ },+ },+ selected: {+ backgroundColor: colorVars['--color-accent-deemphasized'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ ':hover': {+ backgroundColor: colorVars['--color-accent-deemphasized'],+ },+ },+ disabled: {+ color: colorVars['--color-text-disabled'],+ cursor: 'not-allowed',+ pointerEvents: 'none',+ },+ label: {+ flex: 1,+ minWidth: 0,+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ endContent: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ },+ children: {+ paddingInlineStart: spacingVars['--spacing-6'],+ },+});++// =============================================================================+// Types+// =============================================================================++export interface XDSPageNavItemProps {+ /**+ * Item label.+ */+ label: string;+ /**+ * Icon (outline variant).+ */+ icon?: XDSIconType;+ /**+ * Icon when selected (filled variant).+ */+ selectedIcon?: XDSIconType;+ /**+ * Current page indicator.+ * @default false+ */+ isSelected?: boolean;+ /**+ * Whether the item is disabled.+ * @default false+ */+ isDisabled?: boolean;+ /**+ * Navigation URL.+ */+ href?: string;+ /**+ * Click handler.+ */+ onClick?: (e: React.MouseEvent) => void;+ /**+ * Right-side content (badges, counts).+ */+ endContent?: ReactNode;+ /**+ * Sub-items for nesting.+ */+ children?: ReactNode;+ /**+ * Test ID for the item element.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Component+// =============================================================================++/**+ * Navigation item for XDSPageNav.+ *+ * Supports icons, selected state, nesting, and end content like badges or counts.+ *+ * @example+ * ```tsx+ * <XDSPageNavItem+ * label="Dashboard"+ * icon={HomeIcon}+ * selectedIcon={HomeIconSolid}+ * isSelected+ * href="/dashboard"+ * />+ *+ * <XDSPageNavItem label="Settings" icon={CogIcon}>+ * <XDSPageNavItem label="General" href="/settings/general" />+ * <XDSPageNavItem label="Security" href="/settings/security" />+ * </XDSPageNavItem>+ * ```+ */+export const XDSPageNavItem = forwardRef<HTMLElement, XDSPageNavItemProps>(+ function XDSPageNavItem(+ {+ label,+ icon,+ selectedIcon,+ isSelected = false,+ isDisabled = false,+ href,+ onClick,+ endContent,+ children,+ 'data-testid': testId,+ },+ ref,+ ) {+ const id = useId();+ const hasChildren = !!children;++ const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;++ const handleClick = (e: React.MouseEvent) => {+ if (isDisabled) {+ e.preventDefault();+ return;+ }+ onClick?.(e);+ };++ const itemContent = (+ <>+ {displayIcon && (+ <XDSIcon+ icon={displayIcon}+ size="sm"+ color={+ isSelected ? 'accent' : isDisabled ? 'disabled' : 'secondary'+ }+ />+ )}+ <span {...stylex.props(styles.label)}>{label}</span>+ {endContent && (+ <span {...stylex.props(styles.endContent)}>{endContent}</span>+ )}+ </>+ );++ const ariaProps = {+ 'aria-current': isSelected ? ('page' as const) : undefined,+ 'aria-disabled': isDisabled || undefined,+ 'data-testid': testId,+ };++ const itemElement =+ href && !isDisabled ? (+ <a+ ref={ref as React.Ref<HTMLAnchorElement>}+ href={href}+ onClick={handleClick}+ {...ariaProps}+ {...stylex.props(+ styles.item,+ isSelected && styles.selected,+ isDisabled && styles.disabled,+ )}>+ {itemContent}+ </a>+ ) : (+ <button+ ref={ref as React.Ref<HTMLButtonElement>}+ type="button"+ onClick={handleClick}+ disabled={isDisabled}+ {...ariaProps}+ {...stylex.props(+ styles.item,+ isSelected && styles.selected,+ isDisabled && styles.disabled,+ )}>+ {itemContent}+ </button>+ );++ return (+ <div {...stylex.props(styles.root)}>+ {itemElement}+ {hasChildren && (+ <div+ role="group"+ aria-labelledby={`${id}-label`}+ {...stylex.props(styles.children)}>+ <span id={`${id}-label`} hidden>+ {label}+ </span>+ {children}+ </div>+ )}+ </div>+ );+ },+);++XDSPageNavItem.displayName = 'XDSPageNavItem';diff --git a/packages/core/src/PageNav/XDSPageNavSection.tsx b/packages/core/src/PageNav/XDSPageNavSection.tsxnew file mode 100644index 0000000000..d1a49da60f--- /dev/null+++ b/packages/core/src/PageNav/XDSPageNavSection.tsx@@ -0,0 +1,188 @@+/**+ * @file XDSPageNavSection.tsx+ * @input Uses React, StyleX+ * @output Exports XDSPageNavSection component and XDSPageNavSectionProps+ * @position Core implementation; used inside XDSPageNav children+ *+ * Section grouping for navigation items with optional title and end content.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/PageNav/README.md+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx+ * - /packages/core/src/PageNav/index.ts+ * - /apps/storybook/stories/PageNav.stories.tsx+ */++'use client';++import {useId, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ textSizeVars,+ fontWeightVars,+ lineHeightVars,+} from '../theme/tokens.stylex';+// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ flexDirection: 'column',+ paddingBlock: spacingVars['--spacing-1'],+ },+ header: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ paddingBlock: spacingVars['--spacing-1'],+ cursor: 'default',+ userSelect: 'none',+ },++ titleContainer: {+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minWidth: 0,+ },+ title: {+ fontSize: textSizeVars['--text-xsm'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ lineHeight: lineHeightVars['--leading-snug'],+ color: colorVars['--color-text-secondary'],+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ subtitle: {+ fontSize: textSizeVars['--text-xsm'],+ lineHeight: lineHeightVars['--leading-snug'],+ color: colorVars['--color-text-secondary'],+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ endContent: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ },++ items: {+ display: 'flex',+ flexDirection: 'column',+ },+});++// =============================================================================+// Types+// =============================================================================++export interface XDSPageNavSectionProps {+ /**+ * Section title.+ */+ title: string;+ /**+ * Section subtitle.+ */+ subtitle?: string;+ /**+ * Section items.+ */+ children: ReactNode;+ /**+ * Right-side content in the section header.+ */+ endContent?: ReactNode;+ /**+ * Whether the section header is visually hidden.+ * The section title is still accessible to screen readers.+ * @default false+ */+ isHeaderHidden?: boolean;+ /**+ * Test ID for the section element.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Component+// =============================================================================++/**+ * Section grouping for XDSPageNav items.+ *+ * Renders a labeled group of navigation items.+ * Uses `role="group"` with `aria-labelledby` for accessibility.+ *+ * @example+ * ```tsx+ * <XDSPageNavSection title="Main">+ * <XDSPageNavItem label="Dashboard" icon={HomeIcon} isSelected />+ * <XDSPageNavItem label="Projects" icon={FolderIcon} />+ * </XDSPageNavSection>+ * ```+ */+export function XDSPageNavSection({+ title,+ subtitle,+ children,+ endContent,+ isHeaderHidden = false,+ 'data-testid': testId,+}: XDSPageNavSectionProps) {+ const id = useId();+ const titleId = `${id}-title`;++ const headerContent = (+ <>+ <span {...stylex.props(styles.titleContainer)}>+ <span id={titleId} {...stylex.props(styles.title)}>+ {title}+ </span>+ {subtitle && <span {...stylex.props(styles.subtitle)}>{subtitle}</span>}+ </span>+ {endContent && (+ <span {...stylex.props(styles.endContent)}>{endContent}</span>+ )}+ </>+ );++ const visuallyHiddenStyle: React.CSSProperties = isHeaderHidden+ ? {+ position: 'absolute',+ width: 1,+ height: 1,+ padding: 0,+ margin: -1,+ overflow: 'hidden',+ clip: 'rect(0, 0, 0, 0)',+ whiteSpace: 'nowrap',+ borderWidth: 0,+ }+ : {};++ return (+ <div+ role="group"+ aria-labelledby={titleId}+ data-testid={testId}+ {...stylex.props(styles.root)}>+ <div+ style={isHeaderHidden ? visuallyHiddenStyle : undefined}+ {...stylex.props(styles.header)}>+ {headerContent}+ </div>+ <div {...stylex.props(styles.items)}>{children}</div>+ </div>+ );+}++XDSPageNavSection.displayName = 'XDSPageNavSection';diff --git a/packages/core/src/PageNav/index.ts b/packages/core/src/PageNav/index.tsnew file mode 100644index 0000000000..c8527293c9--- /dev/null+++ b/packages/core/src/PageNav/index.ts@@ -0,0 +1,20 @@+/**+ * @file index.ts+ * @input Imports PageNav components and types+ * @output Exports XDSPageNav, XDSPageNavHeader, XDSPageNavItem, XDSPageNavSection+ * @position Component entry point; re-exported by /packages/core/src/index.ts+ *+ * SYNC: When modified, update this header and /packages/core/src/PageNav/README.md+ */++export {XDSPageNav} from './XDSPageNav';+export type {XDSPageNavProps} from './XDSPageNav';++export {XDSPageNavHeader} from './XDSPageNavHeader';+export type {XDSPageNavHeaderProps} from './XDSPageNavHeader';++export {XDSPageNavItem} from './XDSPageNavItem';+export type {XDSPageNavItemProps} from './XDSPageNavItem';++export {XDSPageNavSection} from './XDSPageNavSection';+export type {XDSPageNavSectionProps} from './XDSPageNavSection';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex aa110e6120..1b7abeb9c5 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -44,6 +44,7 @@ export * from './Token';export * from './Dialog';export * from './DropdownMenu';export * from './TopNav';+export * from './PageNav';export * from './ProgressBar';// Layout utilities and components (includes XDSHStack, XDSVStack)