Skip to content

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

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

'use client';

/**
 * @file useHighlightedOptionScroll.ts
 * @input Open state, the highlighted option index, its setter, and an
 *   option-id resolver for the owning listbox
 * @output Exports useHighlightedOptionScroll: keeps the highlighted option
 *   scrolled into view for keyboard navigation while hover-driven highlights
 *   never scroll, and a hover after a keyboard move waits for the pointer to
 *   move or press; the hover callback is stable while `setHighlightedIndex` is
 * @position Internal hook; used by useCombobox, useMultiCombobox,
 *   BaseTypeahead, and DateTimeInput — the owners of combobox highlight state
 */

import {useCallback, useEffect, useRef} from 'react';

interface UseHighlightedOptionScrollOptions {
  isOpen: boolean;
  highlightedIndex: number;
  setHighlightedIndex: (index: number) => void;
  getOptionId: (index: number) => string;
  /**
   * Current option count, when the list can change while open (filtered or
   * min/max-clamped lists). A count change runs the scroll again.
   */
  itemCount?: number;
}

/**
 * Highlights the hovered option at `index`. `onHighlight` runs when the hover
 * takes effect: at once, or after the pointer moves or presses when a
 * keyboard move holds the highlight.
 */
export type HighlightFromHover = (
  index: number,
  onHighlight?: () => void,
) => void;

interface WaitingHover {
  index: number;
  onHighlight?: () => void;
}

/**
 * Keep the highlighted option visible during keyboard navigation — but not for
 * hover highlights. Hover must highlight only: scrollIntoView moves the next
 * option under the stationary pointer, whose mouseenter re-highlights and
 * scrolls again — a runaway auto-scroll loop with no user input.
 * Keyboard paths call the raw setter directly and keep their scrolling; hover
 * paths call the returned callback.
 *
 * A keyboard move holds the highlight. A key that scrolls the list moves rows
 * under a still mouse, and the browser reports the row under it as entered;
 * that row takes the highlight only once the pointer moves or presses.
 */
export function useHighlightedOptionScroll({
  isOpen,
  highlightedIndex,
  setHighlightedIndex,
  getOptionId,
  itemCount,
}: UseHighlightedOptionScrollOptions): HighlightFromHover {
  // The callback reads no render state, so memoized rows keep one function.
  const hoveredIndexRef = useRef<number | null>(null);
  const shownIndexRef = useRef(highlightedIndex);
  // The hover that came while a keyboard move held the highlight.
  const waitingHoverRef = useRef<WaitingHover | null>(null);
  // Set only while a keyboard move holds the highlight.
  const removeHoldListenersRef = useRef<(() => void) | null>(null);
  const setHighlightedIndexRef = useRef(setHighlightedIndex);
  // The pointer's last screen position a hold saw, kept across holds.
  const lastPointerRef = useRef<{x: number; y: number} | null>(null);

  const applyHover = useCallback((hover: WaitingHover) => {
    hoveredIndexRef.current = hover.index;
    setHighlightedIndexRef.current(hover.index);
    hover.onHighlight?.();
  }, []);

  const endHold = useCallback(() => {
    removeHoldListenersRef.current?.();
    removeHoldListenersRef.current = null;
  }, []);

  const releaseHold = useCallback(() => {
    endHold();
    const waiting = waitingHoverRef.current;
    waitingHoverRef.current = null;
    if (waiting != null) {
      applyHover(waiting);
    }
  }, [applyHover, endHold]);

  // Holds the highlight until the pointer moves or presses. The listeners
  // live only while the hold does. Movement is read by screen coordinates: a
  // scroll moves the rows, not the pointer. The browser reports a row as
  // entered before the move that reaches it, so the first real move gives
  // that row the highlight. A press releases at once, so a held press lights
  // the pressed row.
  const startHold = useCallback(() => {
    waitingHoverRef.current = null;
    if (removeHoldListenersRef.current != null) {
      return;
    }
    const onPointerMove = (event: PointerEvent) => {
      const last = lastPointerRef.current;
      lastPointerRef.current = {x: event.screenX, y: event.screenY};
      if (
        last != null &&
        last.x === event.screenX &&
        last.y === event.screenY
      ) {
        return;
      }
      releaseHold();
    };
    const options = {capture: true, passive: true} as const;
    document.addEventListener('pointermove', onPointerMove, options);
    document.addEventListener('pointerdown', releaseHold, options);
    removeHoldListenersRef.current = () => {
      document.removeEventListener('pointermove', onPointerMove, options);
      document.removeEventListener('pointerdown', releaseHold, options);
    };
  }, [releaseHold]);

  const highlightFromHover = useCallback<HighlightFromHover>(
    (index, onHighlight) => {
      if (removeHoldListenersRef.current != null) {
        waitingHoverRef.current = {index, onHighlight};
        return;
      }
      hoveredIndexRef.current = index;
      setHighlightedIndex(index);
      onHighlight?.();
    },
    [setHighlightedIndex],
  );

  // Effect: keeps the hold's document listeners calling the current setter.
  useEffect(() => {
    setHighlightedIndexRef.current = setHighlightedIndex;
  }, [setHighlightedIndex]);

  // Effect: removes the hold's document listeners on unmount.
  useEffect(() => endHold, [endHold]);

  // Effect: scrolls the highlighted option into view in the document, and
  // starts or ends the hold on its document listeners.
  useEffect(() => {
    // Only a move to the hovered row came from the hover. A hover on the row
    // already highlighted changes nothing, so a later run for the same row
    // (a new list) still scrolls it into view.
    const hasMoved = shownIndexRef.current !== highlightedIndex;
    shownIndexRef.current = highlightedIndex;
    const isFromHover =
      hasMoved && hoveredIndexRef.current === highlightedIndex;
    hoveredIndexRef.current = null;
    if (isFromHover) {
      return;
    }
    // A cleared highlight, a closed list, or a list that is not shown (a
    // closed CommandPalette reports itself as open) has nothing to hold.
    const option =
      isOpen && highlightedIndex >= 0
        ? document.getElementById(getOptionId(highlightedIndex))
        : null;
    if (option == null) {
      waitingHoverRef.current = null;
      endHold();
      return;
    }
    startHold();
    option.scrollIntoView?.({block: 'nearest'});
  }, [isOpen, highlightedIndex, getOptionId, itemCount, endHold, startHold]);

  return highlightFromHover;
}