Skip to content

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

TypeScript

fix(core): hand the Bottom Sheet the pull when its content runs out (#5172)

Xinzi Zhou773ff1674642
diff --git a/.changeset/bottom-sheet-continuous-handoff.md b/.changeset/bottom-sheet-continuous-handoff.md
new file mode 100644
index 0000000000..7a1a15d1a1
--- /dev/null
+++ b/.changeset/bottom-sheet-continuous-handoff.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] BottomSheet: a swipe that scrolls to the end of the sheet's content and keeps pulling now expands the sheet, instead of stopping dead at the last line. The handoff used to be decided once, when the finger landed: a gesture that started mid-content stayed a scroll for its whole life, so the natural motion — swipe up through the list, reach the bottom, keep pulling — never reached the sheet. Reaching the end of the content is now enough. The sheet is anchored at the point where the content ran out, so only the travel past it moves the sheet, and the pull is left to the content when the finger comes back down or when there is no taller detent to expand into.
+
+@imdreamrunner
diff --git a/packages/core/src/BottomSheet/useSheetGestures.test.ts b/packages/core/src/BottomSheet/useSheetGestures.test.ts
index 87ac419154..b7d8b52a33 100644
--- a/packages/core/src/BottomSheet/useSheetGestures.test.ts
+++ b/packages/core/src/BottomSheet/useSheetGestures.test.ts
@@ -669,6 +669,187 @@ describe('useSheetGestures', () => {
});
});
+ describe('body touch handoff mid-gesture', () => {
+ // The reported bug: the finger lands mid-content, swipes up, REACHES the
+ // end of the content, and keeps pulling in the same continuous gesture.
+ // Arming decided at touchstart can never see that, and by the time the
+ // scroller is at its end the browser owns the gesture — every remaining
+ // touchmove is non-cancelable, so preventDefault() is not available to
+ // promote with. These cases pin the anchored, cancel-free handoff instead.
+ function makeScroller(opts: {
+ scrollTop: number;
+ clientHeight: number;
+ scrollHeight: number;
+ }) {
+ const sheet = makeTarget();
+ const el = document.createElement('div');
+ Object.defineProperty(el, 'scrollTop', {
+ value: opts.scrollTop,
+ writable: true,
+ });
+ Object.defineProperty(el, 'clientHeight', {value: opts.clientHeight});
+ Object.defineProperty(el, 'scrollHeight', {value: opts.scrollHeight});
+ el.getBoundingClientRect = () => ({height: SHEET_HEIGHT}) as DOMRect;
+ sheet.appendChild(el);
+ document.body.appendChild(sheet);
+ return el;
+ }
+ function touch(el: HTMLElement, type: string, y: number, id = 1) {
+ const ev = new Event(type, {bubbles: true, cancelable: true});
+ Object.defineProperty(ev, 'changedTouches', {
+ value: [{identifier: id, clientY: y}],
+ });
+ Object.defineProperty(ev, 'touches', {
+ value:
+ type === 'touchend' || type === 'touchcancel'
+ ? []
+ : [{identifier: id, clientY: y}],
+ });
+ Object.defineProperty(ev, 'currentTarget', {value: el});
+ el.dispatchEvent(ev);
+ return ev;
+ }
+ // A scroller with 600px of scrollable content, resting one detent down so
+ // an upward pull has somewhere to expand to.
+ function midDetentScroller(hook: Hook, scrollTop: number) {
+ const el = makeScroller({
+ scrollTop,
+ clientHeight: 200,
+ scrollHeight: 800,
+ });
+ act(() => hook.result.current.sheetRef(el));
+ act(() => hook.result.current.bodyProps.ref(el));
+ down(hook, 0, 0, el);
+ move(hook, 180, 700, el);
+ up(hook, 180, 1100, el);
+ expect(hook.result.current.settledOffset).toBe(200);
+ return el;
+ }
+
+ it('hands off when the content runs out under a moving finger', () => {
+ const {hook} = setup({snapHeights: () => [200]});
+ const el = midDetentScroller(hook, 300); // finger lands mid-content
+ act(() => {
+ touch(el, 'touchstart', 500);
+ el.scrollTop = 450; // the swipe scrolls the content...
+ touch(el, 'touchmove', 350);
+ el.scrollTop = 600; // ...until it runs out at the bottom
+ touch(el, 'touchmove', 200); // the content ended here
+ touch(el, 'touchmove', 150); // 50px BEYOND the end
+ });
+ expect(hook.result.current.isDragging).toBe(true);
+ // Anchored where the content ran out, so only the 50px past it moves the
+ // sheet. Anchoring at touchstart would have thrown it 350px instead.
+ expect(hook.result.current.dragOffset).toBe(150);
+ });
+
+ it('does not preventDefault the mid-gesture handoff', () => {
+ // By this point in the gesture the events are non-cancelable anyway, and
+ // there is nothing to cancel: the scroller is clamped at its end.
+ // Claiming the gesture would only strand the content under the finger.
+ const {hook} = setup({snapHeights: () => [200]});
+ const el = midDetentScroller(hook, 300);
+ let atEnd: Event | undefined;
+ let past: Event | undefined;
+ let further: Event | undefined;
+ act(() => {
+ touch(el, 'touchstart', 500);
+ el.scrollTop = 600;
+ atEnd = touch(el, 'touchmove', 200);
+ past = touch(el, 'touchmove', 150);
+ further = touch(el, 'touchmove', 100);
+ });
+ expect(hook.result.current.isDragging).toBe(true);
+ expect(atEnd?.defaultPrevented).toBe(false);
+ expect(past?.defaultPrevented).toBe(false);
+ expect(further?.defaultPrevented).toBe(false);
+ });
+
+ it('gives the gesture back when the finger returns to the content end', () => {
+ const {hook} = setup({snapHeights: () => [200]});
+ const el = midDetentScroller(hook, 300);
+ act(() => {
+ touch(el, 'touchstart', 500);
+ el.scrollTop = 600;
+ touch(el, 'touchmove', 200); // the content ended here
+ touch(el, 'touchmove', 150);
+ });
+ expect(hook.result.current.dragOffset).toBe(150);
+
+ act(() => {
+ touch(el, 'touchmove', 210); // back below the anchor
+ });
+ // The native scroll was never cancelled, so it resumes from here. Two
+ // things moving at once is the failure mode; the sheet yields.
+ expect(hook.result.current.isDragging).toBe(false);
+ expect(hook.result.current.settledOffset).toBe(200);
+
+ act(() => {
+ el.scrollTop = 600; // scrolled back to the end
+ touch(el, 'touchmove', 190); // and pulls past it again
+ touch(el, 'touchmove', 140);
+ });
+ expect(hook.result.current.isDragging).toBe(true);
+ expect(hook.result.current.dragOffset).toBe(150);
+ });
+
+ it('does not hand off on reaching the end without travelling past it', () => {
+ // Landing on the last pixel is not a pull, and the momentum tail after
+ // the finger lifts fires no touchmove at all, so it can never promote.
+ const {hook} = setup({snapHeights: () => [200]});
+ const el = midDetentScroller(hook, 300);
+ act(() => {
+ touch(el, 'touchstart', 500);
+ el.scrollTop = 600;
+ touch(el, 'touchmove', 200);
+ touch(el, 'touchmove', 199); // jitter, not a pull
+ touch(el, 'touchend', 199);
+ el.scrollTop = 600; // momentum carries on with no finger down
+ });
+ expect(hook.result.current.isDragging).toBe(false);
+ expect(hook.result.current.settledOffset).toBe(200);
+ });
+
+ it('leaves the mid-gesture pull to the content at the tallest detent', () => {
+ // Same #5161 rule as the touchstart-armed edge: with no taller detent
+ // there is nothing to expand into, so the scroller keeps the gesture.
+ const {hook} = setup({snapHeights: () => [200]});
+ const el = makeScroller({
+ scrollTop: 300,
+ clientHeight: 200,
+ scrollHeight: 800,
+ });
+ act(() => hook.result.current.sheetRef(el));
+ act(() => hook.result.current.bodyProps.ref(el));
+ expect(hook.result.current.settledOffset).toBe(0);
+
+ let past: Event | undefined;
+ act(() => {
+ touch(el, 'touchstart', 500);
+ el.scrollTop = 600;
+ touch(el, 'touchmove', 200);
+ past = touch(el, 'touchmove', 100);
+ });
+ expect(hook.result.current.isDragging).toBe(false);
+ expect(hook.result.current.dragOffset).toBe(0);
+ expect(past?.defaultPrevented).toBe(false);
+ });
+
+ it('does not hand off while the content can still scroll', () => {
+ const {hook} = setup({snapHeights: () => [200]});
+ const el = midDetentScroller(hook, 0);
+ act(() => {
+ touch(el, 'touchstart', 500);
+ el.scrollTop = 200;
+ touch(el, 'touchmove', 300);
+ el.scrollTop = 400;
+ touch(el, 'touchmove', 100); // 400px of pull, all of it scrolling
+ });
+ expect(hook.result.current.isDragging).toBe(false);
+ expect(hook.result.current.settledOffset).toBe(200);
+ });
+ });
+
describe('viewport resize', () => {
// The panel pins the sheet's height in px at a resizing detent; everywhere
// else the height comes from CSS (`92dvh`), which follows the viewport.
diff --git a/packages/core/src/BottomSheet/useSheetGestures.ts b/packages/core/src/BottomSheet/useSheetGestures.ts
index 454a94c796..5880283519 100644
--- a/packages/core/src/BottomSheet/useSheetGestures.ts
+++ b/packages/core/src/BottomSheet/useSheetGestures.ts
@@ -28,6 +28,16 @@
* is tracked by index: the pixels stop meaning the same thing when the
* viewport changes, the stop the user chose does not.
*
+ * On touch, the scrolling body hands the gesture to the sheet at a scroll
+ * edge. Two shapes, because the browser only offers one of them a choice: a
+ * finger that lands on an edge and pulls away from it promotes by cancelling
+ * the first, still-cancelable touchmove; a finger that scrolls INTO the end of
+ * the content mid-gesture cannot, since the browser has committed the gesture
+ * to scrolling and every remaining event is non-cancelable. The second shape
+ * needs no cancelling — the scroller is clamped at its end, so there is
+ * nothing left to scroll — and instead anchors at the point where the content
+ * ran out and drives the sheet from the travel beyond it.
+ *
* Kept private to BottomSheet: a dismiss edge + detents on a bottom-anchored
* surface are inherently sheet concepts. It is not a general primitive and is
* intentionally not exported.
@@ -79,6 +89,11 @@ const OVERSCROLL_RESISTANCE = 0.35;
// bottom padding the lift reveals). Kept as a local const rather than a shared
// import so it can be used inside stylex.create there.
const OVERSCROLL_MAX = 48;
+// Travel past the point where a scrolling gesture ran out of content before it
+// hands the sheet the rest of the pull. Small enough to feel continuous with
+// the scroll, large enough that a swipe merely coming to rest on the last pixel
+// doesn't start a drag on jitter.
+const CONTENT_END_HANDOFF_SLOP = 4;
// Short haptic tick on detent settle where supported. iOS Safari doesn't
// expose navigator.vibrate, so this is a no-op there; skipped under
@@ -1062,11 +1077,24 @@ export function useSheetGestures({
// Non-passive touchmove is the reliable scroll<->drag handoff on touch:
// preventDefault() at a scroll edge stops the native scroll and drives the
// sheet drag through the pointer math (Touch adapted to the fields it reads).
+ //
+ // Every touch on the body is tracked, not only the ones that begin at an
+ // edge: a gesture that starts mid-content and scrolls to the end has to hand
+ // off too, and by then it is far too late to arm from `touchstart`.
const touchDragRef = useRef<{
id: number;
startY: number;
top: boolean;
bottom: boolean;
+ // Where the finger was when the scroller ran out of content, or null while
+ // it can still scroll. A mid-gesture handoff drives the sheet from travel
+ // BEYOND this point, so the part of the swipe that legitimately scrolled
+ // doesn't move the sheet as well.
+ contentEndY: number | null;
+ // Whether the drag in flight was promoted from `contentEndY` rather than
+ // armed at `touchstart`. That drag never cancelled the native scroll, so
+ // it has to yield again if the finger comes back down.
+ promotedAtContentEnd: boolean;
} | null>(null);
const previousTouchHandlersRef = useRef<{
start: (e: TouchEvent) => void;
@@ -1105,9 +1133,11 @@ export function useSheetGestures({
const onTouchStart = (event: TouchEvent) => {
const scroller = event.currentTarget as HTMLElement;
const touch = event.changedTouches[0];
- // Arm only at a scroll edge; from mid-content this is an ordinary scroll.
+ // Record where the gesture began and whether it began at a scroll edge.
// At the top, a pull DOWN hands off (collapse); at the bottom, a pull UP
- // hands off (expand). Record the edge so the move handler matches it.
+ // hands off (expand). A gesture that starts mid-content is an ordinary
+ // scroll, but it is tracked all the same: the scroller can run out of
+ // content while the finger is still down (see onTouchMove).
if (!touch) {
touchDragRef.current = null;
return;
@@ -1122,31 +1152,48 @@ export function useSheetGestures({
// downward to scroll back would collapse the sheet instead. Leave the
// gesture with the content.
const bottom = atBottom(scroller) && activeOffsetRef.current > 0;
- if (!top && !bottom) {
- touchDragRef.current = null;
- return;
- }
touchDragRef.current = {
id: touch.identifier,
startY: touch.clientY,
top,
bottom,
+ contentEndY: null,
+ promotedAtContentEnd: false,
};
};
const onTouchMove = (event: TouchEvent) => {
const scroller = event.currentTarget as HTMLElement;
+ const armed = touchDragRef.current;
if (dragStateRef.current) {
const t = [...event.changedTouches].find(
x => x.identifier === dragStateRef.current?.pointerId,
);
- if (t) {
- event.preventDefault();
+ if (!t) {
+ return;
+ }
+ if (armed?.promotedAtContentEnd && armed.contentEndY != null) {
+ if (t.clientY >= armed.contentEndY) {
+ // Back at the point where the content ran out. This drag never
+ // cancelled the native scroll — it couldn't, the events were no
+ // longer cancelable — so the scroller is about to move again. Hand
+ // the gesture back rather than driving the sheet and the content
+ // at once; a later pull past the end promotes again.
+ armed.contentEndY = null;
+ armed.promotedAtContentEnd = false;
+ cancelDragRef.current(scroller);
+ return;
+ }
+ // Deliberately NOT preventDefault()ed: the scroller is clamped at
+ // its end, so there is no scrolling left to cancel, and claiming the
+ // gesture would strand the content for as long as the finger is down.
pointerMoveRef.current(asPointer(t, scroller));
+ return;
}
+ event.preventDefault();
+ pointerMoveRef.current(asPointer(t, scroller));
return;
}
- const armed = touchDragRef.current;
if (!armed) {
return;
}
@@ -1170,9 +1217,36 @@ export function useSheetGestures({
armed.startY,
);
pointerMoveRef.current(asPointer(t, scroller));
- } else if ((armed.top && delta < 0) || (armed.bottom && delta > 0)) {
- // Scrolling away from the armed edge; hand back to native scroll.
- touchDragRef.current = null;
+ return;
+ }
+ if ((armed.top && delta < 0) || (armed.bottom && delta > 0)) {
+ // Scrolling away from the armed edge; hand back to native scroll. The
+ // touch stays tracked: this is the swipe that may reach the far edge.
+ armed.top = false;
+ armed.bottom = false;
+ }
+ // Reaching the end of the content mid-gesture. Arming at `touchstart`
+ // cannot see this, and re-arming for a preventDefault() promotion would
+ // be useless anyway: once the browser has committed the gesture to
+ // scrolling, every remaining touchmove is non-cancelable. Nothing needs
+ // cancelling either — the scroller is clamped at its maximum, so further
+ // upward travel scrolls nothing. Anchor at the point where the content
+ // ran out and give the sheet everything past it, so the pull continues
+ // into the sheet with no jump and no lost scrolling.
+ if (activeOffsetRef.current > 0 && atBottom(scroller)) {
+ if (armed.contentEndY == null) {
+ armed.contentEndY = t.clientY;
+ } else if (armed.contentEndY - t.clientY >= CONTENT_END_HANDOFF_SLOP) {
+ armed.promotedAtContentEnd = true;
+ beginDragRef.current(
+ asPointer(t, scroller),
+ measureHeightRef.current(),
+ armed.contentEndY,
+ );
+ pointerMoveRef.current(asPointer(t, scroller));
+ }
+ } else {
+ armed.contentEndY = null;
}
};