react-modal-sheet 5.4.0 → 5.5.0

package/src/sheet.tsx

@@ -9,7 +9,6 @@ import {
 } from 'motion/react';
 import React, {
   forwardRef,
-  useEffect,
   useImperativeHandle,
   useRef,
   useState,
@@ -26,20 +25,15 @@ import {
 } from './constants';
 import { SheetContext } from './context';
 import { useDimensions } from './hooks/use-dimensions';
-import { useFocusedInput } from './hooks/use-focused-input';
+import { useKeyboardAvoidance } from './hooks/use-keyboard-avoidance';
 import { useModalEffect } from './hooks/use-modal-effect';
 import { usePreventScroll } from './hooks/use-prevent-scroll';
 import { useSheetState } from './hooks/use-sheet-state';
 import { useStableCallback } from './hooks/use-stable-callback';
-import { useVirtualKeyboard } from './hooks/use-virtual-keyboard';
-import {
-  computeSnapPoints,
-  handleHighVelocityDrag,
-  handleLowVelocityDrag,
-} from './snap';
+import { classifyDragEnd, computeSnapPoints } from './snap';
 import { styles } from './styles';
 import { type SheetContextType, type SheetProps } from './types';
-import { applyStyles, waitForElement } from './utils';
+import { applyStyles, waitForElement, willOpenKeyboard } from './utils';
 
 export const Sheet = forwardRef<any, SheetProps>(
   (
@@ -98,14 +92,6 @@ export const Sheet = forwardRef<any, SheetProps>(
       ...(reduceMotion ? REDUCED_MOTION_TWEEN_CONFIG : tweenConfig),
     };
 
-    const keyboard = useVirtualKeyboard({
-      isEnabled: isOpen && avoidKeyboard,
-      containerRef: sheetRef,
-    });
-
-    // Disable drag if the keyboard is open to avoid weird behavior
-    const disableDrag = keyboard.isKeyboardOpen || disableDragProp;
-
     // +2 for tolerance in case the animated value is slightly off
     const zIndex = useTransform(y, (val) =>
       val + 2 >= closedY ? -1 : (style?.zIndex ?? 9999)
@@ -158,22 +144,70 @@ export const Sheet = forwardRef<any, SheetProps>(
       });
     });
 
+    const keyboard = useKeyboardAvoidance({
+      isEnabled: isOpen && avoidKeyboard,
+      containerRef: sheetRef,
+      onWillOpenKeyboard: async () => {
+        const lastSnapPoint = snapPoints[snapPoints.length - 1];
+
+        /**
+         * If there are snap points and the sheet is not already at the last snap point,
+         * move it there to make sure the focused input is not covered by the keyboard
+         */
+        if (lastSnapPoint && lastSnapPoint.snapIndex !== currentSnap) {
+          await animate(y, lastSnapPoint.snapValueY, animationOptions);
+          updateSnap(lastSnapPoint.snapIndex);
+        }
+      },
+      onDidOpenKeyboard: (focusedElement) => {
+        const sheetElement = sheetRef.current;
+        if (!sheetElement) return;
+
+        const inputRect = focusedElement.getBoundingClientRect();
+        const containerRect = sheetElement.getBoundingClientRect();
+        const scroller = sheetElement.querySelector(
+          '.react-modal-sheet-content-scroller'
+        ) as HTMLElement;
+
+        const scrollTarget = Math.max(
+          inputRect.top -
+            containerRect.top +
+            scroller.scrollTop -
+            inputRect.height,
+          0
+        );
+
+        requestAnimationFrame(() => {
+          scroller.scrollTo({ top: scrollTarget, behavior: 'smooth' });
+        });
+      },
+    });
+
+    // Disable drag if the keyboard is open to avoid weird behavior
+    const disableDrag = keyboard.isKeyboardOpen || disableDragProp;
+
     const blurActiveInput = useStableCallback(() => {
-      // Find focused input inside the sheet and blur it when dragging starts
-      // to prevent a weird ghost caret "bug" on mobile
+      /**
+       * Find focused input inside the sheet and blur it when dragging starts
+       * to prevent a weird ghost caret "bug" on mobile
+       */
       const focusedElement = document.activeElement as HTMLElement | null;
-      if (!focusedElement || !sheetRef.current) return;
-
-      const isInput =
-        focusedElement.tagName === 'INPUT' ||
-        focusedElement.tagName === 'TEXTAREA';
 
       // Only blur the focused element if it's inside the sheet
-      if (isInput && sheetRef.current.contains(focusedElement)) {
+      if (
+        focusedElement &&
+        willOpenKeyboard(focusedElement) &&
+        sheetRef.current?.contains(focusedElement)
+      ) {
         focusedElement.blur();
       }
     });
 
+    const onDragStart = useStableCallback<DragHandler>((event, info) => {
+      blurActiveInput();
+      onDragStartProp?.(event, info);
+    });
+
     const onDrag = useStableCallback<DragHandler>((event, info) => {
       onDragProp?.(event, info);
 
@@ -188,74 +222,37 @@ export const Sheet = forwardRef<any, SheetProps>(
       y.set(Math.max(currentY + info.delta.y, 0));
     });
 
-    const onDragStart = useStableCallback<DragHandler>((event, info) => {
-      blurActiveInput();
-      onDragStartProp?.(event, info);
-    });
-
     const onDragEnd = useStableCallback<DragHandler>((event, info) => {
       blurActiveInput();
       onDragEndProp?.(event, info);
 
       const currentY = y.get();
 
-      let yTo = 0;
-
-      const currentSnapPoint =
-        currentSnap !== undefined ? getSnapPoint(currentSnap) : null;
-
-      if (currentSnapPoint) {
-        const dragOffsetDirection = info.offset.y > 0 ? 'down' : 'up';
-        const dragVelocityDirection = info.velocity.y > 0 ? 'down' : 'up';
-        const isHighVelocity =
-          Math.abs(info.velocity.y) > dragVelocityThreshold;
+      const result = classifyDragEnd({
+        y: currentY,
+        info,
+        sheetHeight,
+        dragCloseThreshold,
+        snapPoints,
+        dragVelocityThreshold,
+      });
 
-        let result: { yTo: number; snapIndex: number | undefined };
+      let yTo = result.yTo;
 
-        if (isHighVelocity) {
-          result = handleHighVelocityDrag({
-            snapPoints,
-            dragDirection: dragVelocityDirection,
-          });
-        } else {
-          result = handleLowVelocityDrag({
-            currentSnapPoint,
-            currentY,
-            dragDirection: dragOffsetDirection,
-            snapPoints,
-            velocity: info.velocity.y,
-          });
-        }
+      // If disableDismiss is true, prevent closing via gesture
+      if (disableDismiss && yTo + 1 >= sheetHeight) {
+        // Use the bottom-most open snap point
+        const bottomSnapPoint = snapPoints.find((s) => s.snapValue > 0);
 
-        yTo = result.yTo;
-
-        // If disableDismiss is true, prevent closing via gesture
-        if (disableDismiss && yTo + 1 >= sheetHeight) {
-          // Use the bottom-most open snap point
-          const bottomSnapPoint = snapPoints.find((s) => s.snapValue > 0);
-
-          if (bottomSnapPoint) {
-            yTo = bottomSnapPoint.snapValueY;
-            updateSnap(bottomSnapPoint.snapIndex);
-          } else {
-            // If no open snap points available, stay at current position
-            yTo = currentY;
-          }
-        } else if (result.snapIndex !== undefined) {
-          updateSnap(result.snapIndex);
-        }
-      } else if (
-        info.velocity.y > dragVelocityThreshold ||
-        currentY > sheetHeight * dragCloseThreshold
-      ) {
-        // Close the sheet if dragged past the threshold or if the velocity is high enough
-        // But only if disableDismiss is false
-        if (disableDismiss) {
-          // If disableDismiss, snap back to the open position
-          yTo = 0;
+        if (bottomSnapPoint) {
+          yTo = bottomSnapPoint.snapValueY;
+          updateSnap(bottomSnapPoint.snapIndex);
         } else {
-          yTo = closedY;
+          // If no open snap points available, stay at current position
+          yTo = currentY;
         }
+      } else if (result.snapIndex !== undefined) {
+        updateSnap(result.snapIndex);
       }
 
       // Update the spring value so that the sheet is animated to the snap point
@@ -295,67 +292,6 @@ export const Sheet = forwardRef<any, SheetProps>(
       isDisabled: disableScrollLocking || !isOpen,
     });
 
-    const focusedInput = useFocusedInput({
-      isEnabled: isOpen && avoidKeyboard,
-      sheetRef,
-    });
-
-    /**
-     * Keyboard avoidance.
-     *
-     * Move the sheet up when the keyboard opens if the sheet has snap points,
-     * and then scroll the focused input into view to make sure it's not covered
-     * by the keyboard.
-     */
-    useEffect(() => {
-      if (!isOpen || !avoidKeyboard) {
-        return;
-      }
-
-      async function adjustSheetForKeyboard() {
-        const sheetElement = sheetRef.current;
-
-        if (!sheetElement || !focusedInput || !keyboard.isKeyboardOpen) {
-          return;
-        }
-
-        /**
-         * If we have snap points and the sheet is currently snapped to a point
-         * that is being covered by the keyboard, we want to move the sheet up
-         * to reveal it.
-         */
-        const lastSnapPoint = snapPoints[snapPoints.length - 1];
-
-        if (lastSnapPoint) {
-          await animate(y, lastSnapPoint.snapValueY, animationOptions);
-          updateSnap(lastSnapPoint.snapIndex);
-        }
-
-        // Then scroll the focused input into view if it's covered by the keyboard
-        requestAnimationFrame(() => {
-          const inputRect = focusedInput.getBoundingClientRect();
-          const sheetRect = sheetElement.getBoundingClientRect();
-          const scroller = sheetElement.querySelector(
-            '.react-modal-sheet-content-scroller'
-          ) as HTMLElement;
-
-          const scrollTarget = Math.max(
-            inputRect.top -
-              sheetRect.top +
-              scroller.scrollTop -
-              inputRect.height,
-            0
-          );
-
-          requestAnimationFrame(() => {
-            scroller.scrollTo({ top: scrollTarget, behavior: 'smooth' });
-          });
-        });
-      }
-
-      adjustSheetForKeyboard();
-    }, [isOpen, avoidKeyboard, keyboard.isKeyboardOpen, focusedInput]);
-
     const state = useSheetState({
       isOpen,
       onOpen: async () => {

package/src/snap.ts

@@ -1,3 +1,4 @@
+import type { PanInfo } from 'motion';
 import type { SheetSnapPoint } from './types';
 import { isAscendingOrder } from './utils';
 
@@ -107,136 +108,238 @@ export function computeSnapPoints({
   }));
 }
 
-function findClosestSnapPoint({
-  snapPoints,
-  currentY,
-}: {
-  snapPoints: SheetSnapPoint[];
-  currentY: number;
-}) {
+function clamp(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function sign(value: number) {
+  if (value > 0) return 1;
+  if (value < 0) return -1;
+  return 0;
+}
+
+function toAscendingYSnaps(snapPoints: SheetSnapPoint[]) {
+  return snapPoints.slice().sort((a, b) => a.snapValueY - b.snapValueY);
+}
+
+function findNearestSnapByY(snapPoints: SheetSnapPoint[], y: number) {
   return snapPoints.reduce((closest, snap) =>
-    Math.abs(snap.snapValueY - currentY) <
-    Math.abs(closest.snapValueY - currentY)
+    Math.abs(snap.snapValueY - y) < Math.abs(closest.snapValueY - y)
       ? snap
       : closest
   );
 }
 
-function findNextSnapPointInDirection({
-  y,
-  snapPoints,
-  dragDirection,
-}: {
-  y: number;
-  snapPoints: SheetSnapPoint[];
-  dragDirection: 'up' | 'down';
-}) {
-  // NOTE: lower Y means higher in the sheet position!
-  if (dragDirection === 'down') {
-    /**
-     * Example:
-     *
-     * [
-     *   { snapIndex: 0, snapValueY: 810 },
-     *   { snapIndex: 1, snapValueY: 640 },
-     *   { snapIndex: 2, snapValueY: 405 }, <-- next down
-     *   ------------- Y = 60 ------------
-     *   { snapIndex: 3, snapValueY: 50 },
-     *   { snapIndex: 4, snapValueY: 0 },
-     * ]
-     */
-    return snapPoints
-      .slice()
-      .reverse()
-      .find((s) => s.snapValueY > y);
-  } else {
-    /**
-     * Example:
-     * [
-     *   { snapIndex: 0, snapValueY: 810 },
-     *   { snapIndex: 1, snapValueY: 640 },
-     *   { snapIndex: 2, snapValueY: 405 },
-     *   ------------- Y = 60 ------------
-     *   { snapIndex: 3, snapValueY: 50 }, <-- next up
-     *   { snapIndex: 4, snapValueY: 0 },
-     * ]
-     */
-    return snapPoints.find((s) => s.snapValueY < y);
+function findNearestSnapAboveY(snapPoints: SheetSnapPoint[], y: number) {
+  const snaps = toAscendingYSnaps(snapPoints);
+
+  for (let i = snaps.length - 1; i >= 0; i--) {
+    if (snaps[i].snapValueY < y) {
+      return snaps[i];
+    }
   }
+
+  return null;
 }
-export function handleHighVelocityDrag({
-  dragDirection,
-  snapPoints,
+
+function findNearestSnapBelowY(snapPoints: SheetSnapPoint[], y: number) {
+  const snaps = toAscendingYSnaps(snapPoints);
+
+  for (let i = 0; i < snaps.length; i++) {
+    if (snaps[i].snapValueY > y) {
+      return snaps[i];
+    }
+  }
+
+  return null;
+}
+
+function resolveDirection({
+  offsetY,
+  velocityY,
+  deltaY,
 }: {
-  dragDirection: 'up' | 'down';
-  snapPoints: SheetSnapPoint[];
+  offsetY: number;
+  velocityY: number;
+  deltaY: number;
 }) {
-  // Go to either the last or the first snap point depending on the direction
-  const bottomSnapPoint = snapPoints[0];
-  const topSnapPoint = snapPoints[snapPoints.length - 1];
+  if (Math.abs(velocityY) > 50) return sign(velocityY);
 
-  if (dragDirection === 'down') {
-    return {
-      yTo: bottomSnapPoint.snapValueY,
-      snapIndex: bottomSnapPoint.snapIndex,
-    };
-  }
-  return {
-    yTo: topSnapPoint.snapValueY,
-    snapIndex: topSnapPoint.snapIndex,
-  };
+  const offsetDirection = sign(offsetY);
+  if (offsetDirection !== 0) return offsetDirection;
+
+  return sign(deltaY);
 }
 
-export function handleLowVelocityDrag({
-  currentSnapPoint,
-  currentY,
-  dragDirection,
+/**
+ * Classifies the final sheet position when a drag gesture ends.
+ *
+ * Decision flow (high level):
+ * 1) Predict momentum endpoint from current position and velocity.
+ * 2) Resolve drag direction (prefer velocity, fallback to offset/delta).
+ * 3) Detect flick tiers:
+ *    - strong flick -> jump fully open/closed
+ *    - flick -> move to next snap in flick direction
+ * 4) For slower drags:
+ *    - tiny drag or near-snap stickiness -> snap back to nearest snap
+ *    - otherwise, use progress between surrounding snaps and commit threshold
+ * 5) Apply velocity-assisted bias to nearest predicted snap for natural feel.
+ * 6) Fallback to nearest snap.
+ *
+ * Special case with no snap points:
+ * - flick: open/close by direction
+ * - otherwise: open/close by predicted position vs close threshold midpoint
+ */
+export function classifyDragEnd({
+  y,
+  info,
+  sheetHeight,
   snapPoints,
-  velocity,
+  dragVelocityThreshold,
+  dragCloseThreshold,
 }: {
-  currentSnapPoint: SheetSnapPoint;
-  currentY: number;
-  dragDirection: 'up' | 'down';
+  y: number;
+  info: PanInfo;
+  sheetHeight: number;
   snapPoints: SheetSnapPoint[];
-  velocity: number;
+  dragVelocityThreshold: number;
+  dragCloseThreshold: number;
 }) {
-  const closestSnapRelativeToCurrentY = findClosestSnapPoint({
-    snapPoints,
-    currentY,
-  });
-
   /**
-   * If velocity is very low the user has stopped the sheet to a specific
-   * position and we should snap to the closest snap point as there is no
-   * "momentum" that would push the sheet further to the given direction
+   * Thresholds and configuration for drag classification.
+   * Tweak these to adjust the feel of the sheet.
    */
-  if (Math.abs(velocity) < 20) {
+  // Velocity above this is considered a flick gesture.
+  const flickVelocity = dragVelocityThreshold;
+  // Velocity above this is treated as a strong flick and jumps to full open/closed.
+  const strongFlickVelocity = Math.max(2000, flickVelocity);
+  // In slow drags, crossing this portion of the current snap region commits to the next snap.
+  const distanceCommitRatio = 0.35;
+  // Time horizon (in seconds) used to estimate momentum-based end position.
+  const predictionTime = 0.2;
+  // Very small drags below this distance snap back instead of changing snap state.
+  const minDragDistance = 20;
+  // If drag ends within this many pixels from a snap, stick to that snap to reduce jitter.
+  const snapStickiness = 24;
+
+  const minY = 0;
+  const maxY = sheetHeight;
+  const offsetY = info.offset.y;
+  const deltaY = info.delta.y;
+  const velocityY = info.velocity.y;
+
+  // Step 1 — Compute predicted end position from momentum.
+  const predictedY = clamp(y + velocityY * predictionTime, minY, maxY);
+  const absVelocity = Math.abs(velocityY);
+
+  // Step 2 + 3 — Flick detection and gesture direction resolution.
+  const direction = resolveDirection({ offsetY, velocityY, deltaY });
+
+  const isStrongFlick = absVelocity > strongFlickVelocity;
+  const isFlick = absVelocity > flickVelocity;
+
+  // Step 4 — No snap points: decide between open/close only.
+  if (snapPoints.length === 0) {
+    if (isFlick) {
+      return {
+        yTo: direction < 0 ? minY : maxY,
+        snapIndex: undefined,
+      };
+    }
+
+    const midpoint = minY + (maxY - minY) * dragCloseThreshold;
+
     return {
-      yTo: closestSnapRelativeToCurrentY.snapValueY,
-      snapIndex: closestSnapRelativeToCurrentY.snapIndex,
+      yTo: predictedY < midpoint ? minY : maxY,
+      snapIndex: undefined,
     };
   }
 
-  /**
-   * If the dragging has a bit more velocity, we instead want to go to
-   * the next snap point in the given direction if it exists
-   */
-  const nextSnapInDirectionRelativeToCurrentY = findNextSnapPointInDirection({
-    y: currentY,
-    snapPoints,
-    dragDirection,
-  });
+  const nearestSnap = findNearestSnapByY(snapPoints, y);
+
+  // Slow-drag guard — tiny movement: snap back to nearest.
+  if (!isFlick && Math.abs(offsetY) < minDragDistance) {
+    return {
+      yTo: nearestSnap.snapValueY,
+      snapIndex: nearestSnap.snapIndex,
+    };
+  }
 
-  if (nextSnapInDirectionRelativeToCurrentY) {
+  // Hysteresis (stickiness) — avoid jitter if already close to a snap.
+  if (!isFlick && Math.abs(y - nearestSnap.snapValueY) < snapStickiness) {
     return {
-      yTo: nextSnapInDirectionRelativeToCurrentY.snapValueY,
-      snapIndex: nextSnapInDirectionRelativeToCurrentY.snapIndex,
+      yTo: nearestSnap.snapValueY,
+      snapIndex: nearestSnap.snapIndex,
     };
   }
 
-  // No snap point down, stay at current
+  // Step 5 — Strong flick overrides everything and goes fully open/closed.
+  if (isStrongFlick) {
+    const target = direction < 0 ? minY : maxY;
+    const targetSnap = findNearestSnapByY(snapPoints, target);
+
+    return {
+      yTo: target,
+      snapIndex: targetSnap.snapIndex,
+    };
+  }
+
+  // Step 5 — Medium flick moves to the next snap in flick direction.
+  if (isFlick) {
+    const nextSnap =
+      direction < 0
+        ? findNearestSnapAboveY(snapPoints, y)
+        : findNearestSnapBelowY(snapPoints, y);
+
+    const fallbackY = direction < 0 ? minY : maxY;
+    const fallbackSnap = findNearestSnapByY(snapPoints, fallbackY);
+    const targetSnap = nextSnap ?? fallbackSnap;
+
+    return {
+      yTo: targetSnap.snapValueY,
+      snapIndex: targetSnap.snapIndex,
+    };
+  }
+
+  const firstSnap = toAscendingYSnaps(snapPoints)[0];
+  const lastSnap = toAscendingYSnaps(snapPoints)[snapPoints.length - 1];
+  const prevSnap = findNearestSnapAboveY(snapPoints, y) ?? firstSnap;
+  const nextSnap = findNearestSnapBelowY(snapPoints, y) ?? lastSnap;
+
+  if (prevSnap.snapIndex === nextSnap.snapIndex) {
+    return {
+      yTo: prevSnap.snapValueY,
+      snapIndex: prevSnap.snapIndex,
+    };
+  }
+
+  const range = nextSnap.snapValueY - prevSnap.snapValueY;
+  const progress = range > 0 ? (y - prevSnap.snapValueY) / range : 0;
+
+  // Step 6 — Slow drag commit based on progress within the current snap region.
+  let selectedSnap = nearestSnap;
+
+  if (direction > 0) {
+    selectedSnap = progress > distanceCommitRatio ? nextSnap : prevSnap;
+  } else if (direction < 0) {
+    selectedSnap = progress < 1 - distanceCommitRatio ? prevSnap : nextSnap;
+  }
+
+  // Step 7 — Velocity-assisted bias toward predicted-position snap.
+  if (absVelocity > 200) {
+    const predictedSnap = findNearestSnapByY(snapPoints, predictedY);
+
+    if (
+      Math.abs(predictedSnap.snapValueY - y) <
+      Math.abs(selectedSnap.snapValueY - y)
+    ) {
+      selectedSnap = predictedSnap;
+    }
+  }
+
+  // Step 8 — Final fallback.
   return {
-    yTo: currentSnapPoint.snapValueY,
-    snapIndex: currentSnapPoint.snapIndex,
+    yTo: selectedSnap.snapValueY,
+    snapIndex: selectedSnap.snapIndex,
   };
 }

package/src/types.tsx

@@ -7,7 +7,6 @@ import {
 } from 'motion/react';
 import {
   type ComponentPropsWithoutRef,
-  type CSSProperties,
   type ForwardRefExoticComponent,
   type FunctionComponent,
   type HTMLAttributes,
@@ -108,7 +107,7 @@ export interface SheetContextType {
   currentSnap?: number;
   detent: SheetDetent;
   disableDrag: boolean;
-  dragProps?: SheetDragProps;
+  dragProps: SheetDragProps;
   indicatorRotation: MotionValue<number>;
   avoidKeyboard: boolean;
   prefersReducedMotion: boolean;

package/src/utils.ts

@@ -88,3 +88,29 @@ export function waitForElement(
     }, interval);
   });
 }
+
+// HTML input types that do not cause the software keyboard to appear.
+const nonTextInputTypes = new Set([
+  'checkbox',
+  'radio',
+  'range',
+  'color',
+  'file',
+  'image',
+  'button',
+  'submit',
+  'reset',
+]);
+
+export function willOpenKeyboard(target: Element) {
+  return (
+    (target instanceof HTMLInputElement &&
+      !nonTextInputTypes.has(target.type)) ||
+    target instanceof HTMLTextAreaElement ||
+    (target instanceof HTMLElement && target.isContentEditable)
+  );
+}
+
+export function isHTTPS() {
+  return typeof window !== 'undefined' && window.isSecureContext;
+}