Skip to content

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

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

/**
 * @file PressTracker.ts
 * @input Touches the arena delivers to a pressable view (TouchConsumer)
 * @output Exports createPressTracker and its PressTracker interface
 *   (UIControl's touch tracking, built by a factory per
 *   architecture:react-component-runtime INV13), its options, the
 *   control event type, and PRESS_PROFILES (a control's and a table cell's
 *   tracking and release clock)
 * @position View-level consumer of packages/core/src/gestures: what a
 *   UIControl does with the touches no gesture recognizer took
 *
 * UIControl semantics, event for event:
 *
 * - `touchDown` when the finger lands; the highlight comes on in the same
 *   frame, unless the control sits in a scroller. There it waits
 *   `contentTouchDelay` (UIScrollView.delaysContentTouches) from the touch's
 *   own time, so a flick paints nothing.
 * - `touchDragInside` / `touchDragOutside` on every move, `touchDragExit` /
 *   `touchDragEnter` when the finger crosses the control's bounds EXPANDED
 *   by `trackingExpansion` (a fingertip dragged a little off a button is
 *   still on it). The highlight follows inside / outside.
 * - `touchUpInside` / `touchUpOutside` at the lift. A tap quicker than the
 *   scroller delay shows the highlight at the lift for `quickTapFlash`.
 * - `touchCancel` when a recognizer took the touch (`cancelsTouchesInView`)
 *   or the browser took it to scroll: the highlight goes at once, with no
 *   release, one frame before the content moves.
 *
 * Two profiles (PRESS_PROFILES) cover what UIKit does:
 *
 * - `control` (a button, a switch): as above.
 * - `cell` (a table or collection row): the highlight waits the
 *   content-touch delay inside a scroll view and comes on at once outside one
 *   (`spec:AST-094` FR11), travel past the pan hysteresis cancels the press
 *   for good (the scroll view took the touch), and a quicker tap highlights
 *   at the lift straight into the release, with no flash.
 *
 * And UIControl's iOS 6 rule: a single-finger single tap recognizer on an
 * ANCESTOR does not beat the control's own action for a touch on it (the
 * default veto; `vetoesAncestorRecognizer` replaces it, as a slider vetoes a
 * pan along its track).
 *
 * The bounds are read once, when the finger lands; nothing reads layout
 * during the press. Activation stays the browser's click, which the arena
 * swallows for a touch a recognizer took.
 */

import {UIKIT_CONTROL, UIKIT_PAN, UIKIT_PRESS} from '../motion/uikit/gestures';
// Importing the whole table bundles its curves into each press-tracking control.
import {press as pressClocks} from '../motion/uikit/timing';
import {msSinceInput} from '../utils/inputAge';
import {travel} from './geometry';
import type {GestureRecognizer, SelectionLock} from './GestureRecognizer';
import type {TapGestureRecognizer} from './TapGestureRecognizer';
import type {GestureTouch, TouchConsumer} from './types';

export type ControlEvent =
  | 'touchDown'
  | 'touchDragInside'
  | 'touchDragOutside'
  | 'touchDragEnter'
  | 'touchDragExit'
  | 'touchUpInside'
  | 'touchUpOutside'
  | 'touchCancel';

export interface PressBounds {
  readonly left: number;
  readonly top: number;
  readonly right: number;
  readonly bottom: number;
}

export interface PressTrackerOptions {
  /** The control's bounds in client px, read when a finger lands. */
  getBounds: () => PressBounds | null;
  /** The view the tracker belongs to; recognizers on it are not ancestors. */
  view?: unknown;
  onControlEvent?: (event: ControlEvent, touch: GestureTouch) => void;
  onHighlightChange?: (isHighlighted: boolean) => void;
  /**
   * A continuous-tracking control (a held stepper) keeps its touch once its
   * press is delivered: the host cancels the browser's pan for that finger,
   * as UIKit's `touchesShouldCancel(in:)` is false for a tracking control.
   * Its element then gets a blocking `touchmove` listener, so a scroll that
   * starts on it waits on the main thread: never set it on plain buttons,
   * links, cards or list cells.
   * @default false
   */
  keepsTouch?: boolean;
  /**
   * For a control whose own record defines a hold action (a stepper's
   * hold-repeat): pass `lockSelection` (utils/selectionLock.ts) to turn
   * text selection and the callout off for each press by a finger or a pen,
   * under any primary pointer (`spec:AST-094` FR41). A control whose hold
   * does nothing passes none. @default undefined
   */
  selectionLock?: SelectionLock;
  /**
   * Whether the press of `touchId` holds the browser's context menu closed
   * now; the host then cancels it. For a control whose hold acts, such as a
   * switch. @default undefined
   */
  holdsContextMenu?: (touchId: number) => boolean;
  trackingExpansion?: number;
  /**
   * When the highlight waits `contentTouchDelay`: inside a scroller (a
   * control or a cell), always, or never. @default 'inScrollers'
   */
  highlightDelay?: PressHighlightDelay;
  /**
   * Travel (px) past which the press is cancelled for good, with no
   * re-highlight on the way back (a cell whose scroll view took the touch).
   * Unset, the finger is tracked in and out of the expanded bounds.
   */
  cancelTravel?: number;
  /**
   * How long a tap quicker than the delay shows the highlight at the lift,
   * ms; 0 highlights and releases at once. @default the quick-tap flash
   */
  quickTapFlash?: number;
  /** Which ancestor recognizers the control's own action beats. */
  vetoesAncestorRecognizer?: (recognizer: GestureRecognizer) => boolean;
  /** @default () => true */
  isEnabled?: () => boolean;
  /**
   * Whether this finger is braking a scroll it set moving (see
   * GestureHost.isScrollBraking): a native list highlights nothing for one,
   * and the control does not track it at all. Asked only for a finger: a
   * mouse or a pen never brakes (`spec:AST-094` FR11).
   */
  isBraking?: (touch: GestureTouch) => boolean;
}

const PRESS = UIKIT_PRESS;

export type PressHighlightDelay = 'inScrollers' | 'always' | 'never';

/**
 * How a kind of pressable tracks a finger and how long its release takes.
 */
export interface PressProfile {
  readonly highlightDelay: PressHighlightDelay;
  readonly cancelTravel?: number;
  readonly quickTapFlash: number;
  /** The release (`fading`) clock a painter uses, ms. */
  readonly releaseMs: number;
}

export const PRESS_PROFILES = {
  /** UIControl: same-frame highlight outside scrollers, 70 pt tracking. */
  control: {
    highlightDelay: 'inScrollers',
    quickTapFlash: PRESS.quickTapFlash.value,
    // The shared press styles release every surface on the deselect clock
    // until a control runs its own release (UIButton's 250 ms), so a
    // painter's `fading` never outlasts the fade it shows.
    releaseMs: pressClocks.highlightOutMs,
  },
  /**
   * A table or collection cell: inside a scroll view it highlights after the
   * content-touch delay, outside one at once (AST-094 FR11: the delay applies
   * only inside scroll views); cancelled by the scroll.
   */
  cell: {
    highlightDelay: 'inScrollers',
    cancelTravel: UIKIT_PAN.hysteresis.value,
    quickTapFlash: 0,
    releaseMs: pressClocks.highlightOutMs,
  },
} as const satisfies Record<string, PressProfile>;

export type PressProfileName = keyof typeof PRESS_PROFILES;

/**
 * UIButton's rule, the tracker's default ancestor veto: an ancestor's
 * single-finger single tap. A tap is told apart by its `kind`
 * (`architecture:react-component-runtime` INV13).
 */
export function vetoesSingleTap(recognizer: GestureRecognizer): boolean {
  if (recognizer.kind !== 'tap') {
    return false;
  }
  const tap = recognizer as TapGestureRecognizer;
  return tap.numberOfTapsRequired === 1 && tap.numberOfTouchesRequired === 1;
}

/**
 * A control's touch tracking, the gesture host's consumer for one element
 * (UIControl's `beginTracking` / `continueTracking` / `endTracking`): it
 * reports control events and the highlight, and keeps a continuous-tracking
 * control's touch. Built by {@link createPressTracker}.
 */
export interface PressTracker extends TouchConsumer {
  /** Whether the control paints its pressed highlight now. */
  readonly isHighlighted: boolean;
  /** Whether a touch is being tracked. */
  readonly isTracking: boolean;
  /** Whether the tracked touch is inside the bounds plus the expansion. */
  readonly isTouchInside: boolean;
  /**
   * How far past its bounds a tracked touch still counts as inside, px; its
   * hook keeps it in step with the option.
   */
  trackingExpansion: number;
  /**
   * Whether the control takes touches now: a disabled one gives the host no
   * reason to listen (`spec:AST-094` FR24).
   */
  isEnabled(): boolean;
  allowsAncestorRecognizer(recognizer: unknown): boolean;
  /** Drop any highlight and timers (the control unmounted or was disabled). */
  dispose(): void;
  /**
   * Present only for a continuous-tracking control created with
   * `keepsTouch: true` (a held stepper): once its press is delivered, the
   * browser's pan must not take the touch. A plain pressable leaves it
   * undefined and keeps passive listeners, so a scroll starting on it never
   * waits on the main thread.
   */
  readonly keepsTouch?: (touchId: number) => boolean;
  /** The selection lock of a control whose hold acts (FR41); see the option. */
  readonly selectionLock: SelectionLock | undefined;
}

/** Track a control's touches (see {@link PressTracker}). */
export function createPressTracker(options: PressTrackerOptions): PressTracker {
  let isKept = false;
  let touchId: number | null = null;
  let bounds: PressBounds | null = null;
  let highlightTimer: ReturnType<typeof setTimeout> | null = null;
  let flashTimer: ReturnType<typeof setTimeout> | null = null;
  /** A pending highlight whose finger travelled: it will never paint. */
  let isPendingDead = false;

  const state = {
    isHighlighted: false,
    isTracking: false,
    isTouchInside: false,
  };
  const contains = (touch: GestureTouch): boolean => {
    if (bounds == null) {
      return true;
    }
    const margin = tracker.trackingExpansion;
    return (
      touch.x >= bounds.left - margin &&
      touch.x <= bounds.right + margin &&
      touch.y >= bounds.top - margin &&
      touch.y <= bounds.bottom + margin
    );
  };

  const emit = (event: ControlEvent, touch: GestureTouch): void => {
    options.onControlEvent?.(event, touch);
  };

  const setHighlighted = (value: boolean): void => {
    if (value && touchId != null) {
      // Delivered: the control keeps this touch until it ends (also when a
      // quick tap's flash is still showing as the press arrives).
      isKept = true;
    }
    if (state.isHighlighted === value) {
      return;
    }
    state.isHighlighted = value;
    options.onHighlightChange?.(value);
  };

  const clearHighlightTimer = (): void => {
    if (highlightTimer != null) {
      clearTimeout(highlightTimer);
      highlightTimer = null;
    }
  };

  const clearFlash = (): void => {
    if (flashTimer != null) {
      clearTimeout(flashTimer);
      flashTimer = null;
    }
  };

  const finish = (): void => {
    // A highlight shown at the lift (a quick tap's flash) keeps nothing.
    isKept = false;
    touchId = null;
    state.isTracking = false;
    state.isTouchInside = false;
    bounds = null;
  };

  const touchCancelled = (touch: GestureTouch): void => {
    if (touch.id !== touchId) {
      return;
    }
    isKept = false;
    clearHighlightTimer();
    emit('touchCancel', touch);
    setHighlighted(false);
    finish();
  };

  const tracker: PressTracker = {
    get isHighlighted() {
      return state.isHighlighted;
    },
    get isTracking() {
      return state.isTracking;
    },
    get isTouchInside() {
      return state.isTouchInside;
    },
    trackingExpansion:
      options.trackingExpansion ?? UIKIT_CONTROL.trackingExpansion.value,

    isEnabled(): boolean {
      return options.isEnabled?.() !== false;
    },

    holdsContextMenu(id: number): boolean {
      return options.holdsContextMenu?.(id) === true;
    },

    touchBegan(touch: GestureTouch): void {
      if (
        touchId != null ||
        options.isEnabled?.() === false ||
        // The scroll brake is a finger's (`spec:AST-094` FR11, DEC-21).
        (touch.pointerType === 'touch' && options.isBraking?.(touch) === true)
      ) {
        return;
      }
      clearFlash();
      touchId = touch.id;
      bounds = options.getBounds();
      state.isTracking = true;
      state.isTouchInside = true;
      isPendingDead = false;
      emit('touchDown', touch);
      const delay = options.highlightDelay ?? 'inScrollers';
      const delays =
        touch.pointerType === 'touch' &&
        (delay === 'always' ||
          (delay === 'inScrollers' && touch.scroll?.isInsideScroller === true));
      if (delays) {
        // The delay counts from the touch, so the time a busy main thread
        // took to deliver it comes off the wait. The touch's time is on the
        // clock of its own window, which can be an iframe's.
        const wait = Math.max(
          0,
          PRESS.contentTouchDelay.value -
            msSinceInput(touch.time, touch.target),
        );
        highlightTimer = setTimeout(() => {
          highlightTimer = null;
          if (state.isTouchInside) {
            setHighlighted(true);
          }
        }, wait);
      } else {
        setHighlighted(true);
      }
    },

    touchMoved(touch: GestureTouch): void {
      if (touch.id !== touchId) {
        return;
      }
      const cancelTravel = options.cancelTravel;
      if (cancelTravel != null && travel(touch) > cancelTravel) {
        // A cell's scroll view took the touch: the press is over.
        touchCancelled(touch);
        return;
      }
      if (highlightTimer != null && travel(touch) > PRESS.slop.value) {
        // A finger travelling before the delay ran out is scrolling: the
        // press it began never paints, as a flick on a list paints nothing.
        clearTimeout(highlightTimer);
        highlightTimer = null;
        isPendingDead = true;
      }
      const inside = contains(touch);
      if (inside !== state.isTouchInside) {
        state.isTouchInside = inside;
        emit(inside ? 'touchDragEnter' : 'touchDragExit', touch);
        if (highlightTimer == null && !isPendingDead) {
          setHighlighted(inside);
        }
      }
      emit(inside ? 'touchDragInside' : 'touchDragOutside', touch);
    },

    touchEnded(touch: GestureTouch): void {
      if (touch.id !== touchId) {
        return;
      }
      isKept = false;
      const inside = contains(touch);
      const wasPending = highlightTimer != null;
      clearHighlightTimer();
      emit(inside ? 'touchUpInside' : 'touchUpOutside', touch);
      const flash = options.quickTapFlash ?? PRESS.quickTapFlash.value;
      if (wasPending && inside) {
        // Quicker than the delay: the highlight shows at the lift, for the
        // flash, or (a cell) straight into the release.
        setHighlighted(true);
        if (flash > 0) {
          flashTimer = setTimeout(() => {
            flashTimer = null;
            setHighlighted(false);
          }, flash);
        } else {
          setHighlighted(false);
        }
      } else {
        setHighlighted(false);
      }
      finish();
    },

    touchCancelled,

    allowsAncestorRecognizer(recognizer: unknown): boolean {
      const candidate = recognizer as GestureRecognizer;
      if (candidate.view != null && candidate.view === options.view) {
        return true;
      }
      const vetoes = options.vetoesAncestorRecognizer ?? vetoesSingleTap;
      return !vetoes(candidate);
    },

    dispose(): void {
      clearHighlightTimer();
      clearFlash();
      setHighlighted(false);
      finish();
    },

    get selectionLock() {
      return options.selectionLock;
    },
  };
  if (options.keepsTouch === true) {
    // Only the tracked touch whose press was delivered is kept.
    return Object.assign(tracker, {
      keepsTouch: (id: number) => isKept && touchId === id,
    });
  }
  return tracker;
}