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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/packages/core/src/gestures/GestureHost.ts b/packages/core/src/gestures/GestureHost.tsindex 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.tsindex 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-0allowedPointerTypes: [],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.tsindex 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.tsindex 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,};}