@astryxdesign/core 0.7.5 → 0.7.6-canary.bb18c81

package/src/gestures/SwipeGestureRecognizer.ts

@@ -0,0 +1,193 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SwipeGestureRecognizer.ts
+ * @input Touches from a GestureArena
+ * @output Exports SwipeGestureRecognizer (UISwipeGestureRecognizer), its
+ *   options and direction type
+ * @position Discrete recognizer of packages/core/src/gestures
+ *
+ * Recognized WHILE the fingers move, as UIKit's is: as soon as the centroid
+ * has travelled `minimumDistance` along an allowed direction, within
+ * `maximumDuration` of touch-down, with off-axis travel no more than
+ * `maximumSecondaryMovement` px across it. Off-axis travel past that
+ * allowance, or the distance travelled the wrong way, rules a direction out;
+ * the swipe fails once every allowed direction is ruled out, as it does for
+ * too many fingers, the duration running out, and a lift before it was
+ * recognized.
+ */
+
+import {UIKIT_SWIPE} from '../motion/uikit/gestures';
+import {centroid} from './geometry';
+import {
+  GestureRecognizer,
+  type GestureRecognizerOptions,
+  type NativeTouchBehavior,
+} from './GestureRecognizer';
+import type {GestureEventContext, GestureTouch, Point} from './types';
+
+export type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+
+export interface SwipeGestureRecognizerOptions extends GestureRecognizerOptions<SwipeGestureRecognizer> {
+  /** @default ['right'] */
+  direction?: SwipeDirection | ReadonlyArray<SwipeDirection>;
+  /** @default 1 */
+  numberOfTouchesRequired?: number;
+  minimumDistance?: number;
+  maximumDuration?: number;
+  maximumSecondaryMovement?: number;
+}
+
+const SWIPE = UIKIT_SWIPE;
+
+export class SwipeGestureRecognizer extends GestureRecognizer {
+  directions: ReadonlyArray<SwipeDirection>;
+  numberOfTouchesRequired: number;
+  minimumDistance: number;
+  maximumDuration: number;
+  maximumSecondaryMovement: number;
+  /** The direction of the recognized swipe. */
+  recognizedDirection: SwipeDirection | null = null;
+
+  private origin: Point = {x: 0, y: 0};
+  /** Directions this touch's path has ruled out. */
+  private readonly ruledOut = new Set<SwipeDirection>();
+  /** The centroid at the previous move. */
+  private last: Point | null = null;
+
+  constructor(options: SwipeGestureRecognizerOptions = {}) {
+    super(options);
+    const direction = options.direction ?? ['right'];
+    this.directions = typeof direction === 'string' ? [direction] : direction;
+    this.numberOfTouchesRequired = options.numberOfTouchesRequired ?? 1;
+    this.minimumDistance =
+      options.minimumDistance ?? SWIPE.minimumDistance.value;
+    this.maximumDuration =
+      options.maximumDuration ?? SWIPE.maximumDuration.value;
+    this.maximumSecondaryMovement =
+      options.maximumSecondaryMovement ?? SWIPE.maximumSecondaryMovement.value;
+  }
+
+  override get isDiscrete(): boolean {
+    return true;
+  }
+
+  override get nativeTouchBehavior(): NativeTouchBehavior {
+    const horizontal = this.directions.some(
+      direction => direction === 'left' || direction === 'right',
+    );
+    const vertical = this.directions.some(
+      direction => direction === 'up' || direction === 'down',
+    );
+    return {
+      panX: !horizontal,
+      panY: !vertical,
+      pinchZoom: true,
+      doubleTapZoom: false,
+    };
+  }
+
+  protected override touchesBegan(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void {
+    if (this.numberOfTouches > this.numberOfTouchesRequired) {
+      this.setState('failed');
+      return;
+    }
+    if (this.numberOfTouches === touches.length) {
+      this.setTimer(event.time + this.maximumDuration, () => {
+        // A swipe already recognized, waiting on a recognizer it requires to
+        // fail, holds its recognition (spec:AST-094 FR15).
+        if (this.pending == null) {
+          this.setState('failed');
+        }
+      });
+    }
+    // Measure from where every required finger is down.
+    this.origin = centroid(this.touches.values());
+    this.last = null;
+  }
+
+  protected override touchesMoved(): void {
+    if (
+      this.pending != null ||
+      this.numberOfTouches !== this.numberOfTouchesRequired
+    ) {
+      return;
+    }
+    const current = centroid(this.touches.values());
+    const from = this.last ?? this.origin;
+    this.last = current;
+    for (const direction of this.directions) {
+      if (this.ruledOut.has(direction)) {
+        continue;
+      }
+      // Along and across this direction at the start and the end of the
+      // move. The path between two events is read as a straight segment, so
+      // the verdict does not depend on how far apart the events were.
+      const [along0, across0] = this.project(direction, from);
+      const [along1, across1] = this.project(direction, current);
+      const reaches = segmentCrossing(along0, along1, this.minimumDistance);
+      const strays = Math.max(
+        segmentCrossing(across0, across1, this.maximumSecondaryMovement),
+        segmentCrossing(-across0, -across1, this.maximumSecondaryMovement),
+      );
+      const strayAt = strays < 0 ? Infinity : strays;
+      if (reaches >= 0 && reaches <= strayAt) {
+        this.recognizedDirection = direction;
+        this.setState('ended');
+        return;
+      }
+      // Off-axis travel past the allowance, or the distance the wrong way,
+      // rules a direction out for good.
+      if (strays >= 0 || along1 <= -this.minimumDistance) {
+        this.ruledOut.add(direction);
+      }
+    }
+    if (this.directions.every(direction => this.ruledOut.has(direction))) {
+      this.setState('failed');
+    }
+  }
+
+  /** Travel along and across `direction` from the origin to `point`. */
+  private project(direction: SwipeDirection, point: Point): [number, number] {
+    const dx = point.x - this.origin.x;
+    const dy = point.y - this.origin.y;
+    return direction === 'left'
+      ? [-dx, dy]
+      : direction === 'right'
+        ? [dx, dy]
+        : direction === 'up'
+          ? [-dy, dx]
+          : [dy, dx];
+  }
+
+  protected override touchesEnded(): void {
+    // Recognized and waiting, it holds past the lift (FR15).
+    if (this.pending == null) {
+      this.setState('failed');
+    }
+  }
+
+  protected override reset(): void {
+    this.recognizedDirection = null;
+    this.ruledOut.clear();
+    this.last = null;
+    this.origin = {x: 0, y: 0};
+  }
+}
+
+/**
+ * Where on the segment from `start` to `end` (0 to 1) the value first
+ * reaches `limit`; 0 when it starts there, -1 when it never does.
+ */
+function segmentCrossing(start: number, end: number, limit: number): number {
+  if (start >= limit) {
+    return 0;
+  }
+  if (end < limit) {
+    return -1;
+  }
+  return (limit - start) / (end - start);
+}

package/src/gestures/VelocityTracker.ts

@@ -88,15 +88,22 @@ export class VelocityTracker {
    * 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.
+   * 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): void {
+  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) {
+    if (last != null && x === last.x && y === last.y && !isMotion) {
       return;
     }
     if (last != null && time === last.time) {

package/src/gestures/__tests__/PanGestureRecognizer.test.ts

@@ -8,15 +8,15 @@
  */
 
 import {describe, expect, it} from 'vitest';
-import {UIKIT_GESTURES} from '../../motion/uikit/gestures';
+import {UIKIT_PAN, UIKIT_VELOCITY} from '../../motion/uikit/gestures';
 import {PanGestureRecognizer} from '../PanGestureRecognizer';
-import {createHarness, scrollProbe} from './harness';
+import {createHarness} from './harness';
 
 describe('PanGestureRecognizer', () => {
   it('begins past the hysteresis and leaves the threshold out of the translation', () => {
     const h = createHarness();
     const pan = new PanGestureRecognizer({name: 'pan'});
-    const hysteresis = UIKIT_GESTURES.pan.hysteresis.value;
+    const hysteresis = UIKIT_PAN.hysteresis.value;
     h.finger(1).down(100, 100, 0, {recognizers: [pan]});
     h.finger(1).move(100 + hysteresis - 0.1, 100, 16);
     expect(pan.state).toBe('possible');
@@ -75,7 +75,7 @@ describe('PanGestureRecognizer', () => {
   });
 
   it('releases at 0 after a rest longer than the stillness interval (AST-100 FR2)', () => {
-    const stillness = UIKIT_GESTURES.velocity.stillness.value;
+    const stillness = UIKIT_VELOCITY.stillness.value;
     const release = (liftAt: number) => {
       const h = createHarness();
       const pan = new PanGestureRecognizer({name: 'pan'});

package/src/gestures/__tests__/PinchGestureRecognizer.test.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file PinchGestureRecognizer.test.ts
+ * @input Synthetic touches with explicit timestamps through a GestureArena
+ * @output PinchGestureRecognizer's state machine: the hysteresis, the scale against the moved starting span, the velocity, extra fingers, re-basing
+ * @position Unit tests of packages/core/src/gestures/PinchGestureRecognizer.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {PinchGestureRecognizer} from '../PinchGestureRecognizer';
+import {createHarness} from './harness';
+
+describe('PinchGestureRecognizer', () => {
+  it('begins after the hysteresis and reports scale and velocity', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch]});
+    h.finger(2).move(205, 100, 16);
+    expect(pinch.state).toBe('possible');
+    h.finger(2).move(210, 100, 32);
+    expect(pinch.state).toBe('began');
+    // UIKit: against the starting span moved by the hysteresis (100 + 8).
+    expect(pinch.scale).toBeCloseTo(110 / 108, 5);
+    for (let t = 48; t <= 160; t += 16) {
+      h.finger(2).move(210 + (t - 32) * 0.1, 100, t);
+    }
+    // 0.1 px/ms over 108 px.
+    expect(pinch.velocity).toBeCloseTo(100 / 108, 5);
+    h.finger(1).up(170);
+    expect(h.log).toContain('pinch:ended@170');
+  });
+
+  it('ignores a third finger and can be re-based', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    h.finger(1).down(0, 0, 0, {recognizers: [pinch]});
+    h.finger(2).down(100, 0, 0, {recognizers: [pinch]});
+    h.finger(3).down(50, 50, 5, {recognizers: [pinch]});
+    expect(pinch.numberOfTouches).toBe(2);
+    h.finger(2).move(150, 0, 16);
+    pinch.scale = 1;
+    h.finger(2).move(300, 0, 32);
+    expect(pinch.scale).toBeCloseTo(2, 5);
+  });
+
+  it('lets the velocity settle when the span holds while the fingers move', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch]});
+    let time = 0;
+    for (let x = 210; x <= 260; x += 10) {
+      time += 16;
+      h.finger(2).move(x, 100, time);
+    }
+    const spreading = pinch.velocity;
+    expect(spreading).toBeGreaterThan(0);
+    // The second finger circles the first at exactly the same distance (160:
+    // 3-4-5 triangles), so the span holds while it moves.
+    for (const [dx, dy] of [
+      [128, 96],
+      [96, 128],
+      [0, 160],
+      [-96, 128],
+      [-128, 96],
+    ]) {
+      time += 16;
+      h.finger(2).move(100 + dx, 100 + dy, time);
+    }
+    expect(Math.abs(pinch.velocity)).toBeLessThan(spreading * 0.25);
+  });
+});