@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

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

@@ -0,0 +1,193 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file arenaPinchSwipeEdge.test.ts
+ * @input GestureArena with pinches, swipes, edge pans and pans, driven by
+ *   synthetic touches with explicit timestamps
+ * @output Simultaneous recognition (pinch + pan), the first to recognize
+ *   winning without permission, edge pan vs inner pan, swipe vs pan, and a
+ *   delayed touch delivery
+ * @position Unit tests of packages/core/src/gestures/GestureArena.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {UIKIT_PINCH, UIKIT_SWIPE} from '../../motion/uikit/gestures';
+import {GestureRecognizer} from '../GestureRecognizer';
+import {PanGestureRecognizer} from '../PanGestureRecognizer';
+import {PinchGestureRecognizer} from '../PinchGestureRecognizer';
+import {ScreenEdgePanGestureRecognizer} from '../ScreenEdgePanGestureRecognizer';
+import {SwipeGestureRecognizer} from '../SwipeGestureRecognizer';
+import {createHarness, RecordingConsumer} from './harness';
+
+/**
+ * A recognizer that stays possible, even past its finger's lift, until the
+ * test fails it: something another recognizer can wait on.
+ */
+class Held extends GestureRecognizer {
+  // Possible until failed, as a tap waiting for its next tap.
+  override get kind(): GestureRecognizer['kind'] {
+    return 'tap';
+  }
+
+  private isWaiting = true;
+
+  override isInvolved(): boolean {
+    return super.isInvolved() || this.isWaiting;
+  }
+
+  fail(): void {
+    this.isWaiting = false;
+    this.setState('failed');
+  }
+}
+
+describe('conflict matrix', () => {
+  it('pinch + pan recognize simultaneously when allowed', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    pinch.recognizeSimultaneouslyWith(pan);
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(1).move(80, 120, 16);
+    h.finger(2).move(240, 120, 16);
+    expect(h.log.slice(0, 2)).toEqual(['pinch:began@16', 'pan:began@16']);
+    // Span 100 -> 160, measured against 100 + 8.
+    expect(pinch.scale).toBeCloseTo(160 / 108, 5);
+    // The pan began at the first finger's move, centroid (-10, 10), which
+    // the hysteresis swallows; the second finger's move brought it to (10, 20).
+    expect(pan.translation()).toEqual({x: 20, y: 10});
+  });
+
+  it('pinch vs pan without permission: the first to recognize wins', () => {
+    const h = createHarness();
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch, pan]});
+    h.finger(1).move(80, 120, 16);
+    h.finger(2).move(240, 120, 16);
+    expect(h.log.slice(0, 2)).toEqual(['pinch:began@16', 'pan:failed@16']);
+  });
+
+  it('edge pan vs inner pan: in the band the edge pan wins, elsewhere the inner pan runs undelayed', () => {
+    const band = createHarness();
+    const edge = new ScreenEdgePanGestureRecognizer({name: 'edge'});
+    const inner = new PanGestureRecognizer({
+      name: 'inner',
+      direction: 'horizontal',
+    });
+    inner.requireToFail(edge);
+    // A thin edge view: the edge zone, where the pan takes its axis.
+    band.environment.view = {width: edge.edgeRegion, height: 844};
+    band.finger(1).down(8, 300, 0, {recognizers: [inner, edge]});
+    band.finger(1).drag(60, 2, 60, 6);
+    // The edge pan's own hysteresis is 15 px: the second 10 px step.
+    expect(band.log.slice(0, 2)).toEqual(['edge:began@20', 'inner:failed@20']);
+
+    const middle = createHarness();
+    const edge2 = new ScreenEdgePanGestureRecognizer({name: 'edge'});
+    const inner2 = new PanGestureRecognizer({
+      name: 'inner',
+      direction: 'horizontal',
+    });
+    inner2.requireToFail(edge2);
+    middle.finger(1).down(150, 300, 0, {recognizers: [inner2, edge2]});
+    // Failed at touch-down, before any movement: nothing waits on it.
+    expect(middle.log).toEqual(['edge:failed@0']);
+    middle.finger(1).drag(60, 2, 60, 6);
+    expect(middle.log[1]).toBe('inner:began@10');
+  });
+
+  it('swipe vs pan: the pan wins by default, the swipe when the pan requires it to fail', () => {
+    const plain = createHarness();
+    const swipe = new SwipeGestureRecognizer({name: 'swipe'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    plain
+      .finger(1)
+      .down(0, 0, 0, {recognizers: [swipe, pan]})
+      .drag(80, 0, 60, 6);
+    expect(plain.log.slice(0, 2)).toEqual(['pan:began@10', 'swipe:failed@10']);
+
+    const ordered = createHarness();
+    const swipe2 = new SwipeGestureRecognizer({name: 'swipe'});
+    const pan2 = new PanGestureRecognizer({name: 'pan'});
+    pan2.requireToFail(swipe2);
+    ordered
+      .finger(1)
+      .down(0, 0, 0, {recognizers: [swipe2, pan2]})
+      .drag(80, 0, 60, 8);
+    expect(ordered.log.slice(0, 2)).toEqual([
+      'swipe:ended@37.5',
+      'pan:failed@37.5',
+    ]);
+
+    const slow = createHarness();
+    const swipe3 = new SwipeGestureRecognizer({name: 'swipe'});
+    const pan3 = new PanGestureRecognizer({name: 'pan'});
+    pan3.requireToFail(swipe3);
+    slow
+      .finger(1)
+      .down(0, 0, 0, {recognizers: [swipe3, pan3]})
+      .drag(30, 0, 300, 3);
+    expect(pan3.state).toBe('possible');
+    slow.advance(500);
+    // The swipe ran out of time; the waiting pan begins with what it has.
+    expect(slow.log.slice(0, 2)).toEqual(['swipe:failed@500', 'pan:began@500']);
+  });
+});
+
+describe('a recognizer waiting on another', () => {
+  it('a swipe holds its recognition past its lift and its deadline (spec:AST-094 FR15)', () => {
+    const h = createHarness();
+    const held = new Held({name: 'held'});
+    const swipe = new SwipeGestureRecognizer({name: 'swipe'});
+    swipe.requireToFail(held);
+    h.finger(1)
+      .down(0, 0, 0, {recognizers: [swipe, held]})
+      .drag(80, 0, 60, 8)
+      .up(70);
+    h.advance(UIKIT_SWIPE.maximumDuration.value + 100);
+    expect(swipe.state).toBe('possible');
+    expect(h.log.some(entry => entry.startsWith('swipe:failed'))).toBe(false);
+    held.fail();
+    expect(h.log).toContain(
+      `swipe:ended@${UIKIT_SWIPE.maximumDuration.value + 100}`,
+    );
+    expect(swipe.recognizedDirection).toBe('right');
+  });
+
+  it('a pinch keeps its start once it passes the hysteresis, so it begins at the scale its fingers show (spec:AST-094 FR15)', () => {
+    const h = createHarness();
+    const held = new Held({name: 'held'});
+    const pinch = new PinchGestureRecognizer({name: 'pinch'});
+    pinch.requireToFail(held);
+    h.finger(1).down(100, 100, 0, {recognizers: [pinch, held]});
+    h.finger(2).down(200, 100, 0, {recognizers: [pinch, held]});
+    // Span 100 -> 120 -> 140 -> 160 while the pinch waits.
+    h.finger(2).move(220, 100, 16);
+    h.finger(2).move(240, 100, 32);
+    h.finger(2).move(260, 100, 48);
+    expect(pinch.state).toBe('possible');
+    held.fail();
+    expect(h.log).toContain('pinch:began@48');
+    // Measured against 100 + 8 once, not re-based on every move.
+    const hysteresis = UIKIT_PINCH.hysteresis.value;
+    expect(pinch.scale).toBeCloseTo(160 / (100 + hysteresis), 5);
+  });
+});
+
+describe('delivery to the view', () => {
+  it('holds the began with delaysTouchesBegan until the recognizer fails', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const swipe = new SwipeGestureRecognizer({
+      name: 'swipe',
+      delaysTouchesBegan: true,
+    });
+    h.finger(1).down(0, 0, 0, {recognizers: [swipe], consumer});
+    expect(consumer.events).toEqual([]);
+    h.advance(UIKIT_SWIPE.maximumDuration.value);
+    expect(consumer.events).toEqual(['began:1']);
+  });
+});

package/src/gestures/__tests__/browser/build-fixture.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build-fixture.mjs
+ * @input fixture.ts beside this file
+ * @output A standalone HTML page (the fixture bundled inline) for running the
+ *   gesture proofs in any browser, including Mobile Safari on the iOS
+ *   simulator
+ * @position Test-only helper of packages/core/src/gestures
+ *
+ *   node packages/core/src/gestures/__tests__/browser/build-fixture.mjs out.html
+ *
+ * The page records every recognizer transition and every click on
+ * `window.__gestures`; read it with the Web Inspector or by evaluating
+ * `JSON.stringify(window.__gestures)`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {build} from 'esbuild';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const out = process.argv[2];
+if (out == null) {
+  console.error('usage: build-fixture.mjs <out.html>');
+  process.exit(1);
+}
+const result = await build({
+  entryPoints: [path.join(here, 'fixture.ts')],
+  bundle: true,
+  write: false,
+  format: 'iife',
+  platform: 'browser',
+  target: 'es2022',
+});
+const html = `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Gesture fixture</title>
+<body></body>
+<script>${result.outputFiles[0].text.replaceAll('</script', '<\\/script')}</script>
+`;
+fs.writeFileSync(out, html);
+console.log(`wrote ${out} (${html.length} bytes)`);

package/src/gestures/__tests__/browser/fixture.ts

@@ -0,0 +1,307 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file fixture.ts
+ * @input Nothing: bundled by esbuild and injected into a blank page
+ * @output A page of gesture hosts (a horizontal pan inside a scroller, a tap
+ *   target, a long press, a pinch, a sheet body that hands its scroll to a
+ *   pan, a passive control: a press consumer under `pan-y` with no
+ *   recognizer, pans and a long press under narrower author `touch-action`
+ *   values, and leading screen-edge pans on an edge-zone strip and on a wider
+ *   element, left to right and right to left) that records every recognizer
+ *   transition, every consumer event and every click on `window.__gestures`
+ * @position Browser fixture of gestures.interaction.browser.spec.ts;
+ *   test-only
+ */
+
+import {getGestureHost} from '../../GestureHost';
+import type {GestureRecognizer} from '../../GestureRecognizer';
+import {LongPressGestureRecognizer} from '../../LongPressGestureRecognizer';
+import {PanGestureRecognizer} from '../../PanGestureRecognizer';
+import {PinchGestureRecognizer} from '../../PinchGestureRecognizer';
+import {ScreenEdgePanGestureRecognizer} from '../../ScreenEdgePanGestureRecognizer';
+import {TapGestureRecognizer} from '../../TapGestureRecognizer';
+
+interface Entry {
+  name: string;
+  state: string;
+  time: number;
+  x?: number;
+  y?: number;
+  scale?: number;
+  beganAt?: number | null;
+  startedAt?: number;
+}
+
+interface ListenerEntry {
+  id: string;
+  type: string;
+  passive: boolean | null;
+}
+
+declare global {
+  interface Window {
+    __gestures: Entry[];
+    __listeners: ListenerEntry[];
+    /** The page-level (document and window) listeners now added, by type. */
+    __pageListeners: Map<string, number>;
+    /** The page-level listener types the attachments below added. */
+    __attachListeners: string[];
+  }
+}
+
+window.__gestures = [];
+
+// Every touch listener added to an element with an id, as the engine sees
+// it: which elements make a scroll wait for the page.
+window.__listeners = [];
+// And every listener on the document or the window, added and removed: what
+// gesture work costs the page between presses (spec:AST-094 FR24).
+window.__pageListeners = new Map();
+const isPage = (target: EventTarget) =>
+  target === document || target === window;
+const addListener = EventTarget.prototype.addEventListener;
+EventTarget.prototype.addEventListener = function (
+  this: EventTarget,
+  type: string,
+  listener: EventListenerOrEventListenerObject | null,
+  options?: boolean | AddEventListenerOptions,
+) {
+  if (this instanceof Element && this.id !== '' && type.startsWith('touch')) {
+    window.__listeners.push({
+      id: this.id,
+      type,
+      passive: typeof options === 'object' ? (options.passive ?? null) : null,
+    });
+  }
+  if (isPage(this) && listener != null) {
+    window.__pageListeners.set(
+      type,
+      (window.__pageListeners.get(type) ?? 0) + 1,
+    );
+  }
+  addListener.call(this, type, listener, options);
+};
+const removeListener = EventTarget.prototype.removeEventListener;
+EventTarget.prototype.removeEventListener = function (
+  this: EventTarget,
+  type: string,
+  listener: EventListenerOrEventListenerObject | null,
+  options?: boolean | EventListenerOptions,
+) {
+  if (isPage(this) && listener != null) {
+    window.__pageListeners.set(
+      type,
+      (window.__pageListeners.get(type) ?? 0) - 1,
+    );
+  }
+  removeListener.call(this, type, listener, options);
+};
+
+document.body.style.margin = '0';
+document.body.innerHTML = `
+  <div id="page" style="font: 14px sans-serif">
+    <div id="scroller" style="height: 240px; overflow-y: auto; overscroll-behavior: contain; background: #eef">
+      <div style="height: 40px">scroller</div>
+      <div id="hpan" style="height: 140px; background: #ccd">
+        <button id="hbutton" style="width: 200px; height: 80px; margin: 30px">button</button>
+      </div>
+      <div id="scrollRow" style="height: 60px; background: #ece; touch-action: none">row (a press in the scroller)</div>
+      <div style="height: 1200px">content</div>
+    </div>
+    <div id="tapper" style="height: 60px; background: #efe">tap</div>
+    <div id="presser" style="height: 60px; background: #fee">press</div>
+    <div id="pinchable" style="height: 160px; background: #ffe">pinch</div>
+    <div id="sheetBody" style="height: 240px; overflow-y: auto; overscroll-behavior: contain; background: #eee">
+      <div style="height: 1200px">sheet content</div>
+    </div>
+    <div id="passive" style="height: 60px; background: #dfd; touch-action: pan-y pinch-zoom">passive control</div>
+    <div id="card" style="height: 80px; background: #def">card (swipe up)</div>
+    <style>
+      .author-none { touch-action: none; }
+      .author-pan-y { touch-action: pan-y; }
+      .author-pinch-zoom { touch-action: pinch-zoom; }
+      .author-pan-xy { touch-action: pan-x pan-y; }
+    </style>
+    <div id="authorNone" class="author-none" style="height: 60px; background: #fdd">author none</div>
+    <div id="authorPanY" class="author-pan-y" style="height: 60px; background: #dfd">author pan-y</div>
+    <div id="authorPinchZoom" class="author-pinch-zoom" style="height: 60px; background: #ffd">author pinch-zoom</div>
+    <div id="authorPanXY" class="author-pan-xy" style="height: 60px; background: #ddf">author pan-x pan-y</div>
+    <div id="inlinePanXY" style="height: 60px; background: #fdf; touch-action: pan-x pan-y">inline pan-x pan-y</div>
+    <div id="edgeZone" style="width: 40px; height: 120px; background: #fcf">edge</div>
+    <div id="edgeWide" style="width: 200px; height: 120px; overflow-x: auto; background: #cff">
+      <div style="width: 800px; height: 100px">wider than the band</div>
+    </div>
+    <div dir="rtl">
+      <div id="edgeZoneRtl" style="width: 40px; height: 120px; background: #fcf">edge</div>
+      <div id="edgeWideRtl" style="width: 200px; height: 120px; overflow-x: auto; background: #cff">
+        <div style="width: 800px; height: 100px">wider than the band</div>
+      </div>
+    </div>
+    <div style="height: 1600px">page</div>
+    <div id="passiveEnd" style="height: 60px; background: #dfd; touch-action: pan-y pinch-zoom">passive control at the page's end</div>
+  </div>`;
+
+function element(id: string): HTMLElement {
+  const found = document.getElementById(id);
+  if (found == null) {
+    throw new Error(`missing #${id}`);
+  }
+  return found;
+}
+
+const beforeAttach = new Map(window.__pageListeners);
+const host = getGestureHost(document);
+
+function record(recognizer: GestureRecognizer, extra: () => Partial<Entry>) {
+  recognizer.addTransitionListener((current, _from, to) => {
+    window.__gestures.push({
+      name: current.name,
+      state: to,
+      time: current.arena?.now() ?? performance.now(),
+      ...(to === 'possible' || to === 'failed' ? {} : extra()),
+    });
+  });
+}
+
+const hpan = new PanGestureRecognizer({name: 'hpan', direction: 'horizontal'});
+record(hpan, () => ({x: hpan.translation().x, y: hpan.translation().y}));
+host.attach(element('hpan'), hpan);
+
+const tap = new TapGestureRecognizer({name: 'tap'});
+record(tap, () => ({}));
+host.attach(element('tapper'), tap);
+
+const press = new LongPressGestureRecognizer({name: 'press'});
+record(press, () => ({
+  beganAt: press.beganAt,
+  startedAt: press.trackedTouches[0]?.startTime,
+}));
+host.attach(element('presser'), press);
+
+const pinch = new PinchGestureRecognizer({name: 'pinch'});
+const pinchPan = new PanGestureRecognizer({
+  name: 'pinchPan',
+  maximumNumberOfTouches: 2,
+});
+pinch.recognizeSimultaneouslyWith(pinchPan);
+record(pinch, () => ({scale: pinch.scale}));
+record(pinchPan, () => ({x: pinchPan.translation().x}));
+host.attach(element('pinchable'), pinch);
+host.attach(element('pinchable'), pinchPan);
+
+const sheet = new PanGestureRecognizer({
+  name: 'sheet',
+  direction: 'down',
+  scrollEdge: true,
+});
+record(sheet, () => ({y: sheet.translation().y}));
+host.attach(element('sheetBody'), sheet);
+
+// A one-way pan over the scrollable page, as a toast's upward swipe is: it
+// claims its touch as it begins, at UIKit's 10 pt (spec:AST-094 FR19).
+const card = new PanGestureRecognizer({name: 'card', direction: 'up'});
+record(card, () => ({x: card.translation().x, y: card.translation().y}));
+host.attach(element('card'), card);
+
+// Narrower author touch-action (spec:AST-094 FR18, DEC-8): the host's value
+// is the derived one intersected with the author's, never wider.
+const authorNone = new LongPressGestureRecognizer({name: 'authorNone'});
+record(authorNone, () => ({}));
+host.attach(element('authorNone'), authorNone);
+for (const id of [
+  'authorPanY',
+  'authorPinchZoom',
+  'authorPanXY',
+  'inlinePanXY',
+]) {
+  const pan = new PanGestureRecognizer({name: id, direction: 'horizontal'});
+  record(pan, () => ({x: pan.translation().x}));
+  host.attach(element(id), pan);
+}
+
+// Leading screen-edge pans (FR18, DEC-13): on an edge-zone strip within the
+// 40.2 px band and on an element reaching beyond it, left to right and, with
+// the leading edge on the right, right to left.
+for (const id of ['edgeZone', 'edgeWide', 'edgeZoneRtl', 'edgeWideRtl']) {
+  const edge = new ScreenEdgePanGestureRecognizer({
+    name: id,
+    edges: ['leading'],
+  });
+  record(edge, () => ({x: edge.translation().x}));
+  host.attach(element(id), edge);
+}
+
+// A control with no recognizer of its own (no blocking listener): only a
+// press consumer, under pan-y, as a passive switch is.
+const passiveEvent = (state: string) =>
+  window.__gestures.push({name: 'passive', state, time: performance.now()});
+host.attachConsumer(element('passive'), {
+  touchBegan: () => passiveEvent('began'),
+  touchMoved: () => passiveEvent('moved'),
+  touchEnded: () => passiveEvent('ended'),
+  touchCancelled: () => passiveEvent('cancelled'),
+});
+
+// The same control at the very end of the page, where a page scrolled to its
+// end has no room to scroll on: what ends its press is the signal FR20
+// counts there.
+const passiveEndEvent = (state: string) =>
+  window.__gestures.push({name: 'passiveEnd', state, time: performance.now()});
+host.attachConsumer(element('passiveEnd'), {
+  touchBegan: () => passiveEndEvent('began'),
+  touchMoved: () => passiveEndEvent('moved'),
+  touchEnded: () => passiveEndEvent('ended'),
+  touchCancelled: () => passiveEndEvent('cancelled'),
+});
+// Which browser signal arrives, in order with the presses it ends: on the
+// window, whose capture listeners run before the host's on the document.
+addListener.call(
+  window,
+  'pointercancel',
+  event => {
+    if ((event as PointerEvent).pointerType === 'touch') {
+      window.__gestures.push({
+        name: 'dom:pointercancel',
+        state: 'dom',
+        time: performance.now(),
+      });
+    }
+  },
+  true,
+);
+
+// The fixture's own loggers go around the count of page listeners.
+// A press consumer inside the scroller, as a list row is: a scroll of the
+// scroller takes its press only once the finger has moved the take distance
+// (FR20). `touch-action: none` keeps the browser's own pan out of it, so the
+// only scroll is the one the test makes.
+const rowEvent = (state: string) =>
+  window.__gestures.push({name: 'scrollRow', state, time: performance.now()});
+host.attachConsumer(element('scrollRow'), {
+  touchBegan: () => rowEvent('began'),
+  touchMoved: () => rowEvent('moved'),
+  touchEnded: () => rowEvent('ended'),
+  touchCancelled: () => rowEvent('cancelled'),
+});
+
+for (const type of ['click', 'mousedown']) {
+  addListener.call(
+    document,
+    type,
+    event => {
+      const target = event.target as HTMLElement | null;
+      window.__gestures.push({
+        name: `${type}:${target?.id ?? ''}`,
+        state: 'dom',
+        time: event.timeStamp,
+      });
+    },
+    true,
+  );
+}
+
+window.__attachListeners = [...window.__pageListeners]
+  .filter(([type, count]) => count > (beforeAttach.get(type) ?? 0))
+  .map(([type]) => type)
+  .sort();