Skip to content

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

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

/**
 * @file pressGesture.ts
 * @input A press gesture's current phase and one pointer, key or timer event
 * @output Exports the press state machine (pressGestureStep, idlePressGesture),
 *   its clocks (PRESS_ONSET_MS, PRESS_SLOP_PX, PRESS_FLASH_MS, PRESS_FADE_MS,
 *   PRESS_SCROLL_BRAKE_MS) and their types
 * @position Pure half of the touch press model; driven by pressFeedback.ts,
 *   tested by pressGesture.test.ts without a browser
 *
 * SYNC: When modified, update pressFeedback.ts (the controller) and
 * pressGesture.test.ts.
 */

// A native list delays a press by 0.15 s, cancels it when a scroll claims the
// gesture, never brings it back in that gesture, and fades it only on
// release. On iOS Safari, CSS `:active` paints at once and stays painted into
// a scroll. So on a coarse pointer this machine owns the pressed state, and
// `:active` keeps only the mouse. The stylesheet drops `:active` by the
// primary pointer, so a mouse, trackpad or Space press on such a device comes
// here as `buttonDown`: painted at once and faded on release.
//
// Only a finger inside a scroller waits. The controller tells the machine
// which touch waits (`down`'s `delayed`), and a touch that does not wait goes
// straight to `pressed`. After that the machine is the same.
//
// The constants were measured against native apps. The machine knows nothing
// of the DOM, so {@link pressGestureStep}'s cases are the state diagram.

import {resolveTokenReferences} from '../theme/tokenReferences';
import {durationDefaults} from '../theme/tokens.stylex';

/**
 * How long a finger must stay put before the surface believes it.
 *
 * UIKit's own number: `UIScrollView.delaysContentTouches` holds a content
 * touch for 0.15 s. Measured rather than taken on faith: a 1.5 s hold on a
 * Settings row painted the native highlight for 1.34 s, a 1.2 s hold for
 * 1.24 s. It is the whole reason a flick paints nothing: the scroller claims
 * a fling about 30 ms in, which is inside this window.
 */
export const PRESS_ONSET_MS = 150;

/**
 * How far a finger may travel and still be a press, in CSS pixels.
 *
 * iOS Safari's own scroller claims the gesture at about this distance (the
 * measured slow drag got its `pointercancel` after ~12 px of travel).
 * Cancelling on the distance as well as on the claim keeps the two in step
 * when the scroller is slower to decide: a list already at its end, a
 * horizontal drag on a vertical scroller.
 */
export const PRESS_SLOP_PX = 10;

/**
 * How long a too-quick tap holds the paint at full strength before fading.
 *
 * A UIKit scroll view forwards the delayed touch and the release together
 * when the finger lifts early, so the cell highlights AT THE LIFT and the
 * paint is still there while the next screen slides over it. Without this
 * the most common interaction there is would answer with nothing at all.
 */
export const PRESS_FLASH_MS = 100;

/**
 * How long the paint takes to leave after a release when no theme sets
 * `--duration-exit`: that token's default. The release plays the theme's
 * exit motion tokens, so the controller reads the token on
 * the pressed element (`pressFadeMs` in pressFeedback.ts) and falls back to
 * this. When the clock runs out, the controller waits for a release
 * animation that still runs, then removes the attribute.
 */
export const PRESS_FADE_MS: number = Number.parseFloat(
  resolveTokenReferences(durationDefaults)['--duration-exit'],
);

/**
 * How recently a scroller must have moved for a touch on it to be a BRAKE
 * rather than a press.
 *
 * Measured: a touch landing on a list that was still decelerating stopped it
 * and highlighted nothing. On the web that touch ends the momentum, so no
 * further scroll event arrives to cancel the press, and without this the
 * paint would arrive 150 ms after a finger that was only stopping the list.
 */
export const PRESS_SCROLL_BRAKE_MS = 150;

/** What the surface should be painting. `fading` is the release's exit. */
export type PressPaint = 'none' | 'on' | 'fading';

/**
 * Where a gesture is.
 *
 * `dead` is the load-bearing one: a gesture that became a scroll stays dead
 * until the finger lifts and a new one starts, so a finger that stops moving,
 * or comes back to the control it started on, paints nothing. That is the
 * difference between this and `:active`.
 *
 * `buttonHeld` is a press made with a mouse button or the Space key. No
 * scroller can claim one, so it paints at once, travel does not end it, and
 * only the release does.
 */
export type PressPhase =
  'idle' | 'armed' | 'pressed' | 'buttonHeld' | 'flash' | 'fading' | 'dead';

export interface PressGesture {
  readonly phase: PressPhase;
  /** Where the finger landed, in client coordinates. */
  readonly originX: number;
  readonly originY: number;
}

export type PressEvent =
  | {
      kind: 'down';
      x: number;
      y: number;
      /**
       * Whether this touch waits {@link PRESS_ONSET_MS} before it paints:
       * a surface inside a scroller. Defaults to
       * `true`.
       */
      delayed?: boolean;
    }
  /**
   * A mouse button or the Space key went down on the surface. The
   * controller sends this only where the stylesheet has dropped `:active`
   * (a coarse primary pointer), which would otherwise paint it.
   */
  | {kind: 'buttonDown'}
  /** A touch point moved. Coordinates are client-space, like the origin. */
  | {kind: 'move'; x: number; y: number}
  | {kind: 'up'}
  /** The platform took the gesture away: `pointercancel`, `touchcancel`, a scroll, a drag. */
  | {kind: 'cancel'}
  /** {@link PRESS_ONSET_MS} elapsed with the finger still down. */
  | {kind: 'onset'}
  /** {@link PRESS_FLASH_MS} elapsed on a too-quick tap. */
  | {kind: 'flashEnd'}
  /** The release is over: its animation ended, or its clock ran out with none running. */
  | {kind: 'fadeEnd'};

export interface PressStep {
  readonly gesture: PressGesture;
  readonly paint: PressPaint;
  /**
   * The timer this step wants armed.
   *
   * `null` means "arm nothing NEW", which is not the same as "cancel what is
   * running": a step that returns `null` without changing phase is a
   * pass-through, and the phase it leaves running still owes its transition
   * (`armed` owes `onset`, `flash` owes `flashEnd`, `fading` owes `fadeEnd`).
   * The caller keeps a pending timer across such a step and drops it only
   * when the phase moves; `pressFeedback.ts` says what stranding one costs.
   */
  readonly timer: 'onset' | 'flash' | 'fade' | null;
}

const IDLE: PressGesture = {originX: 0, originY: 0, phase: 'idle'};

/** A finger that has gone this far is scrolling, not pressing. */
function travelled(gesture: PressGesture, x: number, y: number): boolean {
  return Math.hypot(x - gesture.originX, y - gesture.originY) > PRESS_SLOP_PX;
}

function step(
  gesture: PressGesture,
  phase: PressPhase,
  paint: PressPaint,
  timer: PressStep['timer'],
): PressStep {
  return {gesture: {...gesture, phase}, paint, timer};
}

/**
 * One event, one answer.
 *
 * The caller owns the DOM and the clock, and nothing here reads either, so a
 * test drives the whole contract by handing it events.
 */
export function pressGestureStep(
  gesture: PressGesture,
  event: PressEvent,
): PressStep {
  if (event.kind === 'down') {
    // A surface with no scroller above it: nothing can turn this touch into a
    // scroll, so it paints in the frame it lands, as a UIControl highlights.
    if (event.delayed === false) {
      return {
        gesture: {originX: event.x, originY: event.y, phase: 'pressed'},
        paint: 'on',
        timer: null,
      };
    }
    // A new touch always starts armed and painting nothing, whatever the last
    // gesture ended as. This is the only way out of `dead`.
    return {
      gesture: {originX: event.x, originY: event.y, phase: 'armed'},
      paint: 'none',
      timer: 'onset',
    };
  }
  if (event.kind === 'buttonDown') {
    // Nothing can turn a mouse button or a key into a scroll, so there is
    // nothing to wait for: paint now, as `:active` does on a desktop.
    return {
      gesture: {originX: 0, originY: 0, phase: 'buttonHeld'},
      paint: 'on',
      timer: null,
    };
  }

  switch (gesture.phase) {
    case 'armed':
      if (event.kind === 'move') {
        // Travel is a scroll. Nothing was painted, so nothing is removed; the
        // gesture is simply over.
        return travelled(gesture, event.x, event.y)
          ? step(gesture, 'dead', 'none', null)
          : {gesture, paint: 'none', timer: null};
      }
      // The scroller claimed it before the delay elapsed: the fling case, and
      // the reason a flick paints nothing at all.
      if (event.kind === 'cancel') {
        return step(gesture, 'dead', 'none', null);
      }
      // The finger stayed. Paint, instantly and completely.
      if (event.kind === 'onset') {
        return step(gesture, 'pressed', 'on', null);
      }
      // Too quick for the delay. UIKit forwards the held touch and the release
      // together, so the paint appears HERE, at the lift.
      if (event.kind === 'up') {
        return step(gesture, 'flash', 'on', 'flash');
      }
      return {gesture, paint: 'none', timer: null};

    case 'pressed':
      if (event.kind === 'move' && !travelled(gesture, event.x, event.y)) {
        // A press with a shaky hand is still a press: measured, a 4 pt drag
        // over 2 s kept the native highlight for the whole gesture.
        return {gesture, paint: 'on', timer: null};
      }
      // A cancel removes the paint with no transition, one frame BEFORE the
      // list moves.
      if (event.kind === 'move' || event.kind === 'cancel') {
        return step(gesture, 'dead', 'none', null);
      }
      // A release fades.
      if (event.kind === 'up') {
        return step(gesture, 'fading', 'fading', 'fade');
      }
      return {gesture, paint: 'on', timer: null};

    case 'buttonHeld':
      // Travel is not a scroll here (a mouse dragged off a button keeps its
      // `:active` until the button comes up), so only the release ends the
      // press, with the same fade a finger's release gets.
      if (event.kind === 'up') {
        return step(gesture, 'fading', 'fading', 'fade');
      }
      // The platform took it (a drag began, the pointer was cancelled): the
      // paint goes at once, as for a finger.
      if (event.kind === 'cancel') {
        return step(gesture, 'dead', 'none', null);
      }
      return {gesture, paint: 'on', timer: null};

    case 'flash':
      // The full-strength hold is over; hand it to the same fade a long press
      // gets, so both releases leave the same way.
      if (event.kind === 'flashEnd') {
        return step(gesture, 'fading', 'fading', 'fade');
      }
      // The finger is already up. A cancel here is the platform tidying up
      // after the tap (iOS sends `pointercancel` at `scrollend`), and it must
      // not clip the answer the tap earned.
      return {gesture, paint: 'on', timer: null};

    case 'fading':
      if (event.kind === 'fadeEnd') {
        return {gesture: IDLE, paint: 'none', timer: null};
      }
      return {gesture, paint: 'fading', timer: null};

    case 'dead':
      // The finger lifting is what ends a cancelled gesture: until it does, a
      // second finger is a second finger and not a press. Resolving to idle
      // here is what lets the NEXT touch be heard at all; without it a gesture
      // that became a scroll holds the controller's one slot for ever, and
      // every press after the first scroll answers with nothing.
      if (event.kind === 'up') {
        return {gesture: IDLE, paint: 'none', timer: null};
      }
      return {gesture, paint: 'none', timer: null};

    case 'idle':
      // Only a touch (handled above) starts a gesture; anything else while
      // idle is a stray timer or a release with nothing to release.
      return {gesture: IDLE, paint: 'none', timer: null};
  }
}

export function idlePressGesture(): PressGesture {
  return IDLE;
}