react-native-reanimated-carousel 5.0.0-beta.7 → 5.0.0

package/src/hooks/useCarouselController.tsx

@@ -1,422 +1,273 @@
 import React, { useRef } from "react";
-import { StyleSheet } from "react-native";
-import { SharedValue, useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import type { SharedValue } from "react-native-reanimated";
+import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 
-import { Easing } from "../constants";
 import { useGlobalState } from "../store";
 import type {
-  ICarouselInstance,
-  TCarouselActionOptions,
-  TCarouselProps,
-  WithTimingAnimation,
+  CarouselAnimation,
+  CarouselRef,
+  InternalCarouselScrollToOptions,
+  InternalCarouselStepOptions,
 } from "../types";
 import {
-  computedRealIndexWithAutoFillData,
-  convertToSharedIndex,
-} from "../utils/computed-with-auto-fill-data";
+  getLogicalProgress,
+  getNearestLogicalPage,
+  getSettledRawIndex,
+  getShortestLoopTargetPage,
+  positiveModulo,
+} from "../utils/carousel-math";
 import { dealWithAnimation } from "../utils/deal-with-animation";
-import { handlerOffsetDirection } from "../utils/handleroffset-direction";
-import { round } from "../utils/log";
 
-interface IOpts {
-  ref: React.ForwardedRef<ICarouselInstance>;
+interface CarouselControllerOptions {
+  ref: React.ForwardedRef<CarouselRef>;
   loop: boolean;
   size: number;
   dataLength: number;
+  rawDataLength: number;
   handlerOffset: SharedValue<number>;
-  autoFillData: TCarouselProps["autoFillData"];
-  withAnimation?: TCarouselProps["withAnimation"];
-  fixedDirection?: TCarouselProps["fixedDirection"];
-  duration?: number;
+  animation: CarouselAnimation;
   defaultIndex?: number;
   onScrollStart?: () => void;
-  onScrollEnd?: () => void;
+  onMovementEnd?: (index: number) => void;
 }
 
-export interface ICarouselController {
+export interface CarouselController {
   getSharedIndex: () => number;
-  prev: (opts?: TCarouselActionOptions) => void;
-  next: (opts?: TCarouselActionOptions) => void;
+  prev: (options?: InternalCarouselStepOptions) => void;
+  next: (options?: InternalCarouselStepOptions) => void;
   getCurrentIndex: () => number;
-  scrollTo: (opts?: TCarouselActionOptions) => void;
+  scrollTo: (options: InternalCarouselScrollToOptions) => void;
   index: SharedValue<number>;
+  startMovement: () => void;
+  cancelMovement: () => void;
+  settle: () => number;
 }
 
-export function useCarouselController(options: IOpts): ICarouselController {
+export function useCarouselController(options: CarouselControllerOptions): CarouselController {
   const {
-    ref,
-    size,
-    loop,
+    animation,
     dataLength,
-    handlerOffset,
-    withAnimation,
     defaultIndex = 0,
-    duration,
-    autoFillData,
-    fixedDirection,
+    handlerOffset,
+    loop,
+    rawDataLength,
+    ref,
+    size,
   } = options;
+  const {
+    common: {
+      cancelMovement: cancelCommonMovement,
+      dataRevision,
+      isMoving,
+      resolvedSize,
+      settleMovement,
+      sizePhase,
+      startMovement: startCommonMovement,
+    },
+  } = useGlobalState();
 
-  const globalState = useGlobalState();
+  const index = useSharedValue(defaultIndex);
+  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 {
-    props: { overscrollEnabled, vertical, style, width, height },
-    layout: { containerSize },
-    common: { sizePhase, resolvedSize },
-  } = globalState;
+  const warnOnce = React.useCallback((key: string, message: string) => {
+    if (!__DEV__ || warnedCommands.current.has(key)) return;
+    warnedCommands.current.add(key);
+    console.warn(`[react-native-reanimated-carousel] ${message}`);
+  }, []);
 
-  const dataInfo = React.useMemo(
-    () => ({
-      length: dataLength,
-      disable: !dataLength,
-      originalLength: dataLength,
-    }),
-    [dataLength]
-  );
+  const currentVisualPage = React.useCallback(() => {
+    if (size <= 0 || rawDataLength <= 0) return 0;
 
-  const index = useSharedValue<number>(defaultIndex);
-  // The Index displayed to the user
-  const sharedIndex = useRef<number>(defaultIndex);
-  const sharedPreIndex = useRef<number>(defaultIndex);
-
-  const currentFixedPage = React.useCallback(() => {
-    if (size <= 0) return 0;
-    if (loop) return -Math.round(handlerOffset.value / size);
-
-    // In non-loop mode, treat the offset as negative when moving forward.
-    // Clamp within valid range to avoid wrapping when a tiny positive offset
-    // appears after overscroll at index 0.
-    const rawPage = -handlerOffset.value / size;
-    const rounded = Math.round(rawPage);
-    const clamped = Math.max(0, Math.min(dataInfo.length - 1, rounded));
-    return clamped;
-  }, [handlerOffset, dataInfo, size, loop]);
-
-  function setSharedIndex(newSharedIndex: number) {
-    sharedIndex.current = newSharedIndex;
+    const page = getNearestLogicalPage(handlerOffset.value, size);
+    return loop ? page : Math.max(0, Math.min(rawDataLength - 1, page));
+  }, [handlerOffset, loop, rawDataLength, size]);
+
+  function setLiveRawIndex(nextIndex: number) {
+    liveRawIndex.current = nextIndex;
   }
 
   useAnimatedReaction(
     () => {
-      if (size <= 0) {
-        return {
-          i: 0,
-          newSharedIndexValue: 0,
-        };
+      if (size <= 0 || dataLength <= 0 || rawDataLength <= 0) {
+        return { physicalIndex: 0, rawIndex: 0 };
       }
 
-      const handlerOffsetValue = handlerOffset.value;
-      const toInt = round(handlerOffsetValue / size) % dataInfo.length;
-      const isPositive = handlerOffsetValue <= 0;
-      const i = isPositive ? Math.abs(toInt) : Math.abs(toInt > 0 ? dataInfo.length - toInt : 0);
-
-      const newSharedIndexValue = convertToSharedIndex({
-        loop,
-        rawDataLength: dataInfo.originalLength,
-        autoFillData: autoFillData!,
-        index: i,
-      });
-
+      const page = getNearestLogicalPage(handlerOffset.value, size);
       return {
-        i,
-        newSharedIndexValue,
+        physicalIndex: positiveModulo(page, dataLength),
+        rawIndex: positiveModulo(page, rawDataLength),
       };
     },
-    ({ i, newSharedIndexValue }) => {
-      index.value = i;
-      scheduleOnRN(setSharedIndex, newSharedIndexValue);
+    ({ physicalIndex, rawIndex }) => {
+      index.value = physicalIndex;
+      scheduleOnRN(setLiveRawIndex, rawIndex);
     },
-    [sharedPreIndex, sharedIndex, size, dataInfo, index, loop, autoFillData, handlerOffset]
+    [dataLength, handlerOffset, index, rawDataLength, size]
   );
 
-  const getCurrentIndex = React.useCallback(() => {
-    const realIndex = computedRealIndexWithAutoFillData({
-      index: index.value,
-      dataLength: dataInfo.originalLength,
-      loop,
-      autoFillData: autoFillData!,
-    });
+  const settle = React.useCallback(
+    (targetIndex?: number) => {
+      settleMovement();
+
+      const nextSettledIndex =
+        typeof targetIndex === "number" && rawDataLength > 0
+          ? positiveModulo(Math.round(targetIndex), rawDataLength)
+          : getSettledRawIndex(
+              loop
+                ? getLogicalProgress(handlerOffset.value, size)
+                : Math.max(
+                    0,
+                    Math.min(rawDataLength - 1, getLogicalProgress(handlerOffset.value, size))
+                  ),
+              rawDataLength
+            );
+
+      settledIndex.current = nextSettledIndex;
+      return nextSettledIndex;
+    },
+    [handlerOffset, loop, rawDataLength, settleMovement, size]
+  );
 
-    return realIndex;
-  }, [index, autoFillData, dataInfo, loop]);
+  const getCurrentIndex = React.useCallback(() => settledIndex.current, []);
+  const getSharedIndex = React.useCallback(() => liveRawIndex.current, []);
+  const startMovement = React.useCallback(() => startCommonMovement(), [startCommonMovement]);
+  const cancelMovement = React.useCallback(() => cancelCommonMovement(), [cancelCommonMovement]);
 
-  const canSliding = React.useCallback(() => {
-    const currentSize = resolvedSize.value ?? size;
-    const ready = sizePhase.value === "ready" && !!currentSize;
+  React.useEffect(() => {
+    if (!isMoving.value) settle();
+  }, [dataRevision, isMoving, rawDataLength, settle]);
 
-    return !dataInfo.disable && ready;
-  }, [dataInfo, resolvedSize, sizePhase, size]);
-
-  const onScrollEnd = React.useCallback(() => {
-    options.onScrollEnd?.();
-  }, [options]);
+  const isReady = React.useCallback(() => {
+    const currentSize = resolvedSize.value ?? size;
+    return sizePhase.value === "ready" && currentSize > 0;
+  }, [resolvedSize, size, sizePhase]);
 
-  const onScrollStart = React.useCallback(() => {
+  const emitStart = React.useCallback(() => {
+    startMovement();
     options.onScrollStart?.();
-  }, [options]);
+  }, [options, startMovement]);
 
-  const scrollWithTiming = React.useCallback(
-    (toValue: number, onFinished?: () => void) => {
+  const emitSettle = React.useCallback(
+    (targetIndex?: number) => {
+      const nextSettledIndex = settle(targetIndex);
+      options.onMovementEnd?.(nextSettledIndex);
+    },
+    [options, settle]
+  );
+
+  const animateTo = React.useCallback(
+    (targetOffset: number, targetIndex: number, onFinished?: () => void) => {
       "worklet";
-      const callback = (isFinished: boolean) => {
+      return dealWithAnimation(animation)(targetOffset, (finished) => {
         "worklet";
-        if (isFinished) {
-          scheduleOnRN(onScrollEnd);
-          onFinished && scheduleOnRN(onFinished);
+        if (finished) {
+          scheduleOnRN(emitSettle, targetIndex);
+          if (onFinished) scheduleOnRN(onFinished);
+        } else {
+          scheduleOnRN(cancelMovement);
         }
-      };
-
-      const defaultWithAnimation: WithTimingAnimation = {
-        type: "timing",
-        config: { duration, easing: Easing.easeOutQuart },
-      };
-
-      return dealWithAnimation(withAnimation ?? defaultWithAnimation)(toValue, callback);
+      });
     },
-    [duration, withAnimation, onScrollEnd]
+    [animation, cancelMovement, emitSettle]
   );
 
-  const flattenedStyle = StyleSheet.flatten(style) || {};
-
-  const next = React.useCallback(
-    (opts: TCarouselActionOptions = {}) => {
+  const moveToPage = React.useCallback(
+    (targetPage: number, animated: boolean, onFinished?: () => void) => {
       "worklet";
-      const { count = 1, animated = true, onFinished } = opts;
-      if (!canSliding()) return;
-
-      if (!loop) {
-        const newIndex = index.value + count;
-        const isOutOfBounds = newIndex > dataInfo.length - 1;
-        if (isOutOfBounds) {
-          return;
-        }
-      }
-
-      /* 
-      [Overscroll Protection Logic]
-      
-      This section handles the overscroll protection when overscrollEnabled is false.
-      It prevents scrolling beyond the visible content area.
-
-      Example scenario:
-      - Container width: 300px
-      - Item width: 75px (4 items per view)
-      - Total items: 6
-      
-      Initial state (index = 0):
-      [0][1][2][3] | [4][5]
-      visible      | remaining
-
-      After 2 slides (index = 2):
-      [0][1] | [2][3][4][5]
-      hidden | visible
-
-      The visibleContentWidth calculation:
-      - At index 2, remaining items = 4 (items 2,3,4,5)
-      - visibleContentWidth = 4 * 75px = 300px
-      
-      If we try to slide again:
-      - New visibleContentWidth would be: 2 * 75px = 150px (only items 4,5 remain)
-      - Since 150px < container width (300px), the slide is prevented
-      
-      This ensures we don't scroll beyond the last set of fully visible items,
-      maintaining a clean UX without partial item visibility at the edges.
-      */
-      // For overscroll calculation, use the intended item size, not the measured container size
-      // In the new dynamic size system, the measured `size` could reflect the container rather than
-      // each item, so prefer explicit width/height props and fall back to style-based dimensions.
-      const styleWidth =
-        typeof flattenedStyle.width === "number" ? flattenedStyle.width : undefined;
-      const styleHeight =
-        typeof flattenedStyle.height === "number" ? flattenedStyle.height : undefined;
-      const propWidth = typeof width === "number" ? width : undefined;
-      const propHeight = typeof height === "number" ? height : undefined;
-
-      // Use the page size (derived from itemWidth/itemHeight) for overscroll calculations.
-      // Fallback to container/style dimensions only if page size is unavailable.
-      const pageSize =
-        size > 0
-          ? size
-          : vertical
-            ? (propHeight ?? styleHeight ?? 0)
-            : (propWidth ?? styleWidth ?? 0);
-
-      const visibleContentWidth = (dataInfo.length - index.value) * pageSize;
-
-      // Get effective container width, with fallback for cases where containerSize
-      // hasn't been updated yet (e.g., in tests or during initialization)
-      const getEffectiveContainerWidth = () => {
-        // 1. Use measured value if available
-        if (containerSize.value.width > 0) {
-          return containerSize.value.width;
-        }
-
-        // 2. Fallback to style width/height when no measurement available
-        if (!vertical) {
-          if (propWidth && propWidth > 0) {
-            return propWidth;
-          }
-          if (styleWidth && styleWidth > 0) {
-            return styleWidth;
-          }
-        }
-        if (vertical) {
-          if (propHeight && propHeight > 0) {
-            return propHeight;
-          }
-          if (styleHeight && styleHeight > 0) {
-            return styleHeight;
-          }
-        }
-
-        // 3. Final fallback - assume multiple items are visible
-        return pageSize * 3; // Assume 3 items per view as reasonable default
-      };
-
-      const effectiveContainerWidth = getEffectiveContainerWidth();
-
-      if (!overscrollEnabled && effectiveContainerWidth > 0) {
-        if (!(visibleContentWidth > effectiveContainerWidth)) {
-          return;
-        }
-      }
-
-      onScrollStart?.();
-
-      const nextPage = currentFixedPage() + count;
-      index.value = nextPage;
+      const targetRawIndex = positiveModulo(targetPage, rawDataLength);
+      emitStart();
+      index.value = positiveModulo(targetPage, Math.max(dataLength, 1));
 
+      const targetOffset = -targetPage * size;
       if (animated) {
-        handlerOffset.value = scrollWithTiming(-nextPage * size, onFinished) as any;
+        handlerOffset.value = animateTo(targetOffset, targetRawIndex, onFinished);
       } else {
-        handlerOffset.value = -nextPage * size;
+        handlerOffset.value = targetOffset;
+        emitSettle(targetRawIndex);
         onFinished?.();
       }
     },
-    [
-      canSliding,
-      loop,
-      index,
-      dataInfo,
-      onScrollStart,
-      handlerOffset,
-      size,
-      scrollWithTiming,
-      currentFixedPage,
-      overscrollEnabled,
-      containerSize,
-      vertical,
-      flattenedStyle,
-      width,
-      height,
-    ]
+    [animateTo, dataLength, emitSettle, emitStart, handlerOffset, index, rawDataLength, size]
   );
 
-  const prev = React.useCallback(
-    (opts: TCarouselActionOptions = {}) => {
-      const { count = 1, animated = true, onFinished } = opts;
-      if (!canSliding()) return;
-
-      if (!loop && index.value <= 0) return;
+  const validateCount = React.useCallback(
+    (command: "next" | "prev", count: number) => {
+      if (count === 0) return false;
+      if (Number.isInteger(count) && count > 0) return true;
 
-      onScrollStart?.();
-
-      const prevPage = currentFixedPage() - count;
-      index.value = prevPage;
-
-      if (animated) {
-        handlerOffset.value = scrollWithTiming(-prevPage * size, onFinished);
-      } else {
-        handlerOffset.value = -prevPage * size;
-        onFinished?.();
-      }
+      warnOnce(
+        `${command}:count`,
+        `${command} count must be a positive integer; received ${String(count)}.`
+      );
+      return false;
     },
-    [
-      canSliding,
-      loop,
-      index,
-      onScrollStart,
-      handlerOffset,
-      size,
-      scrollWithTiming,
-      currentFixedPage,
-    ]
+    [warnOnce]
   );
 
-  const to = React.useCallback(
-    (opts: { i: number; animated: boolean; onFinished?: () => void }) => {
-      const { i, animated = false, onFinished } = opts;
+  const next = React.useCallback(
+    (stepOptions: InternalCarouselStepOptions = {}) => {
+      "worklet";
+      const { animated = true, count = 1, onFinished } = stepOptions;
+      if (!canMove || !isReady() || !validateCount("next", count)) return;
 
-      if (i === index.value) return;
+      const currentPage = currentVisualPage();
+      const targetPage = loop
+        ? currentPage + count
+        : Math.min(rawDataLength - 1, currentPage + count);
+      if (targetPage === currentPage) return;
 
-      if (!canSliding()) return;
+      moveToPage(targetPage, animated, onFinished);
+    },
+    [canMove, currentVisualPage, isReady, loop, moveToPage, rawDataLength, validateCount]
+  );
 
-      onScrollStart?.();
-      let finalOffset: number;
+  const prev = React.useCallback(
+    (stepOptions: InternalCarouselStepOptions = {}) => {
+      "worklet";
+      const { animated = true, count = 1, onFinished } = stepOptions;
+      if (!canMove || !isReady() || !validateCount("prev", count)) return;
 
-      if (!loop) {
-        // Non-loop mode always uses direct page-to-offset mapping.
-        // This avoids sign flips when moving to lower indices.
-        finalOffset = -i * size;
-      } else {
-        // direction -> 1 | -1
-        let direction: -1 | 1;
-        if (fixedDirection === "positive") direction = 1;
-        else if (fixedDirection === "negative") direction = -1;
-        else direction = handlerOffsetDirection(handlerOffset);
-
-        // target offset
-        const offset = i * size * direction;
-        // page width size * page count
-        const totalSize = dataInfo.length * size;
-        const isCloseToNextLoop = Math.abs(handlerOffset.value % totalSize) / totalSize >= 0.5;
-
-        finalOffset =
-          (Math.floor(Math.abs(handlerOffset.value / totalSize)) + (isCloseToNextLoop ? 1 : 0)) *
-            totalSize *
-            direction +
-          offset;
-      }
+      const currentPage = currentVisualPage();
+      const targetPage = loop ? currentPage - count : Math.max(0, currentPage - count);
+      if (targetPage === currentPage) return;
 
-      if (animated) {
-        index.value = i;
-        handlerOffset.value = scrollWithTiming(finalOffset, onFinished);
-      } else {
-        handlerOffset.value = finalOffset;
-        index.value = i;
-        onFinished?.();
-      }
+      moveToPage(targetPage, animated, onFinished);
     },
-    [
-      size,
-      loop,
-      index,
-      fixedDirection,
-      handlerOffset,
-      dataInfo.length,
-      canSliding,
-      onScrollStart,
-      scrollWithTiming,
-    ]
+    [canMove, currentVisualPage, isReady, loop, moveToPage, validateCount]
   );
 
   const scrollTo = React.useCallback(
-    (opts: TCarouselActionOptions = {}) => {
-      const { index: i, count, animated = false, onFinished } = opts;
-
-      if (typeof i === "number" && i > -1) {
-        to({ i, animated, onFinished });
+    (scrollOptions: InternalCarouselScrollToOptions) => {
+      "worklet";
+      const { animated = true, index: targetIndex, onFinished } = scrollOptions;
+      if (!canMove || !isReady()) return;
+
+      if (!Number.isInteger(targetIndex) || targetIndex < 0 || targetIndex >= rawDataLength) {
+        warnOnce(
+          "scrollTo:index",
+          `scrollTo index must be an integer between 0 and ${rawDataLength - 1}; received ${String(targetIndex)}.`
+        );
         return;
       }
 
-      if (!count) return;
-
-      const n = Math.round(count);
-
-      if (n < 0) prev({ count: Math.abs(n), animated, onFinished });
-      else next({ count: n, animated, onFinished });
+      const currentPage = currentVisualPage();
+      const currentRawIndex = positiveModulo(currentPage, rawDataLength);
+      if (currentRawIndex === targetIndex) return;
+
+      const targetPage = loop
+        ? getShortestLoopTargetPage({
+            currentPage,
+            targetIndex,
+            count: rawDataLength,
+          })
+        : targetIndex;
+      moveToPage(targetPage, animated, onFinished);
     },
-    [prev, next, to]
+    [canMove, currentVisualPage, isReady, loop, moveToPage, rawDataLength, warnOnce]
   );
 
   React.useImperativeHandle(
@@ -435,7 +286,10 @@ export function useCarouselController(options: IOpts): ICarouselController {
     prev,
     scrollTo,
     getCurrentIndex,
-    getSharedIndex: () => sharedIndex.current,
+    getSharedIndex,
     index,
+    startMovement,
+    cancelMovement,
+    settle,
   };
 }