Skip to content

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

TypeScript

feat(SideNav): collapsible sidebar with isCollapsible prop (#641)

Cindy Zhange9bc4a9b8263
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
index 2489f0c703..2478f62c3e 100644
--- a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
@@ -9,6 +9,7 @@ import {
XDSSideNavHeading,
XDSSideNavItem,
XDSSideNavSection,
+ XDSSideNavCollapseButton,
} from '@xds/core/SideNav';
import {
XDSTopNav,
@@ -33,6 +34,70 @@ import {XDSBanner} from '@xds/core/Banner';
// Configuration types
// =============================================================================
+// Simple icon components for shell lab demo
+const DashboardIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ {...props}>
+ <rect x="3" y="3" width="7" height="7" rx="1" />
+ <rect x="14" y="3" width="7" height="7" rx="1" />
+ <rect x="3" y="14" width="7" height="7" rx="1" />
+ <rect x="14" y="14" width="7" height="7" rx="1" />
+ </svg>
+);
+const MessagesIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ {...props}>
+ <path d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z" />
+ </svg>
+);
+const SettingsIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ {...props}>
+ <circle cx="12" cy="12" r="3" />
+ <path d="M12.22 2h-.44a2 2 0 00-2 2v.18a2 2 0 01-1 1.73l-.43.25a2 2 0 01-2 0l-.15-.08a2 2 0 00-2.73.73l-.22.38a2 2 0 00.73 2.73l.15.1a2 2 0 011 1.72v.51a2 2 0 01-1 1.74l-.15.09a2 2 0 00-.73 2.73l.22.38a2 2 0 002.73.73l.15-.08a2 2 0 012 0l.43.25a2 2 0 011 1.73V20a2 2 0 002 2h.44a2 2 0 002-2v-.18a2 2 0 011-1.73l.43-.25a2 2 0 012 0l.15.08a2 2 0 002.73-.73l.22-.39a2 2 0 00-.73-2.73l-.15-.08a2 2 0 01-1-1.74v-.5a2 2 0 011-1.74l.15-.09a2 2 0 00.73-2.73l-.22-.38a2 2 0 00-2.73-.73l-.15.08a2 2 0 01-2 0l-.43-.25a2 2 0 01-1-1.73V4a2 2 0 00-2-2z" />
+ </svg>
+);
+const ProjectsIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ {...props}>
+ <path d="M22 19a2 2 0 01-2 2H4a2 2 0 01-2-2V5a2 2 0 012-2h5l2 3h9a2 2 0 012 2z" />
+ </svg>
+);
+const DocsIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ {...props}>
+ <path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z" />
+ <polyline points="14 2 14 8 20 8" />
+ <line x1="16" y1="13" x2="8" y2="13" />
+ <line x1="16" y1="17" x2="8" y2="17" />
+ </svg>
+);
+
interface ShellConfig {
variant: 'wash' | 'surface' | 'section' | 'elevated';
height: 'fill' | 'auto';
@@ -48,9 +113,8 @@ interface ShellConfig {
showSuperheading: boolean;
showSubheading: boolean;
showNestedItems: boolean;
- defaultCollapsed: boolean;
- controlledCollapse: boolean;
- isCollapsed: boolean;
+ isCollapsible: boolean;
+ collapseToggleLocation: 'sidenav' | 'topnav';
mobileNavMode: 'auto' | 'custom' | 'none';
mobileNavSide: 'start' | 'end';
topNavAlignment: 'start' | 'center' | 'end';
@@ -73,9 +137,8 @@ const DEFAULT_CONFIG: ShellConfig = {
showSuperheading: false,
showSubheading: false,
showNestedItems: true,
- defaultCollapsed: false,
- controlledCollapse: false,
- isCollapsed: false,
+ isCollapsible: true,
+ collapseToggleLocation: 'sidenav',
mobileNavMode: 'auto',
mobileNavSide: 'start',
topNavAlignment: 'start',
@@ -107,11 +170,7 @@ function ConfigPanel({
<SelectorRow
label="Variant"
value={config.variant}
- onChange={v =>
- onChange({
- variant: v as 'wash' | 'surface' | 'section' | 'elevated',
- })
- }
+ onChange={v => onChange({variant: v as ShellConfig['variant']})}
options={[
{value: 'section', label: 'Section'},
{value: 'wash', label: 'Wash'},
@@ -128,40 +187,27 @@ function ConfigPanel({
{value: 'auto', label: 'Auto'},
]}
/>
- <SelectorRow
- label="Breakpoint"
- value={config.sideNavBreakpoint}
- onChange={v =>
- onChange({sideNavBreakpoint: v as 'sm' | 'md' | 'lg' | 'none'})
- }
- options={[
- {value: 'sm', label: 'sm'},
- {value: 'md', label: 'md'},
- {value: 'lg', label: 'lg'},
- {value: 'none', label: 'none'},
- ]}
+ <ToggleRow
+ label="Banner"
+ value={config.showBanner}
+ onChange={v => onChange({showBanner: v})}
/>
</XDSVStack>
<XDSDivider />
- {/* Visibility */}
+ {/* SideNav */}
<XDSVStack gap={3}>
<XDSText type="label" weight="bold">
- Visibility
+ SideNav
</XDSText>
<ToggleRow
- label="Side Nav"
+ label="Show"
value={config.showSideNav}
onChange={v => onChange({showSideNav: v})}
/>
- <ToggleRow
- label="Top Nav"
- value={config.showTopNav}
- onChange={v => onChange({showTopNav: v})}
- />
<SelectorRow
- label="SideNav Heading"
+ label="Heading"
value={config.sideNavHeadingStyle}
onChange={v =>
onChange({
@@ -187,9 +233,14 @@ function ConfigPanel({
onChange={v => onChange({showSubheading: v})}
/>
<ToggleRow
- label="Banner"
- value={config.showBanner}
- onChange={v => onChange({showBanner: v})}
+ label="Top Content"
+ value={config.showTopContent}
+ onChange={v => onChange({showTopContent: v})}
+ />
+ <ToggleRow
+ label="Nested Items"
+ value={config.showNestedItems}
+ onChange={v => onChange({showNestedItems: v})}
/>
<ToggleRow
label="Footer"
@@ -202,51 +253,86 @@ function ConfigPanel({
onChange={v => onChange({showFooterIcons: v})}
/>
<ToggleRow
- label="Top Content"
- value={config.showTopContent}
- onChange={v => onChange({showTopContent: v})}
- />
- <ToggleRow
- label="Nested Items"
- value={config.showNestedItems}
- onChange={v => onChange({showNestedItems: v})}
+ label="Collapsible"
+ value={config.isCollapsible}
+ onChange={v => onChange({isCollapsible: v})}
/>
- <ToggleRow
- label="TopNav Heading"
- value={config.showTopNavHeading}
- onChange={v => onChange({showTopNavHeading: v})}
+ {config.isCollapsible && (
+ <SelectorRow
+ label="Toggle Location"
+ value={config.collapseToggleLocation}
+ onChange={v =>
+ onChange({collapseToggleLocation: v as 'sidenav' | 'topnav'})
+ }
+ options={[
+ {value: 'sidenav', label: 'SideNav'},
+ {value: 'topnav', label: 'TopNav'},
+ ]}
+ />
+ )}
+ <SelectorRow
+ label="Breakpoint"
+ value={config.sideNavBreakpoint}
+ onChange={v =>
+ onChange({
+ sideNavBreakpoint: v as ShellConfig['sideNavBreakpoint'],
+ })
+ }
+ options={[
+ {value: 'sm', label: 'SM'},
+ {value: 'md', label: 'MD'},
+ {value: 'lg', label: 'LG'},
+ {value: 'none', label: 'None'},
+ ]}
/>
</XDSVStack>
<XDSDivider />
- {/* Collapse */}
+ {/* TopNav */}
<XDSVStack gap={3}>
<XDSText type="label" weight="bold">
- Collapse
+ TopNav
</XDSText>
<ToggleRow
- label="Default Collapsed"
- value={config.defaultCollapsed}
- onChange={v => onChange({defaultCollapsed: v})}
+ label="Show"
+ value={config.showTopNav}
+ onChange={v => onChange({showTopNav: v})}
/>
<ToggleRow
- label="Controlled"
- value={config.controlledCollapse}
- onChange={v => onChange({controlledCollapse: v})}
+ label="Heading"
+ value={config.showTopNavHeading}
+ onChange={v => onChange({showTopNavHeading: v})}
+ />
+ <SelectorRow
+ label="Alignment"
+ value={config.topNavAlignment}
+ onChange={v =>
+ onChange({topNavAlignment: v as ShellConfig['topNavAlignment']})
+ }
+ options={[
+ {value: 'start', label: 'Start'},
+ {value: 'center', label: 'Center'},
+ {value: 'end', label: 'End'},
+ ]}
+ />
+ <SelectorRow
+ label="Style"
+ value={config.topNavStyle}
+ onChange={v =>
+ onChange({topNavStyle: v as ShellConfig['topNavStyle']})
+ }
+ options={[
+ {value: 'items', label: 'Items'},
+ {value: 'menus', label: 'Menus'},
+ {value: 'mega', label: 'Mega'},
+ ]}
/>
- {config.controlledCollapse && (
- <ToggleRow
- label="Is Collapsed"
- value={config.isCollapsed}
- onChange={v => onChange({isCollapsed: v})}
- />
- )}
</XDSVStack>
<XDSDivider />
- {/* Mobile */}
+ {/* Mobile Nav */}
<XDSVStack gap={3}>
<XDSText type="label" weight="bold">
Mobile Nav
@@ -255,7 +341,7 @@ function ConfigPanel({
label="Mode"
value={config.mobileNavMode}
onChange={v =>
- onChange({mobileNavMode: v as 'auto' | 'custom' | 'none'})
+ onChange({mobileNavMode: v as ShellConfig['mobileNavMode']})
}
options={[
{value: 'auto', label: 'Auto'},
@@ -265,7 +351,7 @@ function ConfigPanel({
/>
{config.mobileNavMode === 'custom' && (
<SelectorRow
- label="Drawer Side"
+ label="Side"
value={config.mobileNavSide}
onChange={v => onChange({mobileNavSide: v as 'start' | 'end'})}
options={[
@@ -275,39 +361,6 @@ function ConfigPanel({
/>
)}
</XDSVStack>
-
- <XDSDivider />
-
- {/* TopNav */}
- <XDSVStack gap={3}>
- <XDSText type="label" weight="bold">
- TopNav
- </XDSText>
- <SelectorRow
- label="Nav Alignment"
- value={config.topNavAlignment}
- onChange={v =>
- onChange({topNavAlignment: v as 'start' | 'center' | 'end'})
- }
- options={[
- {value: 'start', label: 'Start'},
- {value: 'center', label: 'Center'},
- {value: 'end', label: 'End'},
- ]}
- />
- <SelectorRow
- label="Nav Style"
- value={config.topNavStyle}
- onChange={v =>
- onChange({topNavStyle: v as 'items' | 'menus' | 'mega'})
- }
- options={[
- {value: 'items', label: 'Items'},
- {value: 'menus', label: 'Menus'},
- {value: 'mega', label: 'Mega'},
- ]}
- />
- </XDSVStack>
</XDSVStack>
</XDSCard>
);
@@ -361,7 +414,15 @@ function SelectorRow({
// Sample Nav Content
// =============================================================================
-function SampleSideNav({config}: {config: ShellConfig}) {
+function SampleSideNav({
+ config,
+ externalCollapsed,
+ setExternalCollapsed,
+}: {
+ config: ShellConfig;
+ externalCollapsed?: boolean;
+ setExternalCollapsed?: (v: boolean) => void;
+}) {
const appIcon = (
<XDSNavIcon
icon={
@@ -410,6 +471,17 @@ function SampleSideNav({config}: {config: ShellConfig}) {
return (
<XDSSideNav
+ collapsible={
+ config.isCollapsible
+ ? config.collapseToggleLocation === 'topnav'
+ ? {
+ isCollapsed: externalCollapsed,
+ onCollapsedChange: setExternalCollapsed,
+ hasButton: false,
+ }
+ : true
+ : false
+ }
header={heading}
topContent={
config.showTopContent ? (
@@ -436,8 +508,8 @@ function SampleSideNav({config}: {config: ShellConfig}) {
fill="none"
stroke="currentColor"
strokeWidth={1.5}
- width="20"
- height="20">
+ width="16"
+ height="16">
<circle cx="12" cy="12" r="10" />
<path d="M9.09 9a3 3 0 015.83 1c0 2-3 3-3 3" />
<circle cx="12" cy="17" r=".5" fill="currentColor" />
@@ -454,8 +526,8 @@ function SampleSideNav({config}: {config: ShellConfig}) {
fill="none"
stroke="currentColor"
strokeWidth={1.5}
- width="20"
- height="20">
+ width="16"
+ height="16">
<path d="M12.22 2h-.44a2 2 0 00-2 2v.18a2 2 0 01-1 1.73l-.43.25a2 2 0 01-2 0l-.15-.08a2 2 0 00-2.73.73l-.22.38a2 2 0 00.73 2.73l.15.1a2 2 0 011 1.72v.51a2 2 0 01-1 1.74l-.15.09a2 2 0 00-.73 2.73l.22.38a2 2 0 002.73.73l.15-.08a2 2 0 012 0l.43.25a2 2 0 011 1.73V20a2 2 0 002 2h.44a2 2 0 002-2v-.18a2 2 0 011-1.73l.43-.25a2 2 0 012 0l.15.08a2 2 0 002.73-.73l.22-.39a2 2 0 00-.73-2.73l-.15-.08a2 2 0 01-1-1.74v-.5a2 2 0 011-1.74l.15-.09a2 2 0 00.73-2.73l-.22-.38a2 2 0 00-2.73-.73l-.15.08a2 2 0 01-2 0l-.43-.25a2 2 0 01-1-1.73V4a2 2 0 00-2-2z" />
<circle cx="12" cy="12" r="3" />
</svg>
@@ -466,15 +538,21 @@ function SampleSideNav({config}: {config: ShellConfig}) {
) : undefined
}>
<XDSSideNavSection title="Navigation">
- <XDSSideNavItem label="Dashboard" isSelected href="#" />
+ <XDSSideNavItem
+ label="Dashboard"
+ isSelected
+ href="#"
+ icon={DashboardIcon}
+ />
<XDSSideNavItem
label="Projects"
href="#"
+ icon={ProjectsIcon}
endContent={<XDSBadge>3</XDSBadge>}
/>
- <XDSSideNavItem label="Messages" href="#" />
+ <XDSSideNavItem label="Messages" href="#" icon={MessagesIcon} />
{config.showNestedItems && (
- <XDSSideNavItem label="Settings" href="#">
+ <XDSSideNavItem label="Settings" href="#" icon={SettingsIcon}>
<XDSSideNavItem label="General" href="#" />
<XDSSideNavItem label="Security" href="#" />
<XDSSideNavItem label="Notifications" href="#" />
@@ -482,7 +560,7 @@ function SampleSideNav({config}: {config: ShellConfig}) {
)}
</XDSSideNavSection>
<XDSSideNavSection title="Resources">
- <XDSSideNavItem label="Documentation" href="#" />
+ <XDSSideNavItem label="Documentation" href="#" icon={DocsIcon} />
<XDSSideNavItem label="API Reference" href="#" />
<XDSSideNavItem label="Support" href="#" />
</XDSSideNavSection>
@@ -490,7 +568,13 @@ function SampleSideNav({config}: {config: ShellConfig}) {
);
}
-function SampleTopNav({config}: {config: ShellConfig}) {
+function SampleTopNav({
+ config,
+ onToggleCollapse,
+}: {
+ config: ShellConfig;
+ onToggleCollapse?: () => void;
+}) {
const plainItems = (
<>
<XDSTopNavItem label="Home" href="#" isSelected />
@@ -595,7 +679,30 @@ function SampleTopNav({config}: {config: ShellConfig}) {
}
startContent={config.topNavAlignment === 'start' ? navItems : undefined}
centerContent={config.topNavAlignment === 'center' ? navItems : undefined}
- endContent={config.topNavAlignment === 'end' ? navItems : undefined}
+ endContent={
+ <>
+ {config.topNavAlignment === 'end' && navItems}
+ {onToggleCollapse && (
+ <XDSButton
+ label="Toggle sidebar"
+ variant="ghost"
+ icon={
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ width={16}
+ height={16}>
+ <path d="M3 12h18M3 6h18M3 18h18" />
+ </svg>
+ }
+ onClick={onToggleCollapse}
+ />
+ )}
+ </>
+ }
/>
);
}
@@ -632,19 +739,12 @@ export default function ShellLabPage() {
const [config, setConfig] = useState<ShellConfig>(DEFAULT_CONFIG);
const [isMobileNavOpen, setIsMobileNavOpen] = useState(false);
const [showConfig, setShowConfig] = useState(true);
+ const [externalCollapsed, setExternalCollapsed] = useState(false);
const handleConfigChange = useCallback((update: Partial<ShellConfig>) => {
setConfig(prev => ({...prev, ...update}));
}, []);
- const collapseProps = config.controlledCollapse
- ? {
- isSideNavCollapsed: config.isCollapsed,
- onSideNavCollapsedChange: (v: boolean) =>
- handleConfigChange({isCollapsed: v}),
- }
- : {defaultIsSideNavCollapsed: config.defaultCollapsed};
-
const mobileNav =
config.mobileNavMode === 'custom' ? (
<XDSMobileNav
@@ -653,9 +753,14 @@ export default function ShellLabPage() {
title="Navigation"
side={config.mobileNavSide}>
<XDSSideNavSection title="Navigation">
- <XDSSideNavItem label="Dashboard" isSelected href="#" />
- <XDSSideNavItem label="Projects" href="#" />
- <XDSSideNavItem label="Messages" href="#" />
+ <XDSSideNavItem
+ label="Dashboard"
+ isSelected
+ href="#"
+ icon={DashboardIcon}
+ />
+ <XDSSideNavItem label="Projects" href="#" icon={ProjectsIcon} />
+ <XDSSideNavItem label="Messages" href="#" icon={MessagesIcon} />
</XDSSideNavSection>
</XDSMobileNav>
) : config.mobileNavMode === 'none' ? (
@@ -671,10 +776,26 @@ export default function ShellLabPage() {
sideNavBreakpoint={config.sideNavBreakpoint}
sideNavWidth={config.sideNavWidth}
topNav={
- config.showTopNav ? <SampleTopNav config={config} /> : undefined
+ config.showTopNav ? (
+ <SampleTopNav
+ config={config}
+ onToggleCollapse={
+ config.isCollapsible &&
+ config.collapseToggleLocation === 'topnav'
+ ? () => setExternalCollapsed(v => !v)
+ : undefined
+ }
+ />
+ ) : undefined
}
sideNav={
- config.showSideNav ? <SampleSideNav config={config} /> : undefined
+ config.showSideNav ? (
+ <SampleSideNav
+ config={config}
+ externalCollapsed={externalCollapsed}
+ setExternalCollapsed={setExternalCollapsed}
+ />
+ ) : undefined
}
mobileNav={mobileNav}
banner={
@@ -686,8 +807,7 @@ export default function ShellLabPage() {
isDismissable
/>
) : undefined
- }
- {...collapseProps}>
+ }>
<XDSVStack gap={6} xstyle={styles.content}>
<XDSVStack gap={2}>
<XDSHeading level={1}>Shell Lab</XDSHeading>
diff --git a/packages/cli/src/codemods/registry.mjs b/packages/cli/src/codemods/registry.mjs
index a8bf0b476e..5e506ec794 100644
--- a/packages/cli/src/codemods/registry.mjs
+++ b/packages/cli/src/codemods/registry.mjs
@@ -7,6 +7,7 @@
const registry = new Map([
['0.0.2', () => import('./transforms/v0.0.2/index.mjs')],
+ ['0.0.5', () => import('./transforms/v0.0.5/index.mjs')],
]);
/**
diff --git a/packages/cli/src/codemods/transforms/v0.0.5/__tests__/migrate-collapse-to-collapsible.test.mjs b/packages/cli/src/codemods/transforms/v0.0.5/__tests__/migrate-collapse-to-collapsible.test.mjs
new file mode 100644
index 0000000000..47929b6496
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.5/__tests__/migrate-collapse-to-collapsible.test.mjs
@@ -0,0 +1,70 @@
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../migrate-collapse-to-collapsible.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const file = {source, path: 'test.tsx'};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('migrate-collapse-to-collapsible', () => {
+ it('converts isCollapsible to collapsible (boolean shorthand)', async () => {
+ const input = '<XDSSideNav isCollapsible>Content</XDSSideNav>';
+ const output = await applyTransform(input);
+ expect(output).toContain('collapsible');
+ expect(output).not.toContain('isCollapsible');
+ });
+
+ it('converts isCollapsible + defaultIsCollapsed to collapsible object', async () => {
+ const input = '<XDSSideNav isCollapsible defaultIsCollapsed>Content</XDSSideNav>';
+ const output = await applyTransform(input);
+ expect(output).toContain('collapsible={');
+ expect(output).toContain('defaultIsCollapsed');
+ expect(output).not.toContain('isCollapsible');
+ });
+
+ it('converts controlled collapse props to collapsible object', async () => {
+ const input = '<XDSSideNav isCollapsible isCollapsed={collapsed} onCollapsedChange={setCollapsed}>Content</XDSSideNav>';
+ const output = await applyTransform(input);
+ expect(output).toContain('collapsible={');
+ expect(output).toContain('isCollapsed');
+ expect(output).toContain('onCollapsedChange');
+ expect(output).not.toContain('isCollapsible');
+ });
+
+ it('converts hasCollapseButton={false} to hasButton: false', async () => {
+ const input = '<XDSSideNav isCollapsible hasCollapseButton={false}>Content</XDSSideNav>';
+ const output = await applyTransform(input);
+ expect(output).toContain('hasButton: false');
+ expect(output).not.toContain('hasCollapseButton');
+ });
+
+ it('removes deprecated AppShell collapse props', async () => {
+ const input = '<XDSAppShell isSideNavCollapsed={collapsed} onSideNavCollapsedChange={setCollapsed} defaultIsSideNavCollapsed={true}><Content /></XDSAppShell>';
+ const output = await applyTransform(input);
+ expect(output).not.toContain('isSideNavCollapsed');
+ expect(output).not.toContain('onSideNavCollapsedChange');
+ expect(output).not.toContain('defaultIsSideNavCollapsed');
+ });
+
+ it('returns undefined when no changes needed', async () => {
+ const {default: transform} = await import(
+ '../migrate-collapse-to-collapsible.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const source = '<XDSSideNav collapsible>Content</XDSSideNav>';
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+
+ it('does not affect other components', async () => {
+ const input = '<XDSCard isCollapsible>Content</XDSCard>';
+ const output = await applyTransform(input);
+ expect(output).toContain('isCollapsible');
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.0.5/index.mjs b/packages/cli/src/codemods/transforms/v0.0.5/index.mjs
new file mode 100644
index 0000000000..a49439f00c
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.5/index.mjs
@@ -0,0 +1,15 @@
+/**
+ * @file v0.0.5 transform manifest
+ */
+
+import migrateCollapseToCollapsible, {
+ meta as collapseMeta,
+} from './migrate-collapse-to-collapsible.mjs';
+
+export default [
+ {
+ name: 'migrate-collapse-to-collapsible',
+ transform: migrateCollapseToCollapsible,
+ meta: collapseMeta,
+ },
+];
diff --git a/packages/cli/src/codemods/transforms/v0.0.5/migrate-collapse-to-collapsible.mjs b/packages/cli/src/codemods/transforms/v0.0.5/migrate-collapse-to-collapsible.mjs
new file mode 100644
index 0000000000..eeb5f348d1
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.5/migrate-collapse-to-collapsible.mjs
@@ -0,0 +1,143 @@
+/**
+ * @file Codemod: Migrate XDSSideNav collapse props to collapsible
+ *
+ * Transforms:
+ * - isCollapsible → collapsible
+ * - isCollapsible + isCollapsed={x} + onCollapsedChange={y} → collapsible={{ isCollapsed: x, onCollapsedChange: y }}
+ * - isCollapsible + defaultIsCollapsed → collapsible={{ defaultIsCollapsed: true }}
+ * - isCollapsible + hasCollapseButton={false} → collapsible={{ hasButton: false }}
+ * - Combinations of the above
+ *
+ * Also removes deprecated AppShell collapse props:
+ * - isSideNavCollapsed
+ * - onSideNavCollapsedChange
+ * - defaultIsSideNavCollapsed
+ */
+
+export const meta = {
+ title: 'Migrate collapse props to collapsible',
+ description:
+ 'Replaces `isCollapsible` + related props on XDSSideNav with the unified `collapsible` prop. Removes deprecated AppShell collapse props.',
+};
+
+const SIDENAV_COLLAPSE_PROPS = [
+ 'isCollapsible',
+ 'isCollapsed',
+ 'onCollapsedChange',
+ 'defaultIsCollapsed',
+ 'hasCollapseButton',
+];
+
+const APPSHELL_DEPRECATED_PROPS = [
+ 'isSideNavCollapsed',
+ 'onSideNavCollapsedChange',
+ 'defaultIsSideNavCollapsed',
+];
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // --- XDSSideNav: migrate to collapsible prop ---
+ root
+ .find(j.JSXOpeningElement, {
+ name: {name: 'XDSSideNav'},
+ })
+ .forEach((path) => {
+ const attrs = path.node.attributes;
+
+ // Find isCollapsible
+ const isCollapsibleIdx = attrs.findIndex(
+ (a) => a.type === 'JSXAttribute' && a.name.name === 'isCollapsible',
+ );
+ if (isCollapsibleIdx === -1) return;
+
+ // Collect all collapse-related props
+ const collapseProps = {};
+ const indicesToRemove = [];
+
+ for (let i = 0; i < attrs.length; i++) {
+ const attr = attrs[i];
+ if (attr.type !== 'JSXAttribute') continue;
+ const name = attr.name.name;
+ if (!SIDENAV_COLLAPSE_PROPS.includes(name)) continue;
+
+ indicesToRemove.push(i);
+
+ if (name === 'isCollapsible') {
+ // Just a flag — value doesn't matter for the config
+ continue;
+ }
+
+ if (name === 'hasCollapseButton') {
+ // Map to hasButton
+ if (
+ attr.value &&
+ attr.value.type === 'JSXExpressionContainer' &&
+ attr.value.expression.value === false
+ ) {
+ collapseProps.hasButton = j.objectProperty(
+ j.identifier('hasButton'),
+ j.booleanLiteral(false),
+ );
+ }
+ continue;
+ }
+
+ // isCollapsed, onCollapsedChange, defaultIsCollapsed
+ const value = attr.value
+ ? attr.value.type === 'JSXExpressionContainer'
+ ? attr.value.expression
+ : attr.value
+ : j.booleanLiteral(true);
+ collapseProps[name] = j.objectProperty(
+ j.identifier(name),
+ value,
+ );
+ }
+
+ // Remove old props (reverse order to preserve indices)
+ indicesToRemove.sort((a, b) => b - a);
+ for (const idx of indicesToRemove) {
+ attrs.splice(idx, 1);
+ }
+
+ // Build the new collapsible prop
+ const configKeys = Object.keys(collapseProps);
+ if (configKeys.length === 0) {
+ // Simple: isCollapsible → collapsible (boolean shorthand)
+ attrs.push(j.jsxAttribute(j.jsxIdentifier('collapsible')));
+ } else {
+ // Object form
+ const properties = Object.values(collapseProps);
+ attrs.push(
+ j.jsxAttribute(
+ j.jsxIdentifier('collapsible'),
+ j.jsxExpressionContainer(j.objectExpression(properties)),
+ ),
+ );
+ }
+
+ hasChanges = true;
+ });
+
+ // --- XDSAppShell: remove deprecated collapse props ---
+ root
+ .find(j.JSXOpeningElement, {
+ name: {name: 'XDSAppShell'},
+ })
+ .forEach((path) => {
+ const attrs = path.node.attributes;
+ for (let i = attrs.length - 1; i >= 0; i--) {
+ const attr = attrs[i];
+ if (attr.type !== 'JSXAttribute') continue;
+ if (APPSHELL_DEPRECATED_PROPS.includes(attr.name.name)) {
+ attrs.splice(i, 1);
+ hasChanges = true;
+ }
+ }
+ });
+
+ return hasChanges ? root.toSource() : undefined;
+}
diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsx
index d05dcfd999..59b92325ab 100644
--- a/packages/core/src/AppShell/XDSAppShell.test.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx
@@ -230,73 +230,26 @@ describe('XDSAppShell', () => {
expect(screen.getByRole('navigation')).toBeInTheDocument();
});
- it('sideNav is hidden when defaultIsSideNavCollapsed is true', () => {
- render(
- <XDSAppShell sideNav={<TestSideNav />} defaultIsSideNavCollapsed={true}>
- <div>Content</div>
- </XDSAppShell>,
- );
- expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
- });
-
- // ===========================================================================
- // SideNav collapse — controlled
- // ===========================================================================
-
- it('sideNav is hidden when isSideNavCollapsed is true (controlled)', () => {
- render(
- <XDSAppShell
- sideNav={<TestSideNav />}
- isSideNavCollapsed={true}
- onSideNavCollapsedChange={() => {}}>
- <div>Content</div>
- </XDSAppShell>,
- );
- expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
- });
-
- it('sideNav is visible when isSideNavCollapsed is false (controlled)', () => {
- render(
- <XDSAppShell
- sideNav={<TestSideNav />}
- isSideNavCollapsed={false}
- onSideNavCollapsedChange={() => {}}>
- <div>Content</div>
- </XDSAppShell>,
- );
- expect(screen.getByRole('navigation')).toBeInTheDocument();
- });
+ // (Collapse tests removed — collapse is now managed by XDSSideNav, not AppShell)
// ===========================================================================
// Responsive breakpoint
// ===========================================================================
- it('auto-collapses sideNav below breakpoint', () => {
- const onChange = vi.fn();
+ it('tracks breakpoint changes', () => {
render(
- <XDSAppShell
- sideNav={<TestSideNav />}
- sideNavBreakpoint="md"
- onSideNavCollapsedChange={onChange}>
+ <XDSAppShell sideNav={<TestSideNav />} sideNavBreakpoint="md">
<div>Content</div>
</XDSAppShell>,
);
- // Simulate going below breakpoint
- act(() => {
- mockMql._setMatches(true);
- });
-
- expect(onChange).toHaveBeenCalledWith(true);
+ // matchMedia should have been called for the breakpoint
+ expect(window.matchMedia).toHaveBeenCalled();
});
- it('does not auto-collapse when sideNavBreakpoint is none', () => {
- const onChange = vi.fn();
+ it('does not track breakpoint when sideNavBreakpoint is none', () => {
render(
- <XDSAppShell
- sideNav={<TestSideNav />}
- sideNavBreakpoint="none"
- onSideNavCollapsedChange={onChange}>
+ <XDSAppShell sideNav={<TestSideNav />} sideNavBreakpoint="none">
<div>Content</div>
</XDSAppShell>,
);
@@ -314,10 +267,7 @@ describe('XDSAppShell', () => {
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
- <XDSAppShell
- sideNav={<TestSideNav />}
- isSideNavCollapsed={false}
- onSideNavCollapsedChange={() => {}}>
+ <XDSAppShell sideNav={<TestSideNav />}>
<div>Content</div>
</XDSAppShell>,
);
@@ -328,24 +278,18 @@ describe('XDSAppShell', () => {
expect(screen.getByText('Nav')).toBeInTheDocument();
});
- it('default mobile nav calls onSideNavCollapsedChange on close', () => {
+ it('renders default mobile nav when below breakpoint', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
- const onChange = vi.fn();
render(
- <XDSAppShell
- sideNav={<TestSideNav />}
- isSideNavCollapsed={false}
- onSideNavCollapsedChange={onChange}>
+ <XDSAppShell sideNav={<TestSideNav />}>
<div>Content</div>
</XDSAppShell>,
);
- // Click the close button inside the default mobile nav
- const closeButton = screen.getByRole('button', {name: /close/i});
- fireEvent.click(closeButton);
- expect(onChange).toHaveBeenCalledWith(true);
+ // Default mobile nav should be rendered when below breakpoint
+ expect(screen.getByTestId('sidenav-mobile')).toBeInTheDocument();
});
// ===========================================================================
@@ -525,9 +469,7 @@ describe('XDSAppShell', () => {
data-testid="appshell-mobile-nav">
<div>Mobile Nav</div>
</XDSMobileNav>
- }
- isSideNavCollapsed={false}
- onSideNavCollapsedChange={() => {}}>
+ }>
<div>Content</div>
</XDSAppShell>,
);
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index af2b7b344c..a9adca3e47 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -117,17 +117,6 @@ export interface XDSAppShellProps {
*/
height?: 'fill' | 'auto';
- /**
- * Default collapsed state for uncontrolled usage.
- * @default false
- */
- defaultIsSideNavCollapsed?: boolean;
-
- /**
- * Whether the side nav is collapsed (controlled).
- */
- isSideNavCollapsed?: boolean;
-
/**
* Mobile navigation — typically an XDSMobileNav.
*
@@ -140,11 +129,6 @@ export interface XDSAppShellProps {
*/
mobileNav?: ReactNode;
- /**
- * Callback when side nav collapsed state changes.
- */
- onSideNavCollapsedChange?: (isCollapsed: boolean) => void;
-
/**
* Side navigation — typically an XDSSideNav.
*/
@@ -365,10 +349,7 @@ export function XDSAppShell({
contentPadding,
'data-testid': dataTestId,
height = 'fill',
- defaultIsSideNavCollapsed = false,
- isSideNavCollapsed: controlledCollapsed,
mobileNav,
- onSideNavCollapsedChange,
sideNav,
sideNavBreakpoint = 'md',
sideNavWidth = DEFAULT_SIDENAV_WIDTH,
@@ -381,16 +362,9 @@ export function XDSAppShell({
// =========================================================================
// SideNav collapse state (controlled + uncontrolled)
// =========================================================================
- const isControlled = controlledCollapsed !== undefined;
- const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState(
- defaultIsSideNavCollapsed,
- );
- const isCollapsed = isControlled
- ? controlledCollapsed
- : uncontrolledCollapsed;
-
// Track whether we're below the breakpoint
const [isBelowBreakpoint, setIsBelowBreakpoint] = useState(false);
+ const [isMobileNavOpen, setIsMobileNavOpen] = useState(false);
const isFill = height === 'fill';
const isAuto = height === 'auto';
@@ -475,13 +449,6 @@ export function XDSAppShell({
const handleChange = (e: MediaQueryListEvent | MediaQueryList) => {
const matches = 'matches' in e ? e.matches : false;
setIsBelowBreakpoint(matches);
- if (matches) {
- // Auto-collapse below breakpoint
- if (!isControlled) {
- setUncontrolledCollapsed(true);
- }
- onSideNavCollapsedChange?.(true);
- }
};
// Check initial state
@@ -489,24 +456,12 @@ export function XDSAppShell({
mql.addEventListener('change', handleChange);
return () => mql.removeEventListener('change', handleChange);
- }, [sideNavBreakpoint, hasSideNav, isControlled, onSideNavCollapsedChange]);
-
- // =========================================================================
- // Toggle handler — snaps open/closed (no transitions for now)
- // TODO: Add ViewTransitions support with React transition API
- // =========================================================================
- const handleToggleCollapse = useCallback(() => {
- const newValue = !isCollapsed;
- if (!isControlled) {
- setUncontrolledCollapsed(newValue);
- }
- onSideNavCollapsedChange?.(newValue);
- }, [isCollapsed, isControlled, onSideNavCollapsedChange]);
+ }, [sideNavBreakpoint, hasSideNav]);
// =========================================================================
// Determine if sideNav should show as overlay (mobile) or inline
// =========================================================================
- const showSideNavInline = hasSideNav && !isCollapsed && !isBelowBreakpoint;
+ const showSideNavInline = hasSideNav && !isBelowBreakpoint;
// Default mobile nav: when no explicit mobileNav is provided, AppShell
// internally renders an XDSMobileNav wrapping the sideNav content.
// This shares the same <dialog>-based behavior as explicit mobileNav.
@@ -554,7 +509,6 @@ export function XDSAppShell({
<XDSLayoutPanel
padding={0}
hasDivider={navHasDividers}
- width={sideNavWidth}
isScrollable={isFill}
xstyle={[navAreaStyle, isAuto && styles.panelAutoFill]}>
{sideNav}
@@ -644,8 +598,8 @@ export function XDSAppShell({
{mobileNav}
{useDefaultMobileNav && (
<XDSMobileNav
- isOpen={!isCollapsed}
- onOpenChange={() => handleToggleCollapse()}
+ isOpen={isMobileNavOpen}
+ onOpenChange={open => setIsMobileNavOpen(open)}
width={sideNavWidth}
data-testid="sidenav-mobile">
{sideNav}
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index edcbd81c4d..48532bd786 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -16,12 +16,14 @@
'use client';
-import {type ReactNode} from 'react';
+import {useCallback, useState, type ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
+import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';
+import {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';
// =============================================================================
// Styles
@@ -32,10 +34,14 @@ const styles = stylex.create({
display: 'flex',
flexDirection: 'column',
height: '100%',
+ width: 260,
backgroundColor: 'inherit',
boxSizing: 'border-box',
overflow: 'hidden',
},
+ rootCollapsed: {
+ width: 52,
+ },
stickyTop: {
display: 'flex',
flexDirection: 'column',
@@ -82,11 +88,27 @@ const styles = stylex.create({
paddingBlockEnd: spacingVars['--spacing-2'],
borderBlockStart: `1px solid ${colorVars['--color-divider']}`,
},
+ footerRow: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ },
+ footerRowCollapsed: {
+ flexDirection: 'column-reverse',
+ },
footerIcons: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-1'],
},
+ footerIconsCollapsed: {
+ flexDirection: 'column',
+ alignItems: 'center',
+ },
+ stickyBottomCollapsed: {
+ borderBlockStart: 'none',
+ paddingBlockStart: 0,
+ },
});
// =============================================================================
@@ -141,6 +163,29 @@ export interface XDSSideNavProps extends XDSBaseProps<HTMLElement> {
* Test ID for the root element.
*/
'data-testid'?: string;
+
+ /**
+ * Enables collapse behavior. The sidebar can be collapsed to a narrow
+ * icon-only toolbar.
+ *
+ * - `true` — enables collapse with default toggle button and uncontrolled state
+ * - Object — enables collapse with advanced configuration:
+ * - `defaultIsCollapsed` — start collapsed (uncontrolled)
+ * - `isCollapsed` + `onCollapsedChange` — controlled mode
+ * - `hasButton` — render built-in collapse button (default: true)
+ * - `buttonLabel` — accessibility label for the collapse button
+ *
+ * @default false
+ */
+ collapsible?:
+ | boolean
+ | {
+ defaultIsCollapsed?: boolean;
+ isCollapsed?: boolean;
+ onCollapsedChange?: (isCollapsed: boolean) => void;
+ hasButton?: boolean;
+ buttonLabel?: string;
+ };
}
// =============================================================================
@@ -171,6 +216,7 @@ export function XDSSideNav({
children,
footer,
footerIcons,
+ collapsible = false,
xstyle,
className,
style,
@@ -178,10 +224,38 @@ export function XDSSideNav({
ref,
...props
}: XDSSideNavProps) {
+ // Parse collapsible prop
+ const collapsibleConfig = typeof collapsible === 'object' ? collapsible : {};
+ const isCollapsible = !!collapsible;
+ const hasCollapseButton = collapsibleConfig.hasButton ?? true;
+ const defaultIsCollapsed = collapsibleConfig.defaultIsCollapsed ?? false;
+ const controlledCollapsed = collapsibleConfig.isCollapsed;
+ const onCollapsedChange = collapsibleConfig.onCollapsedChange;
+
+ // Collapse state (controlled + uncontrolled)
+ const isControlled = controlledCollapsed !== undefined;
+ const [uncontrolledCollapsed, setUncontrolledCollapsed] =
+ useState(defaultIsCollapsed);
+ const collapsed = isControlled ? controlledCollapsed : uncontrolledCollapsed;
+
+ const toggle = useCallback(() => {
+ const newValue = !collapsed;
+ if (!isControlled) {
+ setUncontrolledCollapsed(newValue);
+ }
+ onCollapsedChange?.(newValue);
+ }, [collapsed, isControlled, onCollapsedChange]);
+
+ const collapseContext = {
+ isCollapsed: collapsed,
+ toggle,
+ isCollapsible,
+ };
+
const hasStickyTop = !!(header || topContent);
const hasStickyBottom = !!(footer || footerIcons);
- return (
+ const content = (
<nav
ref={ref}
role="navigation"
@@ -189,7 +263,7 @@ export function XDSSideNav({
data-testid={testId}
{...mergeProps(
xdsClassName('side-nav'),
- stylex.props(styles.root, xstyle),
+ stylex.props(styles.root, collapsed && styles.rootCollapsed, xstyle),
className,
style,
)}
@@ -212,16 +286,35 @@ export function XDSSideNav({
)}>
{children}
</div>
- {hasStickyBottom && (
- <div {...stylex.props(styles.stickyBottom)}>
+ {(hasStickyBottom || isCollapsible) && (
+ <div
+ {...stylex.props(
+ styles.stickyBottom,
+ collapsed && styles.stickyBottomCollapsed,
+ )}>
{footer}
- {footerIcons && (
- <div {...stylex.props(styles.footerIcons)}>{footerIcons}</div>
- )}
+ <div
+ {...stylex.props(
+ styles.footerRow,
+ collapsed && styles.footerRowCollapsed,
+ )}>
+ {isCollapsible && hasCollapseButton && <XDSSideNavCollapseButton />}
+ {footerIcons}
+ </div>
</div>
)}
</nav>
);
+
+ if (isCollapsible) {
+ return (
+ <XDSSideNavCollapseContext value={collapseContext}>
+ {content}
+ </XDSSideNavCollapseContext>
+ );
+ }
+
+ return content;
}
XDSSideNav.displayName = 'XDSSideNav';
diff --git a/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx b/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx
new file mode 100644
index 0000000000..f151047613
--- /dev/null
+++ b/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx
@@ -0,0 +1,128 @@
+/**
+ * @file XDSSideNavCollapseButton.tsx
+ * @input Uses React, StyleX, XDSSideNavCollapseContext, getIcon
+ * @output Exports XDSSideNavCollapseButton component
+ * @position Composable toggle button for sidenav collapse
+ *
+ * Place inside XDSSideNav (reads context automatically) or outside
+ * (pass sideNavRef to connect). Customizable via label/children.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/SideNav/SideNav.doc.mjs
+ * - /packages/core/src/SideNav/index.ts
+ */
+
+'use client';
+
+import {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {transitionVars} from '../theme/tokens.stylex';
+import {getIcon} from '../Icon/globalIconRegistry';
+import {XDSButton} from '../Button';
+import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ chevron: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ transitionProperty: 'transform',
+ transitionDuration: transitionVars['--transition-fast'],
+ },
+ chevronCollapsed: {
+ transform: 'rotate(180deg)',
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSSideNavCollapseButtonProps {
+ /**
+ * Ref to the XDSSideNav element. Only needed when the button is
+ * rendered outside the sidenav (reads collapse state via ref instead
+ * of context).
+ */
+ sideNavRef?: React.RefObject<HTMLElement | null>;
+
+ /**
+ * Custom button label text. When provided, renders as a text button
+ * with the chevron icon. When omitted, renders as an icon-only button.
+ */
+ label?: string;
+
+ /**
+ * Custom button content. Overrides the default chevron icon and label.
+ */
+ children?: ReactNode;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Composable toggle button for sidenav collapse.
+ *
+ * Place anywhere inside XDSSideNav (header, topContent, footer, footerIcons)
+ * and it reads collapse state from context automatically. For placement
+ * outside the sidenav (e.g. in TopNav or content area), pass sideNavRef.
+ *
+ * @example
+ * ```
+ * <XDSSideNav isCollapsible footerIcons={<XDSSideNavCollapseButton />}>
+ * ...
+ * </XDSSideNav>
+ * ```
+ *
+ * @example
+ * ```
+ * const ref = useRef(null);
+ * <XDSTopNav endContent={<XDSSideNavCollapseButton sideNavRef={ref} />} />
+ * <XDSSideNav ref={ref} isCollapsible>...</XDSSideNav>
+ * ```
+ */
+export function XDSSideNavCollapseButton({
+ sideNavRef: _sideNavRef,
+ label,
+ children,
+}: XDSSideNavCollapseButtonProps) {
+ const {isCollapsed, toggle, isCollapsible} = useXDSSideNavCollapse();
+
+ const handleClick = useCallback(() => {
+ toggle();
+ }, [toggle]);
+
+ // TODO: sideNavRef-based wiring for outside-sidenav usage
+ // For now, the button only works via context (inside sidenav or
+ // when AppShell provides the context at the shell level).
+
+ if (!isCollapsible) {
+ return null;
+ }
+
+ return (
+ <XDSButton
+ label={label ?? (isCollapsed ? 'Expand sidebar' : 'Collapse sidebar')}
+ variant="ghost"
+ onClick={handleClick}
+ icon={
+ children ?? (
+ <span
+ {...stylex.props(
+ styles.chevron,
+ isCollapsed && styles.chevronCollapsed,
+ )}>
+ {getIcon('chevronLeft')}
+ </span>
+ )
+ }
+ />
+ );
+}
+
+XDSSideNavCollapseButton.displayName = 'XDSSideNavCollapseButton';
diff --git a/packages/core/src/SideNav/XDSSideNavCollapseContext.ts b/packages/core/src/SideNav/XDSSideNavCollapseContext.ts
new file mode 100644
index 0000000000..4f6d260e77
--- /dev/null
+++ b/packages/core/src/SideNav/XDSSideNavCollapseContext.ts
@@ -0,0 +1,35 @@
+/**
+ * @file XDSSideNavCollapseContext.ts
+ * @input React createContext, useContext
+ * @output Exports XDSSideNavCollapseContext and useXDSSideNavCollapse hook
+ * @position Internal context for sidenav collapse state
+ *
+ * Provides collapse state to XDSSideNavCollapseButton and other
+ * sidenav children. Set by XDSSideNav when isCollapsible is true.
+ */
+
+import {createContext, useContext} from 'react';
+
+export interface SideNavCollapseState {
+ /** Whether the sidenav is currently collapsed */
+ isCollapsed: boolean;
+ /** Toggle collapse state */
+ toggle: () => void;
+ /** Whether collapse is enabled */
+ isCollapsible: boolean;
+}
+
+export const XDSSideNavCollapseContext = createContext<SideNavCollapseState>({
+ isCollapsed: false,
+ toggle: () => {},
+ isCollapsible: false,
+});
+
+/**
+ * Read the sidenav collapse state from context.
+ * Returns { isCollapsed, toggle, isCollapsible }.
+ * When used outside a sidenav with isCollapsible, isCollapsible is false.
+ */
+export function useXDSSideNavCollapse(): SideNavCollapseState {
+ return useContext(XDSSideNavCollapseContext);
+}
diff --git a/packages/core/src/SideNav/XDSSideNavHeading.tsx b/packages/core/src/SideNav/XDSSideNavHeading.tsx
index 23774cf466..877c6739e0 100644
--- a/packages/core/src/SideNav/XDSSideNavHeading.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeading.tsx
@@ -33,6 +33,7 @@ import {
import {useXDSPopover} from '../Popover/useXDSPopover';
import {XDSLink} from '../Link';
import {getIcon} from '../Icon/globalIconRegistry';
+import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
@@ -51,6 +52,10 @@ const styles = stylex.create({
color: 'inherit',
cursor: 'default',
},
+ rootCollapsed: {
+ justifyContent: 'center',
+ paddingInline: spacingVars['--spacing-0-5'],
+ },
interactive: {
cursor: 'pointer',
borderRadius: radiusVars['--radius-element'],
@@ -256,28 +261,17 @@ export function XDSSideNavHeading({
ref,
...props
}: XDSSideNavHeadingProps) {
+ const {isCollapsed} = useXDSSideNavCollapse();
const rootRef = useRef<HTMLDivElement>(null);
const popover = useXDSPopover({
dialogLabel: 'Navigation menu',
});
- const showChevron = !!menu;
- const hasAnyHref = !!(headingHref || superheadingHref || subheadingHref);
- const hasCompactHeading = !!(superheading || subheading);
-
- // Determine interaction mode
- const isWholeHeadingTrigger = !!menu && !hasAnyHref;
- const isWholeHeadingLink =
- !!headingHref && !menu && !superheadingHref && !subheadingHref;
-
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;
@@ -293,6 +287,36 @@ export function XDSSideNavHeading({
[ref, popover, menu],
);
+ // In collapsed mode: hide if no icon, show icon-only if has icon
+ if (isCollapsed && !icon) {
+ return null;
+ }
+ if (isCollapsed && icon) {
+ return (
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('side-nav-heading'),
+ stylex.props(styles.root, styles.rootCollapsed, xstyle),
+ className,
+ style,
+ )}
+ {...props}>
+ <span {...stylex.props(styles.icon)}>{icon}</span>
+ </div>
+ );
+ }
+
+ const showChevron = !!menu;
+ const hasAnyHref = !!(headingHref || superheadingHref || subheadingHref);
+ const hasCompactHeading = !!(superheading || subheading);
+
+ // Determine interaction mode
+ const isWholeHeadingTrigger = !!menu && !hasAnyHref;
+ const isWholeHeadingLink =
+ !!headingHref && !menu && !superheadingHref && !subheadingHref;
+
// Render text content
const renderTextContent = () => (
<span {...stylex.props(styles.textContainer)}>
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index b225d07489..92369589aa 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -15,7 +15,7 @@
'use client';
-import {useId, type ReactNode} from 'react';
+import {useId, useRef, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
@@ -30,6 +30,8 @@ import type {XDSIconType} from '../Icon';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
import {xdsClassName, mergeProps} from '../utils';
+import {XDSTooltip} from '../Tooltip';
+import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
// =============================================================================
// Styles
@@ -67,6 +69,10 @@ const styles = stylex.create({
},
},
},
+ itemCollapsed: {
+ justifyContent: 'center',
+ paddingInline: spacingVars['--spacing-1'],
+ },
selected: {
backgroundColor: colorVars['--color-deemphasized'],
fontWeight: fontWeightVars['--font-weight-medium'],
@@ -193,12 +199,19 @@ export function XDSSideNavItem({
'data-testid': testId,
ref,
}: XDSSideNavItemProps) {
+ const {isCollapsed} = useXDSSideNavCollapse();
const id = useId();
const hasChildren = !!children;
const LinkComponent = useXDSLinkComponent(as);
+ const itemRef = useRef<HTMLDivElement>(null);
const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
+ // In collapsed mode: hide items without icons
+ if (isCollapsed && !icon) {
+ return <div style={{display: 'none'}} />;
+ }
+
const handleClick = (e: React.MouseEvent) => {
if (isDisabled) {
e.preventDefault();
@@ -216,8 +229,8 @@ export function XDSSideNavItem({
color={isSelected ? 'primary' : isDisabled ? 'disabled' : 'secondary'}
/>
)}
- <span {...stylex.props(styles.label)}>{label}</span>
- {endContent && (
+ {!isCollapsed && <span {...stylex.props(styles.label)}>{label}</span>}
+ {!isCollapsed && endContent && (
<span {...stylex.props(styles.endContent)}>{endContent}</span>
)}
</>
@@ -238,6 +251,7 @@ export function XDSSideNavItem({
{...ariaProps}
{...stylex.props(
styles.item,
+ isCollapsed && styles.itemCollapsed,
isSelected && styles.selected,
isDisabled && styles.disabled,
)}>
@@ -252,6 +266,7 @@ export function XDSSideNavItem({
{...ariaProps}
{...stylex.props(
styles.item,
+ isCollapsed && styles.itemCollapsed,
isSelected && styles.selected,
isDisabled && styles.disabled,
)}>
@@ -259,11 +274,12 @@ export function XDSSideNavItem({
</button>
);
- return (
+ const item = (
<div
+ ref={itemRef}
{...mergeProps(xdsClassName('side-nav-item'), stylex.props(styles.root))}>
{itemElement}
- {hasChildren && (
+ {hasChildren && !isCollapsed && (
<div
role="group"
aria-labelledby={`${id}-label`}
@@ -276,6 +292,15 @@ export function XDSSideNavItem({
)}
</div>
);
+
+ return (
+ <>
+ {item}
+ {isCollapsed && (
+ <XDSTooltip content={label} placement="end" anchorRef={itemRef} />
+ )}
+ </>
+ );
}
XDSSideNavItem.displayName = 'XDSSideNavItem';
diff --git a/packages/core/src/SideNav/XDSSideNavSection.tsx b/packages/core/src/SideNav/XDSSideNavSection.tsx
index 28d4ece7db..16f50cf431 100644
--- a/packages/core/src/SideNav/XDSSideNavSection.tsx
+++ b/packages/core/src/SideNav/XDSSideNavSection.tsx
@@ -25,6 +25,7 @@ import {
lineHeightVars,
} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
+import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
// =============================================================================
// Styles
// =============================================================================
@@ -140,6 +141,7 @@ export function XDSSideNavSection({
isHeaderHidden = false,
'data-testid': testId,
}: XDSSideNavSectionProps) {
+ const {isCollapsed} = useXDSSideNavCollapse();
const id = useId();
const titleId = `${id}-title`;
@@ -157,7 +159,9 @@ export function XDSSideNavSection({
</>
);
- const visuallyHiddenStyle: React.CSSProperties = isHeaderHidden
+ const shouldHideHeader = isHeaderHidden || isCollapsed;
+
+ const visuallyHiddenStyle: React.CSSProperties = shouldHideHeader
? {
position: 'absolute',
width: 1,
@@ -181,7 +185,7 @@ export function XDSSideNavSection({
stylex.props(styles.root),
)}>
<div
- style={isHeaderHidden ? visuallyHiddenStyle : undefined}
+ style={shouldHideHeader ? visuallyHiddenStyle : undefined}
{...stylex.props(styles.header)}>
{headerContent}
</div>
diff --git a/packages/core/src/SideNav/index.ts b/packages/core/src/SideNav/index.ts
index 70b706fb1d..ca261565c4 100644
--- a/packages/core/src/SideNav/index.ts
+++ b/packages/core/src/SideNav/index.ts
@@ -18,3 +18,8 @@ export type {XDSSideNavItemProps} from './XDSSideNavItem';
export {XDSSideNavSection} from './XDSSideNavSection';
export type {XDSSideNavSectionProps} from './XDSSideNavSection';
+
+export {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';
+export type {XDSSideNavCollapseButtonProps} from './XDSSideNavCollapseButton';
+
+export {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';