Skip to content

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

TypeScript

fix(core): a finger stops a pager's goTo move at the touch (#10545)

Christopher Chedeau9a690d52b93b
diff --git a/.changeset/pager-goto-touch-down.md b/.changeset/pager-goto-touch-down.md
new file mode 100644
index 0000000000..03df74dc4a
--- /dev/null
+++ b/.changeset/pager-goto-touch-down.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Carousel paging: a finger or a pen that lands on the row during an edge button's move now stops it at the touch, as on iOS, instead of letting it run on for about 85 ms. The item under the finger still takes the tap. A mouse is unchanged.
+
+@vjeux
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 0c7dac780c..9e5974cee0 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -268,11 +268,15 @@ a measured, sourced difference exists.
change during a drag starts from rest (DEC-25). A finger or a pen that lands
on a pager's settle after a release never reaches the pager's content: no
press feedback and no click. UIKit's content took none of 30 such touches
- (iOS 26.2 simulator, 2026-11-06). A rebase toward the new rest shifts a
- spring heading there whole: its curve and target move by the rest's change,
- and it keeps its start time and velocity. On a starved page, the Switch's
- value change then shows no step in its frame proofs; any other retarget may
- still skip ahead by up to the browser's commit delay.
+ (iOS 26.2 simulator, 2026-11-06). A finger or a pen that lands on a pager's
+ `goTo` move stops it at the touch, and the lift settles on the nearest page;
+ the content still takes the tap. UIKit's animated `setContentOffset` stopped 2
+ to 23 ms after the touch, and its content took 24 of 30 taps (iOS 26.2
+ simulator, 2026-11-06). A rebase toward the new rest shifts a spring heading
+ there whole: its curve and target move by the rest's change, and it keeps its
+ start time and velocity. On a starved page, the Switch's value change then
+ shows no step in its frame proofs; any other retarget may still skip ahead by
+ up to the browser's commit delay.
- **FR7 — Exits keep the native counterpart's look.** A touch presentation MUST
play an exit with the look of its UIKit counterpart's exit, on every touch
platform: a menu shrinks into its trigger, and an alert fades. In a component
diff --git a/packages/core/src/SnapPaging/SnapPaging.ts b/packages/core/src/SnapPaging/SnapPaging.ts
index fd8f877a29..63a3185a66 100644
--- a/packages/core/src/SnapPaging/SnapPaging.ts
+++ b/packages/core/src/SnapPaging/SnapPaging.ts
@@ -480,7 +480,7 @@ function attachPaging(
if (!pager.isDragging) {
const end = track.travel();
const to = Math.min(Math.max(target(track.position(), end), 0), end);
- // The pager's own move: a finger catches it as it catches a settle.
+ // The pager's own move: a finger on the row stops it at the touch.
pager.goTo(pager.nearestPage(to), {offset: to});
}
return true;
diff --git a/packages/core/src/SnapPaging/__tests__/SnapPaging.interaction.browser.spec.ts b/packages/core/src/SnapPaging/__tests__/SnapPaging.interaction.browser.spec.ts
index 6b15789713..b11231d3d9 100644
--- a/packages/core/src/SnapPaging/__tests__/SnapPaging.interaction.browser.spec.ts
+++ b/packages/core/src/SnapPaging/__tests__/SnapPaging.interaction.browser.spec.ts
@@ -668,7 +668,7 @@ test('an edge press late in a settle steps on to a stop', async ({page}) => {
});
for (const holdMs of [150, 40]) {
- test(`during an edge button's move, a ${holdMs} ms touch on the row ${holdMs > 85 ? 'stops it where it shows' : 'lets it run on'}, and the row rests on a stop`, async ({
+ test(`during an edge button's move, a ${holdMs} ms touch on the row stops it where it shows, and the row rests on a stop`, async ({
page,
}) => {
const {scroller} = await open(page, 'snap-paging-three-up', 'paging', {
@@ -686,8 +686,8 @@ for (const holdMs of [150, 40]) {
);
const at = await restingOffset(scroller);
expect(Math.min(...stops.map(stop => Math.abs(stop - at)))).toBeLessThan(1);
- // Past the pager's 85 ms catch time, the move stops short of its target.
- expect(Math.abs(at - stops[5]) < 1).toBe(holdMs < 85);
+ // A finger stops the pager's own move at the touch, short of its target.
+ expect(Math.abs(at - stops[5])).toBeGreaterThan(1);
});
}
diff --git a/packages/core/src/hooks/usePager.test.ts b/packages/core/src/hooks/usePager.test.ts
index 8aaa381500..05e153294c 100644
--- a/packages/core/src/hooks/usePager.test.ts
+++ b/packages/core/src/hooks/usePager.test.ts
@@ -211,10 +211,11 @@ function mouse(
x: number,
y: number,
time: number,
+ pointerType: 'mouse' | 'pen' = 'mouse',
): Event {
const event = new Event(type, {bubbles: true, cancelable: true});
const fields: Record<string, unknown> = {
- pointerType: 'mouse',
+ pointerType,
pointerId: 1,
isPrimary: true,
button: 0,
@@ -230,6 +231,17 @@ function mouse(
return event;
}
+/** A pen's pointer event, as `mouse` sends a mouse's. */
+function pen(
+ type: 'pointerdown' | 'pointermove' | 'pointerup',
+ target: EventTarget,
+ x: number,
+ y: number,
+ time: number,
+): Event {
+ return mouse(type, target, x, y, time, 'pen');
+}
+
/**
* A wheel for the gesture host: `dx`/`dy` px (or lines with `mode` 1). With
* no legacy `wheelDeltaX`/`wheelDeltaY` it reads as a mouse's wheel.
@@ -836,11 +848,10 @@ describe('createPager', () => {
touch('touchend', f.page, 289, 100, now + 40);
});
- it(`a still finger catches a settle ${paging.catchStopMs} ms after it lands, and the lift settles on the nearest page`, async () => {
- const f = setup({defaultIndex: 1});
- f.pager.goTo(2);
- await advance(0, f.clock);
- await advance(60, f.clock);
+ it(`a still finger catches a release settle ${paging.catchStopMs} ms after it lands, and the lift settles on the nearest page`, async () => {
+ const f = setup({defaultIndex: 0});
+ await drag(f, {from: 300, dx: -80});
+ await advance(16, f.clock);
touch('touchstart', f.page, 300, 100, now);
await advance(40, f.clock);
// Still moving 40 ms after the touch.
@@ -854,33 +865,59 @@ describe('createPager', () => {
expect(-f.x()).toBe(held);
touch('touchend', f.page, 300, 100, now);
await settle(f);
- expect(f.x()).toBe(-2 * WIDTH);
+ expect(-f.x()).toBeCloseTo(Math.round(held / WIDTH) * WIDTH, 6);
});
- it('a finger held past the catch delay catches the settle when a busy page delivers its touch and lift together', async () => {
- const f = setup({defaultIndex: 0});
- f.pager.goTo(3);
+ // UIKit's animated `setContentOffset` stops at the touch, and its content
+ // still takes the tap.
+ it('a finger that lands on a goTo move stops it at the touch, the content keeps the tap, and the lift settles on the nearest page', async () => {
+ const f = setup({defaultIndex: 1});
+ f.pager.goTo(2);
await advance(0, f.clock);
await advance(60, f.clock);
+ touch('touchstart', f.page, 300, 100, now);
+ expect(f.pager.isSettling).toBe(false);
+ const held = -f.x();
+ await advance(40, f.clock);
+ expect(-f.x()).toBe(held);
+ const end = touch('touchend', f.page, 300, 100, now);
+ expect(end.defaultPrevented).toBe(false);
+ await settle(f);
+ expect(-f.x()).toBeCloseTo(Math.round(held / WIDTH) * WIDTH, 6);
+ });
+
+ it('a pen that lands on a goTo move stops it at the touch too', async () => {
+ const f = setup({defaultIndex: 1});
+ f.pager.goTo(2);
+ await advance(0, f.clock);
+ await advance(60, f.clock);
+ pen('pointerdown', f.page, 300, 100, now);
+ expect(f.pager.isSettling).toBe(false);
+ pen('pointerup', f.page, 300, 100, now + 40);
+ });
+
+ it('a finger held past the catch delay catches a release settle when a busy page delivers its touch and lift together', async () => {
+ const f = setup({defaultIndex: 0});
+ await drag(f, {from: 300, dx: -80});
+ await advance(16, f.clock);
+ // Nearer page 0 at the touch, so a catch settles back there.
+ expect(-f.x()).toBeLessThan(WIDTH / 2);
// One task delivers both events, with no timer turn between them. Their
// own times say the finger stayed down 150 ms.
touch('touchstart', f.page, 300, 100, now);
touch('touchend', f.page, 300, 100, now + 150);
await settle(f);
- const page = -f.x() / WIDTH;
- expect(page).toBe(Math.round(page));
- expect(page).toBeLessThan(3);
+ expect(f.x()).toBeCloseTo(0, 6);
});
- it('a 40 ms tap that a busy page delivers with its lift lets the settle run on', async () => {
+ it('a 40 ms tap that a busy page delivers with its lift lets a release settle run on', async () => {
const f = setup({defaultIndex: 0});
- f.pager.goTo(3);
- await advance(0, f.clock);
- await advance(60, f.clock);
+ await drag(f, {from: 300, dx: -80});
+ await advance(16, f.clock);
touch('touchstart', f.page, 300, 100, now);
touch('touchend', f.page, 300, 100, now + 40);
await settle(f);
- expect(f.x()).toBe(-3 * WIDTH);
+ expect(f.x()).toBe(-WIDTH);
});
// spec:AST-094 FR6: the touch that stops a scroll view never reaches its
@@ -978,10 +1015,8 @@ describe('createPager', () => {
f.pager.goTo(4, {offset: 3.6 * WIDTH});
await advance(60, f.clock);
touch('touchstart', f.page, 300, 100, now);
- await advance(paging.catchStopMs + 40, f.clock);
- // The catch's deadline is on the gesture clock.
- f.clock.runDue(now);
expect(f.pager.isSettling).toBe(false);
+ await advance(40, f.clock);
touch('touchend', f.page, 300, 100, now);
await settle(f);
expect(-f.x() / WIDTH).toBe(Math.round(-f.x() / WIDTH));
@@ -1095,11 +1130,10 @@ describe('createPager', () => {
try {
pager.goTo(2);
await advance(0, f.clock);
- await advance(60, f.clock);
+ await advance(60 + paging.catchStopMs + 40, f.clock);
+ expect(pager.isSettling).toBe(true);
+ // A finger stops a goTo move at the touch.
touch('touchstart', f.page, 300, 100, now);
- await advance(paging.catchStopMs + 40, f.clock);
- // The catch's deadline is on the gesture clock.
- f.clock.runDue(now);
expect(pager.isSettling).toBe(false);
const held = f.x();
calls.length = 0;
@@ -2477,7 +2511,8 @@ describe('review fixes', () => {
mouse('pointerdown', f.page, 200, 100, now);
await advance(16, f.clock);
expect(refuses()).toBe(false);
- // The catch stops the settle after UIKit's catch delay, as a finger's.
+ // A mouse waits out UIKit's catch delay, even on a goTo move.
+ expect(f.pager.isSettling).toBe(true);
await advance(120, f.clock);
f.clock.runDue(now);
expect(f.pager.isSettling).toBe(false);
diff --git a/packages/core/src/hooks/usePager.ts b/packages/core/src/hooks/usePager.ts
index 8168b05c0a..dd40fbf846 100644
--- a/packages/core/src/hooks/usePager.ts
+++ b/packages/core/src/hooks/usePager.ts
@@ -457,8 +457,9 @@ function isScrollContact(recognizer: PanGestureRecognizer): boolean {
* The track then settles on UIKit's paging integrator (`solvePaging`),
* baked into keyframes.
* - A finger that lands on a settling pager catches it `paging.catchStopMs`
- * after the touch, as in UIKit. A drag catches it at once, from the value
- * on screen. While the pan is off, a touch does not stop the motion.
+ * after the touch, as in UIKit. A finger stops a `goTo` move at once. A
+ * drag catches it at once, from the value on screen. While the pan is off,
+ * a touch does not stop the motion.
* - `goTo` runs the curve of `setContentOffset(_:animated:)` and cancels a
* drag in progress. It reads that duration and curve through
* `resolveMotion`.
@@ -1111,22 +1112,26 @@ export function createPager(
function onCatch(recognizer: LongPressGestureRecognizer): void {
if (recognizer.state === 'began') {
holdSelection(true);
+ const isMouse = catcher.pointerType === 'mouse';
// A mouse keeps its click. A finger or a pen loses it.
- if (isReleaseSettle && catcher.pointerType !== 'mouse') {
+ if (isReleaseSettle && !isMouse) {
catcher.takeFromContent();
}
clearCatchTimer();
caughtSettle = false;
+ if (!isReleaseSettle && !isMouse) {
+ // UIKit stops an animated `setContentOffset` at the touch itself. A
+ // mouse keeps the catch delay.
+ catchSettle();
+ return;
+ }
isCatchTimerArmed = true;
catcher.armCatch(paging.catchStopMs, () => {
if (!isCatchTimerArmed) {
return;
}
isCatchTimerArmed = false;
- if (settleHandle != null && !isDragging) {
- stopSettle();
- caughtSettle = true;
- }
+ catchSettle();
});
return;
}
@@ -1154,6 +1159,13 @@ export function createPager(
}
}
+ function catchSettle(): void {
+ if (settleHandle != null && !isDragging) {
+ stopSettle();
+ caughtSettle = true;
+ }
+ }
+
function goTo(index: number, goToOptions: GoToOptions = {}): void {
if (goToOptions.reason === 'controlled' && deferDepth === 0) {
// The owner's own move: what it calls back waits for a frame.
diff --git a/packages/core/src/motion/uikit/paging.ts b/packages/core/src/motion/uikit/paging.ts
index 197c77faff..b1fb6a45af 100644
--- a/packages/core/src/motion/uikit/paging.ts
+++ b/packages/core/src/motion/uikit/paging.ts
@@ -115,10 +115,10 @@ export const paging = {
maxPagesFromStart: 1,
},
/**
- * A finger that lands on a settling pager does not stop it at once. The
- * settle runs on for about this long, then the content holds under the
- * finger. Lifted without a move, the content settles again on the nearest
- * page.
+ * A finger that lands on a pager settling after a swipe does not stop it at
+ * once. The settle runs on for about this long, then the content holds under
+ * the finger. Lifted without a move, the content settles again on the
+ * nearest page.
* @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. After
* touch-downs 60 and 160 ms into a settle, the content moved on for 82.6
* and 87.5 ms (5 frames), then held.