Skip to content

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.md
new file mode 100644
index 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)
+
+@cixzhang
diff --git a/internal/test-utils/src/setup.ts b/internal/test-utils/src/setup.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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({
<button
type="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({
<button
type="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.tsx
index 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 icons
diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsx
index 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.tsx
index 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({
<button
type="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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.ts
index 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 opens
const 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 mode
const 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 hide
const 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,
};
}