Skip to content

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

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

'use client';

/**
 * @file useTooltip.tsx
 * @input Uses useLayer, useTouchTriggerInternal, React hooks
 * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
 *   and imperative show() and hide() for an app-built toggle trigger
 * @position Layer hook; builds on useLayer for tooltip behavior
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Tooltip/index.ts
 */

import {
  use,
  useCallback,
  useEffect,
  useRef,
  useState,
  type ReactNode,
  type RefCallback,
} from 'react';
import {TooltipPresentInterestContext} from './tooltipPresentInterest';
import {createTriggerFocusGate, isFocusOnTrigger} from '../utils/triggerFocus';
import * as stylex from '@stylexjs/stylex';
import {
  useLayerInternal,
  type ContextRenderProps,
  type LayerAlignment,
  type LayerPlacement,
} from '../Layer/useLayer';
import {
  useTouchTriggerInternal,
  type LayerTouchTrigger,
} from '../Layer/useTouchTrigger';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import {registerLayerSurface} from '../Layer/layerSurfacePress';
import {noteOutsideDismissal} from '../Layer/outsidePress';
import {useLayerDismissal} from '../Layer/useLayerDismissal';
import {themeProps} from '../utils/themeProps';
import {
  colorVars,
  radiusVars,
  spacingVars,
  typographyVars,
  typeScaleVars,
} from '../theme/tokens.stylex';

/**
 * Grace period (ms) before hiding on pointer-leave when no explicit `hideDelay`
 * is set, so the pointer can travel across the small gap from the trigger onto
 * the tooltip surface without the tooltip disappearing (WCAG 1.4.13 hoverable).
 */
const HOVER_BRIDGE_DELAY = 100;

const styles = stylex.create({
  // Base container styles - inverted colors for high contrast
  container: {
    // Inverted color palette: dark background, light text
    backgroundColor: colorVars['--color-text-primary'],
    color: colorVars['--color-background-surface'],
    borderRadius: radiusVars['--radius-container'],
    // Typography
    fontFamily: typographyVars['--font-family-body'],
    fontSize: typeScaleVars['--text-body-size'],
    lineHeight: typeScaleVars['--text-body-leading'],
  },
  // Position-based margin styles
  // Content wrapper for padding
  content: {
    paddingBlockStart: spacingVars['--spacing-1'],
    paddingBlockEnd: spacingVars['--spacing-1'],
    paddingInlineStart: spacingVars['--spacing-2'],
    paddingInlineEnd: spacingVars['--spacing-2'],
    maxWidth: 300,
    wordBreak: 'break-word',
  },
});

/**
 * Focus trigger behavior for tooltips
 */
export type TooltipFocusTrigger = 'auto' | 'always' | 'never';

/**
 * Touch trigger behavior for tooltips
 */
export type TooltipTouchTrigger = LayerTouchTrigger;

export interface TooltipOptions {
  /**
   * 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 200
   */
  delay?: number;

  /**
   * Delay before hiding after mouse/focus leave (ms)
   * @default 0
   */
  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?: TooltipFocusTrigger;

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

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

  /**
   * Controlled open state. When provided, overrides hover/focus triggers:
   * - `true`: force-show the tooltip (hover/focus hide is suppressed)
   * - `false`: force-hide the tooltip. Focus that would show it calls
   *   `onShow` and shows nothing.
   * - `undefined`: uncontrolled — hover/focus triggers manage visibility
   *
   * A controlled tooltip 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 tip stays, and so does the press: nothing underneath dismisses.
   */
  isOpen?: boolean;

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

  /**
   * Callback fired when tooltip is shown. Under `isOpen={false}`, it reports
   * focus that would show the tooltip.
   * Wrap in useCallback for stable identity.
   */
  onShow?: () => void;

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

export interface TooltipReturn {
  /**
   * 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;

  /**
   * ID for aria-describedby on the trigger element.
   * Caller should compose with other IDs using mergeIds utility.
   */
  describedBy: string;

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

  /**
   * Opens the tooltip now and keeps it open until `hide()`, Escape, a press
   * outside, or focus leaving its trigger. If a press on the trigger is down
   * when you call it, and the press ends off the trigger with no click, the
   * hold ends. The hover rules then decide.
   * Its text is announced once. Reports through `onShow`. Under a controlled `isOpen`,
   * it calls `onShow` and does not change `isOpen`. Does nothing while
   * `isEnabled` is false.
   *
   * Use `show()` and `hide()` to build a toggle-style trigger: your own button
   * calls them, sets `aria-describedby` and `aria-controls` to `describedBy`
   * and `aria-expanded` (true while shown), and keeps its own accessible name.
   */
  show: () => void;

  /**
   * Closes the tooltip now. Reports through `onHide`. Under a controlled
   * `isOpen`, it calls `onHide` and does not change `isOpen`.
   */
  hide: () => void;
}

/**
 * Hook for tooltip behavior with hover/focus triggers.
 *
 * Builds on useLayer to add:
 * - Hover triggers with configurable delay
 * - Focus triggers with auto-detection for focusable elements
 * - Tap triggers on touch, where there is no hover (see useTouchTrigger)
 * - Inverted color palette for high contrast
 *
 * Unlike HoverCard, tooltips:
 * - Don't stay open when hovering the tooltip content
 * - Have shorter delays
 * - Use inverted colors (dark background, light text)
 * - Are typically used for short, non-interactive text
 *
 * @example
 * ```
 * const tooltip = useTooltip({ placement: 'above' });
 * <Button ref={tooltip.ref} aria-describedby={tooltip.describedBy}>
 *   Hover me
 * </Button>
 * {tooltip.renderTooltip('Helpful tooltip text')}
 * ```
 */

export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
  const {
    placement = 'above',
    alignment = 'center',
    delay = 200,
    hideDelay = 0,
    focusTrigger = 'auto',
    touchTrigger = 'auto',
    isEnabled = true,
    isOpen,
    isDefaultOpen = false,
    onShow,
    onHide,
  } = options;

  // A tooltip stays open while its trigger is hovered, so it must never settle
  // over the trigger: content taller than the room above and below opens
  // beside it, or on the roomier side sized to that room, and scrolls what does not
  // fit inside the surface, which stays hoverable (spec:AST-059 FR4).
  const layer = useLayerInternal({
    mode: 'context',
    onShow,
    onHide,
    keepsAnchorClear: true,
  });
  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);
  // Set only by a Core component that mounts the tooltip on interaction.
  const presentInterest = use(TooltipPresentInterestContext);
  // Whether the tooltip is enabled now, for a show that runs after a render
  // (a pending hover show) and for the trigger ref callback.
  const isEnabledRef = useRef(isEnabled);
  isEnabledRef.current = isEnabled;
  // Counts the renders in which the tooltip is disabled. A pending show
  // records it, so a show scheduled before a disable is dropped even when
  // the tooltip is enabled again before the timer fires.
  const disabledRendersRef = useRef(0);
  if (!isEnabled) {
    disabledRendersRef.current += 1;
  }

  // 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();
    hideLayer();
  }, [clearTimeouts, hideLayer]);

  // DOM listeners read the latest controlled state through a ref.
  const latestRef = useRef({isOpen, isLayerOpen, onShow, onHide});
  latestRef.current = {isOpen, isLayerOpen, onShow, onHide};

  // The app's show() holds the tooltip open until hide(), Escape, a press or
  // scroll outside, or focus leaving the trigger and the tooltip.
  const isHeldRef = useRef(false);
  const [isHeldState, setIsHeldState] = useState(false);
  const setHeld = useCallback((next: boolean) => {
    isHeldRef.current = next;
    setIsHeldState(next);
  }, []);

  // Whether the current hold began during a press on the trigger. Such a
  // hold ends with the press when the press ends off the trigger, as no click
  // pins it. The hover rules then decide. isHoldInThisTaskRef covers a show()
  // that runs before the hook's own pointerdown listener.
  const isHoldFromPressRef = useRef(false);
  const isHoldInThisTaskRef = useRef(false);
  const handleReleaseInLayer = useCallback(() => {
    if (isHoldFromPressRef.current && isHeldRef.current) {
      isHoldFromPressRef.current = false;
      setHeld(false);
    }
  }, [setHeld]);

  // The touch trigger's outside dismissal (a press or scroll outside) ends a
  // hold with the tooltip.
  const hideFromTouch = useCallback(() => {
    if (isHeldRef.current) {
      setHeld(false);
      const latest = latestRef.current;
      if (latest.isOpen !== undefined) {
        latest.onHide?.();
        return;
      }
    }
    hideNow();
  }, [setHeld, hideNow]);

  const {
    isTouchPointerRef,
    isTouchInteraction,
    handlePointerEnter,
    handlePointerDown: handleTouchPointerDown,
    clearTapOpen,
    armOutsideDismiss,
    answerTap,
  } = useTouchTriggerInternal(
    {
      touchTrigger,
      isEnabled,
      isControlled: isOpen !== undefined,
      isOpen: isLayerOpen,
      layerId,
      triggerRef,
      show: showNow,
      hide: hideFromTouch,
    },
    handleReleaseInLayer,
  );

  const isHeldOpen = useCallback(() => {
    const latest = latestRef.current;
    return isHeldRef.current && latest.isLayerOpen && latest.isOpen !== false;
  }, []);

  const releaseHold = useCallback(() => {
    clearTapOpen();
    setHeld(false);
    const latest = latestRef.current;
    if (latest.isOpen !== undefined) {
      latest.onHide?.();
      return;
    }
    hideNow();
  }, [clearTapOpen, setHeld, hideNow]);

  const dropHold = useCallback(() => {
    if (isHeldRef.current) {
      setHeld(false);
    }
  }, [setHeld]);

  // Focus leaving the trigger and the tooltip ends a hold, whatever
  // `focusTrigger` is. Focus that leaves for no element is a press's to
  // decide. The trigger can sit in another document, so the check uses its
  // own window.
  const handleHeldFocusOut = useCallback(
    (event: FocusEvent) => {
      if (!isHeldOpen()) {
        return;
      }
      const next = event.relatedTarget;
      const trigger = triggerRef.current;
      const view = trigger?.ownerDocument.defaultView;
      if (view == null || !(next instanceof view.Node)) {
        return;
      }
      const surface = trigger?.ownerDocument.getElementById(layerId) ?? null;
      if (
        trigger?.contains(next) === true ||
        surface?.contains(next) === true
      ) {
        return;
      }
      noteOutsideDismissal(view.document);
      releaseHold();
    },
    [isHeldOpen, layerId, releaseHold],
  );

  const isHoldShown = isHeldState && isLayerOpen && isOpen !== false;

  // Only a hold announces the text: a preview is already the trigger's
  // description.
  const contentRef = useRef<HTMLDivElement | null>(null);
  useAnnounceRenderedText(contentRef, isHoldShown, 'pinned');
  const contentRefs = useMergedRefs<HTMLDivElement>(
    contentRef,
    registerLayerSurface,
  );

  // Schedule show with delay (suppressed when isOpen is false)
  const scheduleShow = useCallback(() => {
    if (!isEnabled || isOpen === false) {
      return;
    }
    clearTimeouts();
    const disabledRenders = disabledRendersRef.current;
    showTimeoutRef.current = setTimeout(() => {
      // A show runs only if the tooltip stayed enabled since it was
      // scheduled: nothing would close a tooltip that opens after a disable.
      if (disabledRendersRef.current === disabledRenders) {
        showLayer();
      }
    }, delay);
  }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);

  // Schedule hide with delay (suppressed when isOpen is true).
  // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
  // trigger onto the tooltip surface without the tooltip vanishing — required
  // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
  const scheduleHide = useCallback(() => {
    if (isOpen === true || isHeldOpen()) {
      return;
    }
    clearTimeouts();
    const effectiveHideDelay = hideDelay > 0 ? hideDelay : HOVER_BRIDGE_DELAY;
    hideTimeoutRef.current = setTimeout(() => {
      hideLayer();
    }, effectiveHideDelay);
  }, [isOpen, isHeldOpen, clearTimeouts, hideLayer, hideDelay]);

  // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
  const cancelHide = useCallback(() => {
    if (hideTimeoutRef.current) {
      clearTimeout(hideTimeoutRef.current);
      hideTimeoutRef.current = null;
    }
  }, []);

  // Event handlers
  const handleMouseEnter = useCallback(() => {
    // A tap synthesizes mouseenter. On touch the tap path owns the decision,
    // so hover must not also fire — including the tap that just opened the
    // tooltip, which would otherwise be double-handled.
    if (isTouchPointerRef.current) {
      return;
    }
    scheduleShow();
  }, [isTouchPointerRef, scheduleShow]);

  const handleMouseLeave = useCallback(
    (event: Event) => {
      // On touch the synthesized mouseleave arrives with the next tap elsewhere,
      // which the outside-tap dismissal already handles — and handling it here
      // too would close the tooltip behind the tap-open bookkeeping's back.
      if (isTouchPointerRef.current) {
        return;
      }
      // Leaving straight onto the tooltip: the surface's onMouseEnter already
      // ran, because React dispatches it from the mouseout that precedes this
      // mouseleave, so a hide scheduled now would never be cancelled. The
      // surface's own mouse leave schedules the hide instead.
      const next = (event as MouseEvent).relatedTarget as Node | null;
      const surface =
        next == null ? null : next.ownerDocument?.getElementById(layerId);
      if (surface != null && surface.contains(next)) {
        return;
      }
      scheduleHide();
    },
    [isTouchPointerRef, layerId, scheduleHide],
  );

  // 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);

  // Whether focus on `target` opens the tooltip. With a `trigger`, its
  // `focusTrigger` rule applies too. Only `:focus-visible` focus opens it, and
  // a tap never does: a tapped `<input>` also matches `:focus-visible`.
  const opensOnFocus = useCallback(
    (target: HTMLElement, trigger: HTMLElement | null): boolean => {
      if (trigger != null && !isFocusOnTrigger(target, trigger, focusTrigger)) {
        return false;
      }
      return !isTouchInteraction() && target.matches(':focus-visible');
    },
    [focusTrigger, isTouchInteraction],
  );

  const handleFocusIn = useCallback(
    (e: Event) => {
      if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
        return;
      }
      if (!opensOnFocus(e.target as HTMLElement, null)) {
        return;
      }
      clearTimeouts();
      // Held closed, the focus reports through onShow and shows nothing. The
      // caller decides.
      const latest = latestRef.current;
      if (latest.isOpen === false) {
        latest.onShow?.();
        return;
      }
      showLayer();
    },
    [
      focusGate,
      focusTrigger,
      isEnabled,
      opensOnFocus,
      clearTimeouts,
      showLayer,
    ],
  );

  // A held tooltip's focus-leave close is the hold's own: it listens on the
  // trigger whatever `focusTrigger` is. This schedules the unheld hide, which
  // a held tooltip skips.
  const handleFocusOut = useCallback(
    (e: Event) => {
      if (!focusGate.focusOut(e, focusTrigger)) {
        return;
      }
      scheduleHide();
    },
    [focusGate, focusTrigger, scheduleHide],
  );

  // Pressing the trigger hides its own tooltip: once the control is activated
  // the hint has served its purpose, and a tooltip lingering over a
  // just-pressed control reads as stale. Fires on pointerdown so it feels
  // immediate. Uncontrolled tooltips only — a controlled tooltip's visibility
  // is owned by the consumer. `hideLayer()` self-guards when already closed.
  // A touch press is a different gesture (it may be the only way to open the
  // tooltip at all), so the touch path answers it first.
  // Whether a press on the trigger is down, from the hook's pointerdown to
  // the press's end.
  const isTriggerPressedRef = useRef(false);
  const stopPressTrackingRef = useRef<(() => void) | null>(null);
  const trackTriggerPress = useCallback(() => {
    stopPressTrackingRef.current?.();
    const view = triggerRef.current?.ownerDocument.defaultView;
    if (view == null) {
      return;
    }
    isTriggerPressedRef.current = true;
    const trigger = triggerRef.current;
    const stop = (event?: Event) => {
      // A press that ends on the trigger keeps its hold, as a click does.
      if (
        event?.type === 'pointerup' &&
        event.target instanceof view.Node &&
        trigger?.contains(event.target) === true
      ) {
        isHoldFromPressRef.current = false;
      }
      view.removeEventListener('pointerup', stop, true);
      view.removeEventListener('pointercancel', stop, true);
      isTriggerPressedRef.current = false;
      stopPressTrackingRef.current = null;
    };
    view.addEventListener('pointerup', stop, true);
    view.addEventListener('pointercancel', stop, true);
    stopPressTrackingRef.current = stop;
  }, []);

  const handlePointerDown = useCallback(
    (event: PointerEvent) => {
      trackTriggerPress();
      // The app's hide() closes a held tooltip. A press neither hides it here
      // nor waits for a tap verdict. A show() in a capture handler of this
      // press runs before this listener. Tie that hold to the press.
      if (isHeldRef.current) {
        if (isHoldInThisTaskRef.current) {
          isHoldFromPressRef.current = true;
        }
        return;
      }
      if (handleTouchPointerDown(event)) {
        // A pen in range starts the hover show before it lands. Left pending,
        // that show opens the layer during the press. The tap then closes it.
        if (showTimeoutRef.current) {
          clearTimeout(showTimeoutRef.current);
          showTimeoutRef.current = null;
        }
        return;
      }
      if (isOpen !== undefined) {
        return;
      }
      clearTimeouts();
      hideLayer();
    },
    [
      handleTouchPointerDown,
      trackTriggerPress,
      isOpen,
      clearTimeouts,
      hideLayer,
    ],
  );

  // The trigger's listeners call the latest handlers through this ref, so the
  // trigger ref callback keeps one identity.
  const handlersRef = useRef({
    handleMouseEnter,
    handleMouseLeave,
    handleFocusIn,
    handleFocusOut,
    handleHeldFocusOut,
    handlePointerEnter,
    handlePointerDown,
    focusTrigger,
    isOpen,
    dropHold,
    hideNow,
    showNow,
    opensOnFocus,
    presentInterest,
    answerTap,
  });
  handlersRef.current = {
    handleMouseEnter,
    handleMouseLeave,
    handleFocusIn,
    handleFocusOut,
    handleHeldFocusOut,
    handlePointerEnter,
    handlePointerDown,
    focusTrigger,
    isOpen,
    dropHold,
    hideNow,
    showNow,
    opensOnFocus,
    presentInterest,
    answerTap,
  };

  // Removes the attached trigger's listeners (the trigger ref callback's
  // cleanup).
  const detachTriggerRef = useRef<(() => void) | null>(null);
  // Set when the trigger detached while the tooltip was disabled: the
  // caller removed the wiring (DropdownMenu's Button while its menu is
  // open), so the next enabled attach reads the focus that arrived meanwhile.
  const wasSuppressedRef = useRef(false);

  // The trigger's ref callback owns every trigger listener, and reads the
  // trigger's state when it attaches and detaches.
  const interactionRef = useCallback((el: HTMLElement | null) => {
    // A caller that reports `null` by hand detaches the trigger, as the
    // returned cleanup does.
    if (el == null) {
      detachTriggerRef.current?.();
      return;
    }
    if (el === triggerRef.current) {
      return;
    }
    detachTriggerRef.current?.();
    const latest = () => handlersRef.current;
    // `pointerenter` runs before the synthesized `mouseenter` a tap produces,
    // which is what lets the hover path know it is looking at a finger.
    const onPointerEnter = (e: PointerEvent) => latest().handlePointerEnter(e);
    const onMouseEnter = () => latest().handleMouseEnter();
    const onMouseLeave = (e: Event) => latest().handleMouseLeave(e);
    // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
    const onPointerDown = (e: PointerEvent) => latest().handlePointerDown(e);
    // Focus counts unless focus never opens the tooltip; `auto` decides per
    // event (isFocusForTrigger).
    const onFocusIn = (e: Event) => {
      if (latest().focusTrigger !== 'never') {
        latest().handleFocusIn(e);
      }
    };
    const onFocusOut = (e: Event) => {
      if (latest().focusTrigger !== 'never') {
        latest().handleFocusOut(e);
      }
    };
    // A held tooltip's own focus-leave close, whatever `focusTrigger` is.
    const onHeldFocusOut = (e: FocusEvent) => latest().handleHeldFocusOut(e);
    el.addEventListener('pointerenter', onPointerEnter);
    el.addEventListener('mouseenter', onMouseEnter);
    el.addEventListener('mouseleave', onMouseLeave);
    el.addEventListener('pointerdown', onPointerDown);
    el.addEventListener('focusin', onFocusIn);
    el.addEventListener('focusout', onFocusOut);
    el.addEventListener('focusout', onHeldFocusOut);
    triggerRef.current = el;

    // A trigger that attaches again after its wiring was removed
    // (DropdownMenu's Button as its menu closes) missed the focus that
    // arrived meanwhile. Show for it only if it would open the tooltip:
    // returned keyboard focus does, focus returned after a pointer pick does
    // not. Any other attach leaves the tooltip as it is, so a tooltip
    // dismissed with Escape stays closed.
    const focused = el.ownerDocument.activeElement;
    const wasSuppressed = wasSuppressedRef.current;
    if (isEnabledRef.current) {
      wasSuppressedRef.current = false;
    }
    if (
      wasSuppressed &&
      isEnabledRef.current &&
      latest().isOpen === undefined &&
      latest().focusTrigger !== 'never' &&
      focused instanceof HTMLElement &&
      el.contains(focused) &&
      latest().opensOnFocus(focused, el)
    ) {
      latest().showNow();
    }

    // This tooltip mounted after the interaction that wants it. It answers
    // that interaction once, by the same rules as its listeners.
    const state = latest().presentInterest?.current;
    const interest = state == null || state.isRead ? null : state.interest;
    const tapEvent = state?.tapEvent ?? null;
    if (state != null) {
      state.isRead = true;
    }
    if (isEnabledRef.current && latest().isOpen === undefined) {
      if (interest === 'hover') {
        latest().handleMouseEnter();
      } else if (interest === 'tap') {
        latest().answerTap(tapEvent);
      } else if (
        interest === 'focus' &&
        latest().focusTrigger !== 'never' &&
        focused instanceof HTMLElement &&
        el.contains(focused) &&
        latest().opensOnFocus(focused, el)
      ) {
        latest().showNow();
      }
    }

    const detach = () => {
      if (detachTriggerRef.current === detach) {
        detachTriggerRef.current = null;
      }
      el.removeEventListener('pointerenter', onPointerEnter);
      el.removeEventListener('mouseenter', onMouseEnter);
      el.removeEventListener('mouseleave', onMouseLeave);
      el.removeEventListener('pointerdown', onPointerDown);
      el.removeEventListener('focusin', onFocusIn);
      el.removeEventListener('focusout', onFocusOut);
      el.removeEventListener('focusout', onHeldFocusOut);
      stopPressTrackingRef.current?.();
      if (triggerRef.current === el) {
        triggerRef.current = null;
      }
      // A caller removes the wiring as it disables the tooltip. Close an
      // uncontrolled tooltip then, or the next attach shows a stale tooltip.
      // A detach while enabled, such as a merged ref that changes identity
      // on a re-render, keeps a hovered or held tooltip open.
      if (!isEnabledRef.current && latest().isOpen === undefined) {
        wasSuppressedRef.current = true;
        latest().dropHold();
        latest().hideNow();
      }
    };
    detachTriggerRef.current = detach;
    return detach;
  }, []);

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

  // Cleanup 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 -- mount-only: isDefaultOpen is not reactive
  }, []);

  // Controlled open state — overrides hover/focus triggers
  useEffect(() => {
    if (isOpen === undefined) {
      return;
    }
    if (isOpen) {
      clearTimeouts();
      showLayer();
    } else {
      clearTimeouts();
      // A hold ends when the consumer closes the tooltip.
      dropHold();
      hideLayer();
    }
  }, [isOpen, clearTimeouts, showLayer, hideLayer, dropHold]);

  // Dismiss on Escape (WCAG 1.4.13 — dismissible) through the shared layer
  // stack. A visible tip is the top-most layer, so it takes the press and
  // consumes it: Escape hides the tip and leaves the dialog underneath open.
  // The user presses Escape again to close that. Consuming (rather than also
  // dismissing what is beneath) keeps one rule with no per-component
  // exceptions, and the failure mode is one extra keystroke instead of a
  // dialog closing under someone who only wanted the tip gone.
  //
  // A controlled tooltip 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.
  useLayerDismissal({
    // Registered for the hook's lifetime rather than gated on `isLayerOpen`:
    // 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: true,
    isPresent: () => {
      const el =
        typeof document === 'undefined'
          ? null
          : document.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();
      dropHold();
      if (isOpen !== undefined) {
        onHide?.();
        return;
      }
      hideLayer();
    },
  });

  // Render function that wraps layer.render with tooltip styling
  const renderTooltip = useCallback(
    (
      children: ReactNode,
      props?: Omit<ContextRenderProps, 'positioning'>,
    ): ReactNode => {
      const renderPlacement = props?.placement ?? placement;
      const renderProps = {
        placement: renderPlacement,
        alignment: props?.alignment ?? alignment,
        offset: spacingVars['--spacing-1'],
        role: 'tooltip',
        xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
        className: themeProps('tooltip').className,
        // Keep the tooltip open while the pointer is over the surface itself
        // (WCAG 1.4.13 hoverable). These sit on the layer container — the
        // element the user actually hovers — not the inner content div, since
        // mouseenter/leave do not bubble.
        onMouseEnter: cancelHide,
        onMouseLeave: scheduleHide,
      };

      return renderLayer(
        // FR11: React bubbles a press on the surface to the trigger's
        // ancestors, portaled or not. A registered surface counts as
        // something else in the shared interactive-ancestor walk, so a
        // clickable container around the trigger leaves the press alone while
        // document listeners still see it.
        // The hold's announcement reads this element's text.
        <div ref={contentRefs} {...stylex.props(styles.content)}>
          {children}
        </div>,
        renderProps,
      );
    },
    [
      renderLayer,
      placement,
      alignment,
      popoverXstyle,
      cancelHide,
      scheduleHide,
      contentRefs,
    ],
  );

  const show = useCallback(() => {
    clearTimeouts();
    if (!isEnabled) {
      return;
    }
    setHeld(true);
    armOutsideDismiss();
    isHoldFromPressRef.current = isTriggerPressedRef.current;
    isHoldInThisTaskRef.current = true;
    triggerRef.current?.ownerDocument.defaultView?.setTimeout(() => {
      isHoldInThisTaskRef.current = false;
    }, 0);
    const latest = latestRef.current;
    if (latest.isOpen !== undefined) {
      latest.onShow?.();
      return;
    }
    showLayer();
  }, [clearTimeouts, isEnabled, setHeld, armOutsideDismiss, showLayer]);

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

  return {
    ref,
    positionRef: layerRef,
    interactionRef,
    anchorId: layerAnchorId,
    describedBy: layerId,
    renderTooltip,
    show,
    hide,
  };
}