Skip to content

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

TypeScript

refactor(core): rename XDSPageNav to XDSSideNav (#317)

Cindy Zhang16e6a09fdfbf
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index 34fdd328b4..a0dc52d84c 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -13,11 +13,11 @@ import {
XDSTopNavItem,
} from '@xds/core/TopNav';
import {
- XDSPageNav,
- XDSPageNavHeader,
- XDSPageNavItem,
- XDSPageNavSection,
-} from '@xds/core/PageNav';
+ XDSSideNav,
+ XDSSideNavHeader,
+ XDSSideNavItem,
+ XDSSideNavSection,
+} from '@xds/core/SideNav';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '@xds/core/theme/tokens.stylex';
import {
@@ -123,104 +123,104 @@ function AppTopNav({endContent}: {endContent?: React.ReactNode}) {
}
/**
- * PageNav WITHOUT header — for use alongside a TopNav.
- * The TopNav already displays the app name, so the PageNav omits its header
+ * SideNav WITHOUT header — for use alongside a TopNav.
+ * The TopNav already displays the app name, so the SideNav omits its header
* to avoid doubling the identity.
*/
function SideNavWithoutHeader() {
return (
- <XDSPageNav>
- <XDSPageNavSection title="Main" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNav>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Analytics"
icon={ChartBarIcon}
selectedIcon={ChartBarIconSolid}
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Projects"
icon={FolderIcon}
selectedIcon={FolderIconSolid}
href="#"
endContent={<XDSBadge>12</XDSBadge>}
/>
- </XDSPageNavSection>
- <XDSPageNavSection title="Organization">
- <XDSPageNavItem
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Organization">
+ <XDSSideNavItem
label="Team"
icon={UserGroupIcon}
selectedIcon={UserGroupIconSolid}
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Settings"
icon={Cog6ToothIcon}
selectedIcon={Cog6ToothIconSolid}
href="#"
/>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ </XDSSideNav>
);
}
/**
- * PageNav WITH header — for standalone use without a TopNav.
+ * SideNav WITH header — for standalone use without a TopNav.
* The header provides app identity (icon + title) since there's no TopNav.
*/
function SideNavWithHeader() {
return (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="Acme App"
titleHref="#"
/>
}>
- <XDSPageNavSection title="Main" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Analytics"
icon={ChartBarIcon}
selectedIcon={ChartBarIconSolid}
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Projects"
icon={FolderIcon}
selectedIcon={FolderIconSolid}
href="#"
endContent={<XDSBadge>12</XDSBadge>}
/>
- </XDSPageNavSection>
- <XDSPageNavSection title="Organization">
- <XDSPageNavItem
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Organization">
+ <XDSSideNavItem
label="Team"
icon={UserGroupIcon}
selectedIcon={UserGroupIconSolid}
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Settings"
icon={Cog6ToothIcon}
selectedIcon={Cog6ToothIconSolid}
href="#"
/>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ </XDSSideNav>
);
}
@@ -258,11 +258,11 @@ type Story = StoryObj<typeof XDSAppShell>;
// =============================================================================
/**
- * The most common layout: TopNav provides app identity, PageNav provides
- * page-level navigation. The PageNav omits its header to avoid doubling
+ * The most common layout: TopNav provides app identity, SideNav provides
+ * page-level navigation. The SideNav omits its header to avoid doubling
* the app name that's already in the TopNav.
*/
-export const TopNavWithPageNav: Story = {
+export const TopNavWithSideNav: Story = {
render: () => (
<XDSAppShell topNav={<AppTopNav />} sideNav={<SideNavWithoutHeader />}>
<MockContent />
@@ -271,11 +271,11 @@ export const TopNavWithPageNav: Story = {
};
/**
- * PageNav with its own header (icon + title) and no TopNav.
+ * SideNav with its own header (icon + title) and no TopNav.
* Use this layout for simpler apps where a full top bar isn't needed.
- * The PageNav header provides the app identity instead.
+ * The SideNav header provides the app identity instead.
*/
-export const PageNavOnly: Story = {
+export const SideNavOnly: Story = {
render: () => (
<XDSAppShell sideNav={<SideNavWithHeader />}>
<MockContent />
@@ -296,11 +296,11 @@ export const TopNavOnly: Story = {
};
/**
- * Kitchen sink: TopNav + PageNav with sections, nested items, badges,
+ * Kitchen sink: TopNav + SideNav with sections, nested items, badges,
* footer icons, and a banner. Demonstrates all AppShell zones working
* together.
*
- * Note: The PageNav has no header because the TopNav already shows
+ * Note: The SideNav has no header because the TopNav already shows
* the app identity.
*/
export const FullFeatured: Story = {
@@ -308,7 +308,7 @@ export const FullFeatured: Story = {
<XDSAppShell
topNav={<AppTopNav />}
sideNav={
- <XDSPageNav
+ <XDSSideNav
footerIcons={
<>
<XDSButton
@@ -330,62 +330,62 @@ export const FullFeatured: Story = {
/>
</>
}>
- <XDSPageNavSection title="Main" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Analytics"
icon={ChartBarIcon}
selectedIcon={ChartBarIconSolid}
href="#"
endContent={<XDSBadge variant="info">New</XDSBadge>}
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Projects"
icon={FolderIcon}
selectedIcon={FolderIconSolid}
href="#"
endContent={<XDSBadge>12</XDSBadge>}
/>
- </XDSPageNavSection>
- <XDSPageNavSection title="Organization">
- <XDSPageNavItem
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Organization">
+ <XDSSideNavItem
label="Team"
icon={UserGroupIcon}
selectedIcon={UserGroupIconSolid}
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Settings"
icon={Cog6ToothIcon}
selectedIcon={Cog6ToothIconSolid}
href="#">
- <XDSPageNavItem label="General" href="#" />
- <XDSPageNavItem label="Security" href="#" />
- <XDSPageNavItem label="Integrations" href="#" />
- </XDSPageNavItem>
- </XDSPageNavSection>
- <XDSPageNavSection title="Resources">
- <XDSPageNavItem
+ <XDSSideNavItem label="General" href="#" />
+ <XDSSideNavItem label="Security" href="#" />
+ <XDSSideNavItem label="Integrations" href="#" />
+ </XDSSideNavItem>
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Resources">
+ <XDSSideNavItem
label="Documentation"
icon={DocumentTextIcon}
selectedIcon={DocumentTextIconSolid}
href="#"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Compliance"
icon={ShieldCheckIcon}
selectedIcon={ShieldCheckIconSolid}
href="#"
isDisabled
/>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ </XDSSideNav>
}
banner={
<XDSBanner
@@ -403,7 +403,7 @@ export const FullFeatured: Story = {
/**
* Auto height mode — the shell grows with content instead of filling
- * the viewport. Uses TopNav + PageNav (no PageNav header).
+ * the viewport. Uses TopNav + SideNav (no SideNav header).
*/
export const AutoHeight: Story = {
render: () => (
@@ -464,7 +464,7 @@ export const ContentOnly: Story = {
};
/**
- * Banner with TopNav + PageNav. Shows how the banner sits between
+ * Banner with TopNav + SideNav. Shows how the banner sits between
* the TopNav and the content/sidenav area.
*/
export const WithBanner: Story = {
diff --git a/apps/storybook/stories/PageNav.stories.tsx b/apps/storybook/stories/SideNav.stories.tsx
similarity index 78%
rename from apps/storybook/stories/PageNav.stories.tsx
rename to apps/storybook/stories/SideNav.stories.tsx
index 57bca33983..acee7a188c 100644
--- a/apps/storybook/stories/PageNav.stories.tsx
+++ b/apps/storybook/stories/SideNav.stories.tsx
@@ -1,10 +1,10 @@
import type {Meta, StoryObj} from '@storybook/react';
import {
- XDSPageNav,
- XDSPageNavHeader,
- XDSPageNavItem,
- XDSPageNavSection,
-} from '@xds/core/PageNav';
+ XDSSideNav,
+ XDSSideNavHeader,
+ XDSSideNavItem,
+ XDSSideNavSection,
+} from '@xds/core/SideNav';
import {XDSBadge} from '@xds/core/Badge';
import {XDSButton} from '@xds/core/Button';
import {XDSDivider} from '@xds/core/Divider';
@@ -31,9 +31,9 @@ import {
FolderIcon as FolderIconSolid,
} from '@heroicons/react/24/solid';
-const meta: Meta<typeof XDSPageNav> = {
- title: 'Navigation/XDSPageNav',
- component: XDSPageNav,
+const meta: Meta<typeof XDSSideNav> = {
+ title: 'Navigation/XDSSideNav',
+ component: XDSSideNav,
tags: ['autodocs'],
parameters: {
layout: 'centered',
@@ -48,7 +48,7 @@ const meta: Meta<typeof XDSPageNav> = {
};
export default meta;
-type Story = StoryObj<typeof XDSPageNav>;
+type Story = StoryObj<typeof XDSSideNav>;
// =============================================================================
// Basic
@@ -56,44 +56,44 @@ type Story = StoryObj<typeof XDSPageNav>;
export const Default: Story = {
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="My App"
titleHref="/"
/>
}>
- <XDSPageNavSection title="Main">
- <XDSPageNavItem
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
href="/dashboard"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Projects"
icon={FolderIcon}
selectedIcon={FolderIconSolid}
href="/projects"
endContent={<XDSBadge label="3" />}
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Analytics"
icon={ChartBarIcon}
href="/analytics"
/>
- <XDSPageNavItem label="Team" icon={UserGroupIcon} href="/team" />
- </XDSPageNavSection>
- <XDSPageNavSection title="Documents">
- <XDSPageNavItem
+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Documents">
+ <XDSSideNavItem
label="All Documents"
icon={DocumentTextIcon}
href="/documents"
/>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
@@ -104,9 +104,9 @@ export const Default: Story = {
export const WithHeaderMenu: Story = {
name: 'Header with Menu',
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="Product Name"
subtitle="Business Account"
@@ -148,16 +148,16 @@ export const WithHeaderMenu: Story = {
}
/>
}>
- <XDSPageNavSection title="Navigation">
- <XDSPageNavItem
+ <XDSSideNavSection title="Navigation">
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
/>
- <XDSPageNavItem label="Settings" icon={Cog6ToothIcon} />
- </XDSPageNavSection>
- </XDSPageNav>
+ <XDSSideNavItem label="Settings" icon={Cog6ToothIcon} />
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
@@ -168,9 +168,9 @@ export const WithHeaderMenu: Story = {
export const SuiteHeader: Story = {
name: 'Suite with Independent Links',
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
supertitle="Suite Name"
supertitleHref="/suite"
@@ -205,16 +205,16 @@ export const SuiteHeader: Story = {
}
/>
}>
- <XDSPageNavSection title="Main">
- <XDSPageNavItem
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
/>
- <XDSPageNavItem label="Projects" icon={FolderIcon} />
- </XDSPageNavSection>
- </XDSPageNav>
+ <XDSSideNavItem label="Projects" icon={FolderIcon} />
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
@@ -225,30 +225,30 @@ export const SuiteHeader: Story = {
export const NestedItems: Story = {
name: 'Nested Items',
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="My App"
/>
}>
- <XDSPageNavSection title="Main">
- <XDSPageNavItem
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
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
+ <XDSSideNavItem label="Settings" icon={Cog6ToothIcon}>
+ <XDSSideNavItem label="General" href="/settings/general" />
+ <XDSSideNavItem label="Security" href="/settings/security" />
+ <XDSSideNavItem
label="Notifications"
href="/settings/notifications"
/>
- </XDSPageNavItem>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavItem>
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
@@ -259,9 +259,9 @@ export const NestedItems: Story = {
export const WithFooter: Story = {
name: 'With Footer Icons',
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="My App"
/>
@@ -282,16 +282,16 @@ export const WithFooter: Story = {
/>
</>
}>
- <XDSPageNavSection title="Main">
- <XDSPageNavItem
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
/>
- <XDSPageNavItem label="Projects" icon={FolderIcon} />
- </XDSPageNavSection>
- </XDSPageNav>
+ <XDSSideNavItem label="Projects" icon={FolderIcon} />
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
@@ -302,28 +302,28 @@ export const WithFooter: Story = {
export const DisabledItem: Story = {
name: 'Disabled Items',
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="My App"
/>
}>
- <XDSPageNavSection title="Main">
- <XDSPageNavItem
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
/>
- <XDSPageNavItem label="Projects" icon={FolderIcon} />
- <XDSPageNavItem
+ <XDSSideNavItem label="Projects" icon={FolderIcon} />
+ <XDSSideNavItem
label="Analytics (Coming Soon)"
icon={ChartBarIcon}
isDisabled
/>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
@@ -334,23 +334,23 @@ export const DisabledItem: Story = {
export const HiddenSectionHeader: Story = {
name: 'Hidden Section Header',
render: () => (
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader
+ <XDSSideNavHeader
icon={<XDSIcon icon={CubeIcon} size="lg" />}
title="My App"
/>
}>
- <XDSPageNavSection title="Main navigation" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNavSection title="Main navigation" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
/>
- <XDSPageNavItem label="Projects" icon={FolderIcon} />
- <XDSPageNavItem label="Analytics" icon={ChartBarIcon} />
- </XDSPageNavSection>
- </XDSPageNav>
+ <XDSSideNavItem label="Projects" icon={FolderIcon} />
+ <XDSSideNavItem label="Analytics" icon={ChartBarIcon} />
+ </XDSSideNavSection>
+ </XDSSideNav>
),
};
diff --git a/packages/core/package.json b/packages/core/package.json
index 058d9b87c5..d009093d9d 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -178,11 +178,11 @@
"import": "./dist/NumberInput/index.mjs",
"require": "./dist/NumberInput/index.js"
},
- "./PageNav": {
- "source": "./src/PageNav/index.ts",
- "types": "./dist/PageNav/index.d.ts",
- "import": "./dist/PageNav/index.mjs",
- "require": "./dist/PageNav/index.js"
+ "./SideNav": {
+ "source": "./src/SideNav/index.ts",
+ "types": "./dist/SideNav/index.d.ts",
+ "import": "./dist/SideNav/index.mjs",
+ "require": "./dist/SideNav/index.js"
},
"./ProgressBar": {
"source": "./src/ProgressBar/index.ts",
diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.md
index 9f06c5c1d4..a0da331086 100644
--- a/packages/core/src/AppShell/README.md
+++ b/packages/core/src/AppShell/README.md
@@ -18,9 +18,9 @@ import {XDSAppShell} from '@xds/core/AppShell';
XDSAppShell has two navigation slots: `topNav` (horizontal bar) and `sideNav` (vertical sidebar). How you combine them determines where app identity lives.
-### TopNav + PageNav (most common)
+### TopNav + SideNav (most common)
-When a TopNav is present, the PageNav should **not** include a header — the TopNav already provides the app name and logo. Adding `XDSPageNavHeader` would double the identity.
+When a TopNav is present, the SideNav should **not** include a header — the TopNav already provides the app name and logo. Adding `XDSSideNavHeader` would double the identity.
```tsx
<XDSAppShell
@@ -38,54 +38,54 @@ When a TopNav is present, the PageNav should **not** include a header — the To
}
sideNav={
// No header — TopNav has the app identity
- <XDSPageNav>
- <XDSPageNavSection title="Main" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNav>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
isSelected
href="/dashboard"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Analytics"
icon={ChartBarIcon}
href="/analytics"
/>
- </XDSPageNavSection>
- <XDSPageNavSection title="Settings">
- <XDSPageNavItem label="General" icon={CogIcon} href="/settings" />
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" icon={CogIcon} href="/settings" />
+ </XDSSideNavSection>
+ </XDSSideNav>
}>
<DashboardContent />
</XDSAppShell>
```
-### PageNav Only (no TopNav)
+### SideNav Only (no TopNav)
-Without a TopNav, the PageNav needs its own header to provide app identity.
+Without a TopNav, the SideNav needs its own header to provide app identity.
```tsx
<XDSAppShell
sideNav={
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+ <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
}>
- <XDSPageNavSection title="Main" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
isSelected
href="/dashboard"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Analytics"
icon={ChartBarIcon}
href="/analytics"
/>
- </XDSPageNavSection>
- </XDSPageNav>
+ </XDSSideNavSection>
+ </XDSSideNav>
}>
<DashboardContent />
</XDSAppShell>
@@ -109,10 +109,10 @@ For landing pages or simple apps that don't need secondary navigation.
### Pattern Summary
-| Layout | TopNav | PageNav Header | When to use |
+| Layout | TopNav | SideNav Header | When to use |
| ---------------- | ------ | -------------- | ------------------------------- |
-| TopNav + PageNav | ✅ | ❌ Omit | Dashboards, admin panels, tools |
-| PageNav only | ❌ | ✅ Include | Simpler apps, focused tools |
+| TopNav + SideNav | ✅ | ❌ Omit | Dashboards, admin panels, tools |
+| SideNav only | ❌ | ✅ Include | Simpler apps, focused tools |
| TopNav only | ✅ | N/A | Landing pages, single-page apps |
| Neither | ❌ | N/A | Auth screens, embedded views |
@@ -122,7 +122,7 @@ For landing pages or simple apps that don't need secondary navigation.
// Auto-height for content-heavy pages
<XDSAppShell
topNav={<XDSTopNav label="Docs" title={<XDSTopNavTitle title="Docs" />} />}
- sideNav={<XDSPageNav>...</XDSPageNav>}
+ sideNav={<XDSSideNav>...</XDSSideNav>}
height="auto"
>
<LongDocumentContent />
@@ -131,7 +131,7 @@ For landing pages or simple apps that don't need secondary navigation.
// Controlled sideNav collapse
<XDSAppShell
topNav={<XDSTopNav label="App" title={<XDSTopNavTitle title="App" />} />}
- sideNav={<XDSPageNav>...</XDSPageNav>}
+ sideNav={<XDSSideNav>...</XDSSideNav>}
isSideNavCollapsed={collapsed}
onSideNavCollapsedChange={setCollapsed}
>
@@ -145,7 +145,7 @@ For landing pages or simple apps that don't need secondary navigation.
| --------------------------- | -------------------------------- | -------- | ------------------------------------------- |
| `children` | `ReactNode` | — | Main content area (rendered as `<main>`) |
| `topNav` | `ReactNode` | — | Top navigation slot (typically XDSTopNav) |
-| `sideNav` | `ReactNode` | — | Side navigation slot (typically XDSPageNav) |
+| `sideNav` | `ReactNode` | — | Side navigation slot (typically XDSSideNav) |
| `banner` | `ReactNode` | — | Banner slot for system-wide announcements |
| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior |
| `isSideNavCollapsed` | `boolean` | — | Whether sideNav is collapsed (controlled) |
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 89370a505c..8dd331aa47 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -99,7 +99,7 @@ export interface XDSAppShellProps {
onSideNavCollapsedChange?: (isCollapsed: boolean) => void;
/**
- * Side navigation — typically an XDSPageNav.
+ * Side navigation — typically an XDSSideNav.
*/
sideNav?: ReactNode;
@@ -265,8 +265,8 @@ const dynamicStyles = stylex.create({
*
* @example
* ```tsx
- * // TopNav + PageNav — the most common pattern.
- * // PageNav omits its header because TopNav provides app identity.
+ * // TopNav + SideNav — the most common pattern.
+ * // SideNav omits its header because TopNav provides app identity.
* <XDSAppShell
* topNav={
* <XDSTopNav
@@ -276,25 +276,25 @@ const dynamicStyles = stylex.create({
* />
* }
* sideNav={
- * <XDSPageNav>
- * <XDSPageNavSection title="Main" isHeaderHidden>
- * <XDSPageNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
- * <XDSPageNavItem label="Analytics" icon={ChartBarIcon} href="/analytics" />
- * </XDSPageNavSection>
- * </XDSPageNav>
+ * <XDSSideNav>
+ * <XDSSideNavSection title="Main" isHeaderHidden>
+ * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
+ * <XDSSideNavItem label="Analytics" icon={ChartBarIcon} href="/analytics" />
+ * </XDSSideNavSection>
+ * </XDSSideNav>
* }
* >
* <DashboardContent />
* </XDSAppShell>
*
- * // PageNav only — header provides app identity when there's no TopNav
+ * // SideNav only — header provides app identity when there's no TopNav
* <XDSAppShell
* sideNav={
- * <XDSPageNav header={<XDSPageNavHeader title="My App" titleHref="/" />}>
- * <XDSPageNavSection title="Main" isHeaderHidden>
- * <XDSPageNavItem label="Dashboard" icon={HomeIcon} isSelected />
- * </XDSPageNavSection>
- * </XDSPageNav>
+ * <XDSSideNav header={<XDSSideNavHeader title="My App" titleHref="/" />}>
+ * <XDSSideNavSection title="Main" isHeaderHidden>
+ * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected />
+ * </XDSSideNavSection>
+ * </XDSSideNav>
* }
* >
* <DashboardContent />
diff --git a/packages/core/src/PageNav/index.ts b/packages/core/src/PageNav/index.ts
deleted file mode 100644
index c8527293c9..0000000000
--- a/packages/core/src/PageNav/index.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/**
- * @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/PageNav/README.md b/packages/core/src/SideNav/README.md
similarity index 64%
rename from packages/core/src/PageNav/README.md
rename to packages/core/src/SideNav/README.md
index 484cf15b38..acbd3e5b91 100644
--- a/packages/core/src/PageNav/README.md
+++ b/packages/core/src/SideNav/README.md
@@ -1,4 +1,4 @@
-# PageNav
+# SideNav
Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.
@@ -6,53 +6,53 @@ Sidebar navigation component for application pages. Supports sections, nested it
| 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 |
+| `XDSSideNav` | Container with five zones: header, topContent, children (scrollable), footer, footerIcons |
+| `XDSSideNavHeader` | Product/suite/account header with smart interaction boundary logic |
+| `XDSSideNavItem` | Navigation item with icon, selected state, and nesting |
+| `XDSSideNavSection` | 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 |
+| `XDSSideNav.tsx` | Container component |
+| `XDSSideNavHeader.tsx` | Header component with popover menu support |
+| `XDSSideNavItem.tsx` | Navigation item component |
+| `XDSSideNavSection.tsx` | Section grouping component |
+| `XDSSideNav.test.tsx` | Unit tests |
| `index.ts` | Public exports |
## Usage
```tsx
import {
- XDSPageNav,
- XDSPageNavHeader,
- XDSPageNavItem,
- XDSPageNavSection,
-} from '@xds/core/PageNav';
+ XDSSideNav,
+ XDSSideNavHeader,
+ XDSSideNavItem,
+ XDSSideNavSection,
+} from '@xds/core/SideNav';
```
### With XDSAppShell + TopNav
-When used inside `XDSAppShell` alongside a `XDSTopNav`, **omit the header** — the TopNav already provides the app name and logo. Including `XDSPageNavHeader` would double the identity.
+When used inside `XDSAppShell` alongside a `XDSTopNav`, **omit the header** — the TopNav already provides the app name and logo. Including `XDSSideNavHeader` would double the identity.
```tsx
-// TopNav provides identity → PageNav has no header
+// TopNav provides identity → SideNav has no header
<XDSAppShell
topNav={<XDSTopNav title={<XDSTopNavTitle title="My App" />} />}
sideNav={
- <XDSPageNav>
- <XDSPageNavSection title="Main" isHeaderHidden>
- <XDSPageNavItem
+ <XDSSideNav>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
isSelected
href="/dashboard"
/>
- <XDSPageNavItem label="Projects" icon={FolderIcon} href="/projects" />
- </XDSPageNavSection>
- </XDSPageNav>
+ <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
+ </XDSSideNavSection>
+ </XDSSideNav>
}>
<Content />
</XDSAppShell>
@@ -60,39 +60,39 @@ When used inside `XDSAppShell` alongside a `XDSTopNav`, **omit the header** —
### Standalone (no TopNav)
-Without a TopNav, include `XDSPageNavHeader` to provide app identity.
+Without a TopNav, include `XDSSideNavHeader` to provide app identity.
```tsx
-// No TopNav → PageNav header provides identity
+// No TopNav → SideNav header provides identity
<XDSAppShell
sideNav={
- <XDSPageNav
+ <XDSSideNav
header={
- <XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+ <XDSSideNavHeader 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
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
label="Dashboard"
icon={HomeIcon}
selectedIcon={HomeIconSolid}
isSelected
href="/dashboard"
/>
- <XDSPageNavItem
+ <XDSSideNavItem
label="Projects"
icon={FolderIcon}
href="/projects"
endContent={<XDSBadge>3</XDSBadge>}
/>
- </XDSPageNavSection>
+ </XDSSideNavSection>
- <XDSPageNavSection title="Settings">
- <XDSPageNavItem label="General" href="/settings/general" />
- <XDSPageNavItem label="Security" href="/settings/security" />
- </XDSPageNavSection>
- </XDSPageNav>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" href="/settings/general" />
+ <XDSSideNavItem label="Security" href="/settings/security" />
+ </XDSSideNavSection>
+ </XDSSideNav>
}>
<Content />
</XDSAppShell>
@@ -109,7 +109,7 @@ Without a TopNav, include `XDSPageNavHeader` to provide app identity.
## Accessibility
-- `<nav aria-label="Page navigation">`
+- `<nav aria-label="Side navigation">`
- `aria-current="page"` on selected item
- Sections: `role="group"` with `aria-labelledby`
- Keyboard: Tab through items, Enter/Space to activate
diff --git a/packages/core/src/PageNav/XDSPageNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsx
similarity index 70%
rename from packages/core/src/PageNav/XDSPageNav.test.tsx
rename to packages/core/src/SideNav/XDSSideNav.test.tsx
index f440e81116..ed02113041 100644
--- a/packages/core/src/PageNav/XDSPageNav.test.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx
@@ -1,92 +1,92 @@
/**
- * @file XDSPageNav.test.tsx
- * @input Uses vitest, @testing-library/react, PageNav components
- * @output Unit tests for XDSPageNav component suite
- * @position Testing; validates PageNav implementations
+ * @file XDSSideNav.test.tsx
+ * @input Uses vitest, @testing-library/react, SideNav components
+ * @output Unit tests for XDSSideNav component suite
+ * @position Testing; validates SideNav implementations
*
- * SYNC: When PageNav components change, update tests to match new behavior
+ * SYNC: When SideNav 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';
+import {XDSSideNav} from './XDSSideNav';
+import {XDSSideNavHeader} from './XDSSideNavHeader';
+import {XDSSideNavItem} from './XDSSideNavItem';
+import {XDSSideNavSection} from './XDSSideNavSection';
// =============================================================================
-// XDSPageNav
+// XDSSideNav
// =============================================================================
-describe('XDSPageNav', () => {
+describe('XDSSideNav', () => {
it('renders with navigation role', () => {
- render(<XDSPageNav>Content</XDSPageNav>);
+ render(<XDSSideNav>Content</XDSSideNav>);
expect(screen.getByRole('navigation')).toBeInTheDocument();
});
it('renders aria-label for page navigation', () => {
- render(<XDSPageNav>Content</XDSPageNav>);
+ render(<XDSSideNav>Content</XDSSideNav>);
expect(screen.getByRole('navigation')).toHaveAttribute(
'aria-label',
- 'Page navigation',
+ 'Side navigation',
);
});
it('renders children in scrollable area', () => {
render(
- <XDSPageNav>
+ <XDSSideNav>
<span data-testid="nav-content">Nav items</span>
- </XDSPageNav>,
+ </XDSSideNav>,
);
expect(screen.getByTestId('nav-content')).toBeInTheDocument();
});
it('renders header slot', () => {
render(
- <XDSPageNav header={<span data-testid="header">Header</span>}>
+ <XDSSideNav header={<span data-testid="header">Header</span>}>
Content
- </XDSPageNav>,
+ </XDSSideNav>,
);
expect(screen.getByTestId('header')).toBeInTheDocument();
});
it('renders topContent slot', () => {
render(
- <XDSPageNav topContent={<span data-testid="sticky">Sticky</span>}>
+ <XDSSideNav topContent={<span data-testid="sticky">Sticky</span>}>
Content
- </XDSPageNav>,
+ </XDSSideNav>,
);
expect(screen.getByTestId('sticky')).toBeInTheDocument();
});
it('renders footer slot', () => {
render(
- <XDSPageNav footer={<span data-testid="footer">Footer</span>}>
+ <XDSSideNav footer={<span data-testid="footer">Footer</span>}>
Content
- </XDSPageNav>,
+ </XDSSideNav>,
);
expect(screen.getByTestId('footer')).toBeInTheDocument();
});
it('renders footerIcons slot', () => {
render(
- <XDSPageNav footerIcons={<span data-testid="footer-icons">Icons</span>}>
+ <XDSSideNav footerIcons={<span data-testid="footer-icons">Icons</span>}>
Content
- </XDSPageNav>,
+ </XDSSideNav>,
);
expect(screen.getByTestId('footer-icons')).toBeInTheDocument();
});
it('renders all slots together', () => {
render(
- <XDSPageNav
+ <XDSSideNav
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>,
+ </XDSSideNav>,
);
expect(screen.getByTestId('header')).toBeInTheDocument();
expect(screen.getByTestId('sticky')).toBeInTheDocument();
@@ -97,29 +97,29 @@ describe('XDSPageNav', () => {
it('forwards ref correctly', () => {
const ref = vi.fn();
- render(<XDSPageNav ref={ref}>Content</XDSPageNav>);
+ render(<XDSSideNav ref={ref}>Content</XDSSideNav>);
expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
});
it('passes data-testid to root', () => {
- render(<XDSPageNav data-testid="page-nav">Content</XDSPageNav>);
+ render(<XDSSideNav data-testid="page-nav">Content</XDSSideNav>);
expect(screen.getByTestId('page-nav')).toBeInTheDocument();
});
});
// =============================================================================
-// XDSPageNavHeader
+// XDSSideNavHeader
// =============================================================================
-describe('XDSPageNavHeader', () => {
+describe('XDSSideNavHeader', () => {
it('renders title text', () => {
- render(<XDSPageNavHeader title="My App" />);
+ render(<XDSSideNavHeader title="My App" />);
expect(screen.getByText('My App')).toBeInTheDocument();
});
it('renders icon', () => {
render(
- <XDSPageNavHeader
+ <XDSSideNavHeader
title="My App"
icon={<span data-testid="app-icon">🏠</span>}
/>,
@@ -128,17 +128,17 @@ describe('XDSPageNavHeader', () => {
});
it('renders supertitle', () => {
- render(<XDSPageNavHeader title="Product" supertitle="Suite Name" />);
+ render(<XDSSideNavHeader title="Product" supertitle="Suite Name" />);
expect(screen.getByText('Suite Name')).toBeInTheDocument();
});
it('renders subtitle', () => {
- render(<XDSPageNavHeader title="Product" subtitle="Account" />);
+ render(<XDSSideNavHeader 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" />);
+ render(<XDSSideNavHeader title="My App" titleHref="/home" />);
const link = screen.getByRole('link');
expect(link).toHaveAttribute('href', '/home');
expect(link).toHaveTextContent('My App');
@@ -146,7 +146,7 @@ describe('XDSPageNavHeader', () => {
it('renders independent links when titleHref and supertitleHref are provided', () => {
render(
- <XDSPageNavHeader
+ <XDSSideNavHeader
title="Product"
titleHref="/product"
supertitle="Suite"
@@ -160,20 +160,20 @@ describe('XDSPageNavHeader', () => {
});
it('shows chevron when menu is provided', () => {
- render(<XDSPageNavHeader title="My App" menu={<div>Menu content</div>} />);
+ render(<XDSSideNavHeader 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 {container} = render(<XDSSideNavHeader 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>} />);
+ render(<XDSSideNavHeader title="My App" menu={<div>Menu</div>} />);
const button = screen.getByRole('button');
expect(button).toHaveAttribute('aria-haspopup', 'dialog');
expect(button).toHaveAttribute('aria-expanded', 'false');
@@ -182,7 +182,7 @@ describe('XDSPageNavHeader', () => {
it('toggles popover on click when menu is provided', async () => {
const user = userEvent.setup();
render(
- <XDSPageNavHeader
+ <XDSSideNavHeader
title="My App"
menu={<div data-testid="menu-content">Menu</div>}
/>,
@@ -194,7 +194,7 @@ describe('XDSPageNavHeader', () => {
it('renders chevron as separate trigger when menu and hrefs are provided', () => {
render(
- <XDSPageNavHeader
+ <XDSSideNavHeader
title="Product"
titleHref="/product"
menu={<div>Menu</div>}
@@ -205,46 +205,46 @@ describe('XDSPageNavHeader', () => {
});
it('passes data-testid', () => {
- render(<XDSPageNavHeader title="My App" data-testid="nav-header" />);
+ render(<XDSSideNavHeader title="My App" data-testid="nav-header" />);
expect(screen.getByTestId('nav-header')).toBeInTheDocument();
});
});
// =============================================================================
-// XDSPageNavItem
+// XDSSideNavItem
// =============================================================================
-describe('XDSPageNavItem', () => {
+describe('XDSSideNavItem', () => {
it('renders label text', () => {
- render(<XDSPageNavItem label="Dashboard" />);
+ render(<XDSSideNavItem label="Dashboard" />);
expect(screen.getByText('Dashboard')).toBeInTheDocument();
});
it('renders as link when href is provided', () => {
- render(<XDSPageNavItem label="Dashboard" href="/dashboard" />);
+ render(<XDSSideNavItem 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" />);
+ render(<XDSSideNavItem label="Dashboard" />);
expect(screen.getByRole('button')).toBeInTheDocument();
});
it('sets aria-current="page" when selected', () => {
- render(<XDSPageNavItem label="Dashboard" isSelected />);
+ render(<XDSSideNavItem 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" />);
+ render(<XDSSideNavItem label="Dashboard" />);
const button = screen.getByRole('button');
expect(button).not.toHaveAttribute('aria-current');
});
it('disables the button when isDisabled', () => {
- render(<XDSPageNavItem label="Dashboard" isDisabled />);
+ render(<XDSSideNavItem label="Dashboard" isDisabled />);
const button = screen.getByRole('button');
expect(button).toBeDisabled();
});
@@ -252,14 +252,14 @@ describe('XDSPageNavItem', () => {
it('calls onClick handler', async () => {
const user = userEvent.setup();
const handleClick = vi.fn();
- render(<XDSPageNavItem label="Dashboard" onClick={handleClick} />);
+ render(<XDSSideNavItem label="Dashboard" onClick={handleClick} />);
await user.click(screen.getByRole('button'));
expect(handleClick).toHaveBeenCalledTimes(1);
});
it('renders endContent', () => {
render(
- <XDSPageNavItem
+ <XDSSideNavItem
label="Projects"
endContent={<span data-testid="badge">3</span>}
/>,
@@ -269,55 +269,55 @@ describe('XDSPageNavItem', () => {
it('renders nested children', () => {
render(
- <XDSPageNavItem label="Settings">
- <XDSPageNavItem label="General" />
- <XDSPageNavItem label="Security" />
- </XDSPageNavItem>,
+ <XDSSideNavItem label="Settings">
+ <XDSSideNavItem label="General" />
+ <XDSSideNavItem label="Security" />
+ </XDSSideNavItem>,
);
expect(screen.getByText('General')).toBeInTheDocument();
expect(screen.getByText('Security')).toBeInTheDocument();
});
it('passes data-testid', () => {
- render(<XDSPageNavItem label="Dashboard" data-testid="nav-item" />);
+ render(<XDSSideNavItem label="Dashboard" data-testid="nav-item" />);
expect(screen.getByTestId('nav-item')).toBeInTheDocument();
});
it('renders with selected link', () => {
- render(<XDSPageNavItem label="Dashboard" href="/dashboard" isSelected />);
+ render(<XDSSideNavItem label="Dashboard" href="/dashboard" isSelected />);
const link = screen.getByRole('link');
expect(link).toHaveAttribute('aria-current', 'page');
});
});
// =============================================================================
-// XDSPageNavSection
+// XDSSideNavSection
// =============================================================================
-describe('XDSPageNavSection', () => {
+describe('XDSSideNavSection', () => {
it('renders with group role', () => {
render(
- <XDSPageNavSection title="Main">
- <XDSPageNavItem label="Dashboard" />
- </XDSPageNavSection>,
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" />
+ </XDSSideNavSection>,
);
expect(screen.getByRole('group')).toBeInTheDocument();
});
it('renders title text', () => {
render(
- <XDSPageNavSection title="Main">
- <XDSPageNavItem label="Dashboard" />
- </XDSPageNavSection>,
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" />
+ </XDSSideNavSection>,
);
expect(screen.getByText('Main')).toBeInTheDocument();
});
it('uses aria-labelledby to link title to group', () => {
render(
- <XDSPageNavSection title="Main">
- <XDSPageNavItem label="Dashboard" />
- </XDSPageNavSection>,
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" />
+ </XDSSideNavSection>,
);
const group = screen.getByRole('group');
const labelId = group.getAttribute('aria-labelledby');
@@ -328,29 +328,29 @@ describe('XDSPageNavSection', () => {
it('renders subtitle', () => {
render(
- <XDSPageNavSection title="Main" subtitle="Primary navigation">
- <XDSPageNavItem label="Dashboard" />
- </XDSPageNavSection>,
+ <XDSSideNavSection title="Main" subtitle="Primary navigation">
+ <XDSSideNavItem label="Dashboard" />
+ </XDSSideNavSection>,
);
expect(screen.getByText('Primary navigation')).toBeInTheDocument();
});
it('renders endContent', () => {
render(
- <XDSPageNavSection
+ <XDSSideNavSection
title="Main"
endContent={<span data-testid="section-action">+</span>}>
- <XDSPageNavItem label="Dashboard" />
- </XDSPageNavSection>,
+ <XDSSideNavItem label="Dashboard" />
+ </XDSSideNavSection>,
);
expect(screen.getByTestId('section-action')).toBeInTheDocument();
});
it('passes data-testid', () => {
render(
- <XDSPageNavSection title="Main" data-testid="nav-section">
- <XDSPageNavItem label="Dashboard" />
- </XDSPageNavSection>,
+ <XDSSideNavSection title="Main" data-testid="nav-section">
+ <XDSSideNavItem label="Dashboard" />
+ </XDSSideNavSection>,
);
expect(screen.getByTestId('nav-section')).toBeInTheDocument();
});
@@ -360,22 +360,22 @@ describe('XDSPageNavSection', () => {
// Integration
// =============================================================================
-describe('PageNav integration', () => {
+describe('SideNav integration', () => {
it('renders a complete page nav', () => {
render(
- <XDSPageNav
- header={<XDSPageNavHeader title="My App" />}
+ <XDSSideNav
+ header={<XDSSideNavHeader 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>,
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" isSelected />
+ <XDSSideNavItem label="Projects" />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" />
+ </XDSSideNavSection>
+ </XDSSideNav>,
);
expect(screen.getByRole('navigation')).toBeInTheDocument();
diff --git a/packages/core/src/PageNav/XDSPageNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
similarity index 84%
rename from packages/core/src/PageNav/XDSPageNav.tsx
rename to packages/core/src/SideNav/XDSSideNav.tsx
index d7510286fc..af2dc59d80 100644
--- a/packages/core/src/PageNav/XDSPageNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -1,17 +1,17 @@
/**
- * @file XDSPageNav.tsx
+ * @file XDSSideNav.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
+ * @output Exports XDSSideNav component and XDSSideNavProps
+ * @position Core implementation; consumed by index.ts, tested by XDSSideNav.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
+ * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/XDSSideNav.test.tsx
+ * - /packages/core/src/SideNav/index.ts
+ * - /apps/storybook/stories/SideNav.stories.tsx
*/
'use client';
@@ -88,7 +88,7 @@ const styles = stylex.create({
declare module '../theme/types' {
interface ComponentStyles {
- pageNav?: {
+ sideNav?: {
/** Root container styles */
root?: ThemeStyleXStyles;
};
@@ -99,12 +99,12 @@ declare module '../theme/types' {
// Types
// =============================================================================
-export interface XDSPageNavProps extends Omit<
+export interface XDSSideNavProps extends Omit<
HTMLAttributes<HTMLElement>,
'style' | 'className'
> {
/**
- * Header area — typically XDSPageNavHeader. Sticky at top.
+ * Header area — typically XDSSideNavHeader. Sticky at top.
*/
header?: ReactNode;
/**
@@ -145,20 +145,20 @@ export interface XDSPageNavProps extends Omit<
*
* @example
* ```tsx
- * <XDSPageNav
- * header={<XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}
+ * <XDSSideNav
+ * header={<XDSSideNavHeader 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>
+ * <XDSSideNavSection title="Main">
+ * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
+ * <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
+ * </XDSSideNavSection>
+ * </XDSSideNav>
* ```
*/
-export const XDSPageNav = forwardRef<HTMLElement, XDSPageNavProps>(
- function XDSPageNav(
+export const XDSSideNav = forwardRef<HTMLElement, XDSSideNavProps>(
+ function XDSSideNav(
{
header,
topContent,
@@ -172,7 +172,7 @@ export const XDSPageNav = forwardRef<HTMLElement, XDSPageNavProps>(
ref,
) {
const themeContext = useContext(ThemeContext);
- const rootOverride = themeContext?.theme.components?.pageNav?.root;
+ const rootOverride = themeContext?.theme.components?.sideNav?.root;
const hasStickyTop = !!(header || topContent);
const hasStickyBottom = !!(footer || footerIcons);
@@ -181,7 +181,7 @@ export const XDSPageNav = forwardRef<HTMLElement, XDSPageNavProps>(
<nav
ref={ref}
role="navigation"
- aria-label="Page navigation"
+ aria-label="Side navigation"
data-testid={testId}
{...stylex.props(styles.root, rootOverride, xstyle)}
{...props}>
@@ -207,4 +207,4 @@ export const XDSPageNav = forwardRef<HTMLElement, XDSPageNavProps>(
},
);
-XDSPageNav.displayName = 'XDSPageNav';
+XDSSideNav.displayName = 'XDSSideNav';
diff --git a/packages/core/src/PageNav/XDSPageNavHeader.tsx b/packages/core/src/SideNav/XDSSideNavHeader.tsx
similarity index 95%
rename from packages/core/src/PageNav/XDSPageNavHeader.tsx
rename to packages/core/src/SideNav/XDSSideNavHeader.tsx
index 796cea676d..15e761c91f 100644
--- a/packages/core/src/PageNav/XDSPageNavHeader.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeader.tsx
@@ -1,17 +1,17 @@
/**
- * @file XDSPageNavHeader.tsx
+ * @file XDSSideNavHeader.tsx
* @input Uses React forwardRef, useRef, useCallback, ReactNode, StyleX, useXDSPopover
- * @output Exports XDSPageNavHeader component and XDSPageNavHeaderProps
- * @position Core implementation; used inside XDSPageNav header slot
+ * @output Exports XDSSideNavHeader component and XDSSideNavHeaderProps
+ * @position Core implementation; used inside XDSSideNav 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
+ * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/XDSSideNav.test.tsx
+ * - /packages/core/src/SideNav/index.ts
+ * - /apps/storybook/stories/SideNav.stories.tsx
*/
'use client';
@@ -133,7 +133,7 @@ const styles = stylex.create({
// Types
// =============================================================================
-export interface XDSPageNavHeaderProps {
+export interface XDSSideNavHeaderProps {
/**
* Product/app icon.
*/
@@ -208,7 +208,7 @@ function ChevronDownIcon() {
// =============================================================================
/**
- * Product/suite/account header for XDSPageNav.
+ * Product/suite/account header for XDSSideNav.
*
* Supports smart interaction boundary logic:
* - No hrefs + menu → whole header is the popover trigger
@@ -221,10 +221,10 @@ function ChevronDownIcon() {
* @example
* ```tsx
* // Single product
- * <XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+ * <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
*
* // Suite with menu
- * <XDSPageNavHeader
+ * <XDSSideNavHeader
* icon={<SuiteIcon />}
* supertitle="Suite Name"
* supertitleHref="/suite"
@@ -234,7 +234,7 @@ function ChevronDownIcon() {
* />
*
* // Account context with menu
- * <XDSPageNavHeader
+ * <XDSSideNavHeader
* icon={<AppIcon />}
* title="Product Name"
* subtitle="Business Account"
@@ -242,10 +242,10 @@ function ChevronDownIcon() {
* />
* ```
*/
-export const XDSPageNavHeader = forwardRef<
+export const XDSSideNavHeader = forwardRef<
HTMLDivElement,
- XDSPageNavHeaderProps
->(function XDSPageNavHeader(
+ XDSSideNavHeaderProps
+>(function XDSSideNavHeader(
{
icon,
title,
@@ -503,4 +503,4 @@ export const XDSPageNavHeader = forwardRef<
);
});
-XDSPageNavHeader.displayName = 'XDSPageNavHeader';
+XDSSideNavHeader.displayName = 'XDSSideNavHeader';
diff --git a/packages/core/src/PageNav/XDSPageNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
similarity index 88%
rename from packages/core/src/PageNav/XDSPageNavItem.tsx
rename to packages/core/src/SideNav/XDSSideNavItem.tsx
index 621292dc3b..834116499e 100644
--- a/packages/core/src/PageNav/XDSPageNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -1,16 +1,16 @@
/**
- * @file XDSPageNavItem.tsx
+ * @file XDSSideNavItem.tsx
* @input Uses React forwardRef, ReactNode, StyleX, XDSIcon, XDSIconType
- * @output Exports XDSPageNavItem component and XDSPageNavItemProps
- * @position Core implementation; used inside XDSPageNav children
+ * @output Exports XDSSideNavItem component and XDSSideNavItemProps
+ * @position Core implementation; used inside XDSSideNav 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
+ * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/XDSSideNav.test.tsx
+ * - /packages/core/src/SideNav/index.ts
+ * - /apps/storybook/stories/SideNav.stories.tsx
*/
'use client';
@@ -95,7 +95,7 @@ const styles = stylex.create({
// Types
// =============================================================================
-export interface XDSPageNavItemProps {
+export interface XDSSideNavItemProps {
/**
* Item label.
*/
@@ -145,13 +145,13 @@ export interface XDSPageNavItemProps {
// =============================================================================
/**
- * Navigation item for XDSPageNav.
+ * Navigation item for XDSSideNav.
*
* Supports icons, selected state, nesting, and end content like badges or counts.
*
* @example
* ```tsx
- * <XDSPageNavItem
+ * <XDSSideNavItem
* label="Dashboard"
* icon={HomeIcon}
* selectedIcon={HomeIconSolid}
@@ -159,14 +159,14 @@ export interface XDSPageNavItemProps {
* href="/dashboard"
* />
*
- * <XDSPageNavItem label="Settings" icon={CogIcon}>
- * <XDSPageNavItem label="General" href="/settings/general" />
- * <XDSPageNavItem label="Security" href="/settings/security" />
- * </XDSPageNavItem>
+ * <XDSSideNavItem label="Settings" icon={CogIcon}>
+ * <XDSSideNavItem label="General" href="/settings/general" />
+ * <XDSSideNavItem label="Security" href="/settings/security" />
+ * </XDSSideNavItem>
* ```
*/
-export const XDSPageNavItem = forwardRef<HTMLElement, XDSPageNavItemProps>(
- function XDSPageNavItem(
+export const XDSSideNavItem = forwardRef<HTMLElement, XDSSideNavItemProps>(
+ function XDSSideNavItem(
{
label,
icon,
@@ -267,4 +267,4 @@ export const XDSPageNavItem = forwardRef<HTMLElement, XDSPageNavItemProps>(
},
);
-XDSPageNavItem.displayName = 'XDSPageNavItem';
+XDSSideNavItem.displayName = 'XDSSideNavItem';
diff --git a/packages/core/src/PageNav/XDSPageNavSection.tsx b/packages/core/src/SideNav/XDSSideNavSection.tsx
similarity index 84%
rename from packages/core/src/PageNav/XDSPageNavSection.tsx
rename to packages/core/src/SideNav/XDSSideNavSection.tsx
index d1a49da60f..8299218a01 100644
--- a/packages/core/src/PageNav/XDSPageNavSection.tsx
+++ b/packages/core/src/SideNav/XDSSideNavSection.tsx
@@ -1,16 +1,16 @@
/**
- * @file XDSPageNavSection.tsx
+ * @file XDSSideNavSection.tsx
* @input Uses React, StyleX
- * @output Exports XDSPageNavSection component and XDSPageNavSectionProps
- * @position Core implementation; used inside XDSPageNav children
+ * @output Exports XDSSideNavSection component and XDSSideNavSectionProps
+ * @position Core implementation; used inside XDSSideNav 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
+ * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/XDSSideNav.test.tsx
+ * - /packages/core/src/SideNav/index.ts
+ * - /apps/storybook/stories/SideNav.stories.tsx
*/
'use client';
@@ -83,7 +83,7 @@ const styles = stylex.create({
// Types
// =============================================================================
-export interface XDSPageNavSectionProps {
+export interface XDSSideNavSectionProps {
/**
* Section title.
*/
@@ -117,27 +117,27 @@ export interface XDSPageNavSectionProps {
// =============================================================================
/**
- * Section grouping for XDSPageNav items.
+ * Section grouping for XDSSideNav 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>
+ * <XDSSideNavSection title="Main">
+ * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected />
+ * <XDSSideNavItem label="Projects" icon={FolderIcon} />
+ * </XDSSideNavSection>
* ```
*/
-export function XDSPageNavSection({
+export function XDSSideNavSection({
title,
subtitle,
children,
endContent,
isHeaderHidden = false,
'data-testid': testId,
-}: XDSPageNavSectionProps) {
+}: XDSSideNavSectionProps) {
const id = useId();
const titleId = `${id}-title`;
@@ -185,4 +185,4 @@ export function XDSPageNavSection({
);
}
-XDSPageNavSection.displayName = 'XDSPageNavSection';
+XDSSideNavSection.displayName = 'XDSSideNavSection';
diff --git a/packages/core/src/SideNav/index.ts b/packages/core/src/SideNav/index.ts
new file mode 100644
index 0000000000..40d6dfea8b
--- /dev/null
+++ b/packages/core/src/SideNav/index.ts
@@ -0,0 +1,20 @@
+/**
+ * @file index.ts
+ * @input Imports SideNav components and types
+ * @output Exports XDSSideNav, XDSSideNavHeader, XDSSideNavItem, XDSSideNavSection
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/SideNav/README.md
+ */
+
+export {XDSSideNav} from './XDSSideNav';
+export type {XDSSideNavProps} from './XDSSideNav';
+
+export {XDSSideNavHeader} from './XDSSideNavHeader';
+export type {XDSSideNavHeaderProps} from './XDSSideNavHeader';
+
+export {XDSSideNavItem} from './XDSSideNavItem';
+export type {XDSSideNavItemProps} from './XDSSideNavItem';
+
+export {XDSSideNavSection} from './XDSSideNavSection';
+export type {XDSSideNavSectionProps} from './XDSSideNavSection';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 39d7ee5257..0fea47188a 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -45,7 +45,7 @@ export * from './Token';
export * from './Dialog';
export * from './DropdownMenu';
export * from './TopNav';
-export * from './PageNav';
+export * from './SideNav';
export * from './ProgressBar';
// Layout utilities and components (includes XDSHStack, XDSVStack)