Skip to content

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

TypeScript

feat(SideNav, TopNav): hover-to-open menus with useXDSMenuHover (#1419)

Ernest1c188b907cea
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx b/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx
index 7363ebc7ed..c8fbd01bc0 100644
--- a/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx
@@ -11,6 +11,7 @@ import {XDSStack} from '@xds/core/Layout';
import {XDSCard} from '@xds/core/Card';
import {XDSDropdownMenu} from '@xds/core/DropdownMenu';
import {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSNavMenuItem} from '@xds/core/NavMenu';
import {XDSTable} from '@xds/core/Table';
import {XDSCommandPalette} from '@xds/core/CommandPalette';
import {
@@ -75,10 +76,10 @@ export function DocsView({
const [isSearchOpen, setIsSearchOpen] = useState(false);
const headingMenu = (
- <XDSList density="spacious" style={{minWidth: 240}}>
- <XDSListItem label="Craft" onClick={() => setActiveView('craft')} />
- <XDSListItem label="Library" onClick={() => setActiveView('docs')} />
- </XDSList>
+ <>
+ <XDSNavMenuItem label="Craft" onClick={() => setActiveView('craft')} />
+ <XDSNavMenuItem label="Library" onClick={() => setActiveView('docs')} />
+ </>
);
return (
diff --git a/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx
index 05ba36550a..9b35381389 100644
--- a/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx
+++ b/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx
@@ -33,6 +33,7 @@ import {XDSButton} from '@xds/core/Button';
import {XDSNavIcon} from '@xds/core/NavIcon';
import {XDSBanner} from '@xds/core/Banner';
import {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSNavMenuItem} from '@xds/core/NavMenu';
// =============================================================================
// Configuration types
@@ -569,11 +570,11 @@ function SampleSideNav({
: undefined;
const headingMenu = (
- <XDSList density="spacious">
- <XDSListItem label="Sibling Product 1" href="#" />
- <XDSListItem label="Sibling Product 2" href="#" />
- <XDSListItem label="Sibling Product 3" href="#" />
- </XDSList>
+ <>
+ <XDSNavMenuItem label="Sibling Product 1" onClick={() => {}} />
+ <XDSNavMenuItem label="Sibling Product 2" onClick={() => {}} />
+ <XDSNavMenuItem label="Sibling Product 3" onClick={() => {}} />
+ </>
);
const heading =
@@ -827,11 +828,11 @@ function SampleTopNav({
: undefined;
const topNavHeadingMenu = (
- <XDSList density="spacious">
- <XDSListItem label="Sibling Product 1" href="#" />
- <XDSListItem label="Sibling Product 2" href="#" />
- <XDSListItem label="Sibling Product 3" href="#" />
- </XDSList>
+ <>
+ <XDSNavMenuItem label="Sibling Product 1" onClick={() => {}} />
+ <XDSNavMenuItem label="Sibling Product 2" onClick={() => {}} />
+ <XDSNavMenuItem label="Sibling Product 3" onClick={() => {}} />
+ </>
);
const topNavHeading =
diff --git a/packages/core/package.json b/packages/core/package.json
index 7f0ead35f8..c7b74c4e47 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -286,6 +286,12 @@
"import": "./dist/NavItem/index.mjs",
"require": "./dist/NavItem/index.js"
},
+ "./NavMenu": {
+ "source": "./src/NavMenu/index.ts",
+ "types": "./dist/NavMenu/index.d.ts",
+ "import": "./dist/NavMenu/index.mjs",
+ "require": "./dist/NavMenu/index.js"
+ },
"./NumberInput": {
"source": "./src/NumberInput/index.ts",
"types": "./dist/NumberInput/index.d.ts",
diff --git a/packages/core/src/NavMenu/XDSNavMenuContext.tsx b/packages/core/src/NavMenu/XDSNavMenuContext.tsx
new file mode 100644
index 0000000000..3bd872c103
--- /dev/null
+++ b/packages/core/src/NavMenu/XDSNavMenuContext.tsx
@@ -0,0 +1,27 @@
+'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 */
+ closeMenu: () => void;
+}
+
+export const XDSNavMenuContext =
+ createContext<XDSNavMenuContextValue | null>(null);
+
+/**
+ * Hook for nav menu items to access menu state.
+ * Returns null outside of a nav heading menu.
+ */
+export function useXDSNavMenuContext(): XDSNavMenuContextValue | null {
+ return useContext(XDSNavMenuContext);
+}
diff --git a/packages/core/src/NavMenu/XDSNavMenuItem.tsx b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
new file mode 100644
index 0000000000..9b8cc611de
--- /dev/null
+++ b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
@@ -0,0 +1,161 @@
+'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 {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {XDSIcon} from '../Icon';
+import 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';
+
+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?: 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 merged with the component's base styles. */
+ 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 Element = href ? 'a' : '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 && <XDSIcon icon={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';
diff --git a/packages/core/src/NavMenu/index.ts b/packages/core/src/NavMenu/index.ts
new file mode 100644
index 0000000000..5ff098eb46
--- /dev/null
+++ b/packages/core/src/NavMenu/index.ts
@@ -0,0 +1,5 @@
+'use client';
+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/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsx
index c0eb841298..84814a264a 100644
--- a/packages/core/src/SideNav/XDSSideNav.test.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx
@@ -224,10 +224,10 @@ describe('XDSSideNavHeading', () => {
/>,
);
const button = screen.getByRole('button');
- // Native popover toggle via popoverTarget attribute (jsdom doesn't
- // support the Popover API, so we verify the attribute is set instead
- // of testing the full open/close cycle).
- expect(button).toHaveAttribute('popovertarget');
+ // The trigger button uses aria attributes from useXDSPopover and
+ // an onClick handler from useXDSMenuHover for click-to-lock toggle.
+ expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(button).toHaveAttribute('aria-expanded');
});
it('renders chevron as separate trigger when menu and hrefs are provided', () => {
diff --git a/packages/core/src/SideNav/XDSSideNavHeading.tsx b/packages/core/src/SideNav/XDSSideNavHeading.tsx
index cb72aac663..a41f797990 100644
--- a/packages/core/src/SideNav/XDSSideNavHeading.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeading.tsx
@@ -38,6 +38,8 @@ import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
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';
// =============================================================================
// Styles
@@ -182,6 +184,13 @@ const styles = stylex.create({
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
+ width: '100%',
+ border: 'none',
+ backgroundColor: 'transparent',
+ fontFamily: 'inherit',
+ fontSize: 'inherit',
+ color: 'inherit',
+ textAlign: 'start',
minHeight: spacingVars['--spacing-8'],
paddingInlineStart: {
default: spacingVars['--spacing-2'],
@@ -361,15 +370,24 @@ export function XDSSideNavHeading({
const popover = useXDSPopover({
dialogLabel: 'Navigation menu',
+ hasCloseButton: false,
+ });
+
+ const {triggerProps, contentProps, menuRef, setTriggerEl} = useXDSMenuHover({
+ show: popover.show,
+ hide: popover.hide,
+ isOpen: popover.isOpen,
+ isEnabled: !!menu,
});
const setRef = useCallback(
(el: HTMLDivElement | null) => {
- (rootRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
+ (rootRef as React.RefObject<HTMLDivElement | null>).current = el;
+ setTriggerEl(el);
if (typeof ref === 'function') {
ref(el);
} else if (ref) {
- (ref as React.MutableRefObject<HTMLDivElement | null>).current = el;
+ (ref as React.RefObject<HTMLDivElement | null>).current = el;
}
if (menu) {
popover.triggerRef(el);
@@ -386,12 +404,12 @@ export function XDSSideNavHeading({
const collapsedIcon = <span {...stylex.props(styles.icon)}>{icon}</span>;
const collapsedSetRef = (el: HTMLElement | null) => {
- (collapsedItemRef as React.MutableRefObject<HTMLElement | null>).current =
+ (collapsedItemRef as React.RefObject<HTMLElement | null>).current =
el;
if (typeof ref === 'function') {
ref(el as HTMLDivElement | null);
} else if (ref) {
- (ref as React.MutableRefObject<HTMLDivElement | null>).current =
+ (ref as React.RefObject<HTMLDivElement | null>).current =
el as HTMLDivElement | null;
}
};
@@ -420,10 +438,10 @@ export function XDSSideNavHeading({
<button
ref={collapsedSetRef as React.Ref<HTMLButtonElement>}
type="button"
- popoverTarget={popover.id}
aria-label={heading}
data-testid={testId}
{...popover.triggerProps}
+ {...triggerProps}
{...mergeProps(
xdsClassName('side-nav-heading'),
stylex.props(
@@ -438,12 +456,15 @@ export function XDSSideNavHeading({
{collapsedIcon}
</button>
{popover.render(
- <div {...stylex.props(styles.popoverContent)}>
- <div
+ <div
+ ref={menuRef as React.RefObject<HTMLDivElement>}
+ role="menu"
+ {...stylex.props(styles.popoverContent)}
+ {...contentProps}>
+ <button
+ type="button"
{...stylex.props(styles.popoverHeading)}
- onClick={() => popover.hide()}
- role="button"
- tabIndex={0}>
+ onClick={triggerProps.onClick}>
{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
<span {...stylex.props(styles.textContainer)}>
{superheading && (
@@ -469,8 +490,10 @@ export function XDSSideNavHeading({
</span>
)}
</span>
- </div>
+ </button>
+ <XDSNavMenuContext.Provider value={{closeMenu: popover.hide}}>
{menu}
+ </XDSNavMenuContext.Provider>
</div>,
{placement: 'below', alignment: 'start', xstyle: styles.popover},
)}
@@ -567,18 +590,17 @@ export function XDSSideNavHeading({
// Shared popover heading content — uses renderTextContent for consistent
// sizing, with flipped chevron inline after the title. Always static (no links).
const popoverHeadingContent = (
- <div
+ <button
+ type="button"
{...stylex.props(styles.popoverHeading)}
- onClick={() => popover.hide()}
- role="button"
- tabIndex={0}>
+ onClick={triggerProps.onClick}>
{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
{renderTextContent(
<span {...stylex.props(styles.popoverChevron)}>
{getIcon('chevronDown')}
</span>,
)}
- </div>
+ </button>
);
// Whole heading is a link (no menu, single headingHref)
@@ -610,6 +632,7 @@ export function XDSSideNavHeading({
<div
ref={setRef}
data-testid={testId}
+ {...triggerProps}
{...mergeProps(
xdsClassName('side-nav-heading'),
stylex.props(styles.root, styles.menuTrigger, xstyle),
@@ -620,8 +643,8 @@ export function XDSSideNavHeading({
{renderTextContent(
<button
type="button"
- popoverTarget={popover.id}
aria-label="Open menu"
+ onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -630,7 +653,11 @@ export function XDSSideNavHeading({
{headerEndContentElement}
</div>
{popover.render(
- <div {...stylex.props(styles.popoverContent)}>
+ <div
+ ref={menuRef as React.RefObject<HTMLDivElement>}
+ role="menu"
+ {...stylex.props(styles.popoverContent)}
+ {...contentProps}>
{popoverHeadingContent}
{menu}
</div>,
@@ -653,6 +680,7 @@ export function XDSSideNavHeading({
<div
ref={setRef}
data-testid={testId}
+ {...triggerProps}
{...mergeProps(
xdsClassName('side-nav-heading'),
stylex.props(styles.root, xstyle),
@@ -671,8 +699,8 @@ export function XDSSideNavHeading({
showChevron ? (
<button
type="button"
- popoverTarget={popover.id}
aria-label="Open menu"
+ onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -682,7 +710,11 @@ export function XDSSideNavHeading({
{headerEndContentElement}
</div>
{popover.render(
- <div {...stylex.props(styles.popoverContent)}>
+ <div
+ ref={menuRef as React.RefObject<HTMLDivElement>}
+ role="menu"
+ {...stylex.props(styles.popoverContent)}
+ {...contentProps}>
{popoverHeadingContent}
{menu}
</div>,
diff --git a/packages/core/src/TopNav/XDSTopNavHeading.tsx b/packages/core/src/TopNav/XDSTopNavHeading.tsx
index 5c0976b689..ab96291880 100644
--- a/packages/core/src/TopNav/XDSTopNavHeading.tsx
+++ b/packages/core/src/TopNav/XDSTopNavHeading.tsx
@@ -33,6 +33,8 @@ import {getIcon} from '../Icon/globalIconRegistry';
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';
// =============================================================================
// Styles
@@ -156,6 +158,13 @@ const styles = stylex.create({
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
+ width: '100%',
+ border: 'none',
+ backgroundColor: 'transparent',
+ fontFamily: 'inherit',
+ fontSize: 'inherit',
+ color: 'inherit',
+ textAlign: 'start',
minHeight: spacingVars['--spacing-8'],
paddingInlineStart: {
default: spacingVars['--spacing-2'],
@@ -322,11 +331,20 @@ export function XDSTopNavHeading({
const popover = useXDSPopover({
dialogLabel: 'Navigation menu',
+ hasCloseButton: false,
+ });
+
+ const {triggerProps, contentProps, menuRef, setTriggerEl} = useXDSMenuHover({
+ show: popover.show,
+ hide: popover.hide,
+ isOpen: popover.isOpen,
+ isEnabled: !!menu,
});
const setRef = useCallback(
(el: HTMLElement | null) => {
(rootRef as React.MutableRefObject<HTMLElement | null>).current = el;
+ setTriggerEl(el);
if (typeof ref === 'function') {
ref(el);
} else if (ref) {
@@ -400,18 +418,17 @@ export function XDSTopNavHeading({
// Shared popover heading content — uses renderTextContent for consistent
// sizing, with flipped chevron inline after the title. Always static (no links).
const popoverHeadingContent = (
- <div
+ <button
+ type="button"
{...stylex.props(styles.popoverHeading)}
- onClick={() => popover.hide()}
- role="button"
- tabIndex={0}>
+ onClick={triggerProps.onClick}>
{logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
{renderTextContent(
<span {...stylex.props(styles.popoverChevron)}>
{getIcon('chevronDown')}
</span>,
)}
- </div>
+ </button>
);
// Simple: no heading text, just logo (backward compat for logo-only usage)
@@ -467,6 +484,7 @@ export function XDSTopNavHeading({
<div
ref={setRef}
data-testid={testId}
+ {...triggerProps}
{...mergeProps(
xdsClassName('top-nav-heading'),
stylex.props(styles.root, styles.menuTrigger, xstyle),
@@ -477,8 +495,8 @@ export function XDSTopNavHeading({
{renderTextContent(
<button
type="button"
- popoverTarget={popover.id}
aria-label="Open menu"
+ onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -487,9 +505,15 @@ export function XDSTopNavHeading({
{headerEndContentElement}
</div>
{popover.render(
- <div {...stylex.props(styles.popoverContent)}>
+ <div
+ ref={menuRef as React.RefObject<HTMLDivElement>}
+ role="menu"
+ {...stylex.props(styles.popoverContent)}
+ {...contentProps}>
{popoverHeadingContent}
- {menu}
+ <XDSNavMenuContext.Provider value={{closeMenu: popover.hide}}>
+ {menu}
+ </XDSNavMenuContext.Provider>
</div>,
{
placement: 'below',
@@ -508,6 +532,7 @@ export function XDSTopNavHeading({
<div
ref={setRef}
data-testid={testId}
+ {...triggerProps}
{...mergeProps(
xdsClassName('top-nav-heading'),
stylex.props(styles.root, xstyle),
@@ -526,8 +551,8 @@ export function XDSTopNavHeading({
showChevron ? (
<button
type="button"
- popoverTarget={popover.id}
aria-label="Open menu"
+ onClick={(e) => { e.stopPropagation(); triggerProps.onClick(); }}
{...popover.triggerProps}
{...stylex.props(styles.chevron, styles.interactive)}>
{getIcon('chevronDown')}
@@ -537,9 +562,15 @@ export function XDSTopNavHeading({
{headerEndContentElement}
</div>
{popover.render(
- <div {...stylex.props(styles.popoverContent)}>
+ <div
+ ref={menuRef as React.RefObject<HTMLDivElement>}
+ role="menu"
+ {...stylex.props(styles.popoverContent)}
+ {...contentProps}>
{popoverHeadingContent}
- {menu}
+ <XDSNavMenuContext.Provider value={{closeMenu: popover.hide}}>
+ {menu}
+ </XDSNavMenuContext.Provider>
</div>,
{
placement: 'below',
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsx
index e430e51911..4a019b4306 100644
--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx
@@ -14,7 +14,6 @@
import {
useCallback,
- useEffect,
useId,
useRef,
useState,
@@ -22,7 +21,7 @@ import {
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {useXDSPopover} from '../Popover/useXDSPopover';
-import {useListFocus} from '../hooks/useListFocus';
+import {useXDSMenuHover} from '../hooks/useXDSMenuHover';
import {getIcon} from '../Icon/globalIconRegistry';
import {xdsClassName, mergeProps} from '../utils';
import {navItemStyles} from '../NavItem/navItemStyles.stylex';
@@ -385,99 +384,40 @@ export function XDSTopNavMenu({
// Default: desktop popover
const slot = useTopNavSlot();
- const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
- const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
- const clickLockedRef = useRef(false);
const popover = useXDSPopover({
dialogLabel: label,
xstyle: styles.menuOffset,
});
- const {
- listRef: menuRef,
- handleKeyDown: handleListKeyDown,
- focusFirst,
- } = useListFocus({
- onEscape: () => {
- clearTimeouts();
- clickLockedRef.current = false;
- popover.hide();
- triggerButtonRef.current?.focus();
- },
+ const {triggerProps, contentProps, menuRef, setTriggerEl} = useXDSMenuHover({
+ show: popover.show,
+ hide: popover.hide,
+ isOpen: popover.isOpen,
+ isEnabled: true,
+ showDelay: delay,
+ hideDelay,
});
- const clearTimeouts = useCallback(() => {
- if (showTimeoutRef.current) {
- clearTimeout(showTimeoutRef.current);
- showTimeoutRef.current = null;
- }
- if (hideTimeoutRef.current) {
- clearTimeout(hideTimeoutRef.current);
- hideTimeoutRef.current = null;
- }
- }, []);
-
- const scheduleShow = useCallback(() => {
- clearTimeouts();
- showTimeoutRef.current = setTimeout(() => {
- popover.show({skipAutoFocus: true});
- }, delay);
- }, [clearTimeouts, popover, delay]);
-
- const scheduleHide = useCallback(() => {
- clearTimeouts();
- hideTimeoutRef.current = setTimeout(() => {
- popover.hide();
- }, hideDelay);
- }, [clearTimeouts, popover, hideDelay]);
-
- const handleMouseEnter = useCallback(() => {
- if (!clickLockedRef.current) scheduleShow();
- }, [scheduleShow]);
-
- const handleMouseLeave = useCallback(() => {
- if (!clickLockedRef.current) scheduleHide();
- }, [scheduleHide]);
-
- const handleClick = useCallback(() => {
- clearTimeouts();
- if (popover.isOpen) {
- clickLockedRef.current = false;
- popover.hide();
- triggerButtonRef.current?.focus();
- } else {
- clickLockedRef.current = true;
- popover.show();
- requestAnimationFrame(() => focusFirst());
- }
- }, [popover, clearTimeouts, focusFirst]);
-
- // Combine refs — popover.triggerRef for anchor, triggerButtonRef for focus
const setTriggerRef = useCallback(
(el: HTMLButtonElement | null) => {
(
triggerButtonRef as React.MutableRefObject<HTMLButtonElement | null>
).current = el;
popover.triggerRef(el);
+ setTriggerEl(el);
},
- [popover],
+ [popover, setTriggerEl],
);
- useEffect(() => {
- return () => clearTimeouts();
- }, [clearTimeouts]);
-
return (
<>
<button
ref={setTriggerRef}
type="button"
{...popover.triggerProps}
- onClick={handleClick}
- onMouseEnter={handleMouseEnter}
- onMouseLeave={handleMouseLeave}
+ {...triggerProps}
{...mergeProps(
xdsClassName('top-nav-menu'),
stylex.props(styles.trigger, popover.isOpen && styles.triggerOpen),
@@ -496,9 +436,7 @@ export function XDSTopNavMenu({
ref={menuRef as React.RefObject<HTMLDivElement>}
role="menu"
aria-label={label}
- onMouseEnter={handleMouseEnter}
- onMouseLeave={handleMouseLeave}
- onKeyDown={handleListKeyDown}
+ {...contentProps}
{...stylex.props(styles.menuContainer)}>
{items.map((item, index) => {
const Element = item.href ? 'a' : 'div';
diff --git a/packages/core/src/hooks/useXDSMenuHover.ts b/packages/core/src/hooks/useXDSMenuHover.ts
new file mode 100644
index 0000000000..1b2ceab8ea
--- /dev/null
+++ b/packages/core/src/hooks/useXDSMenuHover.ts
@@ -0,0 +1,177 @@
+'use client';
+
+/**
+ * @file useXDSMenuHover.ts
+ * @input Uses React hooks, useListFocus
+ * @output Exports useXDSMenuHover hook
+ * @position Internal hook; used by nav heading components and XDSTopNavMenu
+ *
+ * Hover as a progressive enhancement on top of standard popover behavior:
+ *
+ * 1. Default popover: click toggles, Escape closes, outside-click closes,
+ * arrow keys navigate menu items.
+ *
+ * 2. Hover add-on:
+ * - mouseenter activates "hover mode" and opens after delay
+ * - While in hover mode, mouseleave closes after delay
+ * - Any close (click, Escape, outside-click) resets hover mode
+ * - Click-to-close additionally skips the next mouseenter
+ *
+ * Only uses mouseenter/mouseleave (not mouseover).
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+import {useListFocus} from './useListFocus';
+
+interface UseXDSMenuHoverOptions {
+ show: (options?: {skipAutoFocus?: boolean}) => void;
+ hide: () => void;
+ isOpen: boolean;
+ isEnabled: boolean;
+ showDelay?: number;
+ hideDelay?: number;
+}
+
+interface UseXDSMenuHoverReturn {
+ triggerProps: {
+ onClick: () => void;
+ onMouseEnter: () => void;
+ onMouseLeave: () => void;
+ };
+ contentProps: {
+ onMouseEnter: () => void;
+ onMouseLeave: () => void;
+ onKeyDown: (e: React.KeyboardEvent) => void;
+ };
+ menuRef: React.RefObject<HTMLElement | null>;
+ focusFirst: () => void;
+ setTriggerEl: (el: HTMLElement | null) => void;
+}
+
+export function useXDSMenuHover(
+ options: UseXDSMenuHoverOptions,
+): UseXDSMenuHoverReturn {
+ const {
+ show,
+ hide,
+ isOpen,
+ isEnabled,
+ showDelay = 150,
+ hideDelay = 200,
+ } = options;
+
+ const showTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+ const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+ const triggerElRef = useRef<HTMLElement | null>(null);
+ // Whether the menu was opened/interacted via hover (enables mouseleave-to-close)
+ const hoverModeRef = useRef(false);
+ // One-shot: skip the next mouseenter after click-to-close
+ const skipNextEnterRef = useRef(false);
+ const prevIsOpenRef = useRef(isOpen);
+
+ // When popover closes (any reason), reset hover mode
+ if (prevIsOpenRef.current && !isOpen) {
+ hoverModeRef.current = false;
+ }
+ prevIsOpenRef.current = isOpen;
+
+ const clearTimeouts = useCallback(() => {
+ if (showTimerRef.current) {
+ clearTimeout(showTimerRef.current);
+ showTimerRef.current = null;
+ }
+ if (hideTimerRef.current) {
+ clearTimeout(hideTimerRef.current);
+ hideTimerRef.current = null;
+ }
+ }, []);
+
+ const {
+ listRef: menuRef,
+ handleKeyDown: handleListKeyDown,
+ focusFirst,
+ } = useListFocus({
+ onEscape: () => {
+ clearTimeouts();
+ hide();
+ },
+ });
+
+ useEffect(() => {
+ return () => clearTimeouts();
+ }, [clearTimeouts]);
+
+ // Click: always toggle
+ const handleClick = useCallback(() => {
+ clearTimeouts();
+ if (isOpen) {
+ skipNextEnterRef.current = true;
+ hide();
+ } else {
+ skipNextEnterRef.current = false;
+ show();
+ requestAnimationFrame(() => focusFirst());
+ }
+ }, [isOpen, clearTimeouts, show, hide, focusFirst]);
+
+ // Hover: mouseenter activates hover mode and opens
+ const handleMouseEnter = useCallback(() => {
+ if (skipNextEnterRef.current) {
+ skipNextEnterRef.current = false;
+ return;
+ }
+ hoverModeRef.current = true;
+ clearTimeouts();
+ showTimerRef.current = setTimeout(() => {
+ show({skipAutoFocus: true});
+ }, showDelay);
+ }, [clearTimeouts, show, showDelay]);
+
+ // Hover: mouseleave only closes if in hover mode
+ const handleMouseLeave = useCallback(() => {
+ if (!hoverModeRef.current) return;
+ clearTimeouts();
+ hideTimerRef.current = setTimeout(() => {
+ hide();
+ }, hideDelay);
+ }, [clearTimeouts, hide, hideDelay]);
+
+ // Content: mouseenter cancels pending hide
+ const handleContentMouseEnter = useCallback(() => {
+ clearTimeouts();
+ }, [clearTimeouts]);
+
+ const setTriggerRef = useCallback((el: HTMLElement | null) => {
+ triggerElRef.current = el;
+ }, []);
+
+ const noop = useCallback(() => {}, []);
+ const noopRef = useCallback((_el: HTMLElement | null) => {}, []);
+ const noopKeyDown = useCallback((_e: React.KeyboardEvent) => {}, []);
+
+ if (!isEnabled) {
+ return {
+ triggerProps: {onClick: noop, onMouseEnter: noop, onMouseLeave: noop},
+ contentProps: {onMouseEnter: noop, onMouseLeave: noop, onKeyDown: noopKeyDown},
+ menuRef,
+ focusFirst,
+ setTriggerEl: noopRef,
+ };
+ }
+
+ return {
+ triggerProps: {
+ onClick: handleClick,
+ onMouseEnter: handleMouseEnter,
+ onMouseLeave: handleMouseLeave,
+ },
+ contentProps: {
+ onMouseEnter: handleContentMouseEnter,
+ onMouseLeave: handleMouseLeave,
+ onKeyDown: handleListKeyDown,
+ },
+ menuRef,
+ focusFirst,
+ setTriggerEl: setTriggerRef,
+ };
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index c27ae08890..8544cb76d7 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -39,6 +39,7 @@ export * from './List';
export * from './MetadataList';
export * from './NavIcon';
export * from './NavItem';
+export * from './NavMenu';
export * from './Slider';
export * from './Stack';
export * from './Switch';