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.tsindex 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.mjsindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsindex 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.tsxindex 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({<buttontype="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({<buttontype="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.tsxindex 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({<buttontype="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({<buttontype="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',