react-native-reanimated-carousel 5.1.1 → 5.2.1

package/src/components/ScrollViewGesture.tsx

@@ -21,6 +21,7 @@ import { useGlobalState } from "../store";
 import { toLogicalGestureValue } from "../utils/carousel-direction";
 import { computeGestureTranslation } from "../utils/compute-gesture-translation";
 import { dealWithAnimation } from "../utils/deal-with-animation";
+import { webOnlyDependencies } from "../utils/web-only-dependencies";
 
 interface Props {
   size: number;
@@ -40,6 +41,7 @@ const IScrollViewGesture: React.FC<PropsWithChildren<Props>> = (props) => {
       onConfigurePanGesture,
       orientation,
       snapMode,
+      snapMomentum,
       loop,
       animation,
       scrollEnabled,
@@ -63,7 +65,7 @@ const IScrollViewGesture: React.FC<PropsWithChildren<Props>> = (props) => {
   const isVertical = orientation === "vertical";
 
   const maxPage = dataLength;
-  const isHorizontal = useDerivedValue(() => !isVertical, [isVertical]);
+  const isHorizontal = useDerivedValue(() => !isVertical, webOnlyDependencies([isVertical]));
   const max = useSharedValue(0);
   const panOffset = useSharedValue<number | undefined>(undefined); // set to undefined when not actively in a pan gesture
   const touching = useSharedValue(false);
@@ -71,10 +73,11 @@ const IScrollViewGesture: React.FC<PropsWithChildren<Props>> = (props) => {
   const hasStartedMovement = useSharedValue(false);
   const scrollEndTranslation = useSharedValue(0);
   const scrollEndVelocity = useSharedValue(0);
+  const sizeReadyDependencies = webOnlyDependencies([resolvedSize, sizePhase]);
   const sizeReady = useDerivedValue(() => {
     const currentSize = resolvedSize.value ?? 0;
     return sizePhase.value === "ready" && currentSize > 0;
-  }, [resolvedSize, sizePhase]);
+  }, sizeReadyDependencies);
 
   // Get the limit of the scroll.
   const getLimit = React.useCallback(() => {
@@ -169,7 +172,11 @@ const IScrollViewGesture: React.FC<PropsWithChildren<Props>> = (props) => {
       }
 
       if (snapMode === "nearest") {
-        finalTranslation = withSpring(withProcessTranslation(-nextPage * currentSize), onFinished);
+        const nearestPage = -Math.round((origin + velocity * snapMomentum) / currentSize);
+        finalTranslation = withSpring(
+          withProcessTranslation(-nearestPage * currentSize),
+          onFinished
+        );
       }
 
       translation.value = finalTranslation;
@@ -183,7 +190,7 @@ const IScrollViewGesture: React.FC<PropsWithChildren<Props>> = (props) => {
         return translation;
       }
     },
-    [withSpring, resolvedSize, maxPage, loop, snapMode, translation]
+    [withSpring, resolvedSize, maxPage, loop, snapMode, snapMomentum, translation]
   );
 
   const onFinish = React.useCallback(
@@ -238,7 +245,7 @@ const IScrollViewGesture: React.FC<PropsWithChildren<Props>> = (props) => {
     () => {
       if (snapMode !== "page") resetBoundary();
     },
-    [resetBoundary, snapMode]
+    webOnlyDependencies([resetBoundary, snapMode])
   );
 
   const onGestureStart = useCallback(

package/src/constants/index.ts

@@ -1,10 +1,10 @@
 import type { EasingFunction } from "react-native-reanimated";
 import { Easing as _Easing } from "react-native-reanimated";
 
-export enum DATA_LENGTH {
-  SINGLE_ITEM = 1,
-  DOUBLE_ITEM = 2,
-}
+export const DATA_LENGTH = {
+  SINGLE_ITEM: 1,
+  DOUBLE_ITEM: 2,
+} as const;
 
 export const Easing = {
   easeOutQuart: _Easing.bezier(0.25, 1, 0.5, 1) as unknown as EasingFunction,

package/src/hooks/useAutoPlay.ts

@@ -2,12 +2,31 @@ import * as React from "react";
 
 import type { CarouselController } from "./useCarouselController";
 
+export interface AutoPlayControls {
+  /** Stops autoplay until `start` is called, for example while the user touches the carousel. */
+  pause: () => void;
+  /** Resumes autoplay and begins a fresh dwell. */
+  start: () => void;
+  /** Begins a fresh dwell if autoplay is running. */
+  trigger: () => void;
+  /** A transition started from any source: drop the pending dwell without stopping autoplay. */
+  onTransitionStart: () => void;
+  /** A transition settled from any source: begin a fresh dwell if autoplay is running. */
+  onTransitionEnd: () => void;
+}
+
+/**
+ * Autoplay waits `autoplayInterval` of idle time, then steps once. The dwell is restarted
+ * when a transition settles, whatever started it (an autoplay step, `ref.next/prev/scrollTo`,
+ * or a pagination tap), so a manual move never cuts the next dwell short and an interrupted
+ * autoplay step does not stop autoplay.
+ */
 export function useAutoPlay(options: {
   autoplay?: boolean;
   autoplayInterval?: number;
   autoplayDirection?: "forward" | "backward";
   carouselController: CarouselController;
-}) {
+}): AutoPlayControls {
   const {
     autoplay = false,
     autoplayDirection = "forward",
@@ -18,28 +37,31 @@ export function useAutoPlay(options: {
   const timer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
   const stopped = React.useRef(!autoplay);
 
-  const play = React.useCallback(() => {
-    if (stopped.current) return;
-
+  const clearDwell = React.useCallback(() => {
     if (timer.current) {
       clearTimeout(timer.current);
       timer.current = null;
     }
+  }, []);
+
+  const play = React.useCallback(() => {
+    if (stopped.current) return;
+
+    clearDwell();
     timer.current = setTimeout(() => {
-      if (autoplayDirection === "backward") prev({ onFinished: play });
-      else next({ onFinished: play });
+      timer.current = null;
+      // The step settles through `onTransitionEnd`, which starts the next dwell.
+      if (autoplayDirection === "backward") prev();
+      else next();
     }, autoplayInterval);
-  }, [autoplayDirection, autoplayInterval, next, prev]);
+  }, [autoplayDirection, autoplayInterval, clearDwell, next, prev]);
 
   const pause = React.useCallback(() => {
     if (!autoplay) return;
 
-    if (timer.current) {
-      clearTimeout(timer.current);
-      timer.current = null;
-    }
+    clearDwell();
     stopped.current = true;
-  }, [autoplay]);
+  }, [autoplay, clearDwell]);
 
   const start = React.useCallback(() => {
     if (!autoplay) return;
@@ -55,9 +77,14 @@ export function useAutoPlay(options: {
     return pause;
   }, [autoplay, pause, start]);
 
-  return {
-    pause,
-    start,
-    trigger: play,
-  };
+  return React.useMemo(
+    () => ({
+      pause,
+      start,
+      trigger: play,
+      onTransitionStart: clearDwell,
+      onTransitionEnd: play,
+    }),
+    [clearDwell, pause, play, start]
+  );
 }

package/src/hooks/useCarouselController.tsx

@@ -18,6 +18,7 @@ import {
   positiveModulo,
 } from "../utils/carousel-math";
 import { dealWithAnimation } from "../utils/deal-with-animation";
+import { webOnlyDependencies } from "../utils/web-only-dependencies";
 
 interface CarouselControllerOptions {
   ref: React.ForwardedRef<CarouselRef>;
@@ -71,7 +72,7 @@ export function useCarouselController(options: CarouselControllerOptions): Carou
   const liveRawIndex = useRef(rawDataLength > 0 ? defaultIndex : 0);
   const settledIndex = useRef(rawDataLength > 0 ? defaultIndex : 0);
   const warnedCommands = useRef(new Set<string>());
-  const canMove = rawDataLength > 1;
+  const canMove = rawDataLength > 1 || (loop && rawDataLength === 1 && dataLength > 1);
 
   const warnOnce = React.useCallback((key: string, message: string) => {
     if (!__DEV__ || warnedCommands.current.has(key)) return;
@@ -106,7 +107,7 @@ export function useCarouselController(options: CarouselControllerOptions): Carou
       index.value = physicalIndex;
       scheduleOnRN(setLiveRawIndex, rawIndex);
     },
-    [dataLength, handlerOffset, index, rawDataLength, size]
+    webOnlyDependencies([dataLength, handlerOffset, index, rawDataLength, size])
   );
 
   const settle = React.useCallback(

package/src/hooks/useCommonVariables.ts

@@ -12,6 +12,7 @@ import {
   reconcileOffsetAfterDataChange,
 } from "../utils/carousel-math";
 import { computeOffsetIfSizeChanged } from "../utils/compute-offset-if-size-changed";
+import { webOnlyDependencies } from "../utils/web-only-dependencies";
 
 export type CarouselSizePhase = "pending" | "ready" | "updating";
 
@@ -97,7 +98,7 @@ export function useCommonVariables(
         scheduleOnRN(syncSize, current);
       }
     },
-    [syncSize]
+    webOnlyDependencies([syncSize])
   );
 
   React.useEffect(() => {
@@ -242,7 +243,7 @@ export function useCommonVariables(
       prevSize.value = currentSize;
       sizePhase.value = "ready";
     },
-    [dataLength, defaultIndex, hasInitializedOffset, resolvedSize, sizePhase]
+    webOnlyDependencies([dataLength, defaultIndex, hasInitializedOffset, resolvedSize, sizePhase])
   );
 
   return {

package/src/hooks/useInitProps.ts

@@ -20,6 +20,7 @@ export type InitializedCarouselProps<Item> = Omit<
   | "overscrollEnabled"
   | "scrollEnabled"
   | "snapMode"
+  | "snapMomentum"
   | "style"
 > & {
   autoplay: boolean;
@@ -32,6 +33,7 @@ export type InitializedCarouselProps<Item> = Omit<
   overscrollEnabled: boolean;
   scrollEnabled: boolean;
   snapMode: CarouselSnapMode;
+  snapMomentum: number;
   style: NonNullable<CarouselProps<Item>["style"]>;
   animation: CarouselAnimation;
   rawData: Item[];
@@ -57,6 +59,7 @@ export function useInitProps<Item>(props: CarouselProps<Item>): InitializedCarou
   });
   const scrollEnabled = props.scrollEnabled ?? true;
   const snapMode = props.snapMode ?? "page";
+  const snapMomentum = props.snapMomentum ?? 2;
   const overscrollEnabled = props.overscrollEnabled ?? true;
   const style = props.style ?? {};
   const animation: CarouselAnimation = props.animation ?? {
@@ -123,6 +126,7 @@ export function useInitProps<Item>(props: CarouselProps<Item>): InitializedCarou
     overscrollEnabled,
     scrollEnabled,
     snapMode,
+    snapMomentum,
     style,
     animation,
     data,
@@ -154,6 +158,15 @@ function validateStaticProps<Item>(props: CarouselProps<Item>) {
     );
   }
 
+  if (
+    props.snapMomentum !== undefined &&
+    (!Number.isFinite(props.snapMomentum) || props.snapMomentum < 0)
+  ) {
+    throw new Error(
+      "[react-native-reanimated-carousel] snapMomentum must be a non-negative number."
+    );
+  }
+
   if (
     props.renderWindowSize !== undefined &&
     (!Number.isInteger(props.renderWindowSize) || props.renderWindowSize <= 0)

package/src/hooks/useOffsetX.ts

@@ -1,6 +1,7 @@
 import type { SharedValue } from "react-native-reanimated";
 import { Extrapolation, interpolate, useDerivedValue } from "react-native-reanimated";
 
+import { webOnlyDependencies } from "../utils/web-only-dependencies";
 import type { VisibleRangesValue } from "./useVisibleRanges";
 
 export interface OffsetOptions {
@@ -38,6 +39,15 @@ export const useOffsetX = (opts: OffsetOptions, visibleRanges: VisibleRangesValu
   const MAX = positiveCount * size;
   const MIN = -((VALID_LENGTH - positiveCount) * size);
 
+  const xDependencies = webOnlyDependencies([
+    loop,
+    dataLength,
+    viewCount,
+    type,
+    size,
+    visibleRanges,
+    handlerOffset,
+  ]);
   const x = useDerivedValue(() => {
     if (!size) return 0;
 
@@ -75,7 +85,7 @@ export const useOffsetX = (opts: OffsetOptions, visibleRanges: VisibleRangesValu
     }
 
     return Number.MAX_SAFE_INTEGER;
-  }, [loop, dataLength, viewCount, type, size, visibleRanges, handlerOffset]);
+  }, xDependencies);
 
   return x;
 };

package/src/hooks/useOnProgressChange.ts

@@ -4,6 +4,7 @@ import { scheduleOnRN } from "react-native-worklets";
 
 import type { CarouselProgressChangeHandler } from "../types";
 import { getLogicalProgress } from "../utils/carousel-math";
+import { webOnlyDependencies } from "../utils/web-only-dependencies";
 
 export function useOnProgressChange(options: {
   loop: boolean;
@@ -28,6 +29,6 @@ export function useOnProgressChange(options: {
       if (progress) progress.value = nextProgress;
       if (onProgressChange) scheduleOnRN(onProgressChange, nextProgress);
     },
-    [loop, offset, onProgressChange, progress, rawDataLength, size, sizeReady]
+    webOnlyDependencies([loop, offset, onProgressChange, progress, rawDataLength, size, sizeReady])
   );
 }

package/src/hooks/useVisibleRanges.tsx

@@ -2,6 +2,8 @@ import { useRef } from "react";
 import type { SharedValue } from "react-native-reanimated";
 import { useDerivedValue } from "react-native-reanimated";
 
+import { webOnlyDependencies } from "../utils/web-only-dependencies";
+
 type Range = [number, number];
 
 export interface VisibleRanges {
@@ -11,7 +13,7 @@ export interface VisibleRanges {
 
 export type VisibleRangesValue = SharedValue<VisibleRanges>;
 
-function normalizeWindowSize(total: number, windowSize?: number) {
+export function normalizeWindowSize(total: number, windowSize?: number) {
   "worklet";
 
   return typeof windowSize === "number" && Number.isFinite(windowSize) && windowSize > 0
@@ -100,6 +102,7 @@ export function useVisibleRanges(options: {
   const windowSize = normalizeWindowSize(total, _windowSize);
   const cachedRanges = useRef<VisibleRanges | null>(null);
 
+  const rangesDependencies = webOnlyDependencies([loop, total, windowSize, translation, viewSize]);
   const ranges = useDerivedValue(() => {
     if (total <= 0) {
       return computeVisibleRanges({ total, currentIndex: 0, windowSize, loop });
@@ -128,7 +131,7 @@ export function useVisibleRanges(options: {
 
     cachedRanges.current = newRanges;
     return newRanges;
-  }, [loop, total, windowSize, translation, viewSize]);
+  }, rangesDependencies);
 
   return ranges;
 }

package/src/layouts/normal.ts

@@ -1,3 +1,4 @@
+import type { ViewStyle } from "react-native";
 import { interpolate } from "react-native-reanimated";
 
 import type { CarouselDirectionSign } from "../utils/carousel-direction";
@@ -10,7 +11,7 @@ export function normalLayout(opts: {
 }) {
   const { size, isVertical, directionSign } = opts;
 
-  return (value: number) => {
+  return (value: number): ViewStyle => {
     "worklet";
     const logicalTranslate = interpolate(value, [-1, 0, 1], [-size, 0, size]);
     const translate = isVertical

package/src/layouts/parallax.ts

@@ -1,3 +1,4 @@
+import type { ViewStyle } from "react-native";
 import { Extrapolation, interpolate } from "react-native-reanimated";
 
 import type { CarouselLayout } from "../types";
@@ -17,7 +18,7 @@ export function parallaxLayout(
   const { size, isVertical, directionSign } = baseConfig;
   const { offset = 100, scale = 0.8, adjacentScale = scale ** 2 } = config;
 
-  return (relativeProgress: number) => {
+  return (relativeProgress: number): ViewStyle => {
     "worklet";
     const logicalTranslate = interpolate(
       relativeProgress,

package/src/public-types.ts

@@ -76,6 +76,7 @@ export type CarouselProps<Item> = {
   itemSize?: number;
   scrollEnabled?: boolean;
   snapMode?: CarouselSnapMode;
+  snapMomentum?: number;
   overscrollEnabled?: boolean;
   renderWindowSize?: number;
   animation?: CarouselAnimation;

package/src/utils/web-only-dependencies.ts

@@ -0,0 +1,10 @@
+import { Platform } from "react-native";
+
+/**
+ * Reanimated only reads hook dependency arrays in its Web implementation when the
+ * worklets Babel plugin is not used. Native derives them from the worklet closure
+ * and, since Reanimated 4.6, warns on every render when an array is passed.
+ */
+export function webOnlyDependencies<T extends unknown[]>(dependencies: T): T | undefined {
+  return Platform.OS === "web" ? dependencies : undefined;
+}