Skip to content

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

TypeScript

feat(SideNav): popover for collapsed items with children (#680)

Cindy Zhange48535916bce
diff --git a/packages/core/src/SideNav/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsx
index 91b42b66dc..7da95f1ff9 100644
--- a/packages/core/src/SideNav/XDSSideNav.test.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx
@@ -7,6 +7,7 @@
* SYNC: When SideNav components change, update tests to match new behavior
*/
+import React from 'react';
import {describe, it, expect, vi} from 'vitest';
import {render, screen, act} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
@@ -16,6 +17,7 @@ import {XDSSideNavHeading} from './XDSSideNavHeading';
import {XDSSideNavItem} from './XDSSideNavItem';
import {XDSSideNavSection} from './XDSSideNavSection';
import {XDSLinkProvider} from '../Link/XDSLinkProvider';
+import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';
const CustomLink = forwardRef<HTMLAnchorElement, ComponentPropsWithoutRef<'a'>>(
({children, ...props}, ref) => (
@@ -496,3 +498,121 @@ describe('SideNav integration', () => {
expect(screen.getByTestId('promo')).toBeInTheDocument();
});
});
+
+// Stub icon for testing
+const StubIcon = () => <svg data-testid="stub-icon" />;
+
+/** Helper to render inside a collapsed SideNav context */
+function renderCollapsed(ui: React.ReactElement) {
+ return render(
+ <XDSSideNavCollapseContext
+ value={{isCollapsed: true, toggle: () => {}, isCollapsible: true}}>
+ {ui}
+ </XDSSideNavCollapseContext>,
+ );
+}
+
+/** Helper to render inside an expanded SideNav context */
+function renderExpanded(ui: React.ReactElement) {
+ return render(
+ <XDSSideNavCollapseContext
+ value={{isCollapsed: false, toggle: () => {}, isCollapsible: true}}>
+ {ui}
+ </XDSSideNavCollapseContext>,
+ );
+}
+
+// =============================================================================
+// XDSSideNavItem — Collapsed mode
+// =============================================================================
+
+describe('XDSSideNavItem (collapsed)', () => {
+ it('hides items without icons when collapsed', () => {
+ const {container} = renderCollapsed(
+ <XDSSideNavItem label="No Icon Item" />,
+ );
+ expect(screen.queryByText('No Icon Item')).not.toBeInTheDocument();
+ expect(container.querySelector('[data-xds="side-nav-item"]')).toBeNull();
+ });
+
+ it('renders icon-only button when collapsed with icon and no children', () => {
+ renderCollapsed(
+ <XDSSideNavItem label="Dashboard" icon={StubIcon} data-testid="item" />,
+ );
+ // Should have an element with aria-label (icon-only)
+ const item = screen.getByLabelText('Dashboard');
+ expect(item).toBeInTheDocument();
+ // Icon should be rendered
+ expect(screen.getByTestId('stub-icon')).toBeInTheDocument();
+ });
+
+ it('renders collapsed link when href is provided', () => {
+ renderCollapsed(
+ <XDSSideNavItem label="Dashboard" icon={StubIcon} href="/dashboard" />,
+ );
+ const link = screen.getByRole('link');
+ expect(link).toHaveAttribute('href', '/dashboard');
+ expect(link).toHaveAttribute('aria-label', 'Dashboard');
+ });
+
+ it('renders popover trigger when collapsed with icon and children', () => {
+ renderCollapsed(
+ <XDSSideNavItem label="Settings" icon={StubIcon} data-testid="parent">
+ <XDSSideNavItem label="General" />
+ <XDSSideNavItem label="Security" />
+ </XDSSideNavItem>,
+ );
+ const trigger = screen.getByTestId('parent');
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ expect(trigger).toHaveAttribute('aria-label', 'Settings');
+ });
+
+ it('opens popover on click showing children in expanded form', async () => {
+ const user = userEvent.setup();
+ renderCollapsed(
+ <XDSSideNavItem label="Settings" icon={StubIcon} data-testid="parent">
+ <XDSSideNavItem label="General" data-testid="child-general" />
+ <XDSSideNavItem label="Security" data-testid="child-security" />
+ </XDSSideNavItem>,
+ );
+ await user.click(screen.getByTestId('parent'));
+
+ // Children should be visible in expanded form (label text visible)
+ expect(screen.getByText('General')).toBeInTheDocument();
+ expect(screen.getByText('Security')).toBeInTheDocument();
+ });
+
+ it('shows parent label as header in the popover', async () => {
+ const user = userEvent.setup();
+ renderCollapsed(
+ <XDSSideNavItem label="Settings" icon={StubIcon} data-testid="parent">
+ <XDSSideNavItem label="General" />
+ </XDSSideNavItem>,
+ );
+ await user.click(screen.getByTestId('parent'));
+ expect(screen.getByText('Settings')).toBeInTheDocument();
+ });
+
+ it('does not render children without icon when collapsed', () => {
+ renderCollapsed(
+ <XDSSideNavItem label="Settings">
+ <XDSSideNavItem label="General" />
+ <XDSSideNavItem label="Security" />
+ </XDSSideNavItem>,
+ );
+ expect(screen.queryByText('Settings')).not.toBeInTheDocument();
+ expect(screen.queryByText('General')).not.toBeInTheDocument();
+ });
+
+ it('renders normally when not collapsed', () => {
+ renderExpanded(
+ <XDSSideNavItem label="Dashboard" icon={StubIcon}>
+ <XDSSideNavItem label="General" />
+ </XDSSideNavItem>,
+ );
+ expect(screen.getAllByText('Dashboard').length).toBeGreaterThanOrEqual(1);
+ expect(screen.getByText('General')).toBeInTheDocument();
+ expect(screen.getByRole('group')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index e220c8dde5..815e6a78e2 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -26,15 +26,20 @@ import {
lineHeightVars,
durationVars,
easeVars,
+ shadowVars,
} from '../theme/tokens.stylex';
import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
+import {useXDSPopover} from '../Popover/useXDSPopover';
import {xdsClassName, mergeProps} from '../utils';
import {XDSTooltip} from '../Tooltip';
import {navItemStyles} from '../NavItem/navItemStyles.stylex';
-import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
+import {
+ useXDSSideNavCollapse,
+ XDSSideNavCollapseContext,
+} from './XDSSideNavCollapseContext';
import {getIcon} from '../Icon/globalIconRegistry';
// =============================================================================
@@ -92,8 +97,36 @@ const styles = stylex.create({
expandChevronCollapsed: {
transform: 'rotate(180deg)',
},
+ // Popover surface for collapsed items with children
+ popoverSurface: {
+ backgroundColor: colorVars['--color-popover'],
+ borderWidth: 1,
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ borderRadius: radiusVars['--radius-2'],
+ boxShadow: shadowVars['--shadow-menu'],
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-1'],
+ marginInlineStart: spacingVars['--spacing-1'],
+ minWidth: 180,
+ },
+ popoverHeader: {
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ fontSize: textSizeVars['--text-xsm'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ color: colorVars['--color-text-secondary'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ },
});
+// Non-collapsed state for popover children — ensures nested items render expanded
+const EXPANDED_COLLAPSE_STATE = {
+ isCollapsed: false,
+ toggle: () => {},
+ isCollapsible: false,
+};
+
// =============================================================================
// Types
// =============================================================================
@@ -214,6 +247,14 @@ export function XDSSideNavItem({
const LinkComponent = useXDSLinkComponent(as);
const itemRef = useRef<HTMLDivElement>(null);
+ // Popover for collapsed items with children
+ const popover = useXDSPopover({
+ hasLightDismiss: true,
+ hasAutoFocus: true,
+ hasCloseButton: false,
+ dialogLabel: `${label} submenu`,
+ });
+
// Collapse state for items with children
const itemCollapsibleConfig =
typeof itemCollapsible === 'object' ? itemCollapsible : {};
@@ -237,11 +278,6 @@ export function XDSSideNavItem({
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();
@@ -255,6 +291,150 @@ export function XDSSideNavItem({
onClick?.(e);
};
+ // Hover handlers for collapsed popover (mirrors TopNavMenu pattern)
+ const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+ const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+ const clearPopoverTimeouts = useCallback(() => {
+ if (showTimeoutRef.current) {
+ clearTimeout(showTimeoutRef.current);
+ showTimeoutRef.current = null;
+ }
+ if (hideTimeoutRef.current) {
+ clearTimeout(hideTimeoutRef.current);
+ hideTimeoutRef.current = null;
+ }
+ }, []);
+
+ const schedulePopoverShow = useCallback(() => {
+ clearPopoverTimeouts();
+ showTimeoutRef.current = setTimeout(() => {
+ popover.show({skipAutoFocus: true});
+ }, 150);
+ }, [clearPopoverTimeouts, popover]);
+
+ const schedulePopoverHide = useCallback(() => {
+ clearPopoverTimeouts();
+ hideTimeoutRef.current = setTimeout(() => {
+ popover.hide();
+ }, 200);
+ }, [clearPopoverTimeouts, popover]);
+
+ const handlePopoverMouseEnter = useCallback(() => {
+ schedulePopoverShow();
+ }, [schedulePopoverShow]);
+
+ const handlePopoverMouseLeave = useCallback(() => {
+ schedulePopoverHide();
+ }, [schedulePopoverHide]);
+
+ // In collapsed mode: hide items without icons
+ if (isCollapsed && !icon) {
+ return null;
+ }
+
+ // =========================================================================
+ // Collapsed mode — icon-only items, popover for items with children
+ // =========================================================================
+ if (isCollapsed) {
+ const collapsedIcon = displayIcon && (
+ <XDSIcon
+ icon={displayIcon}
+ size="sm"
+ color={isSelected ? 'primary' : isDisabled ? 'disabled' : 'secondary'}
+ />
+ );
+
+ // Shared collapsed item styles — used by trigger, link, and button
+ const collapsedItemStyles = mergeProps(
+ xdsClassName('side-nav-item'),
+ stylex.props(
+ navItemStyles.item,
+ styles.itemCollapsed,
+ isSelected && navItemStyles.selected,
+ isDisabled && navItemStyles.disabled,
+ ),
+ );
+
+ // Items with children: popover trigger + popover
+ if (hasChildren) {
+ return (
+ <div {...stylex.props(styles.root)}>
+ <button
+ ref={el => {
+ popover.triggerRef(el);
+ if (typeof ref === 'function') {
+ ref(el);
+ } else if (ref) {
+ (ref as React.MutableRefObject<HTMLElement | null>).current =
+ el;
+ }
+ }}
+ type="button"
+ onClick={popover.toggle}
+ onMouseEnter={handlePopoverMouseEnter}
+ onMouseLeave={handlePopoverMouseLeave}
+ aria-label={label}
+ data-testid={testId}
+ {...popover.triggerProps}
+ {...collapsedItemStyles}>
+ {collapsedIcon}
+ </button>
+ {popover.render(
+ <div
+ {...stylex.props(styles.popoverSurface)}
+ onMouseEnter={handlePopoverMouseEnter}
+ onMouseLeave={handlePopoverMouseLeave}
+ onClick={() => popover.hide()}>
+ <div {...stylex.props(styles.popoverHeader)}>{label}</div>
+ <XDSSideNavCollapseContext value={EXPANDED_COLLAPSE_STATE}>
+ {children}
+ </XDSSideNavCollapseContext>
+ </div>,
+ {placement: 'end', alignment: 'start'},
+ )}
+ </div>
+ );
+ }
+
+ // Items without children: icon-only link/button with tooltip
+ const collapsedAriaProps = {
+ 'aria-current': isSelected ? ('page' as const) : undefined,
+ 'aria-disabled': isDisabled || undefined,
+ 'aria-label': label,
+ 'data-testid': testId,
+ };
+
+ const collapsedElement =
+ href && !isDisabled ? (
+ <LinkComponent
+ ref={ref as React.Ref<HTMLAnchorElement>}
+ href={href}
+ onClick={handleClick}
+ {...collapsedAriaProps}
+ {...collapsedItemStyles}>
+ {collapsedIcon}
+ </LinkComponent>
+ ) : (
+ <button
+ ref={ref as React.Ref<HTMLButtonElement>}
+ type="button"
+ onClick={handleClick}
+ disabled={isDisabled}
+ {...collapsedAriaProps}
+ {...collapsedItemStyles}>
+ {collapsedIcon}
+ </button>
+ );
+
+ return (
+ <div ref={itemRef} {...stylex.props(styles.root)}>
+ {collapsedElement}
+ <XDSTooltip content={label} placement="end" anchorRef={itemRef} />
+ </div>
+ );
+ }
+
const itemContent = (
<>
{displayIcon && (
@@ -295,11 +475,13 @@ export function XDSSideNavItem({
href={href}
onClick={handleClick}
{...ariaProps}
- {...stylex.props(
- navItemStyles.item,
- isCollapsed && styles.itemCollapsed,
- isSelected && navItemStyles.selected,
- isDisabled && navItemStyles.disabled,
+ {...mergeProps(
+ xdsClassName('side-nav-item'),
+ stylex.props(
+ navItemStyles.item,
+ isSelected && navItemStyles.selected,
+ isDisabled && navItemStyles.disabled,
+ ),
)}>
{itemContent}
</LinkComponent>
@@ -310,20 +492,20 @@ export function XDSSideNavItem({
onClick={handleClick}
disabled={isDisabled}
{...ariaProps}
- {...stylex.props(
- navItemStyles.item,
- isCollapsed && styles.itemCollapsed,
- isSelected && navItemStyles.selected,
- isDisabled && navItemStyles.disabled,
+ {...mergeProps(
+ xdsClassName('side-nav-item'),
+ stylex.props(
+ navItemStyles.item,
+ isSelected && navItemStyles.selected,
+ isDisabled && navItemStyles.disabled,
+ ),
)}>
{itemContent}
</button>
);
const item = (
- <div
- ref={itemRef}
- {...mergeProps(xdsClassName('side-nav-item'), stylex.props(styles.root))}>
+ <div ref={itemRef} {...stylex.props(styles.root)}>
{itemElement}
{hasChildren && !isCollapsed && (
<div
@@ -346,14 +528,7 @@ export function XDSSideNavItem({
</div>
);
- return (
- <>
- {item}
- {isCollapsed && (
- <XDSTooltip content={label} placement="end" anchorRef={itemRef} />
- )}
- </>
- );
+ return item;
}
XDSSideNavItem.displayName = 'XDSSideNavItem';