Skip to content

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

TypeScript

feat(NavMenu): add XDSNavHeadingMenu container with size and keyboard nav (#1999)

Cindy Zhangc65bd42dd6d3
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 194af70b8e..893acbff9c 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -195,7 +195,7 @@ describe('componentRegistry', () => {
const core = components['@xds/core'];
const names = core.map(c => c.name);
expect(names).toContain('ChatDictationButton');
- expect(names).toContain('NavMenuItem');
+ expect(names).toContain('NavHeadingMenu');
const hiddenCount = core.filter(c => c.hidden).length;
expect(hiddenCount).toBe(0);
});
diff --git a/packages/core/src/NavMenu/NavMenu.doc.mjs b/packages/core/src/NavMenu/NavMenu.doc.mjs
index 18c2242624..333b627be8 100644
--- a/packages/core/src/NavMenu/NavMenu.doc.mjs
+++ b/packages/core/src/NavMenu/NavMenu.doc.mjs
@@ -1,18 +1,19 @@
/** @type {import('../docs-types').ComponentDoc} */
export const docs = {
- name: 'NavMenuItem',
+ name: 'NavHeadingMenu',
hidden: false,
- keywords: ['nav', 'menu', 'navigation', 'menu-item'],
+ keywords: ['nav', 'menu', 'navigation', 'heading', 'menu-item', 'popover'],
usage: {
- description: 'Menu item used within navigation components like SideNav and TopNav.',
+ description:
+ 'Accessible menu container and items for nav heading popovers. ' +
+ 'XDSNavHeadingMenu provides role="menu" with keyboard navigation; ' +
+ 'XDSNavHeadingMenuItem renders individual selectable items. ' +
+ 'Pass as the menu prop of XDSSideNavHeading or XDSTopNavHeading.',
},
props: [
- {name: 'icon', type: 'XDSIconType', description: 'Icon displayed before the label.'},
- {name: 'label', type: 'ReactNode', required: true, description: 'Primary label text.'},
- {name: 'description', type: 'ReactNode', description: 'Secondary description below the label.'},
- {name: 'href', type: 'string', description: 'URL to navigate to. Renders as an anchor.'},
- {name: 'onClick', type: '() => void', description: 'Callback when the item is selected.'},
- {name: 'isDisabled', type: 'boolean', default: 'false', description: 'Whether the item is disabled.'},
+ {name: 'children', type: 'ReactNode', required: true, description: 'Menu items.'},
+ {name: 'size', type: "'sm' | 'md' | 'lg'", default: "'md'", description: 'Controls min-width and item padding.'},
+ {name: 'minWidth', type: 'number | string', description: 'Minimum width override.'},
],
};
diff --git a/packages/core/src/NavMenu/XDSNavHeadingMenu.test.tsx b/packages/core/src/NavMenu/XDSNavHeadingMenu.test.tsx
new file mode 100644
index 0000000000..bb0400220b
--- /dev/null
+++ b/packages/core/src/NavMenu/XDSNavHeadingMenu.test.tsx
@@ -0,0 +1,261 @@
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSNavHeadingMenu} from './XDSNavHeadingMenu';
+import {XDSNavHeadingMenuItem} from './XDSNavHeadingMenuItem';
+import {XDSNavMenuItem} from './XDSNavMenuItem';
+import {XDSNavHeadingCloseContext} from './XDSNavMenuContext';
+
+describe('XDSNavHeadingMenu', () => {
+ it('renders with role="menu"', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Item 1" />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByRole('menu')).toBeInTheDocument();
+ });
+
+ it('renders children as menuitems', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Dashboard" />
+ <XDSNavHeadingMenuItem label="Settings" />
+ </XDSNavHeadingMenu>,
+ );
+ const items = screen.getAllByRole('menuitem');
+ expect(items).toHaveLength(2);
+ expect(items[0]).toHaveTextContent('Dashboard');
+ expect(items[1]).toHaveTextContent('Settings');
+ });
+
+ it('applies size class to container', () => {
+ const {container} = render(
+ <XDSNavHeadingMenu size="lg">
+ <XDSNavHeadingMenuItem label="Item" />
+ </XDSNavHeadingMenu>,
+ );
+ const menu = screen.getByRole('menu');
+ expect(menu.className).toContain('nav-heading-menu');
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSNavHeadingMenu data-testid="product-menu">
+ <XDSNavHeadingMenuItem label="Item" />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByTestId('product-menu')).toBeInTheDocument();
+ });
+
+ it('applies minWidth override via inline style', () => {
+ render(
+ <XDSNavHeadingMenu minWidth={300}>
+ <XDSNavHeadingMenuItem label="Item" />
+ </XDSNavHeadingMenu>,
+ );
+ const menu = screen.getByRole('menu');
+ expect(menu.style.minWidth).toBe('300px');
+ });
+});
+
+describe('XDSNavHeadingMenuItem', () => {
+ it('renders with role="menuitem"', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Dashboard" />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByRole('menuitem')).toHaveTextContent('Dashboard');
+ });
+
+ it('renders as a link when href is provided', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Docs" href="/docs" />
+ </XDSNavHeadingMenu>,
+ );
+ const item = screen.getByRole('menuitem');
+ expect(item.tagName).toBe('A');
+ expect(item).toHaveAttribute('href', '/docs');
+ });
+
+ it('renders as div when no href', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Action" onClick={() => {}} />
+ </XDSNavHeadingMenu>,
+ );
+ const item = screen.getByRole('menuitem');
+ expect(item.tagName).toBe('DIV');
+ });
+
+ it('calls onClick on click', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Action" onClick={onClick} />
+ </XDSNavHeadingMenu>,
+ );
+ await user.click(screen.getByRole('menuitem'));
+ expect(onClick).toHaveBeenCalledOnce();
+ });
+
+ it('does not call onClick when disabled', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Action" onClick={onClick} isDisabled />
+ </XDSNavHeadingMenu>,
+ );
+ await user.click(screen.getByRole('menuitem'));
+ expect(onClick).not.toHaveBeenCalled();
+ });
+
+ it('sets aria-disabled when disabled', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Disabled" isDisabled />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByRole('menuitem')).toHaveAttribute(
+ 'aria-disabled',
+ 'true',
+ );
+ });
+
+ it('renders description text', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Dashboard" description="View metrics" />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByText('View metrics')).toBeInTheDocument();
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Item" data-testid="menu-item-1" />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByTestId('menu-item-1')).toBeInTheDocument();
+ });
+});
+
+describe('keyboard navigation', () => {
+ it('moves focus with arrow keys', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="First" />
+ <XDSNavHeadingMenuItem label="Second" />
+ <XDSNavHeadingMenuItem label="Third" />
+ </XDSNavHeadingMenu>,
+ );
+ const items = screen.getAllByRole('menuitem');
+ items[0].focus();
+ expect(document.activeElement).toBe(items[0]);
+
+ await user.keyboard('{ArrowDown}');
+ expect(document.activeElement).toBe(items[1]);
+
+ await user.keyboard('{ArrowDown}');
+ expect(document.activeElement).toBe(items[2]);
+
+ await user.keyboard('{ArrowUp}');
+ expect(document.activeElement).toBe(items[1]);
+ });
+
+ it('wraps focus at boundaries', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="First" />
+ <XDSNavHeadingMenuItem label="Last" />
+ </XDSNavHeadingMenu>,
+ );
+ const items = screen.getAllByRole('menuitem');
+ items[1].focus();
+
+ await user.keyboard('{ArrowDown}');
+ expect(document.activeElement).toBe(items[0]);
+ });
+
+ it('Home focuses first item, End focuses last', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="First" />
+ <XDSNavHeadingMenuItem label="Middle" />
+ <XDSNavHeadingMenuItem label="Last" />
+ </XDSNavHeadingMenu>,
+ );
+ const items = screen.getAllByRole('menuitem');
+ items[1].focus();
+
+ await user.keyboard('{Home}');
+ expect(document.activeElement).toBe(items[0]);
+
+ await user.keyboard('{End}');
+ expect(document.activeElement).toBe(items[2]);
+ });
+});
+
+describe('context forwarding', () => {
+ it('forwards closeMenu from parent NavMenuContext', async () => {
+ const user = userEvent.setup();
+ const closeMenu = vi.fn();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="Action" onClick={() => {}} />
+ </XDSNavHeadingMenu>,
+ {
+ wrapper: ({children}) => (
+ <XDSNavHeadingCloseContext.Provider value={{closeMenu}}>
+ {children}
+ </XDSNavHeadingCloseContext.Provider>
+ ),
+ },
+ );
+ await user.click(screen.getByRole('menuitem'));
+ expect(closeMenu).toHaveBeenCalledOnce();
+ });
+
+ it('calls parent closeMenu on Escape', async () => {
+ const user = userEvent.setup();
+ const closeMenu = vi.fn();
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavHeadingMenuItem label="First" />
+ </XDSNavHeadingMenu>,
+ {
+ wrapper: ({children}) => (
+ <XDSNavHeadingCloseContext.Provider value={{closeMenu}}>
+ {children}
+ </XDSNavHeadingCloseContext.Provider>
+ ),
+ },
+ );
+ screen.getByRole('menuitem').focus();
+ await user.keyboard('{Escape}');
+ expect(closeMenu).toHaveBeenCalledOnce();
+ });
+});
+
+describe('XDSNavMenuItem backward compat', () => {
+ it('is the same component as XDSNavHeadingMenuItem', () => {
+ expect(XDSNavMenuItem).toBe(XDSNavHeadingMenuItem);
+ });
+
+ it('renders correctly when used as XDSNavMenuItem', () => {
+ render(
+ <XDSNavHeadingMenu>
+ <XDSNavMenuItem label="Legacy" />
+ </XDSNavHeadingMenu>,
+ );
+ expect(screen.getByRole('menuitem')).toHaveTextContent('Legacy');
+ });
+});
diff --git a/packages/core/src/NavMenu/XDSNavHeadingMenu.tsx b/packages/core/src/NavMenu/XDSNavHeadingMenu.tsx
new file mode 100644
index 0000000000..1d6b08f730
--- /dev/null
+++ b/packages/core/src/NavMenu/XDSNavHeadingMenu.tsx
@@ -0,0 +1,134 @@
+'use client';
+
+import {useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
+import {useListFocus} from '../hooks/useListFocus';
+import {
+ XDSNavHeadingMenuContext,
+ useXDSNavHeadingCloseContext,
+ type XDSNavHeadingMenuSize,
+} from './XDSNavMenuContext';
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {
+ minWidth: 160,
+ },
+ md: {
+ minWidth: 200,
+ },
+ lg: {
+ minWidth: 240,
+ },
+});
+
+export interface XDSNavHeadingMenuProps {
+ /** Menu items (XDSNavHeadingMenuItem, dividers, custom content). */
+ children: ReactNode;
+
+ /**
+ * Size — controls min-width and flows to items for padding.
+ * @default 'md'
+ */
+ size?: XDSNavHeadingMenuSize;
+
+ /**
+ * Minimum width override. Takes precedence over size-based defaults.
+ */
+ minWidth?: number | string;
+
+ /**
+ * StyleX styles for layout customization.
+ * Must be a `stylex.create()` value.
+ */
+ xstyle?: StyleXStyles;
+
+ /** CSS class name(s) appended to the root element. */
+ className?: string;
+
+ /** Inline styles applied to the root element. */
+ style?: React.CSSProperties;
+
+ /** Test ID for testing frameworks. */
+ 'data-testid'?: string;
+}
+
+/**
+ * Accessible menu container for nav heading popovers.
+ *
+ * Provides `role="menu"` with arrow-key navigation (Home/End/Escape)
+ * and a size context that flows to child items for consistent padding.
+ * Pass as the `menu` prop of XDSSideNavHeading or XDSTopNavHeading.
+ *
+ * The parent heading component injects the close callback via context,
+ * so items automatically dismiss the popover on selection.
+ *
+ * @example
+ * ```
+ * <XDSSideNavHeading
+ * heading="Products"
+ * menu={
+ * <XDSNavHeadingMenu size="lg">
+ * <XDSNavHeadingMenuItem label="Dashboard" href="/dashboard" />
+ * <XDSNavHeadingMenuItem label="Analytics" href="/analytics" />
+ * </XDSNavHeadingMenu>
+ * }
+ * />
+ * ```
+ */
+export function XDSNavHeadingMenu({
+ children,
+ size = 'md',
+ minWidth,
+ xstyle,
+ className,
+ style: styleProp,
+ 'data-testid': testId,
+}: XDSNavHeadingMenuProps) {
+ const closeCtx = useXDSNavHeadingCloseContext();
+ const closeMenu = closeCtx?.closeMenu;
+
+ const {listRef, handleKeyDown} = useListFocus({
+ onEscape: closeMenu,
+ });
+
+ const ctx = useMemo(
+ () => ({
+ closeMenu: closeMenu ?? (() => {}),
+ size,
+ }),
+ [closeMenu, size],
+ );
+
+ const inlineStyle = minWidth != null ? {...styleProp, minWidth} : styleProp;
+
+ return (
+ <XDSNavHeadingMenuContext.Provider value={ctx}>
+ <div
+ ref={listRef as React.RefObject<HTMLDivElement>}
+ role="menu"
+ onKeyDown={handleKeyDown}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('nav-heading-menu', {size}),
+ stylex.props(styles.root, sizeStyles[size], xstyle),
+ className,
+ inlineStyle,
+ )}>
+ {children}
+ </div>
+ </XDSNavHeadingMenuContext.Provider>
+ );
+}
+
+XDSNavHeadingMenu.displayName = 'XDSNavHeadingMenu';
diff --git a/packages/core/src/NavMenu/XDSNavHeadingMenuItem.tsx b/packages/core/src/NavMenu/XDSNavHeadingMenuItem.tsx
new file mode 100644
index 0000000000..7dc178ca74
--- /dev/null
+++ b/packages/core/src/NavMenu/XDSNavHeadingMenuItem.tsx
@@ -0,0 +1,171 @@
+'use client';
+
+import {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {renderIconSlot, type XDSIconType} from '../Icon';
+import {XDSText} from '../Text';
+import {
+ colorVars,
+ spacingVars,
+ typographyVars,
+ typeScaleVars,
+ radiusVars,
+} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
+import {useXDSNavHeadingMenuContext} from './XDSNavMenuContext';
+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
+
+const styles = stylex.create({
+ root: {
+ boxSizing: 'border-box',
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ borderRadius: radiusVars['--radius-element'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-label-size'],
+ color: colorVars['--color-text-primary'],
+ backgroundColor: {
+ default: 'transparent',
+ ':focus': colorVars['--color-overlay-hover'],
+ ':hover': colorVars['--color-overlay-hover'],
+ },
+ border: 'none',
+ cursor: 'pointer',
+ textAlign: 'left',
+ outline: 'none',
+ textDecoration: 'none',
+ },
+ content: {
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ },
+ disabled: {
+ opacity: 0.5,
+ cursor: 'not-allowed',
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ },
+ md: {
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-2'],
+ },
+ lg: {
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-3'],
+ },
+});
+
+export interface XDSNavHeadingMenuItemProps {
+ /** Icon to display before the label. */
+ icon?: ReactNode | XDSIconType;
+ /** Primary label text. */
+ label: ReactNode;
+ /** Secondary description text displayed below the label. */
+ description?: ReactNode;
+ /** URL to navigate to. Renders as an anchor element when provided. */
+ href?: string;
+ /** Callback when the item is selected. */
+ onClick?: () => void;
+ /** Whether the item is disabled. @default false */
+ isDisabled?: boolean;
+ /**
+ * StyleX styles for layout customization.
+ * Must be a `stylex.create()` value.
+ */
+ xstyle?: StyleXStyles;
+ /** CSS class name(s) appended to the root element. */
+ className?: string;
+ /** Inline styles applied to the root element. */
+ style?: React.CSSProperties;
+ /** Test ID for testing frameworks. */
+ 'data-testid'?: string;
+}
+
+/**
+ * Menu item for nav heading popovers.
+ *
+ * Reads size from the parent XDSNavHeadingMenu for consistent padding.
+ * Automatically dismisses the menu on click via context.
+ * Renders as a link when `href` is provided.
+ *
+ * @example
+ * ```
+ * <XDSNavHeadingMenu>
+ * <XDSNavHeadingMenuItem label="Dashboard" href="/dashboard" />
+ * <XDSNavHeadingMenuItem label="Settings" icon={GearIcon} onClick={open} />
+ * </XDSNavHeadingMenu>
+ * ```
+ */
+export function XDSNavHeadingMenuItem({
+ icon,
+ label,
+ description,
+ href,
+ onClick,
+ isDisabled = false,
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+}: XDSNavHeadingMenuItemProps) {
+ const ctx = useXDSNavHeadingMenuContext();
+ const size = ctx?.size ?? 'md';
+
+ const handleClick = useCallback(() => {
+ if (isDisabled) return;
+ onClick?.();
+ ctx?.closeMenu();
+ }, [isDisabled, onClick, ctx]);
+
+ const LinkComponent = useXDSLinkComponent();
+ const Element = href ? LinkComponent : 'div';
+
+ return (
+ <Element
+ role="menuitem"
+ tabIndex={isDisabled ? undefined : -1}
+ aria-disabled={isDisabled || undefined}
+ href={href}
+ onClick={handleClick}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('nav-heading-menu-item', {size}),
+ stylex.props(
+ styles.root,
+ sizeStyles[size],
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {icon && renderIconSlot(icon, {size: 'sm', color: 'secondary'})}
+ <span {...stylex.props(styles.content)}>
+ {typeof label === 'string' ? (
+ <XDSText type="body" maxLines={1}>
+ {label}
+ </XDSText>
+ ) : (
+ label
+ )}
+ {description && (
+ <XDSText type="supporting" maxLines={1}>
+ {description}
+ </XDSText>
+ )}
+ </span>
+ </Element>
+ );
+}
+
+XDSNavHeadingMenuItem.displayName = 'XDSNavHeadingMenuItem';
diff --git a/packages/core/src/NavMenu/XDSNavMenuContext.tsx b/packages/core/src/NavMenu/XDSNavMenuContext.tsx
index 3bd872c103..6907065d08 100644
--- a/packages/core/src/NavMenu/XDSNavMenuContext.tsx
+++ b/packages/core/src/NavMenu/XDSNavMenuContext.tsx
@@ -1,27 +1,37 @@
'use client';
-/**
- * @file XDSNavMenuContext.tsx
- * @output Exports context and hook for nav heading menu coordination
- * @position Internal; used by nav heading components and XDSNavMenuItem
- *
- * Provides a close callback so menu items can dismiss the popover on click.
- */
-
import {createContext, useContext} from 'react';
-export interface XDSNavMenuContextValue {
- /** Close the menu popover */
+export type XDSNavHeadingMenuSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Close callback provided by the nav heading popover.
+ * XDSNavHeadingMenu reads this to dismiss the popover on item selection
+ * and on Escape.
+ */
+export interface XDSNavHeadingCloseContextValue {
closeMenu: () => void;
}
-export const XDSNavMenuContext =
- createContext<XDSNavMenuContextValue | null>(null);
+export const XDSNavHeadingCloseContext =
+ createContext<XDSNavHeadingCloseContextValue | null>(null);
+
+export function useXDSNavHeadingCloseContext(): XDSNavHeadingCloseContextValue | null {
+ return useContext(XDSNavHeadingCloseContext);
+}
/**
- * Hook for nav menu items to access menu state.
- * Returns null outside of a nav heading menu.
+ * Size and close context provided by XDSNavHeadingMenu to its children.
+ * Items read this for consistent padding and dismiss-on-click.
*/
-export function useXDSNavMenuContext(): XDSNavMenuContextValue | null {
- return useContext(XDSNavMenuContext);
+export interface XDSNavHeadingMenuContextValue {
+ size: XDSNavHeadingMenuSize;
+ closeMenu: () => void;
+}
+
+export const XDSNavHeadingMenuContext =
+ createContext<XDSNavHeadingMenuContextValue | null>(null);
+
+export function useXDSNavHeadingMenuContext(): XDSNavHeadingMenuContextValue | null {
+ return useContext(XDSNavHeadingMenuContext);
}
diff --git a/packages/core/src/NavMenu/XDSNavMenuItem.tsx b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
index aba2cb86dd..d7c48ca59e 100644
--- a/packages/core/src/NavMenu/XDSNavMenuItem.tsx
+++ b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
@@ -1,168 +1,10 @@
'use client';
-/**
- * @file XDSNavMenuItem.tsx
- * @output Exports XDSNavMenuItem component
- * @position Sub-component; used inside nav heading menu popovers
- *
- * Interactive menu item with role="menuitem" for use in SideNavHeading
- * and TopNavHeading menu popovers. Keyboard navigation is handled by
- * useListFocus via the useXDSMenuHover hook on the parent container.
- */
+import {XDSNavHeadingMenuItem} from './XDSNavHeadingMenuItem';
+import type {XDSNavHeadingMenuItemProps} from './XDSNavHeadingMenuItem';
-import {useCallback, type ReactNode} from 'react';
-import * as stylex from '@stylexjs/stylex';
-import type {StyleXStyles} from '@stylexjs/stylex';
-import {XDSIcon} from '../Icon';
-import {renderIconSlot, type XDSIconType} from '../Icon';
-import {XDSText} from '../Text';
-import {
- colorVars,
- spacingVars,
- typographyVars,
- typeScaleVars,
- radiusVars,
-} from '../theme/tokens.stylex';
-import {xdsClassName, mergeProps} from '../utils';
-import {useXDSNavMenuContext} from './XDSNavMenuContext';
-import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
+/** @deprecated Use XDSNavHeadingMenuItem instead. */
+export type XDSNavMenuItemProps = XDSNavHeadingMenuItemProps;
-const styles = stylex.create({
- root: {
- boxSizing: 'border-box',
- display: 'flex',
- alignItems: 'center',
- gap: spacingVars['--spacing-2'],
- width: '100%',
- padding: spacingVars['--spacing-2'],
- borderRadius: radiusVars['--radius-element'],
- fontFamily: typographyVars['--font-family-body'],
- fontSize: typeScaleVars['--text-label-size'],
- color: colorVars['--color-text-primary'],
- backgroundColor: {
- default: 'transparent',
- ':focus': colorVars['--color-overlay-hover'],
- ':hover': colorVars['--color-overlay-hover'],
- },
- border: 'none',
- cursor: 'pointer',
- textAlign: 'left',
- outline: 'none',
- textDecoration: 'none',
- },
- content: {
- display: 'flex',
- flexDirection: 'column',
- flex: 1,
- minWidth: 0,
- },
- disabled: {
- opacity: 0.5,
- cursor: 'not-allowed',
- },
-});
-
-export interface XDSNavMenuItemProps {
- /** Icon to display before the label. */
- icon?: ReactNode | XDSIconType;
- /** Primary label text. */
- label: ReactNode;
- /** Secondary description text displayed below the label. */
- description?: ReactNode;
- /** URL to navigate to. Renders as an anchor element when provided. */
- href?: string;
- /** Callback when the item is selected. */
- onClick?: () => void;
- /** Whether the item is disabled. @default false */
- isDisabled?: boolean;
- /**
- * StyleX styles for layout customization (margins, positioning, sizing).
- * Must be a `stylex.create()` value — not an inline style object.
- *
- * @example
- * ```
- * const styles = stylex.create({ wrapper: { marginTop: 8 } });
- * <XDSNavMenuItem xstyle={styles.wrapper} />
- * ```
- */
- xstyle?: StyleXStyles;
- /** CSS class name(s) appended to the root element. */
- className?: string;
- /** Inline styles applied to the root element. */
- style?: React.CSSProperties;
-}
-
-/**
- * A menu item for use inside nav heading menu popovers.
- *
- * Provides `role="menuitem"` for accessibility and integrates with
- * the nav menu context to dismiss the popover on click.
- *
- * @example
- * ```
- * <XDSSideNavHeading
- * heading="Products"
- * menu={
- * <>
- * <XDSNavMenuItem label="Dashboard" href="/dashboard" />
- * <XDSNavMenuItem label="Analytics" href="/analytics" />
- * </>
- * }
- * />
- * ```
- */
-export function XDSNavMenuItem({
- icon,
- label,
- description,
- href,
- onClick,
- isDisabled = false,
- xstyle,
- className,
- style,
-}: XDSNavMenuItemProps) {
- const ctx = useXDSNavMenuContext();
-
- const handleClick = useCallback(() => {
- if (isDisabled) return;
- onClick?.();
- ctx?.closeMenu();
- }, [isDisabled, onClick, ctx]);
-
- const LinkComponent = useXDSLinkComponent();
- const Element = href ? LinkComponent : 'div';
-
- return (
- <Element
- role="menuitem"
- tabIndex={isDisabled ? undefined : -1}
- aria-disabled={isDisabled || undefined}
- href={href}
- onClick={handleClick}
- {...mergeProps(
- xdsClassName('nav-menu-item'),
- stylex.props(styles.root, isDisabled && styles.disabled, xstyle),
- className,
- style,
- )}>
- {icon && renderIconSlot(icon, {size: 'sm', color: 'secondary'})}
- <span {...stylex.props(styles.content)}>
- {typeof label === 'string' ? (
- <XDSText type="body" maxLines={1}>
- {label}
- </XDSText>
- ) : (
- label
- )}
- {description && (
- <XDSText type="supporting" maxLines={1}>
- {description}
- </XDSText>
- )}
- </span>
- </Element>
- );
-}
-
-XDSNavMenuItem.displayName = 'XDSNavMenuItem';
+/** @deprecated Use XDSNavHeadingMenuItem instead. */
+export const XDSNavMenuItem = XDSNavHeadingMenuItem;
diff --git a/packages/core/src/NavMenu/index.ts b/packages/core/src/NavMenu/index.ts
index 5ff098eb46..518eb3251f 100644
--- a/packages/core/src/NavMenu/index.ts
+++ b/packages/core/src/NavMenu/index.ts
@@ -1,5 +1,20 @@
'use client';
+export {XDSNavHeadingMenu} from './XDSNavHeadingMenu';
+export type {XDSNavHeadingMenuProps} from './XDSNavHeadingMenu';
+export {XDSNavHeadingMenuItem} from './XDSNavHeadingMenuItem';
+export type {XDSNavHeadingMenuItemProps} from './XDSNavHeadingMenuItem';
+export {
+ XDSNavHeadingMenuContext,
+ useXDSNavHeadingMenuContext,
+ XDSNavHeadingCloseContext,
+ useXDSNavHeadingCloseContext,
+} from './XDSNavMenuContext';
+export type {
+ XDSNavHeadingMenuContextValue,
+ XDSNavHeadingCloseContextValue,
+ XDSNavHeadingMenuSize,
+} from './XDSNavMenuContext';
+
+// Backward compat — use XDSNavHeadingMenuItem instead.
export {XDSNavMenuItem} from './XDSNavMenuItem';
export type {XDSNavMenuItemProps} from './XDSNavMenuItem';
-export {XDSNavMenuContext, useXDSNavMenuContext} from './XDSNavMenuContext';
-export type {XDSNavMenuContextValue} from './XDSNavMenuContext';
diff --git a/packages/core/src/SideNav/XDSSideNavHeading.tsx b/packages/core/src/SideNav/XDSSideNavHeading.tsx
index c6fe4dafe5..3a840fd6f7 100644
--- a/packages/core/src/SideNav/XDSSideNavHeading.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeading.tsx
@@ -40,7 +40,7 @@ import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
import {xdsClassName, mergeProps} from '../utils';
import {useXDSMenuHover} from '../hooks/useXDSMenuHover';
-import {XDSNavMenuContext} from '../NavMenu/XDSNavMenuContext';
+import {XDSNavHeadingCloseContext} from '../NavMenu/XDSNavMenuContext';
// =============================================================================
// Styles
@@ -405,8 +405,7 @@ export function XDSSideNavHeading({
const collapsedIcon = <span {...stylex.props(styles.icon)}>{icon}</span>;
const collapsedSetRef = (el: HTMLElement | null) => {
- (collapsedItemRef as React.RefObject<HTMLElement | null>).current =
- el;
+ (collapsedItemRef as React.RefObject<HTMLElement | null>).current = el;
if (typeof ref === 'function') {
ref(el as HTMLDivElement | null);
} else if (ref) {
@@ -492,9 +491,10 @@ export function XDSSideNavHeading({
)}
</span>
</button>
- <XDSNavMenuContext.Provider value={{closeMenu: popover.hide}}>
- {menu}
- </XDSNavMenuContext.Provider>
+ <XDSNavHeadingCloseContext.Provider
+ value={{closeMenu: popover.hide}}>
+ {menu}
+ </XDSNavHeadingCloseContext.Provider>
</div>,
{placement: 'below', alignment: 'start', xstyle: styles.popover},
)}
@@ -645,7 +645,10 @@ export function XDSSideNavHeading({
<button
type="button"
aria-label="Open menu"
- onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
+ onClick={e => {
+ e.stopPropagation();
+ triggerProps.onClick();
+ }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -701,7 +704,10 @@ export function XDSSideNavHeading({
<button
type="button"
aria-label="Open menu"
- onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
+ onClick={e => {
+ e.stopPropagation();
+ triggerProps.onClick();
+ }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
diff --git a/packages/core/src/TopNav/XDSTopNavHeading.tsx b/packages/core/src/TopNav/XDSTopNavHeading.tsx
index 03984250a8..735e5fd248 100644
--- a/packages/core/src/TopNav/XDSTopNavHeading.tsx
+++ b/packages/core/src/TopNav/XDSTopNavHeading.tsx
@@ -35,7 +35,7 @@ import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
import {xdsClassName, mergeProps} from '../utils';
import {useXDSMenuHover} from '../hooks/useXDSMenuHover';
-import {XDSNavMenuContext} from '../NavMenu/XDSNavMenuContext';
+import {XDSNavHeadingCloseContext} from '../NavMenu/XDSNavMenuContext';
// =============================================================================
// Styles
@@ -497,7 +497,10 @@ export function XDSTopNavHeading({
<button
type="button"
aria-label="Open menu"
- onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
+ onClick={e => {
+ e.stopPropagation();
+ triggerProps.onClick();
+ }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -512,9 +515,10 @@ export function XDSTopNavHeading({
{...stylex.props(styles.popoverContent)}
{...contentProps}>
{popoverHeadingContent}
- <XDSNavMenuContext.Provider value={{closeMenu: popover.hide}}>
+ <XDSNavHeadingCloseContext.Provider
+ value={{closeMenu: popover.hide}}>
{menu}
- </XDSNavMenuContext.Provider>
+ </XDSNavHeadingCloseContext.Provider>
</div>,
{
placement: 'below',
@@ -553,7 +557,10 @@ export function XDSTopNavHeading({
<button
type="button"
aria-label="Open menu"
- onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
+ onClick={e => {
+ e.stopPropagation();
+ triggerProps.onClick();
+ }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -569,9 +576,10 @@ export function XDSTopNavHeading({
{...stylex.props(styles.popoverContent)}
{...contentProps}>
{popoverHeadingContent}
- <XDSNavMenuContext.Provider value={{closeMenu: popover.hide}}>
+ <XDSNavHeadingCloseContext.Provider
+ value={{closeMenu: popover.hide}}>
{menu}
- </XDSNavMenuContext.Provider>
+ </XDSNavHeadingCloseContext.Provider>
</div>,
{
placement: 'below',