Skip to content

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

TypeScript

fix(gestures): a trackpad wheel within 1.5 ms of the one before sets no speed (#9667)

Christopher Chedeaucad41e367e25
diff --git a/.changeset/trackpad-merged-wheel-speed.md b/.changeset/trackpad-merged-wheel-speed.md
new file mode 100644
index 0000000000..baa4ce87aa
--- /dev/null
+++ b/.changeset/trackpad-merged-wheel-speed.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: a followed trackpad pan takes no speed from a wheel within 1.5 ms of the one before, so bunched wheels after a main-thread stall no longer carry it past the fingers' travel, at 60 to 500 Hz. Not exported from the package entry point.
+
+@vjeux
diff --git a/packages/core/src/gestures/GestureHost.ts b/packages/core/src/gestures/GestureHost.ts
index 47b5ec8f92..e9d15b3fa4 100644
--- a/packages/core/src/gestures/GestureHost.ts
+++ b/packages/core/src/gestures/GestureHost.ts
@@ -2286,8 +2286,10 @@ export class GestureHost {
const debtY = absorbedDebt(gesture.y - beforeY, dy);
const trueX = beforeX - dx;
const trueY = beforeY - dy;
+ // A wheel the splitter reads as one stall's merge sets no speed. Its
+ // speed is one the fingers never had.
const elapsed = time - f.lastMove;
- if (elapsed > 0) {
+ if (elapsed > 0 && this.wheelSegment?.bunched !== true) {
f.speedX = (trueX - f.trueX) / elapsed;
f.speedY = (trueY - f.trueY) / elapsed;
}
diff --git a/packages/core/src/gestures/__tests__/wheel.test.ts b/packages/core/src/gestures/__tests__/wheel.test.ts
index 45582eb4d5..854094d56a 100644
--- a/packages/core/src/gestures/__tests__/wheel.test.ts
+++ b/packages/core/src/gestures/__tests__/wheel.test.ts
@@ -1228,12 +1228,14 @@ describe("a trackpad scroll through the splitter's undecided stretch (spec:AST-0
allowedPointerTypes: [],
allowedScrollTypes: ['continuous'],
});
- const seen: {state: string; x: number; velocity: number}[] = [];
+ const seen: {state: string; x: number; velocity: number; time: number}[] =
+ [];
pan.addTransitionListener((recognizer, _from, to) => {
seen.push({
state: to,
x: recognizer.translation().x,
velocity: recognizer.velocity().x,
+ time: clock.time,
});
});
detachers.push(host.attach(box, pan));
@@ -1274,6 +1276,165 @@ describe("a trackpad scroll through the splitter's undecided stretch (spec:AST-0
).toEqual(['possible']);
});
+ it("ends a slow trackpad drag on the fingers' travel when a stalled page receives a merged step 1 ms after the one before: a bunched pair sets no speed", () => {
+ const {box, seen} = followed();
+ // The fingers move 2 px every 16 ms. The page stalls 50 ms and gets the
+ // next two steps as one 4 px wheel, 1 ms after the one before. Then 2 px
+ // every 16 ms again, and the fingers stop.
+ const times: number[] = [0, 16, 32, 48, 64, 114, 115];
+ const deltas: number[] = [2, 2, 2, 2, 2, 2, 4];
+ for (let i = 0; i < 12; i++) {
+ times.push(131 + 16 * i);
+ deltas.push(2);
+ }
+ times.forEach((time, index) => {
+ wheel(box, {trackpad: true, dx: deltas[index], time});
+ });
+ clock.runDue(times[times.length - 1] + 500);
+ const ended = seen.filter(entry => entry.state === 'ended');
+ expect(ended).toHaveLength(1);
+ // 40 px of fingers' travel, 10 of it the pan's hysteresis: -30. The
+ // fingers stopped, so the release is still.
+ expect(ended[0].x).toBeCloseTo(-30, 0);
+ expect(ended[0].velocity).toBe(0);
+ });
+
+ it("keeps the fingers' speed through a held tail when a stalled page merges two steps right after a held wheel", () => {
+ const {box, seen} = followed();
+ // A 4 px wheel every 16 ms. A shrinking wheel is held, and a stalled page
+ // receives the next two steps as one 8 px wheel 1 ms after it.
+ const times = [0, 16, 32, 48, 64, 80, 81, 97, 113, 129, 145, 161];
+ const deltas = [4, 4, 4, 4, 4, 3.9, 8, 4.2, 4.1, 4, 3.9, 3.8];
+ times.forEach((time, i) => {
+ wheel(box, {trackpad: true, dx: deltas[i], time});
+ });
+ clock.runDue(times[times.length - 1] + 500);
+ // After the merge, the pan never moves faster than the fingers' fastest
+ // step, 4.2 px in 16 ms.
+ const tail = seen.filter(
+ entry => entry.state === 'changed' && entry.time > 81,
+ );
+ expect(tail.length).toBeGreaterThan(1);
+ for (let i = 1; i < tail.length; i++) {
+ const speed =
+ Math.abs(tail[i].x - tail[i - 1].x) / (tail[i].time - tail[i - 1].time);
+ expect(speed).toBeLessThanOrEqual(4.2 / 16 + 1e-9);
+ }
+ });
+
+ /** Wheel times at `hz` from `from` ms, through `stamp`, moved by ±`jitter`. */
+ function framesAt(
+ hz: number,
+ count: number,
+ stamp: (time: number) => number,
+ jitter: number,
+ from = 0,
+ ): number[] {
+ return Array.from({length: count}, (_, i) =>
+ stamp(from + (i * 1000) / hz + (i % 2 === 0 ? jitter : -jitter)),
+ );
+ }
+
+ const asIs = (time: number) => time;
+ const whole = (time: number) => Math.round(time);
+
+ /** Trackpad streams: frame rates, whole-millisecond stamps and jitter. */
+ const STREAMS = [
+ ['60 Hz', 60, asIs, 0],
+ ['120 Hz', 120, asIs, 0],
+ ['240 Hz', 240, asIs, 0],
+ ['240 Hz, ±0.3 ms jitter', 240, asIs, 0.3],
+ ['240 Hz, whole ms', 240, whole, 0],
+ ['300 Hz', 300, asIs, 0],
+ ['300 Hz, whole ms', 300, whole, 0],
+ ['360 Hz', 360, asIs, 0],
+ ['360 Hz, whole ms', 360, whole, 0],
+ ['480 Hz, whole ms', 480, whole, 0],
+ ['500 Hz, whole ms', 500, whole, 0],
+ ] as const;
+
+ it.each([
+ [
+ 'six 2 px wheels 80 ms apart',
+ [0, 80, 160, 240, 320, 400],
+ [416, 432, 448, 464, 480],
+ ],
+ [
+ 'wheels 64, 64, 64, 48 and 32 ms apart',
+ [0, 64, 128, 192, 240, 272],
+ [288, 304, 320, 336, 352],
+ ],
+ ] as const)(
+ "keeps the fingers' speed when a slow drag turns into a flick: %s, then 10 px frames into the lift",
+ (_name, slow, fast) => {
+ const {box, seen} = followed();
+ slow.forEach(time => {
+ wheel(box, {trackpad: true, dx: 2, time});
+ });
+ [10, 9.5, 9, 8.5, 8].forEach((dx, i) => {
+ wheel(box, {trackpad: true, dx, time: fast[i]});
+ });
+ clock.runDue(fast[fast.length - 1] + 500);
+ // As on main, the first 10 px frame sets the fingers' speed, 10 px in 16
+ // ms. The pan lets go at the lift still moving at it.
+ const ended = seen.filter(entry => entry.state === 'ended');
+ expect(ended).toHaveLength(1);
+ expect(ended[0].x).toBeCloseTo(-52, 6);
+ expect(ended[0].velocity).toBeCloseTo(-625, 6);
+ },
+ );
+
+ it.each(STREAMS)(
+ "keeps a trackpad pan moving at the fingers' speed through the undecided stretch at %s",
+ (_name, hz, stamp, jitter) => {
+ const {box, seen} = followed();
+ const deltas = [10, 10, 10, 10, 9.5, 9, 8.5, 8, 7.5, 7, 6.5, 6];
+ const times = framesAt(hz, deltas.length, stamp, jitter);
+ deltas.forEach((dx, i) => {
+ wheel(box, {trackpad: true, dx, time: times[i]});
+ });
+ clock.runDue(times[times.length - 1] + 500);
+ // The fingers last move on the fourth wheel, to -30, at the speed of
+ // their last pair. Through the shrinking wheels the pan goes on at it.
+ const speed = -10 / (times[3] - times[2]);
+ const shown = seen
+ .filter(entry => entry.state === 'changed')
+ .map(entry => entry.x)
+ .slice(-4);
+ expect(shown).toHaveLength(4);
+ [4, 5, 6, 7].forEach((wheelIndex, k) => {
+ expect(shown[k]).toBeCloseTo(
+ -30 + speed * (times[wheelIndex] - times[3]),
+ 6,
+ );
+ });
+ },
+ );
+
+ it.each(STREAMS)(
+ "ends a slow trackpad drag on the fingers' travel when a stalled page merges two steps at %s",
+ (_name, hz, stamp, jitter) => {
+ const {box, seen} = followed();
+ // Eight 2 px steps, then a 50 ms stall. The page receives one step,
+ // then the next two as one 4 px wheel 1 ms later. Four more steps
+ // follow, and the fingers stop.
+ const before = framesAt(hz, 8, stamp, jitter);
+ const resumed = before[before.length - 1] + 50;
+ const tail = framesAt(hz, 5, stamp, jitter, resumed + 1).slice(1);
+ const times = [...before, resumed, resumed + 1, ...tail];
+ const deltas = [2, 2, 2, 2, 2, 2, 2, 2, 2, 4, 2, 2, 2, 2];
+ deltas.forEach((dx, i) => {
+ wheel(box, {trackpad: true, dx, time: times[i]});
+ });
+ clock.runDue(times[times.length - 1] + 500);
+ const ended = seen.filter(entry => entry.state === 'ended');
+ expect(ended).toHaveLength(1);
+ // 30 px of fingers' travel, 10 of it the pan's hysteresis.
+ expect(ended[0].x).toBeCloseTo(-20, 6);
+ expect(ended[0].velocity).toBe(0);
+ },
+ );
+
it.each([
['a blur', 'blur', false],
['a hidden page', 'hidden', false],
diff --git a/packages/core/src/gestures/__tests__/wheelSegmenter.test.ts b/packages/core/src/gestures/__tests__/wheelSegmenter.test.ts
index 340381ec32..e77cd87e33 100644
--- a/packages/core/src/gestures/__tests__/wheelSegmenter.test.ts
+++ b/packages/core/src/gestures/__tests__/wheelSegmenter.test.ts
@@ -3,13 +3,14 @@
/**
* @file wheelSegmenter.test.ts
* @input A WheelSegmenter fed deltas along one axis with their times
- * @output Tests for how a wheel stream splits into gestures and where a
- * trackpad's fingers lift (spec:AST-094 FR43)
+ * @output Tests for how a wheel stream splits into gestures, where a
+ * trackpad's fingers lift, and which wheels a stall merged (spec:AST-094
+ * FR43)
* @position Unit tests of wheelSegmenter.ts
*/
import {describe, expect, it} from 'vitest';
-import {WheelSegmenter} from '../wheelSegmenter';
+import {isBunched, WheelSegmenter} from '../wheelSegmenter';
/** Push `deltas` 16 ms apart from `from`, with a 180 ms finger pause. */
function feed(segmenter: WheelSegmenter, deltas: number[], from = 0) {
@@ -87,3 +88,100 @@ describe('WheelSegmenter (spec:AST-094 FR43)', () => {
expect(segmenter.push(40, 10, 180).boundary).toBe('idle');
});
});
+
+/** Wheel times at `hz` from 1000 ms, through `stamp`, each moved by ±`jitter`. */
+function frames(
+ hz: number,
+ count: number,
+ stamp: (time: number) => number = time => time,
+ jitter = 0,
+): number[] {
+ return Array.from({length: count}, (_, i) =>
+ stamp(1000 + (i * 1000) / hz + (i % 2 === 0 ? jitter : -jitter)),
+ );
+}
+
+const whole = (time: number) => Math.round(time);
+
+/** Trackpad streams: frame rates, whole-millisecond stamps and jitter. */
+const STREAMS = [
+ ['60 Hz', 60, undefined, 0],
+ ['120 Hz', 120, undefined, 0],
+ ['240 Hz', 240, undefined, 0],
+ ['240 Hz, ±0.3 ms jitter', 240, undefined, 0.3],
+ ['240 Hz, whole ms', 240, whole, 0],
+ ['300 Hz', 300, undefined, 0],
+ ['300 Hz, whole ms', 300, whole, 0],
+ ['360 Hz', 360, undefined, 0],
+ ['360 Hz, whole ms', 360, whole, 0],
+ ['480 Hz, whole ms', 480, whole, 0],
+ ['500 Hz, whole ms', 500, whole, 0],
+] as const;
+
+describe("WheelSegmenter's merges: one stall's wheels, not frames", () => {
+ it.each(STREAMS)(
+ 'takes no frame of a steady stream at %s as a merge',
+ (_name, hz, stamp, jitter) => {
+ const segmenter = new WheelSegmenter();
+ const seen = frames(hz, 40, stamp, jitter).map(time =>
+ segmenter.push(time, 10, 180),
+ );
+ expect(seen.filter(segment => segment.bunched)).toEqual([]);
+ },
+ );
+
+ it.each(STREAMS)(
+ "takes a wheel 1 ms after a stall's last one as a merge at %s",
+ (_name, hz, stamp, jitter) => {
+ const segmenter = new WheelSegmenter();
+ const times = frames(hz, 20, stamp, jitter);
+ for (const time of times) {
+ segmenter.push(time, 10, 180);
+ }
+ // The page stalls 50 ms, then receives the steps it held back.
+ const resumed = times[times.length - 1] + 50;
+ expect(segmenter.push(resumed, 10, 180).bunched).toBe(false);
+ const merged = segmenter.push(resumed + 1, 20, 180);
+ expect(merged.boundary).toBeNull();
+ expect(merged.bunched).toBe(true);
+ },
+ );
+
+ it("takes each of a stall's held-back wheels as a merge when the page receives them one by one, 1 ms apart", () => {
+ const segmenter = new WheelSegmenter();
+ const times = frames(120, 20);
+ for (const time of times) {
+ segmenter.push(time, 10, 180);
+ }
+ const resumed = times[times.length - 1] + 50;
+ segmenter.push(resumed, 10, 180);
+ const held = [1, 2, 3, 4, 5].map(ms =>
+ segmenter.push(resumed + ms, 10, 180),
+ );
+ expect(held.map(segment => segment.bunched)).toEqual([
+ true,
+ true,
+ true,
+ true,
+ true,
+ ]);
+ });
+
+ it('judges a wheel by its own interval alone: a frame after slow wheels is a frame', () => {
+ const segmenter = new WheelSegmenter();
+ for (const time of [0, 80, 160, 240, 320, 400]) {
+ segmenter.push(time, 2, 180);
+ }
+ expect(segmenter.push(416, 10, 180).bunched).toBe(false);
+ expect(segmenter.push(418, 10, 180).bunched).toBe(false);
+ });
+
+ it('takes a wheel within 1.5 ms of the one before as a merge, and no frame up to 500 Hz', () => {
+ expect(isBunched(0)).toBe(true);
+ expect(isBunched(1)).toBe(true);
+ expect(isBunched(1.5)).toBe(true);
+ expect(isBunched(2)).toBe(false);
+ expect(isBunched(1000 / 480)).toBe(false);
+ expect(isBunched(1000 / 60)).toBe(false);
+ });
+});
diff --git a/packages/core/src/gestures/wheelSegmenter.ts b/packages/core/src/gestures/wheelSegmenter.ts
index 1fec9701d0..e46f273bbb 100644
--- a/packages/core/src/gestures/wheelSegmenter.ts
+++ b/packages/core/src/gestures/wheelSegmenter.ts
@@ -3,8 +3,9 @@
/**
* @file wheelSegmenter.ts
* @input A wheel stream's deltas along one axis, with their event times
- * @output Exports WheelSegmenter: splits the stream into gestures and reads
- * a trackpad's lift (the onset of momentum)
+ * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
+ * stream into gestures and reads a trackpad's lift (the onset of momentum).
+ * isBunched tells one stall's merge from a frame.
* @position Read by GestureHost.ts's wheel input: the web reports no
* trackpad contact or phase, so both are inferred.
*/
@@ -22,15 +23,32 @@ export interface WheelSegment {
readonly liftNow: boolean;
/** This event shrank, so it may be momentum: hold it until known. */
readonly decaying: boolean;
+ /** This event came so soon after the one before that it is a merge. */
+ readonly bunched: boolean;
}
/** Momentum arrives at frame rate: a pause this long ends it. */
const MOMENTUM_GAP_MS = 50;
+/**
+ * A wheel this close to the one before, ms, is one stall's merge. Frames come
+ * further apart at every display rate up to 500 Hz, which is 2 ms.
+ */
+const BUNCHED_MS = 1.5;
/** Shrinking deltas in a row before the lift is read. */
const LIFT_RUN = 4;
/** And how much of its size the run has lost by then. */
const LIFT_DECAY = 0.8;
+/**
+ * Whether a wheel `intervalMs` after the one before is one stall's merge, not
+ * a frame. A stalled page receives the wheels it held back together, within
+ * 1.5 ms of each other. The rule reads no history, so slow wheels never make
+ * a real frame look like a merge.
+ */
+export function isBunched(intervalMs: number): boolean {
+ return intervalMs <= BUNCHED_MS;
+}
+
/**
* A trackpad gesture has a finger phase and, after a fling, a momentum phase.
* In the finger phase, deltas come while the fingers move, with pauses when
@@ -55,6 +73,7 @@ export class WheelSegmenter {
const size = Math.abs(delta);
const sign = Math.sign(delta);
const gap = time - this.last;
+ const bunched = this.count > 0 && isBunched(gap);
let boundary: WheelBoundary | null = null;
if (this.count === 0) {
boundary = this.gesture === 0 ? 'first' : 'idle';
@@ -104,6 +123,7 @@ export class WheelSegmenter {
gesture: this.gesture,
liftNow,
decaying: decaying && !liftNow,
+ bunched: boundary == null && bunched,
};
}