Skip to content

Commit 8ad2f67

Browse files
airowethymikee
authored andcommitted
fix(scroll): keep clamped swipe endpoints strictly inside the container
The lane clamp treated the container's bottom edge as reachable, but Android bounds are half-open, so a shortened `scroll down` above a footer could start one pixel below the list. The usable band is now the container's half-open range inset by 8 px on both sides, on both axes. Along the scrolled axis it is intersected with the padded frame, which still wins when it leaves nothing of the container. Across it, the padded range is preferred, but a rail or chip row lying wholly in that padding is swiped along its own inset range rather than missed. A lane that only loses the rounding pixel of an odd span is no longer reported as shortened. Refs callstack#2714
1 parent c8baeb3 commit 8ad2f67

3 files changed

Lines changed: 225 additions & 98 deletions

File tree

‎packages/contracts/src/scroll-gesture-container.test.ts‎

Lines changed: 111 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -4,44 +4,81 @@ import type { Rect } from '@agent-device/kernel/snapshot';
44
import { buildScrollGesturePlan, type ScrollDirection } from './scroll-gesture.ts';
55

66
// The iPhone geometry #2714 was reported on: a 402x874 frame, the default 10% edge padding leaving
7-
// y 87..787 for a swipe.
7+
// x 40..362 and y 87..787 for a swipe.
88
const FRAME = { referenceWidth: 402, referenceHeight: 874 };
9+
const PADDED_LEFT = 40;
910
const PADDED_TOP = 87;
1011
const PADDED_BOTTOM = 787;
12+
// Inset under a navigation bar and running to the bottom of the frame.
1113
const INSET_CONTAINER: Rect = { x: 18, y: 178, width: 366, height: 662 };
14+
// Inset at both ends: a footer sits below it, well above the padded band's bottom.
15+
const FOOTERED_CONTAINER: Rect = { x: 18, y: 178, width: 366, height: 500 };
1216
const FITTING_CONTAINER: Rect = { x: 18, y: 62, width: 366, height: 729 };
1317

14-
function endpointsInside(
15-
plan: { x1: number; y1: number; x2: number; y2: number },
16-
rect: Rect,
17-
): boolean {
18+
type Endpoints = { x1: number; y1: number; x2: number; y2: number };
19+
20+
/**
21+
* A container rect is half-open, as Android bounds and View hit-testing are: `y + height` is the
22+
* first row outside it. Strictly inside on both sides also keeps the drag off the edge row.
23+
*/
24+
function strictlyInside(plan: Endpoints, rect: Rect): boolean {
1825
const inside = (x: number, y: number) =>
19-
x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
26+
x > rect.x && x < rect.x + rect.width && y > rect.y && y < rect.y + rect.height;
2027
return inside(plan.x1, plan.y1) && inside(plan.x2, plan.y2);
2128
}
2229

23-
test.each<ScrollDirection>(['up', 'down'])(
24-
'a %s swipe longer than an inset container shrinks to the container and reports both spans',
25-
(direction) => {
30+
test.each<[ScrollDirection, string, Rect]>([
31+
['up', 'inset', INSET_CONTAINER],
32+
['down', 'inset', INSET_CONTAINER],
33+
['up', 'footered', FOOTERED_CONTAINER],
34+
['down', 'footered', FOOTERED_CONTAINER],
35+
])(
36+
'a %s swipe longer than an %s container shrinks inside it and reports both spans',
37+
(direction, _, container) => {
2638
const unclamped = buildScrollGesturePlan({ direction, amount: 0.75, ...FRAME });
27-
const plan = buildScrollGesturePlan({
28-
direction,
29-
amount: 0.75,
30-
...FRAME,
31-
container: INSET_CONTAINER,
32-
});
39+
const plan = buildScrollGesturePlan({ direction, amount: 0.75, ...FRAME, container });
3340

34-
assert.ok(endpointsInside(plan, INSET_CONTAINER), JSON.stringify(plan));
35-
assert.deepEqual(
36-
[Math.min(plan.y1, plan.y2), Math.max(plan.y1, plan.y2)],
37-
[INSET_CONTAINER.y, PADDED_BOTTOM],
38-
);
39-
assert.equal(plan.pixels, PADDED_BOTTOM - INSET_CONTAINER.y);
41+
assert.ok(strictlyInside(plan, container), JSON.stringify(plan));
42+
assert.ok(Math.max(plan.y1, plan.y2) <= PADDED_BOTTOM, JSON.stringify(plan));
43+
assert.equal(plan.pixels, Math.abs(plan.y2 - plan.y1));
44+
assert.ok(plan.pixels < unclamped.pixels);
4045
assert.equal(plan.requestedPixels, unclamped.pixels);
4146
assert.equal(Math.sign(plan.y2 - plan.y1), Math.sign(unclamped.y2 - unclamped.y1));
4247
},
4348
);
4449

50+
test.each<ScrollDirection>(['left', 'right'])(
51+
'a %s swipe longer than a narrow container shrinks inside it along x',
52+
(direction) => {
53+
const column: Rect = { x: 100, y: 0, width: 200, height: 874 };
54+
const unclamped = buildScrollGesturePlan({ direction, ...FRAME });
55+
const plan = buildScrollGesturePlan({ direction, ...FRAME, container: column });
56+
57+
assert.ok(strictlyInside(plan, column), JSON.stringify(plan));
58+
assert.deepEqual([plan.y1, plan.y2], [unclamped.y1, unclamped.y2]);
59+
assert.equal(plan.pixels, Math.abs(plan.x2 - plan.x1));
60+
assert.ok(plan.pixels < unclamped.pixels);
61+
assert.equal(plan.requestedPixels, unclamped.pixels);
62+
assert.equal(Math.sign(plan.x2 - plan.x1), Math.sign(unclamped.x2 - unclamped.x1));
63+
},
64+
);
65+
66+
test('a horizontal swipe that fits an offset container moves into it without shortening', () => {
67+
const rightPane: Rect = { x: 180, y: 0, width: 222, height: 874 };
68+
const unclamped = buildScrollGesturePlan({ direction: 'left', pixels: 100, ...FRAME });
69+
const plan = buildScrollGesturePlan({
70+
direction: 'left',
71+
pixels: 100,
72+
...FRAME,
73+
container: rightPane,
74+
});
75+
76+
assert.ok(strictlyInside(plan, rightPane), JSON.stringify(plan));
77+
assert.equal(Math.abs(plan.x2 - plan.x1), Math.abs(unclamped.x2 - unclamped.x1));
78+
assert.equal(plan.pixels, unclamped.pixels);
79+
assert.equal('requestedPixels' in plan, false);
80+
});
81+
4582
test.each<ScrollDirection>(['up', 'down', 'left', 'right'])(
4683
'a %s swipe already inside its container keeps today’s endpoints and distance',
4784
(direction) => {
@@ -68,24 +105,72 @@ test('a swipe that fits an offset container moves into it without shortening', (
68105
container: lowerContainer,
69106
});
70107

71-
assert.ok(endpointsInside(plan, lowerContainer), JSON.stringify(plan));
72-
assert.equal(Math.min(plan.y1, plan.y2), lowerContainer.y);
108+
assert.ok(strictlyInside(plan, lowerContainer), JSON.stringify(plan));
73109
assert.equal(Math.abs(plan.y1 - plan.y2), Math.abs(unclamped.y1 - unclamped.y2));
74110
assert.equal(plan.pixels, unclamped.pixels);
75111
assert.equal('requestedPixels' in plan, false);
76112
});
77113

78-
test('a vertical swipe beside a narrow container runs down its centre line', () => {
114+
test('an odd span that only loses its rounding pixel is not reported as shortened', () => {
115+
// On an 875-point axis the padded band is 88..787 (699 points), and a 699-point request centred
116+
// on 438 rounds its halves to a 700-point lane. Fitting it into the band drops that rounding
117+
// pixel, not any of the travel asked for.
118+
const frame = { referenceWidth: 402, referenceHeight: 875 };
119+
const wholeFrame: Rect = { x: 0, y: 0, width: 402, height: 875 };
120+
const plan = buildScrollGesturePlan({
121+
direction: 'up',
122+
pixels: 699,
123+
...frame,
124+
container: wholeFrame,
125+
});
126+
127+
assert.equal(plan.pixels, 699);
128+
assert.equal(Math.abs(plan.y2 - plan.y1), 699);
129+
assert.equal('requestedPixels' in plan, false);
130+
});
131+
132+
test('a vertical swipe beside a narrow container moves across into it', () => {
79133
const rightColumn: Rect = { x: 250, y: 0, width: 152, height: 874 };
80134
const unclamped = buildScrollGesturePlan({ direction: 'up', ...FRAME });
81135
const plan = buildScrollGesturePlan({ direction: 'up', ...FRAME, container: rightColumn });
82136

83-
assert.equal(plan.x1, rightColumn.x + rightColumn.width / 2);
137+
assert.ok(strictlyInside(plan, rightColumn), JSON.stringify(plan));
138+
assert.ok(plan.x1 <= FRAME.referenceWidth - PADDED_LEFT, `swipe x ${plan.x1} is in the padding`);
84139
assert.equal(plan.x2, plan.x1);
85140
assert.deepEqual([plan.y1, plan.y2, plan.pixels], [unclamped.y1, unclamped.y2, unclamped.pixels]);
86141
});
87142

88-
test('a container lying wholly in the edge padding leaves the padded swipe as it was', () => {
143+
test('a container reaching into the side padding is swiped in the part the padding leaves', () => {
144+
const edgeColumn: Rect = { x: 0, y: 0, width: 60, height: 874 };
145+
const plan = buildScrollGesturePlan({ direction: 'up', ...FRAME, container: edgeColumn });
146+
147+
assert.ok(strictlyInside(plan, edgeColumn), JSON.stringify(plan));
148+
assert.ok(plan.x1 >= PADDED_LEFT, `swipe x ${plan.x1} is inside the side padding`);
149+
});
150+
151+
test.each<[ScrollDirection, string, Rect]>([
152+
[
153+
'up',
154+
'a navigation rail along the left edge',
155+
{ x: 0, y: 0, width: PADDED_LEFT - 1, height: 874 },
156+
],
157+
[
158+
'left',
159+
'a chip row just above the padded band',
160+
{ x: 0, y: 60, width: 402, height: PADDED_TOP - 61 },
161+
],
162+
])(
163+
'a %s swipe aimed at %s runs inside it when the cross-axis padding leaves none of it',
164+
(direction, _, container) => {
165+
const unclamped = buildScrollGesturePlan({ direction, ...FRAME });
166+
const plan = buildScrollGesturePlan({ direction, ...FRAME, container });
167+
168+
assert.ok(strictlyInside(plan, container), JSON.stringify(plan));
169+
assert.equal(plan.pixels, unclamped.pixels);
170+
},
171+
);
172+
173+
test('a container lying wholly in the padding of the scrolled axis leaves the padded swipe as it was', () => {
89174
const statusBand: Rect = { x: 0, y: 0, width: 402, height: PADDED_TOP - 1 };
90175
const unclamped = buildScrollGesturePlan({ direction: 'up', ...FRAME });
91176
const plan = buildScrollGesturePlan({ direction: 'up', ...FRAME, container: statusBand });

‎packages/contracts/src/scroll-gesture.ts‎

Lines changed: 86 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,10 @@ export type ScrollGestureOptions = {
5151
referenceHeight: number;
5252
/**
5353
* The scroll container the swipe is meant for, in the reference frame's own zero-origin space.
54-
* Both endpoints stay inside its intersection with the padded frame (#2714): a span that already
55-
* fits is unchanged, one that leaves it is moved in, and one longer than it is shortened.
54+
* Both endpoints stay strictly inside its intersection with the padded frame (#2714): a span
55+
* that already fits is unchanged, one that leaves it is moved in, and one longer than it is
56+
* shortened. A container the padding leaves nothing of along the scrolled axis gets the padded
57+
* swipe unchanged, since the safe bounds outrank the container.
5658
*/
5759
container?: Rect;
5860
};
@@ -106,95 +108,124 @@ export const DEFAULT_SCROLL_AMOUNT = 0.6;
106108
const DEFAULT_EDGE_PADDING_FRACTION = 0.1;
107109
// Edge presets stay close to the system gesture boundary without emitting edge coordinates.
108110
const SWIPE_PRESET_EDGE_MARGIN_PX = 8;
111+
// A swipe kept inside a container stays this far off its edges, so the drag never starts on the
112+
// container's boundary row.
113+
const SCROLL_CONTAINER_EDGE_INSET = 8;
109114

110115
export function buildScrollGesturePlan(options: ScrollGestureOptions): ScrollGesturePlan {
111116
const direction = options.direction;
112-
const axisLength =
113-
direction === 'up' || direction === 'down' ? options.referenceHeight : options.referenceWidth;
117+
const vertical = direction === 'up' || direction === 'down';
118+
const axisLength = vertical ? options.referenceHeight : options.referenceWidth;
119+
const crossLength = vertical ? options.referenceWidth : options.referenceHeight;
114120
const requestedAmount = resolveRequestedAmount(options.amount);
115121
const requestedPixels =
116122
options.pixels !== undefined
117123
? normalizeRequestedPixels(options.pixels)
118124
: Math.round(axisLength * requestedAmount);
119-
const edgePadding = Math.max(1, Math.round(axisLength * DEFAULT_EDGE_PADDING_FRACTION));
125+
const edgePadding = scrollEdgePadding(axisLength);
120126
const maxTravelPixels = Math.max(1, axisLength - edgePadding * 2);
121127
const travelPixels = Math.max(1, Math.min(requestedPixels, maxTravelPixels));
122128
const halfTravel = Math.round(travelPixels / 2);
123-
const centerX = Math.round(options.referenceWidth / 2);
124-
const centerY = Math.round(options.referenceHeight / 2);
125-
const buildPlan = (x1: number, y1: number, x2: number, y2: number): ScrollGesturePlan => ({
126-
direction,
127-
x1,
128-
y1,
129-
x2,
130-
y2,
131-
referenceWidth: options.referenceWidth,
132-
referenceHeight: options.referenceHeight,
133-
amount: options.amount,
134-
pixels: travelPixels,
135-
});
136-
137-
const vertical = direction === 'up' || direction === 'down';
129+
const axisCenter = Math.round(axisLength / 2);
138130
const unclamped = {
139-
axisStart: (vertical ? centerY : centerX) - halfTravel,
140-
axisEnd: (vertical ? centerY : centerX) + halfTravel,
141-
cross: vertical ? centerX : centerY,
131+
axisStart: axisCenter - halfTravel,
132+
axisEnd: axisCenter + halfTravel,
133+
cross: Math.round(crossLength / 2),
142134
};
135+
const crossPadding = scrollEdgePadding(crossLength);
143136
const lane = options.container
144137
? keepSwipeInContainer(unclamped, options.container, vertical, {
145-
min: edgePadding,
146-
max: axisLength - edgePadding,
138+
axis: { min: edgePadding, max: axisLength - edgePadding },
139+
cross: { min: crossPadding, max: crossLength - crossPadding },
140+
crossFrame: { min: 0, max: crossLength },
147141
})
148142
: unclamped;
149-
const shortened = lane.axisEnd - lane.axisStart < unclamped.axisEnd - unclamped.axisStart;
150-
const plan = buildPlan(
151-
vertical ? lane.cross : lane.axisStart,
152-
vertical ? lane.axisStart : lane.cross,
153-
vertical ? lane.cross : lane.axisEnd,
154-
vertical ? lane.axisEnd : lane.cross,
155-
);
156-
const placed = shortened
157-
? { ...plan, pixels: lane.axisEnd - lane.axisStart, requestedPixels: travelPixels }
158-
: plan;
159-
// `up`/`left` drag from the low end toward the high end; `down`/`right` drag the other way.
160-
return direction === 'up' || direction === 'left'
161-
? placed
162-
: { ...placed, x1: placed.x2, y1: placed.y2, x2: placed.x1, y2: placed.y1 };
143+
const laneLength = lane.axisEnd - lane.axisStart;
144+
// Centring rounds an odd span up by one, so only a lane shorter than the travel itself is short.
145+
const shortened = laneLength < travelPixels;
146+
return {
147+
direction,
148+
...laneEndpoints(direction, lane),
149+
referenceWidth: options.referenceWidth,
150+
referenceHeight: options.referenceHeight,
151+
amount: options.amount,
152+
pixels: shortened ? laneLength : travelPixels,
153+
...(shortened ? { requestedPixels: travelPixels } : {}),
154+
};
155+
}
156+
157+
/** `up`/`left` drag from the lane's low end toward its high end; `down`/`right` drag the other way. */
158+
function laneEndpoints(
159+
direction: ScrollDirection,
160+
lane: SwipeLane,
161+
): Pick<ScrollGesturePlan, 'x1' | 'y1' | 'x2' | 'y2'> {
162+
const vertical = direction === 'up' || direction === 'down';
163+
const low = vertical
164+
? { x: lane.cross, y: lane.axisStart }
165+
: { x: lane.axisStart, y: lane.cross };
166+
const high = vertical ? { x: lane.cross, y: lane.axisEnd } : { x: lane.axisEnd, y: lane.cross };
167+
const [start, end] = direction === 'up' || direction === 'left' ? [low, high] : [high, low];
168+
return { x1: start.x, y1: start.y, x2: end.x, y2: end.y };
163169
}
164170

165171
type SwipeLane = { axisStart: number; axisEnd: number; cross: number };
166172

173+
type CoordinateRange = { min: number; max: number };
174+
175+
function scrollEdgePadding(length: number): number {
176+
return Math.max(1, Math.round(length * DEFAULT_EDGE_PADDING_FRACTION));
177+
}
178+
167179
/**
168-
* Moves a centred swipe lane inside the container's intersection with the padded axis, shortening
169-
* it only when the intersection is shorter than the lane. A container wholly inside the padding
170-
* leaves nothing to swipe in, so the lane stays as the padded frame planned it.
180+
* Moves a centred swipe lane inside the container's intersection with the padded frame,
181+
* shortening it only when that intersection is shorter than the lane. The container is half-open,
182+
* as Android bounds and View hit-testing are, and inset from its edges, so every endpoint lands on
183+
* a row the container owns. A container the padding leaves nothing of on the scrolled axis keeps
184+
* the lane the padded frame planned: the safe bounds outrank the container, and the movement read
185+
* reports the miss as `container-outside-swipe` when nothing else moved.
171186
*/
172187
function keepSwipeInContainer(
173188
lane: SwipeLane,
174189
container: Rect,
175190
vertical: boolean,
176-
padded: { min: number; max: number },
191+
padded: { axis: CoordinateRange; cross: CoordinateRange; crossFrame: CoordinateRange },
177192
): SwipeLane {
178-
const containerMin = vertical ? container.y : container.x;
179-
const containerSize = vertical ? container.height : container.width;
180-
const bandMin = Math.max(padded.min, Math.round(containerMin));
181-
const bandMax = Math.min(padded.max, Math.round(containerMin + containerSize));
182-
if (bandMax <= bandMin) return lane;
183-
184-
const crossMin = vertical ? container.x : container.y;
193+
const band = insetContainerRange(
194+
vertical ? container.y : container.x,
195+
vertical ? container.height : container.width,
196+
padded.axis,
197+
);
198+
const crossStart = vertical ? container.x : container.y;
185199
const crossSize = vertical ? container.width : container.height;
200+
// The padding guards the scrolled axis against system bars. Across it, a rail or chip row that
201+
// sits wholly in the padding is still the surface asked for, so the swipe runs along it there.
202+
const crossBand =
203+
insetContainerRange(crossStart, crossSize, padded.cross) ??
204+
insetContainerRange(crossStart, crossSize, padded.crossFrame);
205+
if (!band || !crossBand) return lane;
206+
186207
const cross =
187-
lane.cross >= crossMin && lane.cross <= crossMin + crossSize
208+
lane.cross >= crossBand.min && lane.cross <= crossBand.max
188209
? lane.cross
189-
: Math.round(crossMin + crossSize / 2);
190-
210+
: Math.round((crossBand.min + crossBand.max) / 2);
191211
const length = lane.axisEnd - lane.axisStart;
192-
if (length >= bandMax - bandMin) return { axisStart: bandMin, axisEnd: bandMax, cross };
212+
if (length >= band.max - band.min) return { axisStart: band.min, axisEnd: band.max, cross };
193213
const shift =
194-
lane.axisStart < bandMin ? bandMin - lane.axisStart : Math.min(0, bandMax - lane.axisEnd);
214+
lane.axisStart < band.min ? band.min - lane.axisStart : Math.min(0, band.max - lane.axisEnd);
195215
return { axisStart: lane.axisStart + shift, axisEnd: lane.axisEnd + shift, cross };
196216
}
197217

218+
/** The coordinates of `[start, start + size)` an inset swipe may use inside `padded`, if any. */
219+
function insetContainerRange(
220+
start: number,
221+
size: number,
222+
padded: CoordinateRange,
223+
): CoordinateRange | undefined {
224+
const min = Math.max(padded.min, Math.ceil(start) + SCROLL_CONTAINER_EDGE_INSET);
225+
const max = Math.min(padded.max, Math.floor(start + size) - 1 - SCROLL_CONTAINER_EDGE_INSET);
226+
return max > min ? { min, max } : undefined;
227+
}
228+
198229
/**
199230
* Validates pre-frame scroll inputs (amount/pixels) the same way buildScrollGesturePlan would,
200231
* so the daemon throws INVALID_ARGS for bad inputs BEFORE sending the fused runner `scroll`

0 commit comments

Comments
 (0)