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.tsxindex 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.tsxindex 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 childrenconst 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';