An open source design system that's fully customizable and agent ready
TypeScript
fix(core): consolidate the hover→click guard into useMenuHover (#3121) (#4936)
Cindy Zhang2abfff493d8d
diff --git a/.changeset/menu-hover-click-guard.md b/.changeset/menu-hover-click-guard.mdnew file mode 100644index 0000000000..7c043d2924--- /dev/null+++ b/.changeset/menu-hover-click-guard.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Menus that open on hover no longer close when you click them. A hover-opened menu is already open under the cursor by the time the pointer arrives, so the click that naturally follows was dismissing it — fixed for TopNavMegaMenu in #4555, and now shared: the hover→click guard lives in `useMenuHover`, so TopNavMenu, TopNavHeading, SideNavHeading and DropdownMenuSubMenu get it too, and TopNavMegaMenu runs on the shared machine instead of its own copy. Also from the consolidation: opening a menu moves focus into it synchronously rather than a frame later, closing one returns focus to its trigger instead of dropping it to the document, and keyboard activation always opens rather than toggling an open menu shut (#3121)++@cixzhangdiff --git a/internal/test-utils/src/setup.ts b/internal/test-utils/src/setup.tsindex 20e0100144..8fc581b159 100644--- a/internal/test-utils/src/setup.ts+++ b/internal/test-utils/src/setup.ts@@ -25,11 +25,20 @@ import {configure} from '@testing-library/react';// Keeps the jsdom defaults (script, style).configure({defaultIgnore: 'script, style, [data-astryx-live-region]'});-// Polyfill for matchMedia (not supported in jsdom)+// Polyfill for matchMedia (not supported in jsdom).+//+// `(hover: hover)` reports TRUE: jsdom models a desktop browser driven by a+// mouse, and userEvent's hover()/unhover() dispatch real mouseenter/mouseleave.+// Reporting false made every hover-gated behavior (useMenuHover, HoverCard,+// Tooltip) silently dead in tests — the hover-then-click bug fixed in #3121+// went unnoticed in three components partly because no unit test could reach+// the hover path. Tests that need a touch device override this per-test.+const HOVER_CAPABLE = /\(\s*hover\s*:\s*hover\s*\)/;+if (typeof window !== 'undefined' && !window.matchMedia) {window.matchMedia = (query: string) => {const mql: MediaQueryList = {- matches: false,+ matches: HOVER_CAPABLE.test(query),media: query,onchange: null,addListener: () => {},@@ -58,7 +67,7 @@ if (typeof window.matchMedia === 'undefined') {Object.defineProperty(window, 'matchMedia', {writable: true,value: (query: string) => ({- matches: false,+ matches: HOVER_CAPABLE.test(query),media: query,onchange: null,addListener: () => {},diff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsxindex e84168c4c0..ffa6ef2b5a 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx@@ -8,7 +8,7 @@import {describe, it, expect, vi, beforeEach} from 'vitest';import {useState} from 'react';-import {render, screen, waitFor, fireEvent} from '@testing-library/react';+import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {DropdownMenu} from './DropdownMenu';import {DropdownMenuItem} from './DropdownMenuItem';@@ -708,3 +708,74 @@ describe('DropdownMenuSubMenu theming slots', () => {).toBeInTheDocument();});});++describe('DropdownMenuSubMenu hover/click guard', () => {+ it('keeps the flyout open when a hover-open is immediately clicked', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<MoveMenu />);++ await user.click(screen.getByRole('button', {name: /Actions/}));+ const trigger = screen.getByRole('menuitem', {+ name: /Move to/,+ hidden: true,+ });++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ expect(+ screen.getByRole('menuitem', {name: 'Folder A', hidden: true}),+ ).toHaveFocus();++ vi.useRealTimers();+ });++ it('closes on a click that lands well after the hover-open', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<MoveMenu />);++ await user.click(screen.getByRole('button', {name: /Actions/}));+ const trigger = screen.getByRole('menuitem', {+ name: /Move to/,+ hidden: true,+ });++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ act(() => {+ vi.advanceTimersByTime(1200);+ });++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ vi.useRealTimers();+ });++ it('moves focus into the flyout synchronously on a click-open', async () => {+ const user = userEvent.setup();+ render(<MoveMenu />);++ await user.click(screen.getByRole('button', {name: /Actions/}));+ const trigger = screen.getByRole('menuitem', {+ name: /Move to/,+ hidden: true,+ });++ await user.click(trigger);++ // No waitFor: a deferred (rAF) focus would fail here.+ expect(+ screen.getByRole('menuitem', {name: 'Folder A', hidden: true}),+ ).toHaveFocus();+ });+});diff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsxindex 131ffd0dc2..330d9dc21b 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx@@ -299,12 +299,16 @@ export function DropdownMenuSubMenu(// Hover-intent: entering the trigger opens after a short delay; leaving// either surface closes after a delay. Hover-open does not steal focus.- const {triggerProps, contentProps} = useMenuHover<HTMLDivElement>({- show: showLayer,- hide: hideLayer,- isOpen,- isEnabled: canOpen,- });+ // Hover intent and the shared hover→click guard only: this level owns its own+ // click handling, roving focus and typeahead. popover="manual", so the+ // invoker wiring other consumers need does not apply.+ const {triggerProps, contentProps, confirmHoverOpen} =+ useMenuHover<HTMLDivElement>({+ show: showLayer,+ hide: hideLayer,+ isOpen,+ isEnabled: canOpen,+ });const open = useCallback((options?: {focusFirst?: boolean}) => {@@ -313,18 +317,12 @@ export function DropdownMenuSubMenu(}layer.show();if (options?.focusFirst) {- requestAnimationFrame(() => {- // Move focus into the flyout. When it has no focusable items yet- // (e.g. an async submenu showing only a disabled "Loading…" row via- // hasSpinner), focusFirst() finds nothing — fall back to focusing the- // flyout container itself so keyboard ownership still transfers off- // the parent list. Otherwise the parent would keep focus, letting- // arrow keys rove the parent while the empty flyout stays open.- const focusedItem = focusFirst();- if (!focusedItem) {- menuRef.current?.focus();- }- });+ // Synchronous by design — see the focus note in useMenuHover. A+ // still-loading flyout has no focusable item, so fall back to the+ // container: keyboard ownership must leave the parent list either way.+ if (!focusFirst()) {+ menuRef.current?.focus();+ }}},[canOpen, layer, focusFirst, menuRef],@@ -354,13 +352,19 @@ export function DropdownMenuSubMenu(if (isDisabled) {return;}- // Click toggles the flyout, moving focus into it on open.+ // Toggles, except for the click that follows a hover-open (#3121).if (isOpen) {+ if (confirmHoverOpen()) {+ if (!focusFirst()) {+ menuRef.current?.focus();+ }+ return;+ }close({focusTrigger: true});} else {open({focusFirst: true});}- }, [isDisabled, isOpen, open, close]);+ }, [isDisabled, isOpen, open, close, confirmHoverOpen, focusFirst, menuRef]);const handleTriggerKeyDown = useCallback((e: React.KeyboardEvent) => {diff --git a/packages/core/src/SideNav/SideNav.test.tsx b/packages/core/src/SideNav/SideNav.test.tsxindex 7fece66d65..5e6ed26e2e 100644--- a/packages/core/src/SideNav/SideNav.test.tsx+++ b/packages/core/src/SideNav/SideNav.test.tsx@@ -1259,7 +1259,9 @@ describe('SideNavItem — collapsed submenu hover intent', () => {vi.useFakeTimers();const trigger = renderFlyout();- fireEvent.click(trigger);+ // `detail: 1` marks a pointer click: the hook reads a detail-0 click as+ // Enter/Space, which always opens rather than toggling.+ fireEvent.click(trigger, {detail: 1});expect(trigger).toHaveAttribute('aria-expanded', 'true');// Clicking is a commitment: the flyout outlives the pointer.@@ -1279,7 +1281,7 @@ describe('SideNavItem — collapsed submenu hover intent', () => {// The pointer never left, so dismissing fires a fresh mouseenter as the// flyout unmounts — which used to reopen what the user just closed.- fireEvent.click(trigger);+ fireEvent.click(trigger, {detail: 1});expect(trigger).toHaveAttribute('aria-expanded', 'false');fireEvent.mouseEnter(trigger);@@ -1307,7 +1309,7 @@ describe('SideNavItem — collapsed submenu hover intent', () => {expect(trigger).toHaveAttribute('aria-expanded', 'false');// Tapping still opens it — the touch path goes through click, untouched.- fireEvent.click(trigger);+ fireEvent.click(trigger, {detail: 1});expect(trigger).toHaveAttribute('aria-expanded', 'true');});@@ -2162,3 +2164,88 @@ describe('SideNav footer icon row sizing', () => {expect(mirror && getComputedStyle(mirror).display).toBe('flex');});});++describe('SideNavHeading hover/click guard', () => {+ // tabIndex={-1} matches real menu items; a bare role=menuitem div is not+ // focusable.+ const menuItems = (+ <>+ <div role="menuitem" tabIndex={-1}>+ Alpha+ </div>+ <div role="menuitem" tabIndex={-1}>+ Beta+ </div>+ </>+ );++ it('keeps the menu open when a hover-open is immediately clicked', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<SideNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(50);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ vi.useRealTimers();+ });++ it('closes on a click that lands well after the hover-open', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<SideNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(50);+ });+ act(() => {+ vi.advanceTimersByTime(1200);+ });++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ vi.useRealTimers();+ });++ it('leaves focus on the trigger for a hover-open, and moves it in on click', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<SideNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(50);+ });+ const firstItem = screen.getAllByRole('menuitem', {hidden: true})[0];+ expect(firstItem).not.toHaveFocus();++ await user.click(trigger);+ expect(firstItem).toHaveFocus();++ vi.useRealTimers();+ });++ it('returns focus to the trigger on Escape', async () => {+ const user = userEvent.setup();+ render(<SideNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.keyboard('{Escape}');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ expect(trigger).toHaveFocus();+ });+});diff --git a/packages/core/src/SideNav/SideNavHeading.tsx b/packages/core/src/SideNav/SideNavHeading.tsxindex 71c0415fc2..5f00f9209b 100644--- a/packages/core/src/SideNav/SideNavHeading.tsx+++ b/packages/core/src/SideNav/SideNavHeading.tsx@@ -371,23 +371,27 @@ export function SideNavHeading({hasCloseButton: false,});- const closeMenuCtx = useMemo(- () => ({closeMenu: popover.hide}),- [popover.hide],- );+ const {+ triggerProps,+ contentProps,+ menuRef,+ setTriggerEl,+ close: closeMenu,+ } = useMenuHover<HTMLDivElement>({+ show: popover.show,+ hide: popover.hide,+ isOpen: popover.isOpen,+ isEnabled: !!menu,+ showDelay: 0,+ });- const {triggerProps, contentProps, menuRef, setTriggerEl} =- useMenuHover<HTMLDivElement>({- show: popover.show,- hide: popover.hide,- isOpen: popover.isOpen,- isEnabled: !!menu,- showDelay: 0,- });+ const closeMenuCtx = useMemo(() => ({closeMenu}), [closeMenu]);+ // setTriggerEl belongs on the chevron button, not this root: it is the+ // focus-restore target and a <div> cannot take focus. triggerRef stays here+ // because the panel anchors to the whole heading.const setRef = mergeRefs<HTMLDivElement>(rootRef,- setTriggerEl,ref,menu ? popover.triggerRef : undefined,);@@ -402,7 +406,9 @@ export function SideNavHeading({const collapsedSetRef = mergeRefs<HTMLElement>(collapsedItemRef,ref,+ // Collapsed, this button is the trigger, so it takes both roles.menu ? popover.triggerRef : undefined,+ menu ? setTriggerEl : undefined,);let collapsedElement: ReactNode;@@ -458,7 +464,8 @@ export function SideNavHeading({<buttontype="button"{...focusOutlineProps.focusVisible(styles.popoverHeading)}- onClick={triggerProps.onClick}>+ // A close affordance, not the trigger: dismiss only.+ onClick={closeMenu}>{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}<span {...stylex.props(styles.textContainer)}>{superheading && (@@ -595,7 +602,8 @@ export function SideNavHeading({<buttontype="button"{...focusOutlineProps.focusVisible(styles.popoverHeading)}- onClick={triggerProps.onClick}>+ // A close affordance, not the trigger: dismiss only.+ onClick={closeMenu}>{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}{renderTextContent(<Icon@@ -651,6 +659,7 @@ export function SideNavHeading({{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}{renderTextContent(<button+ ref={setTriggerEl}type="button"aria-label={t('@astryx.sideNav.heading.openMenu')}onClick={e => {@@ -725,6 +734,7 @@ export function SideNavHeading({{renderTextContent(showChevron ? (<button+ ref={setTriggerEl}type="button"aria-label={t('@astryx.sideNav.heading.openMenu')}onClick={e => {diff --git a/packages/core/src/SideNav/SideNavItem.tsx b/packages/core/src/SideNav/SideNavItem.tsxindex dc516ef7bd..1c1611677d 100644--- a/packages/core/src/SideNav/SideNavItem.tsx+++ b/packages/core/src/SideNav/SideNavItem.tsx@@ -468,6 +468,11 @@ export function SideNavItem({hide: popover.hide,isOpen: popover.isOpen,isEnabled: isCollapsed && hasChildren,+ // Standard popover toggling: the flyout opens beside the rail, not over+ // the icon, so the click after a hover-open is a deliberate dismissal+ // rather than the #3121 confirmation the nav menus need.+ clickGuardMs: 0,+ ownsFocus: false,});// In collapsed mode: hide items without iconsdiff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsxindex 034c2c064b..bfa85f602d 100644--- a/packages/core/src/TopNav/TopNav.test.tsx+++ b/packages/core/src/TopNav/TopNav.test.tsx@@ -10,7 +10,7 @@*/import {describe, it, expect, vi} from 'vitest';-import {fireEvent, render, screen} from '@testing-library/react';+import {fireEvent, render, screen, act} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {TopNav} from './TopNav';import {TopNavRenderContext} from './TopNavRenderContext';@@ -660,3 +660,88 @@ describe('TopNavItem', () => {});});});++describe('TopNavHeading hover/click guard', () => {+ // tabIndex={-1} matches real menu items; a bare role=menuitem div is not+ // focusable.+ const menuItems = (+ <>+ <div role="menuitem" tabIndex={-1}>+ Alpha+ </div>+ <div role="menuitem" tabIndex={-1}>+ Beta+ </div>+ </>+ );++ it('keeps the menu open when a hover-open is immediately clicked', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<TopNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(50);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ vi.useRealTimers();+ });++ it('closes on a click that lands well after the hover-open', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<TopNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(50);+ });+ act(() => {+ vi.advanceTimersByTime(1200);+ });++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ vi.useRealTimers();+ });++ it('leaves focus on the trigger for a hover-open, and moves it in on click', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ render(<TopNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(50);+ });+ const firstItem = screen.getAllByRole('menuitem', {hidden: true})[0];+ expect(firstItem).not.toHaveFocus();++ await user.click(trigger);+ expect(firstItem).toHaveFocus();++ vi.useRealTimers();+ });++ it('returns focus to the trigger on Escape', async () => {+ const user = userEvent.setup();+ render(<TopNavHeading heading="My App" menu={menuItems} />);+ const trigger = screen.getByRole('button', {name: 'Open menu'});++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.keyboard('{Escape}');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ expect(trigger).toHaveFocus();+ });+});diff --git a/packages/core/src/TopNav/TopNavHeading.tsx b/packages/core/src/TopNav/TopNavHeading.tsxindex 9d0c656349..9598bf5e8b 100644--- a/packages/core/src/TopNav/TopNavHeading.tsx+++ b/packages/core/src/TopNav/TopNavHeading.tsx@@ -335,23 +335,27 @@ export function TopNavHeading({hasCloseButton: false,});- const closeMenuCtx = useMemo(- () => ({closeMenu: popover.hide}),- [popover.hide],- );+ const {+ triggerProps,+ contentProps,+ menuRef,+ setTriggerEl,+ close: closeMenu,+ } = useMenuHover<HTMLDivElement>({+ show: popover.show,+ hide: popover.hide,+ isOpen: popover.isOpen,+ isEnabled: !!menu,+ showDelay: 0,+ });- const {triggerProps, contentProps, menuRef, setTriggerEl} =- useMenuHover<HTMLDivElement>({- show: popover.show,- hide: popover.hide,- isOpen: popover.isOpen,- isEnabled: !!menu,- showDelay: 0,- });+ const closeMenuCtx = useMemo(() => ({closeMenu}), [closeMenu]);+ // setTriggerEl belongs on the chevron button, not this root: it is the+ // focus-restore target and a <div> cannot take focus. triggerRef stays here+ // because the panel anchors to the whole heading.const setRef = mergeRefs<HTMLElement>(rootRef,- setTriggerEl,ref,menu ? popover.triggerRef : undefined,);@@ -426,7 +430,8 @@ export function TopNavHeading({<buttontype="button"{...stylex.props(styles.popoverHeading)}- onClick={triggerProps.onClick}>+ // A close affordance, not the trigger: dismiss only.+ onClick={closeMenu}>{logo && <span {...stylex.props(styles.logo)}>{logo}</span>}{renderTextContent(<Icon@@ -505,6 +510,7 @@ export function TopNavHeading({// Stays a <button>: this box is the popover trigger, so it carries// the accessible name and handlers — only the glyph moves to Icon.<button+ ref={setTriggerEl}type="button"aria-label={t('@astryx.topNav.heading.openMenu')}onClick={e => {@@ -582,6 +588,7 @@ export function TopNavHeading({// carries the accessible name and handlers — only the glyph// moves to Icon.<button+ ref={setTriggerEl}type="button"aria-label={t('@astryx.topNav.heading.openMenu')}onClick={e => {diff --git a/packages/core/src/TopNav/TopNavMegaMenu.tsx b/packages/core/src/TopNav/TopNavMegaMenu.tsxindex 5df2688b94..04ebceda3f 100644--- a/packages/core/src/TopNav/TopNavMegaMenu.tsx+++ b/packages/core/src/TopNav/TopNavMegaMenu.tsx@@ -50,6 +50,7 @@ import {borderVars,} from '../theme/tokens.stylex';import {usePopover} from '../Popover/usePopover';+import {useMenuHover} from '../hooks/useMenuHover';import {Grid} from '../Grid/Grid';import {Icon} from '../Icon';import {mergeProps, mergeRefs} from '../utils';@@ -370,7 +371,9 @@ TopNavMegaMenu.displayName = 'TopNavMegaMenu';// DefaultMegaMenu — desktop popover mode// =============================================================================-const CLICK_GUARD_MS = 500;+/** The panel is a grid of links, not `role="menuitem"` rows. */+const PANEL_ITEM_SELECTOR =+ 'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])';function DefaultMegaMenu({ref,@@ -382,19 +385,13 @@ function DefaultMegaMenu({onOpenChange,}: TopNavMegaMenuProps) {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 hoverOpenedAtRef = useRef(0);- const stickyRef = useRef(false);const handlePopoverShow = useCallback(() => {onOpenChange?.(true);}, [onOpenChange]);const handlePopoverHide = useCallback(() => {- hoverOpenedAtRef.current = 0;- stickyRef.current = false;onOpenChange?.(false);}, [onOpenChange]);@@ -430,107 +427,31 @@ function DefaultMegaMenu({};}, [popover]);- 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(() => {- hoverOpenedAtRef.current = Date.now();- popover.show({skipAutoFocus: true});- }, delay);- }, [clearTimeouts, delay, popover]);-- const scheduleHide = useCallback(() => {- clearTimeouts();- hideTimeoutRef.current = setTimeout(() => {- popover.hide();- }, hideDelay);- }, [clearTimeouts, hideDelay, popover]);-- const focusFirstPanelItem = useCallback(() => {- popover.contentRef.current- ?.querySelector<HTMLElement>(- 'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])',- )- ?.focus();- }, [popover.contentRef]);-- const handleTriggerMouseEnter = useCallback(() => {- clearTimeouts();- if (!popover.isOpen) {- scheduleShow();- }- }, [clearTimeouts, popover.isOpen, scheduleShow]);-- const handlePanelMouseEnter = useCallback(() => {- clearTimeouts();- }, [clearTimeouts]);-- const handleMouseLeave = useCallback(() => {- if (!stickyRef.current) {- scheduleHide();- }- }, [scheduleHide]);-- const handleClick = useCallback(- (event: React.MouseEvent<HTMLButtonElement>) => {- // Cancel the native invoker toggle so this guard is the single source of- // truth for trigger activation. popoverTarget still establishes the- // invoker relationship used by native light-dismiss and stacking.- event.preventDefault();- clearTimeouts();-- if (event.detail === 0) {- stickyRef.current = true;- hoverOpenedAtRef.current = 0;- if (popover.isOpen) {- focusFirstPanelItem();- } else {- popover.show();- }- } else if (!popover.isOpen) {- stickyRef.current = true;- popover.show({skipAutoFocus: true});- } else if (Date.now() - hoverOpenedAtRef.current < CLICK_GUARD_MS) {- // A click that naturally follows a hover-open confirms the open state- // instead of toggling the panel shut. From here it behaves like any- // other click-open and stays pinned until explicit dismissal.- stickyRef.current = true;- hoverOpenedAtRef.current = 0;- } else {- popover.hide();- triggerButtonRef.current?.focus();- }- },- [clearTimeouts, focusFirstPanelItem, popover],- );-- useEffect(() => {- return () => {- clearTimeouts();- };- }, [clearTimeouts]);+ const {+ triggerProps: hoverTriggerProps,+ contentProps,+ menuRef,+ setTriggerEl,+ } = useMenuHover<HTMLDivElement>({+ show: popover.show,+ hide: popover.hide,+ isOpen: popover.isOpen,+ isEnabled: true,+ showDelay: delay,+ hideDelay,+ itemSelector: PANEL_ITEM_SELECTOR,+ // Trigger sits outside an auto popover; the invoker relationship exempts it+ // from light dismiss.+ popoverId: popover.id,+ });return (<><button- ref={mergeRefs(triggerButtonRef, ref)}+ ref={mergeRefs(triggerButtonRef, setTriggerEl, ref)}type="button"{...popover.triggerProps}- // Native invoker prevents trigger light-dismiss.- popoverTarget={popover.id}- onClick={handleClick}- onMouseEnter={handleTriggerMouseEnter}- onMouseLeave={handleMouseLeave}+ {...hoverTriggerProps}{...mergeProps(themeProps('top-nav-mega-menu'),focusOutlineProps.focusVisible(@@ -551,10 +472,10 @@ function DefaultMegaMenu({// role="group" — a mega menu is a browsing grid of links, not an// ARIA menu of menuitems (per the WAI-ARIA APG, the menu role is// for action menus; link mega menus are the documented anti-case).+ ref={menuRef}role="group"aria-label={label}- onMouseEnter={handlePanelMouseEnter}- onMouseLeave={handleMouseLeave}+ {...contentProps}{...stylex.props(styles.panelContainer)}><div {...stylex.props(styles.panelContent)}>{/* Menu items section */}diff --git a/packages/core/src/TopNav/TopNavMenu.tsx b/packages/core/src/TopNav/TopNavMenu.tsxindex 064901c501..0ed7a6d2ba 100644--- a/packages/core/src/TopNav/TopNavMenu.tsx+++ b/packages/core/src/TopNav/TopNavMenu.tsx@@ -342,7 +342,7 @@ export function TopNavMenu({role: 'none',});- const {triggerProps, contentProps, menuRef, setTriggerEl} =+ const {triggerProps, contentProps, menuRef, setTriggerEl, close} =useMenuHover<HTMLDivElement>({show: popover.show,hide: popover.hide,@@ -350,6 +350,9 @@ export function TopNavMenu({isEnabled: true,showDelay: delay,hideDelay,+ // Trigger sits outside an auto popover; the invoker relationship exempts+ // it from light dismiss.+ popoverId: popover.id,});const setTriggerRef = mergeRefs<HTMLButtonElement>(@@ -368,7 +371,8 @@ export function TopNavMenu({useListFocus<HTMLDivElement>({itemSelector: '[role="menuitem"]',hasRovingTabIndex: true,- onEscape: popover.hide,+ // Not popover.hide: Escape must also restore focus to the trigger.+ onEscape: close,});// First-character typeahead over the menu items (menus-11).diff --git a/packages/core/src/hooks/useMenuHover.test.tsx b/packages/core/src/hooks/useMenuHover.test.tsxnew file mode 100644index 0000000000..1212c002ac--- /dev/null+++ b/packages/core/src/hooks/useMenuHover.test.tsx@@ -0,0 +1,364 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file useMenuHover.test.tsx+ * @input Uses vitest, @testing-library/react, TopNavMenu (a real consumer)+ * @output Unit tests for the shared hover-menu interaction contract (#3121)+ * @position Testing; exercised through TopNavMenu rather than a synthetic+ * harness, so the hook cannot drift from how consumers wire it+ *+ * SYNC: When useMenuHover changes, update tests to match new behavior+ */+import {describe, it, expect, vi, afterEach} from 'vitest';+import {render, screen, act} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {TopNavMenu} from '../TopNav/TopNavMenu';++const items = [+ {title: 'Analytics', description: 'Track user behavior', href: '/analytics'},+ {title: 'Messaging', description: 'Real-time comms', href: '/messaging'},+];++/** A touchscreen: no hover-capable pointer. */+function mockPointerlessDevice() {+ vi.spyOn(window, 'matchMedia').mockImplementation(+ (query: string) =>+ ({+ matches: false,+ media: query,+ onchange: null,+ addListener: () => {},+ removeListener: () => {},+ addEventListener: () => {},+ removeEventListener: () => {},+ dispatchEvent: () => false,+ }) as MediaQueryList,+ );+}++function renderMenu() {+ render(<TopNavMenu label="Products" items={items} />);+ return screen.getByRole('button', {name: 'Products'});+}++function firstMenuItem() {+ return document.querySelector<HTMLElement>('[role="menuitem"]');+}++afterEach(() => {+ vi.useRealTimers();+ vi.restoreAllMocks();+});++describe('useMenuHover — hover/click guard', () => {+ it('opens on hover after the show delay', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ act(() => {+ vi.advanceTimersByTime(300);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('keeps the menu open when a hover-open is immediately clicked', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('pins a confirmed menu so leaving the trigger no longer closes it', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ await user.click(trigger);++ await user.unhover(trigger);+ act(() => {+ vi.advanceTimersByTime(500);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('closes on a click that lands well after the hover-open', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ // Past the guard: a deliberate dismissal, not a follow-on.+ act(() => {+ vi.advanceTimersByTime(1200);+ });++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('closes a transient (hover-opened) menu when the pointer leaves', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ await user.unhover(trigger);+ act(() => {+ vi.advanceTimersByTime(400);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('re-entering the trigger of an open menu does not re-arm the guard', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ // Click-open pins the menu.+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ // Re-entering must not un-pin it, nor make the next click a "confirm".+ await user.unhover(trigger);+ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('stays closed when the panel vanishing puts the trigger back under the pointer', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ // Without suppression, the mouseenter fired when the panel stops covering+ // the trigger reopens the menu — which made Escape look inert.+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(200);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('reopens on a deliberate re-hover once the suppression window passes', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.click(trigger);+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ await user.unhover(trigger);+ act(() => {+ vi.advanceTimersByTime(600);+ });+ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('toggles cleanly for click-only interaction', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });+});++describe('useMenuHover — focus management', () => {+ it('leaves focus on the trigger for a hover-open', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });++ expect(firstMenuItem()).not.toHaveFocus();+ });++ it('moves focus to the first item on a click-open, synchronously', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();++ await user.click(trigger);++ // No waitFor and no timer flush: a deferred (rAF) focus fails here, which+ // is the point of the assertion.+ expect(firstMenuItem()).toHaveFocus();+ });++ it('moves focus into the menu when a hover-open is confirmed by click', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ expect(firstMenuItem()).not.toHaveFocus();++ await user.click(trigger);+ expect(firstMenuItem()).toHaveFocus();+ });++ it('returns focus to the trigger when a click closes the menu', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();++ await user.click(trigger);+ expect(firstMenuItem()).toHaveFocus();++ await user.click(trigger);+ expect(trigger).toHaveFocus();+ });++ it('returns focus to the trigger on Escape', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();++ await user.click(trigger);+ expect(firstMenuItem()).toHaveFocus();++ await user.keyboard('{Escape}');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ expect(trigger).toHaveFocus();+ });+});++describe('useMenuHover — keyboard activation', () => {+ it('opens on Enter and moves focus into the menu', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();+ trigger.focus();++ await user.keyboard('{Enter}');++ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ expect(firstMenuItem()).toHaveFocus();+ });++ it('opens on Space', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();+ trigger.focus();++ await user.keyboard(' ');++ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('never toggles an open menu closed — it moves focus in instead', async () => {+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ // A hover-open is the only state where a keyboard user can activate the+ // trigger of an open menu; closing on Enter would strand them.+ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(300);+ });+ trigger.focus();++ await user.keyboard('{Enter}');++ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ expect(firstMenuItem()).toHaveFocus();+ });++ it('arrow keys walk the menu items', async () => {+ const user = userEvent.setup();+ const trigger = renderMenu();++ await user.click(trigger);+ const menuItems =+ document.querySelectorAll<HTMLElement>('[role="menuitem"]');+ expect(menuItems[0]).toHaveFocus();++ await user.keyboard('{ArrowDown}');+ expect(menuItems[1]).toHaveFocus();+ });+});++describe('useMenuHover — devices without hover', () => {+ it('does not open on a synthetic mouseenter from a tap', async () => {+ mockPointerlessDevice();+ vi.useFakeTimers({shouldAdvanceTime: true});+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});+ const trigger = renderMenu();++ // Taps emit a compatibility mouseenter; opening on it leaves a menu+ // hanging open behind the tap.+ await user.hover(trigger);+ act(() => {+ vi.advanceTimersByTime(500);+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('still opens and closes on click', async () => {+ mockPointerlessDevice();+ const user = userEvent.setup();+ const trigger = renderMenu();++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });+});++describe('useMenuHover — native invoker wiring', () => {+ it('registers the trigger as the panel it controls', () => {+ const trigger = renderMenu();++ // jsdom implements neither light dismiss nor invokers, so this asserts the+ // wiring; the behavior itself is browser-verified.+ expect(trigger).toHaveAttribute(+ 'popovertarget',+ trigger.getAttribute('aria-controls'),+ );+ });+});diff --git a/packages/core/src/hooks/useMenuHover.ts b/packages/core/src/hooks/useMenuHover.tsindex 943ee10118..aa1560c9c5 100644--- a/packages/core/src/hooks/useMenuHover.ts+++ b/packages/core/src/hooks/useMenuHover.ts@@ -4,42 +4,98 @@/*** @file useMenuHover.ts- * @input Uses React hooks, useListFocus+ * @input Uses React hooks, useListFocus, useMediaQuery* @output Exports useMenuHover hook- * @position Internal hook; used by nav heading components and TopNavMenu+ * @position Internal hook; used by nav heading components, TopNavMenu,+ * TopNavMegaMenu and DropdownMenuSubMenu*- * Hover as a progressive enhancement on top of standard popover behavior:+ * Hover as a progressive enhancement over standard popover behavior: click+ * toggles, Escape and outside-click close, arrows navigate; on top of that,+ * mouseenter opens after a delay and mouseleave closes one that hover opened.*- * 1. Default popover: click toggles, Escape closes, outside-click closes,- * arrow keys navigate menu items.+ * Three behaviors here are not obvious and are load-bearing:*- * 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+ * 1. Hover→click guard (#3121). A hover-opened menu is already open under the+ * cursor when the pointer arrives, so the click that naturally follows would+ * toggle it shut. Within `clickGuardMs` a click instead confirms it: the menu+ * pins and behaves like a click-open from then on.*- * Only uses mouseenter/mouseleave (not mouseover).+ * 2. Focus moves synchronously. `useLayer.show()` calls `showPopover()` in the+ * same tick and the layer's children are always mounted, so items are+ * focusable the moment `show()` returns — a `requestAnimationFrame` here+ * lands after paint and races anything else moving focus. Hover-opens are the+ * exception: the pointer is driving, so focus stays on the trigger. The hook+ * always passes `skipAutoFocus` and owns focus itself, because the popover's+ * auto-focus targets the first *tabbable* node while a menu wants its first+ * item — under roving tabindex those are different elements.+ *+ * 3. Native light dismiss. A `popover="auto"` is dismissed by the browser on+ * pointer interaction outside the panel, and a trigger outside the panel+ * counts — before React's click handler runs. `popoverId` makes the trigger+ * the panel's invoker, which exempts it. jsdom implements neither light+ * dismiss nor invokers, so that wiring is only verifiable in a browser.*/import {useCallback, useEffect, useRef} from 'react';+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';import {useListFocus} from './useListFocus';import {useMediaQuery} from './useMediaQuery';-interface UseMenuHoverOptions {+const DEFAULT_CLICK_GUARD_MS = 500;++/**+ * How long after a close a mouseenter on the trigger is ignored.+ *+ * A panel positioned over its own trigger puts that trigger back under a+ * stationary pointer when it closes, and the browser fires a fresh mouseenter —+ * which reopened the menu the user had just dismissed. Time-bounded rather than+ * a one-shot flag, so a deliberate re-hover seconds later still opens; a real+ * mouseleave clears it early.+ */+const REOPEN_SUPPRESS_MS = 300;++export interface UseMenuHoverOptions {show: (options?: {skipAutoFocus?: boolean}) => void;hide: () => void;isOpen: boolean;isEnabled: boolean;+ /** Delay before a hover opens the menu (ms). @default 150 */showDelay?: number;+ /** Delay before leaving the trigger or menu closes it (ms). @default 200 */hideDelay?: number;+ /**+ * Window after a hover-open in which a click confirms the menu instead of+ * closing it. 0 opts out, making every click toggle. @default 500+ */+ clickGuardMs?: number;+ /**+ * Selector for the menu's focusable items, forwarded to `useListFocus`. A+ * panel of links (a mega menu) needs an override; `role="menuitem"` rows do+ * not. @default '[role="menuitem"]'+ */+ itemSelector?: string;+ /**+ * The popup's DOM id (`usePopover().id`). Supply it when the popup is a+ * native `popover="auto"` and the trigger sits outside it; omit it for+ * `popover="manual"` popups and triggers inside the panel.+ */+ popoverId?: string;+ /**+ * Whether the hook moves focus on a click or keyboard open. False for+ * consumers that wire the pointer half only and leave focus to the popover's+ * own trap — a panel that is a dialog rather than a menu (`SideNavItem`'s+ * collapsed flyout) has no items for the hook to focus. @default true+ */+ ownsFocus?: boolean;}-interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {+export interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {triggerProps: {- onClick: () => void;+ onClick: (event?: React.MouseEvent) => void;onMouseEnter: () => void;onMouseLeave: () => void;+ /** Present only when `popoverId` is supplied. */+ popoverTarget?: string;};contentProps: {onMouseEnter: () => void;@@ -47,7 +103,25 @@ interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {onKeyDown: (e: React.KeyboardEvent) => void;};menuRef: React.RefObject<T | null>;- focusFirst: () => void;+ /** Focus the first enabled item. Returns false when there was none. */+ focusFirst: () => boolean;+ /**+ * Focus the first enabled item, falling back to the menu container when the+ * menu is empty or still loading.+ */+ focusMenu: () => void;+ /**+ * For consumers with their own click handler: call this in the open branch.+ * Returns `true` when the click was the one following a hover-open — the menu+ * is now pinned and the click must NOT be treated as a dismissal.+ */+ confirmHoverOpen: () => boolean;+ /**+ * Close, restoring focus to the trigger. For dismiss affordances rendered+ * inside the popup, which are close buttons rather than the trigger and so+ * must not carry its toggle and keyboard-activation semantics.+ */+ close: () => void;setTriggerEl: (el: HTMLElement | null) => void;}@@ -61,6 +135,10 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(isEnabled,showDelay = 150,hideDelay = 200,+ clickGuardMs = DEFAULT_CLICK_GUARD_MS,+ itemSelector,+ popoverId,+ ownsFocus = true,} = options;const hasHover = useMediaQuery('(hover: hover)');@@ -68,17 +146,25 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(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)+ /** Menu was hover-opened, so mouseleave may close it. */const hoverModeRef = useRef(false);- // One-shot: skip the next mouseenter after click-to-close- const skipNextEnterRef = useRef(false);+ const closedAtRef = useRef(0);+ /** When the current open began as a hover-open; 0 once confirmed or closed. */+ const hoverOpenedAtRef = useRef(0);const prevIsOpenRef = useRef(isOpen);- // When popover closes (any reason), reset hover mode- if (prevIsOpenRef.current && !isOpen) {- hoverModeRef.current = false;- }- prevIsOpenRef.current = isOpen;+ // Catches every close, whatever caused it. A layout effect, not render: it+ // must land before the browser hit-tests the vanished panel and fires the+ // mouseenter REOPEN_SUPPRESS_MS exists to swallow.+ useIsomorphicLayoutEffect(() => {+ const wasOpen = prevIsOpenRef.current;+ prevIsOpenRef.current = isOpen;+ if (wasOpen && !isOpen) {+ hoverModeRef.current = false;+ hoverOpenedAtRef.current = 0;+ closedAtRef.current = Date.now();+ }+ }, [isOpen]);const clearTimeouts = useCallback(() => {if (showTimerRef.current) {@@ -91,56 +177,160 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(}}, []);+ // useListFocus needs an onEscape that is defined in terms of its own listRef;+ // the indirection avoids the use-before-declare.+ const escapeHandlerRef = useRef<() => void>(() => {});+const {listRef: menuRef,handleKeyDown: handleListKeyDown,focusFirst,} = useListFocus<T>({- onEscape: () => {- clearTimeouts();- hide();- },+ itemSelector,+ onEscape: () => escapeHandlerRef.current(),});+ const hideAndRestoreFocus = useCallback(() => {+ // Read before hiding: closing the layer moves focus itself.+ const menuHadFocus =+ menuRef.current?.contains(document.activeElement) ?? false;+ hide();+ if (menuHadFocus) {+ triggerElRef.current?.focus();+ }+ }, [hide, menuRef]);++ useEffect(() => {+ escapeHandlerRef.current = () => {+ clearTimeouts();+ hideAndRestoreFocus();+ };+ }, [clearTimeouts, hideAndRestoreFocus]);+useEffect(() => {return () => clearTimeouts();}, [clearTimeouts]);- // Click: always toggle- const handleClick = useCallback(() => {- clearTimeouts();- if (isOpen) {- skipNextEnterRef.current = true;- hide();- } else {- skipNextEnterRef.current = false;+ const focusMenu = useCallback(() => {+ // An empty or still-loading menu has no focusable item; focus the container+ // so keyboard ownership still transfers off the trigger's list.+ if (!focusFirst()) {+ menuRef.current?.focus();+ }+ }, [focusFirst, menuRef]);++ const openAndFocus = useCallback(() => {+ if (!ownsFocus) {show();- requestAnimationFrame(() => focusFirst());+ return;+ }+ show({skipAutoFocus: true});+ focusMenu();+ }, [ownsFocus, show, focusMenu]);++ const confirmHoverOpen = useCallback((): boolean => {+ const isConfirming =+ clickGuardMs > 0 &&+ hoverOpenedAtRef.current > 0 &&+ Date.now() - hoverOpenedAtRef.current < clickGuardMs;+ if (!isConfirming) {+ return false;}- }, [isOpen, clearTimeouts, show, hide, focusFirst]);+ hoverModeRef.current = false;+ hoverOpenedAtRef.current = 0;+ return true;+ }, [clickGuardMs]);++ const handleClick = useCallback(+ (event?: React.MouseEvent) => {+ // Cancel the invoker's default toggle so this handler stays the single+ // source of truth; popoverTarget still exempts the trigger from dismissal.+ if (popoverId) {+ event?.preventDefault();+ }+ clearTimeouts();++ // Enter/Space arrive as a click with detail 0, and always open. A keyboard+ // user reaches the trigger of an open menu only because a hover-open left+ // focus behind; closing there would stranded them outside a visible menu.+ const isKeyboardActivation = event != null && event.detail === 0;+ if (isKeyboardActivation) {+ closedAtRef.current = 0;+ hoverModeRef.current = false;+ hoverOpenedAtRef.current = 0;+ if (isOpen) {+ if (ownsFocus) {+ focusMenu();+ }+ } else {+ openAndFocus();+ }+ return;+ }++ if (!isOpen) {+ closedAtRef.current = 0;+ hoverModeRef.current = false;+ hoverOpenedAtRef.current = 0;+ openAndFocus();+ return;+ }++ if (confirmHoverOpen()) {+ if (ownsFocus) {+ focusMenu();+ }+ return;+ }++ hideAndRestoreFocus();+ },+ [+ popoverId,+ clearTimeouts,+ isOpen,+ ownsFocus,+ confirmHoverOpen,+ openAndFocus,+ focusMenu,+ hideAndRestoreFocus,+ ],+ );- // Hover: mouseenter activates hover mode and opensconst handleMouseEnter = useCallback(() => {if (!hasHover) {return;}- if (skipNextEnterRef.current) {- skipNextEnterRef.current = false;+ if (+ closedAtRef.current > 0 &&+ Date.now() - closedAtRef.current < REOPEN_SUPPRESS_MS+ ) {+ return;+ }+ // Re-entering an open menu's trigger must not un-pin it or re-arm the+ // guard, which would make the next deliberate click another "confirm" and+ // leave the menu undismissable.+ if (isOpen) {+ clearTimeouts();return;}hoverModeRef.current = true;clearTimeouts();+ const openByHover = () => {+ hoverOpenedAtRef.current = Date.now();+ show({skipAutoFocus: true});+ };if (showDelay > 0) {- showTimerRef.current = setTimeout(() => {- show({skipAutoFocus: true});- }, showDelay);+ showTimerRef.current = setTimeout(openByHover, showDelay);} else {- show({skipAutoFocus: true});+ openByHover();}- }, [hasHover, clearTimeouts, show, showDelay]);+ }, [hasHover, isOpen, clearTimeouts, show, showDelay]);- // Hover: mouseleave only closes if in hover modeconst handleMouseLeave = useCallback(() => {+ // A real leave ends the stationary-pointer case the suppression window+ // exists for, so the next enter is deliberate whenever it arrives.+ closedAtRef.current = 0;if (!hoverModeRef.current) {return;}@@ -150,7 +340,6 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(}, hideDelay);}, [clearTimeouts, hide, hideDelay]);- // Content: mouseenter cancels pending hideconst handleContentMouseEnter = useCallback(() => {clearTimeouts();}, [clearTimeouts]);@@ -173,6 +362,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(},menuRef,focusFirst,+ focusMenu,+ confirmHoverOpen,+ close: hideAndRestoreFocus,setTriggerEl: noopRef,};}@@ -182,6 +374,7 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(onClick: handleClick,onMouseEnter: handleMouseEnter,onMouseLeave: handleMouseLeave,+ ...(popoverId ? {popoverTarget: popoverId} : null),},contentProps: {onMouseEnter: handleContentMouseEnter,@@ -190,6 +383,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(},menuRef,focusFirst,+ focusMenu,+ confirmHoverOpen,+ close: hideAndRestoreFocus,setTriggerEl: setTriggerRef,};}