Skip to content

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

TypeScript

fix(core): a BottomSheet release settles where it would coast to (#7170)

Christopher Chedeau9613feb6d486
diff --git a/.changeset/bottom-sheet-projected-release.md b/.changeset/bottom-sheet-projected-release.md
new file mode 100644
index 0000000000..371f349584
--- /dev/null
+++ b/.changeset/bottom-sheet-projected-release.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] A BottomSheet release is judged where the sheet would coast to at the finger's speed, not where the finger left it: a medium throw dismisses from short of the dismiss line and a gentle throw lands on the next detent instead of snapping back, the release speed is read over the finger's last 100ms rather than its last two samples, and a finger that rests before lifting releases no throw. A nudge under 48px still projects nothing.
+
+@vjeux
diff --git a/packages/core/src/BottomSheet/useSheetGestures.test.ts b/packages/core/src/BottomSheet/useSheetGestures.test.ts
index 4c5cef8121..2df1312f9f 100644
--- a/packages/core/src/BottomSheet/useSheetGestures.test.ts
+++ b/packages/core/src/BottomSheet/useSheetGestures.test.ts
@@ -157,11 +157,97 @@ describe('useSheetGestures', () => {
expect(hook.result.current.settledOffset).toBe(0);
});
+ describe('release projection', () => {
+ // A release is judged where the sheet would coast to at the finger's
+ // speed, the way a thrown scroll view is, not where the finger left it.
+ it('dismisses on a medium throw released short of the dismiss line', () => {
+ const {hook, onDismiss} = setup({snapHeights: () => [200]});
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ // 150px in 150ms = 1px/ms. The finger stops at 150, well short of the
+ // 280px line; a surface moving at that speed coasts far past it.
+ move(hook, 50, 50, t);
+ move(hook, 100, 100, t);
+ move(hook, 150, 150, t);
+ up(hook, 150, 152, t);
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('lands a gentle throw on the next detent, not back where it started', () => {
+ const onSnap = vi.fn();
+ const {hook, onDismiss} = setup({snapHeights: () => [200], onSnap});
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ // 60px in 200ms = 0.3px/ms: too slow to be a flick, too short to reach
+ // the 200px detent by position. The coast carries it there.
+ move(hook, 30, 100, t);
+ move(hook, 60, 200, t);
+ up(hook, 60, 202, t);
+ expect(onDismiss).not.toHaveBeenCalled();
+ expect(hook.result.current.settledOffset).toBe(200);
+ expect(onSnap).toHaveBeenLastCalledWith(200);
+ });
+
+ it('reads the release speed over the last stretch, so one slow sample does not cancel a throw', () => {
+ const {hook, onDismiss} = setup({snapHeights: () => [200]});
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ move(hook, 60, 20, t); // 3px/ms
+ move(hook, 62, 90, t); // the lift's own last, slow sample
+ up(hook, 62, 92, t);
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('reads a throw that begins after a hold at its own speed, not the average since touch-down', () => {
+ const {hook, onDismiss} = setup({snapHeights: () => [200]});
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ move(hook, 0, 250, t); // a still hold on the handle
+ move(hook, 30, 275, t); // then 60px in 50ms
+ move(hook, 60, 300, t);
+ up(hook, 60, 302, t);
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('reads a single move after a hold as a move, not as the whole hold', () => {
+ const {hook, onDismiss} = setup({snapHeights: () => [200]});
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ move(hook, 60, 300, t); // one sample, 300ms after touch-down
+ up(hook, 60, 302, t);
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('releases no throw from a finger that rested before lifting', () => {
+ const {hook, onDismiss} = setup({snapHeights: () => [200]});
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ move(hook, 60, 20, t); // 3px/ms ...
+ up(hook, 60, 400, t); // ... then 380ms of rest, then the lift
+ expect(onDismiss).not.toHaveBeenCalled();
+ expect(hook.result.current.settledOffset).toBe(0);
+ });
+
+ it('settles a throw that would coast past the line at the shortest detent when canDismiss is false', () => {
+ const {hook, onDismiss} = setup({
+ canDismiss: false,
+ snapHeights: () => [200],
+ });
+ const t = makeTarget();
+ down(hook, 0, 0, t);
+ move(hook, 50, 50, t);
+ move(hook, 100, 100, t);
+ up(hook, 100, 102, t);
+ expect(onDismiss).not.toHaveBeenCalled();
+ expect(hook.result.current.settledOffset).toBe(200);
+ });
+ });
+
it('does not flick-dismiss on a fast but short nudge', () => {
const {hook, onDismiss} = setup({snapHeights: () => [200]});
const t = makeTarget();
// Fast (20px/10ms = 2px/ms) but only 20px of travel — under the distance
- // floor, so it settles rather than dismissing.
+ // floor, so nothing is projected and it settles rather than dismissing.
down(hook, 0, 0, t);
move(hook, 20, 10, t);
up(hook, 20, 12, t);
diff --git a/packages/core/src/BottomSheet/useSheetGestures.ts b/packages/core/src/BottomSheet/useSheetGestures.ts
index 097eb56dc5..a04879a8a1 100644
--- a/packages/core/src/BottomSheet/useSheetGestures.ts
+++ b/packages/core/src/BottomSheet/useSheetGestures.ts
@@ -10,9 +10,10 @@
* @position Internal to BottomSheet; not exported from the core entry point
*
* Drag + snap machinery for the bottom sheet. Tracks a pointer drag down the
- * block axis, translates the sliding surface live, and on release either
- * settles to the nearest snap detent (a slow drag) or dismisses (a fast flick
- * down). A fast flick up expands to the tallest detent. This is the core
+ * block axis, translates the sliding surface live, and on release settles to
+ * the detent nearest where the sheet would coast to at the finger's speed, or
+ * dismisses when that is past the dismiss line. A slow drag projects onto
+ * itself and places; a throw continues past the finger. This is the core
* behavior split the sheet needs: DRAG places, SWIPE closes.
*
* A settled detent is split across two properties: `settledLayoutOffset` is
@@ -93,11 +94,19 @@ interface SheetDetents {
peekOffset: number | null;
}
-// A flick (fast throw) dismisses (down) or expands (up) regardless of where
-// it ends. Requires both a speed and a distance floor so a small nudge
-// doesn't trigger it.
-const FLICK_VELOCITY = 1.2; // px/ms
-const FLICK_MIN_DISTANCE = 48; // px traveled during the gesture
+// A release is judged where the sheet WOULD come to rest, not where the
+// finger left it: the release position plus the distance a surface moving at
+// the finger's speed travels while it decelerates. The rate is UIKit's normal
+// scroll deceleration (0.998 per ms), so a throw ends where a thrown scroll
+// view would, and a slow release projects onto itself. A gesture shorter than
+// the travel floor projects nothing: a nudge has no throw to continue.
+const DECELERATION_RATE = 0.998;
+const PROJECTION_FACTOR = DECELERATION_RATE / (1 - DECELERATION_RATE); // ms
+const PROJECTION_MIN_TRAVEL = 48; // px traveled during the gesture
+// The release speed is the finger's speed over its last stretch, not between
+// its last two samples: one slow sample before the lift must not cancel a
+// throw, and a finger that paused before lifting has no speed at all.
+const VELOCITY_WINDOW_MS = 100;
// On a slow drag below the shortest detent, dismiss once dragged past it by
// more than this fraction of that detent's height; otherwise snap back to it.
const DISMISS_OVERSHOOT_RATIO = 0.4;
@@ -582,6 +591,9 @@ export function useSheetGestures({
startCoord: number;
lastCoord: number;
lastTime: number;
+ // The finger's recent positions, oldest first, kept to VELOCITY_WINDOW_MS
+ // (and never fewer than two) for the release speed.
+ samples: {t: number; y: number}[];
velocity: number;
height: number;
baseOffset: number;
@@ -942,8 +954,12 @@ export function useSheetGestures({
maxOffset,
offscreenBlockEndInsetRef.current,
);
- const speed = Math.abs(velocity);
- const isFlick = speed > FLICK_VELOCITY && travel > FLICK_MIN_DISTANCE;
+ const dismissOffset =
+ maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
+ const projected =
+ travel > PROJECTION_MIN_TRAVEL
+ ? offset + velocity * PROJECTION_FACTOR
+ : offset;
const settleAt = (target: number) => {
// A peek keeps the full layout height and slides below the viewport;
// every taller detent resizes the scrolling area to what it shows.
@@ -967,8 +983,6 @@ export function useSheetGestures({
offscreenBlockEndInsetRef.current,
),
);
- const dismissOffset =
- maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
onScrimOpacityRef.current?.(
scrimOpacityForOffset(target, offsets, dismissOffset, peekOffset),
);
@@ -977,7 +991,9 @@ export function useSheetGestures({
}
};
- if (dir > 0 && isFlick) {
+ // A release that would coast past the dismiss line closes the sheet: a
+ // throw from anywhere, or a slow drag that already crossed it.
+ if (dir > 0 && projected > dismissOffset) {
if (canDismissRef.current) {
prepareScrollAreaSettle(
baseLayoutOffset,
@@ -994,49 +1010,16 @@ export function useSheetGestures({
}
return;
}
- // Fast upward flick = expand to the tallest detent (the sheet's full
- // provided height).
- if (dir < 0 && isFlick) {
- prepareScrollAreaSettle(
- baseLayoutOffset,
- 0,
- 0,
- renderedOffset,
- layoutOffset,
- naturalEndGap,
- true,
- );
- recordSettledLayoutOffset(0);
- settledDetentIndexRef.current = 0;
- setDragOffset(0);
- setSettledOffset(0);
- onSnapRef.current?.(
- visibleHeightForOffset(height, 0, offscreenBlockEndInsetRef.current),
- );
- onScrimOpacityRef.current?.(1);
- hapticTick();
- return;
- }
- if (offset > maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO) {
- if (canDismissRef.current) {
- prepareScrollAreaSettle(
- baseLayoutOffset,
- baseOffset,
- baseLayoutOffset,
- baseLayoutOffset,
- baseLayoutOffset,
- naturalEndGap,
- false,
- );
- onDismissRef.current();
- } else {
- settleAt(maxOffset);
- }
- return;
- }
- // Settle to the nearest detent in the drag direction (never back past
- // the starting detent), de-duped and direction-clamped by the util.
- const target = resolveSettleOffset(offset, offsets, dir, baseOffset);
+ // Settle to the detent nearest where the release would coast to, in the
+ // drag direction (never back past the starting detent), de-duped and
+ // direction-clamped by the util. A throw upward projects past the
+ // tallest detent and lands on it.
+ const target = resolveSettleOffset(
+ Math.min(Math.max(projected, 0), maxOffset),
+ offsets,
+ dir,
+ baseOffset,
+ );
settleAt(target);
},
[prepareScrollAreaSettle, recordSettledLayoutOffset, resolveDetents],
@@ -1067,6 +1050,7 @@ export function useSheetGestures({
startCoord: start,
lastCoord: event.clientY,
lastTime: event.timeStamp,
+ samples: [{t: event.timeStamp, y: event.clientY}],
velocity: 0,
height: sheetHeight,
baseOffset: settledOffset,
@@ -1145,9 +1129,23 @@ export function useSheetGestures({
const delta = event.clientY - state.startCoord;
const dt = event.timeStamp - state.lastTime;
if (dt > 0) {
- state.velocity = (event.clientY - state.lastCoord) / dt;
state.lastCoord = event.clientY;
state.lastTime = event.timeStamp;
+ state.samples.push({t: event.timeStamp, y: event.clientY});
+ // Drop what fell out of the window while a partner remains: a throw
+ // that begins after a rest reads its own speed, not the average since
+ // touch-down.
+ while (
+ state.samples.length > 2 &&
+ event.timeStamp - state.samples[0].t > VELOCITY_WINDOW_MS
+ ) {
+ state.samples.shift();
+ }
+ const first = state.samples[0];
+ // A lone partner older than the window says only where the finger
+ // rested; the move it precedes is read as if it took the window.
+ const span = Math.min(event.timeStamp - first.t, VELOCITY_WINDOW_MS);
+ state.velocity = span > 0 ? (event.clientY - first.y) / span : 0;
}
const {offsets, peekOffset} = resolveDetents(state.height);
@@ -1224,6 +1222,11 @@ export function useSheetGestures({
const delta = event.clientY - state.startCoord;
const offset = Math.max(0, state.baseOffset + delta);
const dir = delta === 0 ? 0 : delta > 0 ? 1 : -1;
+ // A finger that rested before lifting released nothing in motion.
+ const velocity =
+ event.timeStamp - state.lastTime < VELOCITY_WINDOW_MS
+ ? state.velocity
+ : 0;
dragStateRef.current = null;
if (!state.syntheticTouch) {
target.releasePointerCapture?.(event.pointerId);
@@ -1232,7 +1235,7 @@ export function useSheetGestures({
setIsTraveling(false);
settleFromDrag(
offset,
- state.velocity,
+ velocity,
state.height || 1,
dir,
Math.abs(delta),