Skip to content

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

TypeScript
17.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useMenuHover.ts
 * @input React hooks, useListFocus, useMediaQuery
 * @output useMenuHover hook
 * @position Internal hook for nav heading components, TopNavMenu,
 *   TopNavMegaMenu and DropdownMenuSubMenu
 */

// Hover adds to the standard popover behavior. A click toggles, Escape and an
// outside click close, and arrows navigate. Also, mouseenter opens after a
// delay, and mouseleave closes a menu that hover opened.
//
// - A hover-opened menu is open when the click that follows arrives. Within
//   `clickGuardMs`, that click pins the menu and does not close it.
// - Focus moves synchronously. `useLayer.show()` shows the popover in the
//   same tick, and the items are always mounted. A frame delay lands after
//   paint and races other focus moves. A hover open keeps focus on the
//   trigger.
// - The hook passes `skipAutoFocus` and moves focus itself. Popover
//   auto-focus goes to the first tabbable node, but under roving tabindex a
//   menu wants its first item.
// - The browser light-dismisses a `popover="auto"` on a pointer press
//   outside the panel, also on the trigger. `popoverId` makes the trigger the
//   panel's invoker, which exempts it. jsdom has neither feature, so only a
//   browser can test this.

import {useCallback, useEffect, useRef} from 'react';
import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
import {useListFocus} from './useListFocus';
import {useMediaQuery} from './useMediaQuery';
import {focusForLastInput} from '../utils/focusReturn';

const DEFAULT_CLICK_GUARD_MS = 500;

/**
 * How long after a close a mouseenter on the trigger is ignored. A panel over
 * its own trigger puts the trigger back under a still pointer when it closes,
 * and the browser fires a new mouseenter. A time limit, not a one-shot flag,
 * lets a later re-hover open the menu. A real mouseleave clears it early.
 */
const REOPEN_SUPPRESS_MS = 300;

/**
 * Slack added to the flyout's near edge when building the safe triangle, so a
 * pointer skimming the edge's corners still counts as heading for the flyout.
 */
const SAFE_TRIANGLE_PADDING_PX = 8;

interface Point {
  x: number;
  y: number;
}

interface EdgeRect {
  top: number;
  bottom: number;
  left: number;
  right: number;
}

function sign(p1: Point, p2: Point, p3: Point): number {
  return (p1.x - p3.x) * (p2.y - p3.y) - (p2.x - p3.x) * (p1.y - p3.y);
}

function isPointInTriangle(p: Point, a: Point, b: Point, c: Point): boolean {
  const d1 = sign(p, a, b);
  const d2 = sign(p, b, c);
  const d3 = sign(p, c, a);
  const hasNegative = d1 < 0 || d2 < 0 || d3 < 0;
  const hasPositive = d1 > 0 || d2 > 0 || d3 > 0;
  return !(hasNegative && hasPositive);
}

/**
 * Whether `point` lies inside the safe triangle from `origin` (where the
 * pointer left the trigger row) to the flyout's NEAR edge — the edge of
 * `flyout` facing the origin. A pointer travelling inside it is heading for
 * the flyout, so the flyout must stay open. Exported for unit tests.
 */
export function isPointInSafeTriangle(
  point: Point,
  origin: Point,
  flyout: EdgeRect,
): boolean {
  const pad = SAFE_TRIANGLE_PADDING_PX;
  let edgeStart: Point;
  let edgeEnd: Point;
  if (origin.x <= flyout.left) {
    edgeStart = {x: flyout.left, y: flyout.top - pad};
    edgeEnd = {x: flyout.left, y: flyout.bottom + pad};
  } else if (origin.x >= flyout.right) {
    edgeStart = {x: flyout.right, y: flyout.top - pad};
    edgeEnd = {x: flyout.right, y: flyout.bottom + pad};
  } else if (origin.y <= flyout.top) {
    edgeStart = {x: flyout.left - pad, y: flyout.top};
    edgeEnd = {x: flyout.right + pad, y: flyout.top};
  } else if (origin.y >= flyout.bottom) {
    edgeStart = {x: flyout.left - pad, y: flyout.bottom};
    edgeEnd = {x: flyout.right + pad, y: flyout.bottom};
  } else {
    // The origin is over the flyout itself: nothing to travel toward.
    return false;
  }
  return isPointInTriangle(point, origin, edgeStart, edgeEnd);
}

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;
  /**
   * The flyout element, for consumers that manage their own list and do not
   * attach the hook's `menuRef`. The safe triangle toward the flyout's near
   * edge is built from it; without it the triangle is off.
   */
  flyoutRef?: React.RefObject<HTMLElement | null>;
}

export interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
  triggerProps: {
    onClick: (event?: React.MouseEvent) => void;
    onMouseEnter: () => void;
    /**
     * Pass the event through: the pointer's position when it leaves the
     * trigger is the apex of the safe triangle toward the flyout.
     */
    onMouseLeave: (event?: React.MouseEvent) => void;
    /** Present only when `popoverId` is supplied. */
    popoverTarget?: string;
  };
  contentProps: {
    onMouseEnter: () => void;
    onMouseLeave: (event?: React.MouseEvent) => void;
    onKeyDown: (e: React.KeyboardEvent) => void;
  };
  menuRef: React.RefObject<T | null>;
  /** 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;
}

export function useMenuHover<T extends HTMLElement = HTMLElement>(
  options: UseMenuHoverOptions,
): UseMenuHoverReturn<T> {
  const {
    show,
    hide,
    isOpen,
    isEnabled,
    showDelay = 150,
    hideDelay = 200,
    clickGuardMs = DEFAULT_CLICK_GUARD_MS,
    itemSelector,
    popoverId,
    ownsFocus = true,
    flyoutRef,
  } = options;

  const hasHover = useMediaQuery('(hover: hover)');

  const showTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const triggerElRef = useRef<HTMLElement | null>(null);
  /** Removes the document pointer listener that watches the safe triangle. */
  const safeTriangleCleanupRef = useRef<(() => void) | null>(null);
  /** Menu was hover-opened, so mouseleave may close it. */
  const hoverModeRef = 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);

  const clearTimeouts = useCallback(() => {
    if (showTimerRef.current) {
      clearTimeout(showTimerRef.current);
      showTimerRef.current = null;
    }
    if (hideTimerRef.current) {
      clearTimeout(hideTimerRef.current);
      hideTimerRef.current = null;
    }
    safeTriangleCleanupRef.current?.();
    safeTriangleCleanupRef.current = null;
  }, []);

  // 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) {
      // Cancel a hover-open that was scheduled before the close. Otherwise it
      // reopens a menu that closed from elsewhere, such as a submenu flyout
      // that the root menu light-dismissed. A new mouseenter still opens.
      clearTimeouts();
      hoverModeRef.current = false;
      hoverOpenedAtRef.current = 0;
      closedAtRef.current = Date.now();
    }
  }, [isOpen, clearTimeouts]);

  // 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>({
    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();
    const trigger = triggerElRef.current;
    if (menuHadFocus && trigger != null) {
      // A pointer pick leaves no keyboard ring on the trigger. A keyboard pick
      // keeps it.
      focusForLastInput(trigger);
    }
  }, [hide, menuRef]);

  // A menu placed in the content can own its own list keys (NavHeadingMenu
  // runs useListFocus over the same `menuitem`s); a key it consumed must not
  // move focus a second time here as it bubbles out (APG menu: one item per
  // arrow press).
  const handleContentKeyDown = useCallback(
    (event: React.KeyboardEvent) => {
      if (event.defaultPrevented) {
        return;
      }
      handleListKeyDown(event);
    },
    [handleListKeyDown],
  );

  useEffect(() => {
    escapeHandlerRef.current = () => {
      clearTimeouts();
      hideAndRestoreFocus();
    };
  }, [clearTimeouts, hideAndRestoreFocus]);

  // Releases the hover timers on unmount.
  useEffect(() => {
    return () => clearTimeouts();
  }, [clearTimeouts]);

  // A trigger disabled while a hover is in flight must stay closed. Returning
  // inert handlers below is not enough on its own: the open this hover already
  // scheduled would still fire, and it would open a surface whose handlers can
  // no longer close it.
  useEffect(() => {
    if (!isEnabled) {
      clearTimeouts();
    }
  }, [isEnabled, clearTimeouts]);

  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();
      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;
    }
    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 and Space arrive as a click with detail 0, and always open. A
      // keyboard user reaches the trigger of an open menu only when a
      // hover-open left focus there. A close would leave 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,
    ],
  );

  const handleMouseEnter = useCallback(() => {
    if (!hasHover) {
      return;
    }
    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(openByHover, showDelay);
    } else {
      openByHover();
    }
  }, [hasHover, isOpen, clearTimeouts, show, showDelay]);

  const handleMouseLeave = useCallback(
    (event?: React.MouseEvent) => {
      // 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;
      }
      clearTimeouts();
      // Where the pointer was last seen, so the delay can ask whether it is
      // still heading for the flyout rather than only reacting to movement.
      let lastPoint: Point | null = null;
      let isTracking = false;
      let isInside: (point: Point) => boolean = () => false;
      const scheduleHide = () => {
        if (hideTimerRef.current) {
          clearTimeout(hideTimerRef.current);
        }
        hideTimerRef.current = setTimeout(() => {
          // A pointer that stops mid-diagonal is still heading for the
          // flyout. Restart the delay, and do not close under it. The first
          // move outside the triangle ends this.
          if (isTracking && lastPoint != null && isInside(lastPoint)) {
            scheduleHide();
            return;
          }
          hide();
        }, hideDelay);
      };
      scheduleHide();

      // The safe triangle: while the pointer travels from where it left
      // the trigger toward the flyout's near edge, it is heading for the
      // flyout, and every move inside the triangle restarts the hide delay.
      // The first move outside it lets the delay run out.
      const menu = flyoutRef?.current ?? menuRef.current;
      const apex: Point | null =
        event != null ? {x: event.clientX, y: event.clientY} : null;
      if (menu == null || apex == null || !isOpen) {
        return;
      }
      const rect = menu.getBoundingClientRect();
      if (rect.width <= 0 || rect.height <= 0) {
        return;
      }
      const doc = menu.ownerDocument;
      isInside = point => isPointInSafeTriangle(point, apex, rect);
      isTracking = true;
      lastPoint = apex;
      const onPointerMove = (move: PointerEvent) => {
        const point = {x: move.clientX, y: move.clientY};
        lastPoint = point;
        if (isInside(point)) {
          scheduleHide();
          return;
        }
        isTracking = false;
        safeTriangleCleanupRef.current?.();
        safeTriangleCleanupRef.current = null;
      };
      doc.addEventListener('pointermove', onPointerMove, true);
      safeTriangleCleanupRef.current = () => {
        doc.removeEventListener('pointermove', onPointerMove, true);
      };
    },
    [clearTimeouts, hide, hideDelay, isOpen, menuRef, flyoutRef],
  );

  const handleContentMouseEnter = useCallback(() => {
    clearTimeouts();
  }, [clearTimeouts]);

  const setTriggerRef = useCallback((el: HTMLElement | null) => {
    triggerElRef.current = el;
  }, []);

  const noop = useCallback(() => {}, []);
  const noopRef = useCallback((_el: HTMLElement | null) => {}, []);
  const noopKeyDown = useCallback((_e: React.KeyboardEvent) => {}, []);

  if (!isEnabled) {
    return {
      triggerProps: {onClick: noop, onMouseEnter: noop, onMouseLeave: noop},
      contentProps: {
        onMouseEnter: noop,
        onMouseLeave: noop,
        onKeyDown: noopKeyDown,
      },
      menuRef,
      focusFirst,
      focusMenu,
      confirmHoverOpen,
      close: hideAndRestoreFocus,
      setTriggerEl: noopRef,
    };
  }

  return {
    triggerProps: {
      onClick: handleClick,
      onMouseEnter: handleMouseEnter,
      onMouseLeave: handleMouseLeave,
      ...(popoverId ? {popoverTarget: popoverId} : null),
    },
    contentProps: {
      onMouseEnter: handleContentMouseEnter,
      onMouseLeave: handleMouseLeave,
      onKeyDown: handleContentKeyDown,
    },
    menuRef,
    focusFirst,
    focusMenu,
    confirmHoverOpen,
    close: hideAndRestoreFocus,
    setTriggerEl: setTriggerRef,
  };
}