Skip to content

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

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

/**
 * @file fingerScroll.ts
 * @input A scroller (an element, or the document for the page's own scroll),
 *   its document's scroll and scrollend events, and the gesture host's
 *   finger record
 * @output Exports watchFingerScrolls and isFingerScroll (now or at a past
 *   time). A watcher can ask to hear when a finger's scroll ends.
 * @position Finger-scroll watch of packages/core/src/gestures (useFingerScroll
 *   reads it), in its own module so a page that never asks never ships it;
 *   internal to the touch module, not in the gestures barrel
 *
 * A watched scroller's scroll is a finger's from a scroll event while a
 * finger that landed inside it is down, until the scroller's own `scrollend`
 * (the momentum after the lift is still the finger's). A scroll that ends
 * while its finger still rests there stays the finger's until the lift. A
 * scroll the program starts while no finger is down there (`scrollTo`, a
 * status-bar tap) is not. Where the browser sends no `scrollend`, a quiet
 * spell of `SCROLL_END_FALLBACK_MS` after its last scroll event ends a
 * finger's scroll instead. The host keeps the one finger record; this module
 * adds only passive scroll listeners, and only while something is watched.
 */

import {subscribeInput} from '../utils/inputStream';
import {isCoarsePointer, watchCoarsePointer} from '../utils/coarsePointer';
import type {GestureHost} from './GestureHost';
import {isNode} from '../utils/nodeType';

/**
 * Where the browser sends no `scrollend`, how long a finger-driven scroller
 * stays quiet (no scroll event) before its scroll counts as ended, in ms:
 * longer than the gap between a momentum scroll's events, short enough that
 * a program's scroll right after it is not read as the finger's.
 */
const SCROLL_END_FALLBACK_MS = 150;

/** A finger scroll's span on the page's clock, ms: landing to end. */
interface FingerScrollSpan {
  readonly start: number;
  readonly end: number;
}

interface Watch {
  /** Watched scrollers, and how many watchers each has. */
  readonly scrollers: Map<Node, number>;
  /** Watched scrollers whose current scroll is a finger's. */
  readonly fingerScrollers: Set<Node>;
  /** Finger scrolls whose `scrollend` came while the finger still rested. */
  readonly endedWhileDown: Set<Node>;
  /** Per scroller, the watchers to tell when its finger scroll ends. */
  readonly endListeners: Map<Node, Set<() => void>>;
  /** Per watched scroller, when the finger now down in it landed. */
  readonly landings: Map<Node, number>;
  /** Per finger scroll in progress, when its finger landed. */
  readonly fingerScrollStarts: Map<Node, number>;
  /** Per scroller, the span of its last finger scroll that ended. */
  readonly lastFingerScrolls: Map<Node, FingerScrollSpan>;
  stop: (() => void) | null;
}

const watches = new WeakMap<GestureHost, Watch>();

/**
 * A scroller's finger scroll is over at `at`. It stops counting as the
 * finger's, and its span stays readable. Then its end listeners hear of it,
 * so one that reads isFingerScroll already reads false.
 */
function endFingerScroll(watch: Watch, scroller: Node, at: number): void {
  if (!watch.fingerScrollers.delete(scroller)) {
    return;
  }
  watch.lastFingerScrolls.set(scroller, {
    start: watch.fingerScrollStarts.get(scroller) ?? at,
    end: at,
  });
  watch.fingerScrollStarts.delete(scroller);
  for (const listener of [...(watch.endListeners.get(scroller) ?? [])]) {
    listener();
  }
}

function start(host: GestureHost, watch: Watch): () => void {
  const doc = host.document;
  // The clock of the page's IntersectionObserver entries and events.
  const now = (): number => (doc.defaultView?.performance ?? performance).now();
  const scrollerOf = (event: Event): Node | null => {
    const target = event.target === doc ? doc : event.target;
    return isNode(target) ? target : null;
  };
  // A finger's scroll ends at the scroller's scrollend, or, where the
  // browser sends none, after a quiet spell.
  const endScroll = (scroller: Node): void => {
    if (!watch.fingerScrollers.has(scroller)) {
      return;
    }
    if (host.isFingerDownIn(scroller)) {
      // The finger still rests there: the scroll is its until the lift.
      watch.endedWhileDown.add(scroller);
    } else {
      endFingerScroll(watch, scroller, now());
    }
  };
  const scrollEndFallbacks = new Map<Node, ReturnType<typeof setTimeout>>();
  const clearScrollEndFallback = (scroller: Node): void => {
    const timer = scrollEndFallbacks.get(scroller);
    if (timer != null) {
      clearTimeout(timer);
      scrollEndFallbacks.delete(scroller);
    }
  };
  const hasScrollEnd = (): boolean => {
    const view = doc.defaultView;
    return view != null && 'onscrollend' in view;
  };
  const onScroll = (event: Event): void => {
    const scroller = scrollerOf(event);
    // A recognizer's own scroll (a menu's edge autoscroll) is never the
    // finger's, even with a finger resting inside.
    if (
      scroller == null ||
      !watch.scrollers.has(scroller) ||
      host.isOwnScroll(scroller)
    ) {
      return;
    }
    watch.endedWhileDown.delete(scroller);
    if (host.isFingerDownIn(scroller)) {
      if (!watch.fingerScrollers.has(scroller)) {
        watch.fingerScrollStarts.set(
          scroller,
          watch.landings.get(scroller) ?? now(),
        );
      }
      watch.fingerScrollers.add(scroller);
    }
    if (watch.fingerScrollers.has(scroller) && !hasScrollEnd()) {
      clearScrollEndFallback(scroller);
      scrollEndFallbacks.set(
        scroller,
        setTimeout(() => {
          scrollEndFallbacks.delete(scroller);
          endScroll(scroller);
        }, SCROLL_END_FALLBACK_MS),
      );
    }
  };
  const onScrollEnd = (event: Event): void => {
    const scroller = scrollerOf(event);
    if (scroller != null) {
      endScroll(scroller);
    }
  };
  const onFingers = (): void => {
    // A finger scroll's span starts at its finger's landing: the observer
    // records a crossing at its frame's start, before that frame's scroll
    // event runs.
    for (const scroller of watch.scrollers.keys()) {
      if (!host.isFingerDownIn(scroller)) {
        watch.landings.delete(scroller);
      } else if (!watch.landings.has(scroller)) {
        watch.landings.set(scroller, now());
      }
    }
    // A scroll that ended while its finger rested ends with the lift.
    for (const scroller of watch.endedWhileDown) {
      if (!host.isFingerDownIn(scroller)) {
        watch.endedWhileDown.delete(scroller);
        endFingerScroll(watch, scroller, now());
      }
    }
  };
  // Its listeners are on only while the primary pointer is coarse
  // (`spec:AST-094` FR19, FR24): elsewhere no finger scrolls, as far as the
  // touch presentation is concerned. Passive, on the window's capture phase
  // through the shared input stream.
  const view = doc.defaultView;
  let unsubscribers: (() => void)[] = [];
  const listen = (on: boolean): void => {
    if (view == null || on === unsubscribers.length > 0) {
      return;
    }
    if (on) {
      unsubscribers = [
        subscribeInput(view, 'scroll', onScroll),
        subscribeInput(view, 'scrollend', onScrollEnd),
      ];
    } else {
      for (const stop of unsubscribers.splice(0)) {
        stop();
      }
      for (const scroller of [...scrollEndFallbacks.keys()]) {
        clearScrollEndFallback(scroller);
      }
      // No finger scrolls once the pointer is no longer coarse: each one in
      // progress ends here.
      watch.endedWhileDown.clear();
      watch.landings.clear();
      for (const scroller of [...watch.fingerScrollers]) {
        endFingerScroll(watch, scroller, now());
      }
    }
  };
  const stopWatchingPointer = watchCoarsePointer(view, listen);
  listen(isCoarsePointer(view));
  const unsubscribe = host.onFingersChange(onFingers);
  const release = host.retain();
  return () => {
    stopWatchingPointer();
    listen(false);
    unsubscribe();
    release();
  };
}

/**
 * Keep track of whether the scrolls of `scroller` (an element in `host`'s
 * document, or the document itself) are a finger's, for isFingerScroll,
 * until the returned function runs. `onEnd`, when given, runs each time a
 * finger's scroll on the scroller ends (its `scrollend` after the lift, the
 * lift after a `scrollend` that came while the finger rested, the quiet
 * fallback, or the pointer turning fine), after isFingerScroll turns false.
 * Stopping the watch does not call it.
 * Internal: not exported from the package.
 */
export function watchFingerScrolls(
  host: GestureHost,
  scroller: Node,
  onEnd?: () => void,
): () => void {
  let watch = watches.get(host);
  if (watch == null) {
    watch = {
      scrollers: new Map(),
      fingerScrollers: new Set(),
      endedWhileDown: new Set(),
      endListeners: new Map(),
      landings: new Map(),
      fingerScrollStarts: new Map(),
      lastFingerScrolls: new Map(),
      stop: null,
    };
    watches.set(host, watch);
  }
  const owned = watch;
  owned.scrollers.set(scroller, (owned.scrollers.get(scroller) ?? 0) + 1);
  // Each watch registers its own listener, so two watchers of one scroller
  // each hear every end once.
  const listener = onEnd == null ? null : () => onEnd();
  if (listener != null) {
    const listeners = owned.endListeners.get(scroller) ?? new Set();
    listeners.add(listener);
    owned.endListeners.set(scroller, listeners);
  }
  owned.stop ??= start(host, owned);
  let isWatching = true;
  return () => {
    if (!isWatching) {
      return;
    }
    isWatching = false;
    if (listener != null) {
      const listeners = owned.endListeners.get(scroller);
      listeners?.delete(listener);
      if (listeners?.size === 0) {
        owned.endListeners.delete(scroller);
      }
    }
    const count = (owned.scrollers.get(scroller) ?? 1) - 1;
    if (count > 0) {
      owned.scrollers.set(scroller, count);
      return;
    }
    owned.scrollers.delete(scroller);
    owned.fingerScrollers.delete(scroller);
    owned.endedWhileDown.delete(scroller);
    owned.landings.delete(scroller);
    owned.fingerScrollStarts.delete(scroller);
    owned.lastFingerScrolls.delete(scroller);
    if (owned.scrollers.size === 0) {
      owned.stop?.();
      owned.stop = null;
    }
  };
}

/**
 * Whether the scroll now moving a watched `scroller` is a finger's. Given a
 * time on the page's clock (`performance.now()`, like an IntersectionObserver
 * entry's `time`), whether the scroll at that time was a finger's. A finger's
 * scroll runs from the finger's landing to its end, momentum included. A
 * report that runs late, such as an IntersectionObserver callback on a busy
 * page, passes the time it describes.
 * Internal: not exported from the package.
 */
export function isFingerScroll(
  host: GestureHost,
  scroller: Node,
  at?: number,
): boolean {
  const watch = watches.get(host);
  if (watch == null) {
    return false;
  }
  if (at == null) {
    return watch.fingerScrollers.has(scroller);
  }
  const start = watch.fingerScrollStarts.get(scroller);
  if (start != null && at >= start) {
    return true;
  }
  const last = watch.lastFingerScrolls.get(scroller);
  return last != null && at >= last.start && at <= last.end;
}