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.tsxindex 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.tsxindex 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.jsonindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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({<buttonref={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({<divref={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(<buttontype="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({<divref={setRef}data-testid={testId}+ {...triggerProps}{...mergeProps(xdsClassName('side-nav-heading'),stylex.props(styles.root, xstyle),@@ -671,8 +699,8 @@ export function XDSSideNavHeading({showChevron ? (<buttontype="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.tsxindex 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({<divref={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(<buttontype="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({<divref={setRef}data-testid={testId}+ {...triggerProps}{...mergeProps(xdsClassName('top-nav-heading'),stylex.props(styles.root, xstyle),@@ -526,8 +551,8 @@ export function XDSTopNavHeading({showChevron ? (<buttontype="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.tsxindex 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 popoverconst 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 focusconst 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 (<><buttonref={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.tsnew file mode 100644index 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.tsindex 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';