Skip to content

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

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

'use client';

/**
 * @file useHoverCard.ts
 * @input Uses useLayer, useTouchTrigger, React hooks
 * @output Exports useHoverCard hook with stable trigger refs for hover/focus/tap layers
 * @position Layer hook; builds on useLayer for hover card behavior
 *
 * SYNC: When modified, update:
 * - /packages/core/src/HoverCard/index.ts
 */

import {
  useCallback,
  useEffect,
  useRef,
  useState,
  type ReactNode,
  type RefCallback,
} from 'react';
import {createTriggerFocusGate} from '../utils/triggerFocus';
import * as stylex from '@stylexjs/stylex';
import {
  useLayer,
  type ContextRenderProps,
  type LayerAlignment,
  type LayerPlacement,
} from '../Layer/useLayer';
import {
  useTouchTrigger,
  type LayerTouchTrigger,
} from '../Layer/useTouchTrigger';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import {registerLayerSurface} from '../Layer/layerSurfacePress';
import {useKeyedLayerDismissal} from '../Layer/useLayerDismissal';
import {
  colorVars,
  shadowVars,
  radiusVars,
  spacingVars,
} from '../theme/tokens.stylex';
import {themeProps} from '../utils/themeProps';

const styles = stylex.create({
  // Base container styles passed to useLayer
  container: {
    backgroundColor: colorVars['--color-background-surface'],
    '--_hovercard-radius': radiusVars['--radius-container'],
    borderRadius: 'var(--_hovercard-radius)',
    boxShadow: shadowVars['--shadow-med'],
  },
  // Content wrapper for padding and interaction events.
  content: {
    display: 'block',
    paddingBlockStart: spacingVars['--spacing-3'],
    paddingBlockEnd: spacingVars['--spacing-3'],
    paddingInlineStart: spacingVars['--spacing-3'],
    paddingInlineEnd: spacingVars['--spacing-3'],
  },
});

/**
 * The card lives in its trigger's document, which can be an iframe or a
 * Picture-in-Picture window rather than this page.
 */
function ownerDocumentOf(el: HTMLElement | null): Document | null {
  if (el != null) {
    return el.ownerDocument;
  }
  return typeof document === 'undefined' ? null : document;
}

/**
 * When focus on the trigger opens the hover card
 */
export type HoverCardFocusTrigger = 'auto' | 'always' | 'never';

/**
 * Touch trigger behavior for hover cards
 */
export type HoverCardTouchTrigger = LayerTouchTrigger;

export interface HoverCardOptions {
  /**
   * Position placement relative to anchor
   * @default 'above'
   */
  placement?: LayerPlacement;

  /**
   * Alignment along the placement axis
   * @default 'center'
   */
  alignment?: LayerAlignment;

  /**
   * Delay before showing on hover (ms)
   * @default 300
   */
  delay?: number;

  /**
   * Delay before hiding after mouse/focus leave (ms)
   * @default 200
   */
  hideDelay?: number;

  /**
   * When to trigger on focus:
   * - `auto`: focus on the trigger itself, or within a trigger that is
   *   focusable when focus arrives
   * - `always`: focus on the trigger or anything inside it
   * - `never`: never on focus (for composite widgets)
   *
   * @default 'auto'
   */
  focusTrigger?: HoverCardFocusTrigger;

  /**
   * What a tap does on a touch pointer, where there is no hover:
   * - `auto`: tap opens the card, unless the trigger performs an action of its
   *   own (a button, a link, a form control) — that tap belongs to the control
   * - `tap`: tap always opens the card, even on a trigger that acts
   * - `none`: touch never opens the card
   *
   * @default 'auto'
   */
  touchTrigger?: HoverCardTouchTrigger;

  /**
   * Whether the hover card is enabled.
   * When false, hover/focus triggers are disabled.
   *
   * @default true
   */
  isEnabled?: boolean;

  /**
   * Accessible name for the hover card popup.
   *
   * When provided, the popup is exposed to assistive technology as a named
   * `role="dialog"`. When omitted, the popup falls back to `role="group"` —
   * a group may validly be unnamed, an unnamed dialog may not.
   */
  label?: string;

  /**
   * Controlled open state. When provided, overrides the hover trigger:
   * - `true`: force-show the hover card (hover/focus hide is suppressed)
   * - `false`: hide the hover card and keep hover and focus from opening it
   * - `undefined`: uncontrolled — hover/focus triggers manage visibility
   *
   * A controlled hover card still takes Escape when it is the top-most layer,
   * and answers by calling `onHide` without hiding itself — closing is your
   * update's decision, exactly as for a controlled Dialog. Ignore the call and
   * the card stays, and so does the press: nothing underneath dismisses.
   */
  isOpen?: boolean;

  /**
   * Whether the hover card should be shown on mount.
   * The hover card is still dismissible — this just opens it initially.
   */
  isDefaultOpen?: boolean;

  /**
   * Callback fired when hover card is shown.
   * Wrap in useCallback for stable identity.
   */
  onShow?: () => void;

  /**
   * Callback fired when hover card is hidden.
   * Wrap in useCallback for stable identity.
   */
  onHide?: () => void;
}

export interface HoverCardReturn {
  /**
   * Combined ref that sets both position and interaction on the same element.
   * Shorthand for calling both positionRef and interactionRef.
   */
  ref: RefCallback<HTMLElement>;

  /**
   * Ref for the positioning anchor element.
   * While the layer is shown, and until its exit animation ends, the trigger
   * carries the layer's CSS anchor name.
   */
  positionRef: RefCallback<HTMLElement>;

  /**
   * Ref for the interaction element.
   * Attaches hover/focus event listeners via addEventListener.
   * Can be the same element as positionRef or different.
   */
  interactionRef: RefCallback<HTMLElement>;

  /**
   * The CSS anchor name to use for positioning.
   * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
   * Set it only while the layer is shown or its exit animation runs.
   */
  anchorId: string;

  /**
   * Unique ID for the hover card container.
   * Useful for `aria-controls` or `aria-owns` on the trigger.
   */
  id: string;

  /**
   * Deprecated alias of `id`. Kept for backwards compatibility; prefer `id`.
   */
  describedBy: string;

  /**
   * Whether the hover card is currently open.
   * Useful for driving `aria-expanded` on the trigger — but only when the
   * trigger's role permits it (`button`, `link`, `combobox`, …). A role-less
   * trigger supports neither `aria-expanded` nor `aria-haspopup`; name the
   * open card through `aria-controls` alone there.
   */
  isOpen: boolean;

  /**
   * Render function for hover card content.
   * Returns anchor-positioned popover element.
   *
   * `positioning` is excluded: the hover card always derives its position
   * from placement/alignment, so accepting the custom opt-out here would be
   * a silent no-op.
   */
  renderHoverCard: (
    children: ReactNode,
    props?: Omit<ContextRenderProps, 'positioning'>,
  ) => ReactNode;

  /**
   * Imperatively show the hover card (bypassing hover delay).
   */
  show: () => void;

  /**
   * Imperatively hide the hover card.
   */
  hide: () => void;
}

/**
 * Hook for hover card behavior with hover/focus triggers.
 *
 * Builds on useLayer to add:
 * - Hover triggers with configurable delay
 * - Focus triggers with auto-detection for focusable elements
 * - Stay-open behavior when mouse/focus moves into the hover card
 *
 * @example
 * ```
 * const hoverCard = useHoverCard({ placement: 'above' });
 * <Button ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>
 *   Hover me
 * </Button>
 * {hoverCard.renderHoverCard(<ProfileCard user={user} />)}
 * ```
 */

export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
  const {
    placement = 'above',
    alignment = 'center',
    delay = 300,
    hideDelay = 200,
    focusTrigger = 'auto',
    touchTrigger = 'auto',
    isEnabled = true,
    label,
    isOpen,
    isDefaultOpen = false,
    onShow,
    onHide,
  } = options;

  const layer = useLayer({
    mode: 'context',
    lazyMount: true,
    onShow,
    onHide,
  });
  // Destructure the layer and touch objects once: both are rebuilt every
  // render, but their members are stable. Depending on the members instead of
  // the enclosing objects keeps the refs below identity-stable across
  // unchanged rerenders, so React never detaches and re-attaches the trigger
  // (and never rewrites the trigger's `anchor-name`) while the card streams
  // alongside it.
  const {
    ref: layerRef,
    anchorId: layerAnchorId,
    show: showLayer,
    hide: hideLayer,
    isOpen: isLayerOpen,
    id: layerId,
    render: renderLayer,
  } = layer;

  const popoverXstyle = styles.container;

  const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const triggerRef = useRef<HTMLElement | null>(null);
  // The dismissal stack listens in the document a layer registers with, so
  // the card registers when its trigger attaches, and again when the trigger
  // attaches in another document. The key counts those documents.
  const triggerDocumentRef = useRef<Document | null>(null);
  const [triggerDocumentKey, setTriggerDocumentKey] = useState(0);
  const isHoveringContentRef = useRef(false);
  // Track when we're dismissing via Escape to prevent re-show on refocus
  const isEscapeDismissingRef = useRef(false);

  // Clear all timeouts
  const clearTimeouts = useCallback(() => {
    if (showTimeoutRef.current) {
      clearTimeout(showTimeoutRef.current);
      showTimeoutRef.current = null;
    }
    if (hideTimeoutRef.current) {
      clearTimeout(hideTimeoutRef.current);
      hideTimeoutRef.current = null;
    }
  }, []);

  // Touch resolves immediately: the hover delays exist to filter out a pointer
  // passing across the trigger, and a tap is never that.
  const showNow = useCallback(() => {
    clearTimeouts();
    showLayer();
  }, [clearTimeouts, showLayer]);

  const hideNow = useCallback(() => {
    clearTimeouts();
    isHoveringContentRef.current = false;
    hideLayer();
  }, [clearTimeouts, hideLayer]);

  // The imperative hide. A card closed while the pointer rests on it unmounts
  // without a mouseleave, so the content-hover latch is cleared here; left set,
  // it would keep the trigger's next hover-open from closing on leave.
  const hide = useCallback(() => {
    isHoveringContentRef.current = false;
    hideLayer();
  }, [hideLayer]);

  const {
    isTouchPointerRef,
    isTouchInteraction,
    handlePointerEnter,
    handlePointerDown: handleTouchPointerDown,
    clearTapOpen,
  } = useTouchTrigger({
    touchTrigger,
    isEnabled,
    isControlled: isOpen !== undefined,
    isOpen: isLayerOpen,
    layerId: layerId,
    triggerRef,
    show: showNow,
    hide: hideNow,
  });

  // Schedule show with delay (suppressed when isOpen is false)
  const scheduleShow = useCallback(() => {
    if (!isEnabled || isOpen === false) {
      return;
    }
    clearTimeouts();
    showTimeoutRef.current = setTimeout(() => {
      showLayer();
    }, delay);
  }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);

  // Schedule hide with delay (suppressed when isOpen is true)
  const scheduleHide = useCallback(() => {
    if (isOpen === true) {
      return;
    }
    clearTimeouts();
    hideTimeoutRef.current = setTimeout(() => {
      // Don't hide if hovering content
      if (!isHoveringContentRef.current) {
        hideLayer();
      }
    }, hideDelay);
  }, [isOpen, clearTimeouts, hideLayer, hideDelay]);

  // Event handlers
  const handleMouseEnter = useCallback(() => {
    // A tap synthesizes mouseenter. On touch the tap path owns the decision,
    // so hover must not also fire — without this a hover card opens on every
    // tap of its trigger and has nothing to close it.
    if (isTouchPointerRef.current) {
      return;
    }
    scheduleShow();
  }, [isTouchPointerRef, scheduleShow]);

  const handleMouseLeave = useCallback(() => {
    // On touch the synthesized mouseleave arrives with the next tap elsewhere,
    // which the outside-tap dismissal already handles.
    if (isTouchPointerRef.current) {
      return;
    }
    scheduleHide();
  }, [isTouchPointerRef, scheduleHide]);

  // Tap-to-open on touch; on a mouse this does nothing and hover still rules.
  const handlePointerDown = useCallback(
    (event: PointerEvent) => {
      // A pen in range starts the hover show before it lands. Left pending,
      // that show opens the card during the press. The tap then closes it.
      if (handleTouchPointerDown(event) && showTimeoutRef.current) {
        clearTimeout(showTimeoutRef.current);
        showTimeoutRef.current = null;
      }
    },
    [handleTouchPointerDown],
  );

  // Under `auto`, whether focus counts is decided when it arrives, and a
  // focus that counted still hides on blur (utils/triggerFocus.ts).
  const [focusGate] = useState(createTriggerFocusGate);

  const handleFocusIn = useCallback(
    (e: Event) => {
      if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
        return;
      }
      // A tap focuses the trigger it activates. Opening on that focus would
      // reinstate exactly the behavior the touch path just decided against —
      // and on an action trigger it covers the thing the user tapped.
      if (isTouchInteraction()) {
        return;
      }
      // Skip showing if we're in the middle of an Escape dismiss
      if (isEscapeDismissingRef.current) {
        isEscapeDismissingRef.current = false;
        return;
      }
      // The caller owns a controlled `false`, so no focus opens the card.
      if (isOpen === false) {
        return;
      }
      clearTimeouts();
      showLayer();
    },
    [
      focusGate,
      focusTrigger,
      isEnabled,
      isOpen,
      isTouchInteraction,
      clearTimeouts,
      showLayer,
    ],
  );

  const handleFocusOut = useCallback(
    (e: FocusEvent) => {
      if (!focusGate.focusOut(e, focusTrigger)) {
        return;
      }
      // Check if focus is moving to the hover card content
      const relatedTarget = e.relatedTarget as HTMLElement | null;
      const popoverElement = ownerDocumentOf(
        triggerRef.current,
      )?.getElementById(layerId);

      if (popoverElement?.contains(relatedTarget)) {
        // Focus moving into hover card, keep it open
        return;
      }

      scheduleHide();
    },
    [focusGate, focusTrigger, layerId, scheduleHide],
  );

  // Escape dismissal (WCAG 1.4.13) goes through the shared layer stack: a
  // visible card is the top-most layer, so it takes the press and consumes it.
  //
  // This replaces a keydown listener on the TRIGGER that called
  // stopPropagation() on any Escape while the trigger merely had focus — open
  // card or not — so focusing a HoverCard trigger inside a Dialog silently ate
  // the press that should have closed the Dialog. Presence is now answered from
  // the DOM, so a closed card never claims a press.
  // A controlled hover card stays on the stack and takes the press like any
  // other layer, but answers it by reporting instead of hiding: `isOpen` is
  // the consumer's value, so only their update may change it. Same contract as
  // a controlled Dialog.
  useKeyedLayerDismissal(
    {
      // Registered from the trigger's attach for the hook's lifetime, in the
      // trigger's document, rather than gated on `layer.isOpen`:
      // that state can lag a frame behind the DOM, so a press arriving right after
      // the layer appears would find nothing registered. Because this layer
      // CONSUMES the press, a stale registration would be worse than a missed one
      // — it would silently eat Escapes meant for the dialog underneath — so
      // presence is answered from the DOM at press time instead of from state.
      isActive: triggerDocumentKey > 0,
      // The stack listens for Escape in the trigger's own document, which may be
      // an iframe or a Picture-in-Picture window rather than this page.
      getContainer: () => triggerRef.current,
      isPresent: () => {
        const el = ownerDocumentOf(triggerRef.current)?.getElementById(layerId);
        if (el == null) {
          return false;
        }
        try {
          return el.matches(':popover-open');
        } catch {
          // Browsers without the Popover API (and some test environments) cannot
          // answer the selector; fall back to the hook's own state.
          return isLayerOpen;
        }
      },
      onDismiss: () => {
        clearTimeouts();
        clearTapOpen();
        // Controlled: report and stop. The close — and the focus restore that
        // goes with it — happens in the controlled effect if and when the
        // consumer flips `isOpen`.
        if (isOpen !== undefined) {
          onHide?.();
          return;
        }
        // Only when the card itself held focus, which is the one case the
        // content-level handler this replaced could run in. Refocusing
        // unconditionally would drag the caret out of a field the user was
        // typing in while a hover card happened to be up; arming the re-show
        // guard unconditionally would swallow their next focus on the trigger,
        // because a focus() on the already-focused trigger fires no focusin to
        // clear it.
        const doc = ownerDocumentOf(triggerRef.current);
        const card = doc?.getElementById(layerId);
        const hadFocus = card?.contains(doc?.activeElement ?? null) ?? false;
        hide();
        if (hadFocus) {
          isEscapeDismissingRef.current = true;
          triggerRef.current?.focus();
        }
      },
    },
    triggerDocumentKey,
  );

  // Interaction ref that handles event listeners only
  const interactionRef: RefCallback<HTMLElement> = useCallback(
    (el: HTMLElement | null) => {
      // Cleanup previous element
      if (triggerRef.current) {
        triggerRef.current.removeEventListener('mouseenter', handleMouseEnter);
        triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
        triggerRef.current.removeEventListener('focusin', handleFocusIn);
        triggerRef.current.removeEventListener(
          'focusout',
          handleFocusOut as EventListener,
        );
        triggerRef.current.removeEventListener(
          'pointerenter',
          handlePointerEnter,
        );
        triggerRef.current.removeEventListener(
          'pointerdown',
          handlePointerDown,
        );
      }

      if (el) {
        // Attach hover listeners. `pointerenter` runs before the synthesized
        // `mouseenter` a tap produces, which is what lets the hover path know
        // it is looking at a finger.
        el.addEventListener('pointerenter', handlePointerEnter);
        el.addEventListener('mouseenter', handleMouseEnter);
        el.addEventListener('mouseleave', handleMouseLeave);
        el.addEventListener('pointerdown', handlePointerDown);

        // Focus listeners unless focus never opens the card; `auto` decides
        // per event (utils/triggerFocus.ts).
        if (focusTrigger !== 'never') {
          el.addEventListener('focusin', handleFocusIn);
          el.addEventListener('focusout', handleFocusOut as EventListener);
        }
      }

      triggerRef.current = el;
      if (el != null && el.ownerDocument !== triggerDocumentRef.current) {
        triggerDocumentRef.current = el.ownerDocument;
        setTriggerDocumentKey(key => key + 1);
      }
    },
    [
      focusTrigger,
      handleMouseEnter,
      handleMouseLeave,
      handleFocusIn,
      handleFocusOut,
      handlePointerEnter,
      handlePointerDown,
    ],
  );

  // Combined ref - shorthand for calling both positionRef and interactionRef
  const ref: RefCallback<HTMLElement> = useCallback(
    (el: HTMLElement | null) => {
      layerRef(el);
      interactionRef(el);
    },
    [layerRef, interactionRef],
  );

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

  // Show on mount when isDefaultOpen is true
  useEffect(() => {
    if (isDefaultOpen) {
      showLayer();
    }
    // eslint-disable-next-line @eslint-react/exhaustive-deps -- intentionally only on mount
  }, []);

  // Syncs the layer with the controlled `isOpen`. A close moves focus back to
  // the trigger when the card holds it.
  useEffect(() => {
    if (isOpen === undefined) {
      return;
    }
    if (isOpen) {
      clearTimeouts();
      showLayer();
    } else {
      clearTimeouts();
      // A consumer closing the card while it holds focus would strand focus on
      // <body>. Arming the re-show guard is what keeps the refocus from
      // reopening the card through `handleFocusIn`, which shows on any focusin.
      const doc = ownerDocumentOf(triggerRef.current);
      const card = doc?.getElementById(layerId);
      const hadFocus = card?.contains(doc?.activeElement ?? null) ?? false;
      hideLayer();
      if (hadFocus) {
        isEscapeDismissingRef.current = true;
        triggerRef.current?.focus();
      }
    }
  }, [isOpen, clearTimeouts, showLayer, hideLayer, layerId]);

  // Render function that wraps layer.render with hover card behavior
  const renderHoverCard = useCallback(
    (
      children: ReactNode,
      props?: Omit<ContextRenderProps, 'positioning'>,
    ): ReactNode => {
      const renderPlacement = props?.placement ?? placement;
      const themeClassName = themeProps('hover-card').className;
      const renderProps = {
        placement: renderPlacement,
        alignment: props?.alignment ?? alignment,
        offset: spacingVars['--spacing-1'],
        // A named dialog when a label is provided; otherwise a group. A group
        // may validly be unnamed, an unnamed dialog may not — and hover cards
        // are non-modal, so group is honest semantics without a name.
        role: label ? 'dialog' : 'group',
        'aria-label': label || undefined,
        // Consumer surface style props land on the layer container — the
        // themed surface (bg/radius/shadow) where the theme class lives — so
        // customizing the card targets the same element as the theme. The inner
        // div keeps `styles.content` for padding.
        xstyle: [
          popoverXstyle,
          layerAnimations[renderPlacement],
          props?.xstyle,
        ],
        className: props?.className
          ? `${themeClassName} ${props.className}`
          : themeClassName,
        style: props?.style,
        // useLayer mounts only after it has verified or corrected the parent,
        // so rich HoverCard content can use block-safe markup.
        as: 'div' as const,
      };

      return renderLayer(
        <div
          // FR11: a press inside the card acts only within the card. A
          // registered surface counts as something else in the shared
          // interactive-ancestor walk, so a clickable container around the
          // trigger leaves it alone; document listeners still see it.
          ref={registerLayerSurface}
          {...stylex.props(styles.content)}
          onMouseEnter={() => {
            // Touch synthesizes these over the card too; letting a tap inside
            // register as "hovering content" would block every later hide.
            if (isTouchPointerRef.current) {
              return;
            }
            isHoveringContentRef.current = true;
            clearTimeouts();
          }}
          onMouseLeave={() => {
            if (isTouchPointerRef.current) {
              return;
            }
            isHoveringContentRef.current = false;
            scheduleHide();
          }}
          onBlur={e => {
            // Check if focus is moving back to the trigger or staying within content
            const relatedTarget = e.relatedTarget as HTMLElement | null;
            const popoverElement = e.currentTarget;

            // If focus stays within the hover card, do nothing
            if (popoverElement.contains(relatedTarget)) {
              return;
            }

            // If focus is moving back to the trigger, do nothing
            if (triggerRef.current?.contains(relatedTarget)) {
              return;
            }

            // Focus is leaving the hover card entirely
            scheduleHide();
          }}>
          {children}
        </div>,
        renderProps,
      );
    },
    [
      renderLayer,
      placement,
      alignment,
      label,
      clearTimeouts,
      scheduleHide,
      popoverXstyle,
      isTouchPointerRef,
    ],
  );

  return {
    ref,
    positionRef: layerRef,
    interactionRef,
    anchorId: layerAnchorId,
    id: layerId,
    describedBy: layerId,
    isOpen: isLayerOpen,
    renderHoverCard,
    show: showLayer,
    hide,
  };
}