Skip to content

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

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

'use client';

/**
 * @file useFingerScroll.ts
 * @input A scroller (a ref to an element, or the document for the page) and
 *   the document's gesture host
 * @output useFingerScroll: whether the scroller's scroll is a finger's, read
 *   now or at a past time, and an optional call when one ends
 * @position Gesture hook of packages/core/src/gestures, over the
 *   finger-scroll watch (fingerScroll.ts), kept on the scroller's node by
 *   the gesture hooks' shared attachment (hooks/useAttachment.ts). An internal
 *   piece of the touch
 *   module with no public API, not in the gestures barrel: a scroll-driven
 *   component (a tab bar that minimizes, a header that collapses, a picker
 *   that commits at rest) imports it from here, so it ships only where used
 *
 * A scroll is a finger's from a scroll event while a finger that landed
 * inside the scroller is down, until the scroller's `scrollend` (the lift
 * starts the momentum, which is still the finger's), or, where the browser
 * sends no `scrollend`, until a 150 ms fallback after the last scroll event.
 * A scroll with no finger down, or a recognizer's own scroll, is the
 * program's, even right after a tap. A
 * component that reacts to the person's scrolling only (a tab bar that
 * minimizes as the page scrolls down) reads this instead of listening to
 * touches itself.
 *
 * SYNC: When modified, update __tests__/useFingerScroll.test.tsx.
 */

import {useCallback, useRef, type RefObject} from 'react';
import {isFingerScroll, watchFingerScrolls} from './fingerScroll';
import {getGestureHost} from './GestureHost';
import {useAttachment} from '../hooks/useAttachment';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {isDocument} from '../utils/nodeType';

/** The document a scroller is in: itself, for the page's own scroll. */
function documentOf(node: Element | Document): Document {
  return isDocument(node) ? node : node.ownerDocument;
}

export interface UseFingerScrollOptions {
  /**
   * Runs each time a finger's scroll on the scroller ends, once the reader
   * says `false`: at its `scrollend` after the lift (the momentum is still
   * the finger's), at the lift when the scroll ended under a resting finger,
   * after the quiet fallback where the browser fires no `scrollend`, or when
   * the primary pointer stops being coarse. Unmounting, or the scroller
   * changing, does not call it. The latest function is the one called.
   */
  onEnd?: () => void;
}

/**
 * Watch a scroller's finger scrolls. Pass a ref to a scrolling element, or
 * the document for the page's own scroll. Returns a reader, stable across
 * renders: `true` while the scroller's scroll is a finger's. Given a time on
 * the page's clock (`performance.now()`, as an IntersectionObserver entry's
 * `time` is), it reads whether the scroll at that time was a finger's.
 * Internal: not exported from the package.
 */
export function useFingerScroll(
  scroller: RefObject<Element | null> | Document,
  {onEnd}: UseFingerScrollOptions = {},
): (at?: number) => boolean {
  /** The node the watch is on now, for the reader. */
  const watchedRef = useRef<Element | Document | null>(null);
  // The watch outlives renders, so it calls the latest onEnd through a ref
  // written at commit.
  const onEndRef = useRef(onEnd);
  useIsomorphicLayoutEffect(function keepLatestOnEnd() {
    onEndRef.current = onEnd;
  });
  // Keeps the finger-scroll watch on the node the scroller names after each
  // commit (useAttachment): a ref that now points at another element moves
  // the watch to it, and unmounting releases it.
  useAttachment<Element | Document>(
    isDocument(scroller) ? {current: scroller} : scroller,
    node => {
      watchedRef.current = node;
      const stop = watchFingerScrolls(
        getGestureHost(documentOf(node)),
        node,
        () => onEndRef.current?.(),
      );
      return () => {
        stop();
        watchedRef.current = null;
      };
    },
    null,
  );
  return useCallback((at?: number) => {
    const node = watchedRef.current;
    return (
      node != null && isFingerScroll(getGestureHost(documentOf(node)), node, at)
    );
  }, []);
}