Skip to content

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

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

/**
 * @file VelocityTracker.ts
 * @input Timestamped positions of a moving contact, and the release time
 * @output Exports VelocityTracker, the one velocity tracker every continuous
 *   recognizer uses (architecture:interaction-modality INV10,
 *   spec:AST-100 FR1, FR2)
 * @position Pure math under packages/core/src/gestures; no DOM
 *
 * What a release hands to a spring or a deceleration: the finger's velocity
 * when it lifted, in px per SECOND (UIKit's unit for `velocity(in:)`).
 *
 * One filter, iOS's measured blend, updated on each MOVED sample (a sample
 * at the newest position is not motion):
 *
 * - A pan's velocity is 0.2 times the newest interval's velocity plus 0.8
 *   times the previous interval's (an interval runs from one moved sample to
 *   the next; the touch-down counts as the first). With one interval so far
 *   it is that interval, as UIKit reports it. It reproduces every value
 *   UIKit reported on six HID streams, and like UIKit's it reacts a frame
 *   late to an acceleration.
 * - A scrolling surface's release (paging, a wheel) is 0.25 times the newest
 *   pan value plus 0.75 times the previous one.
 *
 * A release (`velocity(releaseTime)`, `scrollVelocity(releaseTime)`) reads 0
 * when the contact was still for longer than the stillness interval before
 * lifting, the one difference from iOS, whose filter never decays and so
 * flings after a rest; and 0 with fewer than two moved samples.
 *
 * Feed it one sample per input event: coalesced samples would change its
 * timing.
 *
 * SYNC: When modified, update VelocityTracker.test.ts.
 */

import {UIKIT_VELOCITY} from '../motion/uikit/gestures';
import type {Point, TouchSample} from './types';

export interface VelocityTrackerOptions {
  /**
   * A contact that has not moved for longer than this (ms) before its
   * release releases at 0 (spec:AST-100 FR2).
   */
  stillness?: number;
}

const ZERO: Point = {x: 0, y: 0};
const PAN_CURRENT_WEIGHT = UIKIT_VELOCITY.currentWeight.value;
const SCROLL_CURRENT_WEIGHT = UIKIT_VELOCITY.scrollReleaseWeight.value;

function blend(weight: number, current: Point, previous: Point): Point {
  return {
    x: weight * current.x + (1 - weight) * previous.x,
    y: weight * current.y + (1 - weight) * previous.y,
  };
}

export class VelocityTracker {
  private readonly stillness: number;
  /** The newest sample added, moved or not. */
  private newest: TouchSample | null = null;
  /**
   * The newest moved samples, oldest first (the touch-down counts as the
   * first); the filter reads the last three.
   */
  private moved: TouchSample[] = [];
  /** Moved samples since the touch-down. */
  private moves = 0;
  /** The newest pan value, and the one before it. */
  private pan: Point = ZERO;
  private previousPan: Point = ZERO;

  constructor(options: VelocityTrackerOptions = {}) {
    this.stillness = options.stillness ?? UIKIT_VELOCITY.stillness.value;
  }

  /** Forget every sample (a new gesture). */
  reset(): void {
    this.newest = null;
    this.moved = [];
    this.moves = 0;
    this.pan = ZERO;
    this.previousPan = ZERO;
  }

  /**
   * Record a position. Timestamps must not go backwards (an older sample is
   * ignored), and a moved sample at the newest moved sample's timestamp
   * replaces it. A sample at the newest position is not motion: it changes
   * no velocity, unless `isMotion` says the contact moved anyway (a pinch's
   * value holding while both fingers move, which reads as zero velocity for
   * that interval).
   */
  add(
    x: number,
    y: number,
    time: number,
    {isMotion = false}: {isMotion?: boolean} = {},
  ): void {
    if (this.newest != null && time < this.newest.time) {
      return;
    }
    this.newest = {x, y, time};
    const last = this.moved[this.moved.length - 1];
    if (last != null && x === last.x && y === last.y && !isMotion) {
      return;
    }
    if (last != null && time === last.time) {
      this.moved[this.moved.length - 1] = {x, y, time};
    } else {
      this.moved.push({x, y, time});
      if (this.moved.length > 3) {
        this.moved.shift();
      }
      if (last != null) {
        this.moves += 1;
        this.previousPan = this.pan;
      }
    }
    this.pan = panVelocity(this.moved);
  }

  /**
   * Re-base the samples by an offset (a recognizer whose value was set
   * mid-gesture): every interval, the moved-sample count and the velocity
   * carry on unchanged.
   */
  offsetBy(dx: number, dy: number): void {
    const shift = (sample: TouchSample): TouchSample => ({
      ...sample,
      x: sample.x + dx,
      y: sample.y + dy,
    });
    this.newest = this.newest == null ? null : shift(this.newest);
    this.moved = this.moved.map(shift);
  }

  /**
   * Re-base the samples by a factor (a pinch whose scale was set
   * mid-gesture): positions and velocities scale with it, and the
   * moved-sample count carries on.
   */
  scaleBy(factor: number): void {
    const scale = (sample: TouchSample): TouchSample => ({
      ...sample,
      x: sample.x * factor,
      y: sample.y * factor,
    });
    this.newest = this.newest == null ? null : scale(this.newest);
    this.moved = this.moved.map(scale);
    this.pan = {x: this.pan.x * factor, y: this.pan.y * factor};
    this.previousPan = {
      x: this.previousPan.x * factor,
      y: this.previousPan.y * factor,
    };
  }

  /** Record every sample in order. */
  addSamples(samples: ReadonlyArray<TouchSample>): void {
    for (const sample of samples) {
      this.add(sample.x, sample.y, sample.time);
    }
  }

  /** The newest sample, if any. */
  get lastSample(): TouchSample | null {
    return this.newest;
  }

  /**
   * The pan's velocity in px/s. Pass the release's event time to read the
   * release velocity of a dragged surface: 0 after a rest longer than the
   * stillness interval, or with fewer than two moved samples (AST-100 FR2).
   */
  velocity(releaseTime?: number): Point {
    if (releaseTime != null && !this.releases(releaseTime)) {
      return ZERO;
    }
    return this.pan;
  }

  /**
   * A scrolling surface's release velocity in px/s (paging, a wheel): 0.25
   * times the newest pan value plus 0.75 times the previous one, with the
   * same stillness and two-moved-sample rules (AST-100 FR2).
   */
  scrollVelocity(releaseTime: number): Point {
    if (!this.releases(releaseTime)) {
      return ZERO;
    }
    return blend(SCROLL_CURRENT_WEIGHT, this.pan, this.previousPan);
  }

  private releases(releaseTime: number): boolean {
    const last = this.moved[this.moved.length - 1];
    return (
      this.moves >= 2 &&
      last != null &&
      releaseTime - last.time <= this.stillness
    );
  }
}

/**
 * UIPanGestureRecognizer's filter over the newest moved samples: 0.2 x the
 * newest interval's velocity + 0.8 x the previous one's; one interval so far
 * is reported whole, as UIKit does.
 */
function panVelocity(moved: ReadonlyArray<TouchSample>): Point {
  const n = moved.length;
  if (n < 2) {
    return ZERO;
  }
  const current = pairVelocity(moved[n - 2], moved[n - 1]);
  if (n === 2) {
    return current;
  }
  return blend(
    PAN_CURRENT_WEIGHT,
    current,
    pairVelocity(moved[n - 3], moved[n - 2]),
  );
}

/** Instantaneous velocity (px/s) between two samples, zero across no time. */
function pairVelocity(start: TouchSample, end: TouchSample): Point {
  const dt = end.time - start.time;
  if (dt <= 0) {
    return ZERO;
  }
  return {
    x: ((end.x - start.x) / dt) * 1000,
    y: ((end.y - start.y) / dt) * 1000,
  };
}