react-native-reanimated-carousel 5.0.0-beta.8 → 5.1.0

package/src/hooks/useCommonVariables.ts

@@ -4,74 +4,86 @@ import type { SharedValue } from "react-native-reanimated";
 import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 
-import type { TInitializeCarouselProps } from "./useInitProps";
+import type { InitializedCarouselProps } from "./useInitProps";
 
-import { computeOffsetIfDataChanged } from "../utils/compute-offset-if-data-changed";
+import {
+  getNearestLogicalPage,
+  positiveModulo,
+  reconcileOffsetAfterDataChange,
+} from "../utils/carousel-math";
 import { computeOffsetIfSizeChanged } from "../utils/compute-offset-if-size-changed";
-import { handlerOffsetDirection } from "../utils/handleroffset-direction";
 
-export type TCarouselSizePhase = "pending" | "ready" | "updating";
+export type CarouselSizePhase = "pending" | "ready" | "updating";
 
-export interface ICommonVariables {
+export interface CarouselCommonVariables {
   size: number;
   validLength: number;
   handlerOffset: SharedValue<number>;
   resolvedSize: SharedValue<number | null>;
-  sizePhase: SharedValue<TCarouselSizePhase>;
+  sizePhase: SharedValue<CarouselSizePhase>;
   sizeExplicit: boolean;
+  isMoving: SharedValue<boolean>;
+  dataRevision: number;
+  startMovement: () => void;
+  cancelMovement: () => void;
+  settleMovement: () => void;
 }
 
-export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommonVariables {
+export function useCommonVariables(
+  props: InitializedCarouselProps<unknown>
+): CarouselCommonVariables {
   const {
-    vertical,
+    orientation,
     style,
     dataLength,
     defaultIndex,
-    defaultScrollOffsetValue,
+    keyExtractor,
     loop,
-    width: explicitWidth,
-    height: explicitHeight,
-    itemWidth: explicitItemWidth,
-    itemHeight: explicitItemHeight,
+    itemSize,
+    rawData,
+    rawDataLength,
   } = props;
+  const isVertical = orientation === "vertical";
 
   const manualSize = React.useMemo(() => {
-    const explicitPageSize = vertical ? explicitItemHeight : explicitItemWidth;
-    if (typeof explicitPageSize === "number" && explicitPageSize > 0) {
-      return explicitPageSize;
+    if (typeof itemSize === "number" && itemSize > 0) {
+      return itemSize;
     }
 
     const { width, height } = StyleSheet.flatten(style) || {};
-    const candidate = vertical ? height : width;
+    const candidate = isVertical ? height : width;
     if (typeof candidate === "number" && candidate > 0) {
       return candidate;
     }
 
-    // NOTE: `width`/`height` props are deprecated in v5. They are still respected here to
-    // maintain backwards compatibility with v4-style usage. Prefer using `style` when both exist.
-    const explicitCandidate = vertical ? explicitHeight : explicitWidth;
-    if (typeof explicitCandidate === "number" && explicitCandidate > 0) {
-      return explicitCandidate;
-    }
-
     return null;
-  }, [vertical, style, explicitWidth, explicitHeight, explicitItemHeight, explicitItemWidth]);
+  }, [isVertical, itemSize, style]);
 
   const resolvedSize = useSharedValue<number | null>(manualSize);
-  const sizePhase = useSharedValue<TCarouselSizePhase>(manualSize ? "ready" : "pending");
+  const sizePhase = useSharedValue<CarouselSizePhase>(manualSize ? "ready" : "pending");
 
-  const defaultHandlerOffsetValue = manualSize ? -Math.abs(defaultIndex * manualSize) : 0;
+  const defaultHandlerOffsetValue =
+    manualSize && dataLength > 0 ? -Math.abs(defaultIndex * manualSize) : 0;
   const _handlerOffset = useSharedValue<number>(defaultHandlerOffsetValue);
-  // Prefer the newer `scrollOffsetValue` name, but keep the legacy prop for compatibility.
-  const handlerOffset = props.scrollOffsetValue ?? defaultScrollOffsetValue ?? _handlerOffset;
-  const prevDataLength = useSharedValue(dataLength);
-  const prevSize = useSharedValue(manualSize ?? 0);
-  const sizeExplicit = React.useMemo(() => {
-    const explicitPageSize = vertical ? explicitItemHeight : explicitItemWidth;
-    return typeof explicitPageSize === "number" && explicitPageSize > 0;
-  }, [explicitItemHeight, explicitItemWidth, vertical]);
+  const handlerOffset = props.scrollOffsetValue ?? _handlerOffset;
+  const prevDataLength = useSharedValue(rawDataLength);
+  const previousRawData = React.useRef(rawData);
+  const previousKeyExtractor = React.useRef(keyExtractor);
+  const isMoving = useSharedValue(false);
+  const pendingDataChange = useSharedValue<{
+    previousLength: number;
+    currentLength: number;
+    retainedIndex: number | null;
+  } | null>(null);
+  // Start at zero even when a synchronous item size is available. The first
+  // size reaction owns initialization and must write the default-index offset
+  // into consumer-provided SharedValues as well as the internal value.
+  const prevSize = useSharedValue(0);
+  const hasInitializedOffset = useSharedValue(false);
+  const sizeExplicit = typeof itemSize === "number" && itemSize > 0;
 
   const [size, setSize] = React.useState<number>(manualSize ?? 0);
+  const [dataRevision, setDataRevision] = React.useState(0);
 
   const syncSize = React.useCallback((next: number) => {
     setSize((current) => (current === next ? current : next));
@@ -95,43 +107,107 @@ export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommo
     }
   }, [manualSize, resolvedSize, sizePhase]);
 
+  React.useEffect(() => {
+    const currentSize = resolvedSize.value ?? 0;
+    if (currentSize <= 0 || dataLength <= 0 || hasInitializedOffset.value) return;
+
+    handlerOffset.value = -(defaultIndex * currentSize);
+    prevSize.value = currentSize;
+    hasInitializedOffset.value = true;
+  }, [dataLength, defaultIndex, handlerOffset, hasInitializedOffset, prevSize, resolvedSize]);
+
+  const reconcileDataChange = React.useCallback(
+    (previousLength: number, currentLength: number, retainedIndex?: number) => {
+      const currentSize = resolvedSize.value ?? 0;
+      if (currentSize <= 0) return;
+
+      handlerOffset.value = reconcileOffsetAfterDataChange({
+        offset: handlerOffset.value,
+        itemSize: currentSize,
+        previousCount: previousLength,
+        nextCount: currentLength,
+        defaultIndex,
+        loop,
+        retainedIndex,
+      });
+      setDataRevision((revision) => revision + 1);
+    },
+    [defaultIndex, handlerOffset, loop, resolvedSize]
+  );
+
+  const startMovement = React.useCallback(() => {
+    isMoving.value = true;
+  }, [isMoving]);
+
+  const finishMovement = React.useCallback(() => {
+    isMoving.value = false;
+    const pending = pendingDataChange.value;
+    if (!pending) return;
+
+    pendingDataChange.value = null;
+    reconcileDataChange(
+      pending.previousLength,
+      pending.currentLength,
+      pending.retainedIndex ?? undefined
+    );
+  }, [isMoving, pendingDataChange, reconcileDataChange]);
+
   /**
    * When data changes, we need to compute new index for handlerOffset
    */
-  useAnimatedReaction(
-    () => {
-      const previousLength = prevDataLength.value;
-      const currentLength = dataLength;
-      const isLengthChanged = previousLength !== currentLength;
-      const shouldComputed = isLengthChanged && loop;
-
-      if (shouldComputed) prevDataLength.value = dataLength;
-
-      return {
-        shouldComputed,
-        previousLength,
-        currentLength,
-      };
-    },
-    ({ shouldComputed, previousLength, currentLength }) => {
-      if (shouldComputed) {
-        // direction -> 1 | -1
-        const direction = handlerOffsetDirection(handlerOffset);
-
-        const _size = resolvedSize.value ?? 0;
-        if (_size <= 0) return;
-
-        handlerOffset.value = computeOffsetIfDataChanged({
-          direction,
-          previousLength,
-          currentLength,
-          size: _size,
-          handlerOffset: handlerOffset.value,
-        });
+  React.useEffect(() => {
+    const previousLength = prevDataLength.value;
+    const previousItems = previousRawData.current;
+    const dataChanged =
+      previousLength !== rawDataLength ||
+      previousItems.length !== rawData.length ||
+      previousItems.some((item, index) => !Object.is(item, rawData[index]));
+
+    previousRawData.current = rawData;
+    const extractorForPreviousData = previousKeyExtractor.current ?? keyExtractor;
+    previousKeyExtractor.current = keyExtractor;
+
+    if (!dataChanged) return;
+
+    let retainedIndex: number | undefined;
+    if (keyExtractor && extractorForPreviousData && previousLength > 0 && rawDataLength > 0) {
+      const currentSize = resolvedSize.value ?? 0;
+      const pendingIndex = pendingDataChange.value?.retainedIndex;
+      const previousIndex =
+        typeof pendingIndex === "number"
+          ? pendingIndex
+          : positiveModulo(getNearestLogicalPage(handlerOffset.value, currentSize), previousLength);
+      if (previousIndex < previousItems.length) {
+        const selectedKey = extractorForPreviousData(previousItems[previousIndex], previousIndex);
+        const matchingIndex = rawData.findIndex(
+          (item, index) => keyExtractor(item, index) === selectedKey
+        );
+        if (matchingIndex >= 0) retainedIndex = matchingIndex;
       }
-    },
-    [dataLength, loop, resolvedSize]
-  );
+    }
+
+    prevDataLength.value = rawDataLength;
+    if (isMoving.value) {
+      pendingDataChange.value = {
+        previousLength: pendingDataChange.value?.previousLength ?? previousLength,
+        currentLength: rawDataLength,
+        retainedIndex: retainedIndex ?? null,
+      };
+      return;
+    }
+
+    reconcileDataChange(previousLength, rawDataLength, retainedIndex);
+  }, [
+    handlerOffset,
+    isMoving,
+    keyExtractor,
+    pendingDataChange,
+    prevDataLength,
+    rawData,
+    rawDataLength,
+    reconcileDataChange,
+    resolvedSize,
+  ]);
 
   /**
    * When size changes, we need to compute new index for handlerOffset
@@ -146,8 +222,15 @@ export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommo
 
       sizePhase.value = previousSize > 0 ? "updating" : sizePhase.value;
 
-      if (previousSize <= 0) {
-        handlerOffset.value = -Math.abs(defaultIndex * currentSize);
+      if (dataLength <= 0) {
+        prevSize.value = currentSize;
+        sizePhase.value = "ready";
+        return;
+      }
+
+      if (previousSize <= 0 || !hasInitializedOffset.value) {
+        handlerOffset.value = -(defaultIndex * currentSize);
+        hasInitializedOffset.value = true;
       } else {
         handlerOffset.value = computeOffsetIfSizeChanged({
           handlerOffset: handlerOffset.value,
@@ -159,7 +242,7 @@ export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommo
       prevSize.value = currentSize;
       sizePhase.value = "ready";
     },
-    [defaultIndex, resolvedSize, sizePhase]
+    [dataLength, defaultIndex, hasInitializedOffset, resolvedSize, sizePhase]
   );
 
   return {
@@ -169,5 +252,10 @@ export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommo
     resolvedSize,
     sizePhase,
     sizeExplicit,
+    isMoving,
+    dataRevision,
+    startMovement,
+    cancelMovement: finishMovement,
+    settleMovement: finishMovement,
   };
 }

package/src/hooks/useInitProps.ts

@@ -1,87 +1,177 @@
 import React from "react";
+import { I18nManager } from "react-native";
 
-import type { TCarouselProps } from "../types";
+import { Easing } from "../constants";
+import type { CarouselAnimation, CarouselProps } from "../types";
+import { type CarouselDirectionSign, getCarouselDirectionSign } from "../utils/carousel-direction";
 import { computedFillDataWithAutoFillData } from "../utils/computed-with-auto-fill-data";
 
-type TGetRequiredProps<P extends keyof TCarouselProps> = Record<P, Required<TCarouselProps>[P]>;
+type CarouselSnapMode = NonNullable<CarouselProps<unknown>["snapMode"]>;
 
-export type TInitializeCarouselProps<T> = TCarouselProps<T> &
-  TGetRequiredProps<
-    "defaultIndex" | "loop" | "scrollAnimationDuration" | "autoPlayInterval" | "autoFillData"
-  > & {
-    // Raw data that has not been processed
-    rawData: T[];
-    dataLength: number;
-    rawDataLength: number;
+export type InitializedCarouselProps<Item> = Omit<
+  CarouselProps<Item>,
+  | "autoplay"
+  | "autoplayDirection"
+  | "autoplayInterval"
+  | "data"
+  | "defaultIndex"
+  | "loop"
+  | "orientation"
+  | "overscrollEnabled"
+  | "scrollEnabled"
+  | "snapMode"
+  | "style"
+> & {
+  autoplay: boolean;
+  autoplayDirection: "forward" | "backward";
+  autoplayInterval: number;
+  data: Item[];
+  defaultIndex: number;
+  loop: boolean;
+  orientation: "horizontal" | "vertical";
+  overscrollEnabled: boolean;
+  scrollEnabled: boolean;
+  snapMode: CarouselSnapMode;
+  style: NonNullable<CarouselProps<Item>["style"]>;
+  animation: CarouselAnimation;
+  rawData: Item[];
+  dataLength: number;
+  rawDataLength: number;
+  autoFillData: true;
+  directionSign: CarouselDirectionSign;
+};
+
+export function useInitProps<Item>(props: CarouselProps<Item>): InitializedCarouselProps<Item> {
+  validateStaticProps(props);
+
+  const rawData = props.data ?? [];
+  const requestedDefaultIndex = props.defaultIndex ?? 0;
+  const loop = props.loop ?? false;
+  const autoplay = props.autoplay ?? false;
+  const autoplayInterval = props.autoplayInterval ?? 3000;
+  const autoplayDirection = props.autoplayDirection ?? "forward";
+  const orientation = props.orientation ?? "horizontal";
+  const directionSign = getCarouselDirectionSign({
+    isRTL: I18nManager.isRTL,
+    orientation,
+  });
+  const scrollEnabled = props.scrollEnabled ?? true;
+  const snapMode = props.snapMode ?? "page";
+  const overscrollEnabled = props.overscrollEnabled ?? true;
+  const style = props.style ?? {};
+  const animation: CarouselAnimation = props.animation ?? {
+    type: "timing",
+    duration: 500,
+    easing: Easing.easeOutQuart,
   };
 
-export function useInitProps<T>(props: TCarouselProps<T>): TInitializeCarouselProps<T> {
-  const {
-    defaultIndex = 0,
-    data: rawData = [],
-    loop = true,
-    autoPlayInterval: _autoPlayInterval = 1000,
-    scrollAnimationDuration = 500,
-    style = {},
-    autoFillData = true,
-    // switchers
-    enabled = true,
-    pagingEnabled = true,
-    overscrollEnabled = true,
-    snapEnabled = props.enableSnap ?? true,
-    width: _width,
-    height: _height,
-    itemWidth: _itemWidth,
-    itemHeight: _itemHeight,
-  } = props;
-
-  const width = typeof _width === "number" ? Math.round(_width) : undefined;
-  const height = typeof _height === "number" ? Math.round(_height) : undefined;
-  const itemWidth = typeof _itemWidth === "number" && _itemWidth > 0 ? _itemWidth : undefined;
-  const itemHeight = typeof _itemHeight === "number" && _itemHeight > 0 ? _itemHeight : undefined;
-  const autoPlayInterval = Math.max(_autoPlayInterval, 0);
-
-  const data = React.useMemo<T[]>(() => {
-    return computedFillDataWithAutoFillData<T>({
-      loop,
-      autoFillData,
-      data: rawData,
-      dataLength: rawData.length,
-    });
-  }, [rawData, loop, autoFillData]);
-
-  const dataLength = data.length;
-  const rawDataLength = rawData.length;
-
-  if (props.mode === "vertical-stack" || props.mode === "horizontal-stack") {
-    if (!props.modeConfig) props.modeConfig = {};
-
-    props.modeConfig.showLength = props.modeConfig?.showLength ?? dataLength - 1;
+  const defaultIndexState = React.useRef<{
+    consumed: boolean;
+    requested: number;
+    resolved: number;
+    warned: boolean;
+  } | null>(null);
+
+  if (!defaultIndexState.current) {
+    if (rawData.length > 0) {
+      assertValidDefaultIndex(requestedDefaultIndex, rawData.length);
+    }
+
+    defaultIndexState.current = {
+      consumed: rawData.length > 0,
+      requested: requestedDefaultIndex,
+      resolved: rawData.length > 0 ? requestedDefaultIndex : 0,
+      warned: false,
+    };
+  } else if (!defaultIndexState.current.consumed && rawData.length > 0) {
+    const pendingIndex = defaultIndexState.current.requested;
+    defaultIndexState.current.consumed = true;
+
+    if (isValidDefaultIndex(pendingIndex, rawData.length)) {
+      defaultIndexState.current.resolved = pendingIndex;
+    } else {
+      defaultIndexState.current.resolved = 0;
+      if (__DEV__ && !defaultIndexState.current.warned) {
+        console.warn(
+          `[react-native-reanimated-carousel] Ignored defaultIndex ${pendingIndex} because it is outside the first non-empty data set.`
+        );
+        defaultIndexState.current.warned = true;
+      }
+    }
   }
 
+  const defaultIndex = defaultIndexState.current.resolved;
+  const data = React.useMemo(
+    () =>
+      computedFillDataWithAutoFillData({
+        loop,
+        autoFillData: true,
+        data: rawData,
+        dataLength: rawData.length,
+      }),
+    [loop, rawData]
+  );
+
   return {
     ...props,
+    autoplay,
+    autoplayDirection,
+    autoplayInterval,
     defaultIndex,
-    autoFillData,
-    // Fill data with autoFillData
-    data,
-    // Length of fill data
-    dataLength,
-    // Raw data that has not been processed
-    rawData,
-    // Length of raw data
-    rawDataLength,
     loop,
-    enabled,
-    autoPlayInterval,
-    scrollAnimationDuration,
-    style,
-    pagingEnabled,
-    snapEnabled,
+    orientation,
     overscrollEnabled,
-    width,
-    height,
-    itemWidth,
-    itemHeight,
+    scrollEnabled,
+    snapMode,
+    style,
+    animation,
+    data,
+    rawData,
+    dataLength: data.length,
+    rawDataLength: rawData.length,
+    autoFillData: true,
+    directionSign,
   };
 }
+
+function validateStaticProps<Item>(props: CarouselProps<Item>) {
+  if (props.layout && props.itemAnimation) {
+    throw new Error(
+      "[react-native-reanimated-carousel] `layout` and `itemAnimation` are mutually exclusive."
+    );
+  }
+
+  if (props.itemSize !== undefined && (!Number.isFinite(props.itemSize) || props.itemSize <= 0)) {
+    throw new Error("[react-native-reanimated-carousel] itemSize must be a positive number.");
+  }
+
+  if (
+    props.autoplayInterval !== undefined &&
+    (!Number.isFinite(props.autoplayInterval) || props.autoplayInterval < 0)
+  ) {
+    throw new Error(
+      "[react-native-reanimated-carousel] autoplayInterval must be a non-negative number."
+    );
+  }
+
+  if (
+    props.renderWindowSize !== undefined &&
+    (!Number.isInteger(props.renderWindowSize) || props.renderWindowSize <= 0)
+  ) {
+    throw new Error(
+      "[react-native-reanimated-carousel] renderWindowSize must be a positive integer."
+    );
+  }
+}
+
+function isValidDefaultIndex(defaultIndex: number, dataLength: number) {
+  return Number.isInteger(defaultIndex) && defaultIndex >= 0 && defaultIndex < dataLength;
+}
+
+function assertValidDefaultIndex(defaultIndex: number, dataLength: number) {
+  if (!isValidDefaultIndex(defaultIndex, dataLength)) {
+    throw new Error(
+      `[react-native-reanimated-carousel] defaultIndex must be an integer between 0 and ${dataLength - 1}.`
+    );
+  }
+}

package/src/hooks/useLayoutConfig.ts

@@ -1,26 +1,35 @@
 import React from "react";
 
-import type { TInitializeCarouselProps } from "./useInitProps";
-
-import type { TAnimationStyle } from "../components/ItemLayout";
 import { Layouts } from "../layouts";
+import type { CarouselItemAnimation } from "../types";
+import type { InitializedCarouselProps } from "./useInitProps";
 
-type TLayoutConfigOpts<T> = TInitializeCarouselProps<T> & { size: number };
+type LayoutConfigOptions<Item> = InitializedCarouselProps<Item> & { size: number };
 
-export function useLayoutConfig<T>(opts: TLayoutConfigOpts<T>): TAnimationStyle {
-  const { size, vertical } = opts as Required<TLayoutConfigOpts<T>>;
+export function useLayoutConfig<Item>(options: LayoutConfigOptions<Item>): CarouselItemAnimation {
+  const { dataLength, directionSign, layout, orientation, size } = options;
+  const isVertical = orientation === "vertical";
 
   return React.useMemo(() => {
-    const baseConfig = { size, vertical };
-    switch (opts.mode) {
+    const baseConfig = { size, isVertical, directionSign };
+    switch (layout?.type) {
       case "parallax":
-        return Layouts.parallax(baseConfig, opts.modeConfig);
+        return Layouts.parallax(baseConfig, layout);
       case "horizontal-stack":
-        return Layouts.horizontalStack(opts.modeConfig);
+        return Layouts.horizontalStack(
+          {
+            ...layout,
+            visibleCount: layout.visibleCount ?? Math.max(0, dataLength - 1),
+          },
+          directionSign
+        );
       case "vertical-stack":
-        return Layouts.verticalStack(opts.modeConfig);
+        return Layouts.verticalStack({
+          ...layout,
+          visibleCount: layout.visibleCount ?? Math.max(0, dataLength - 1),
+        });
       default:
         return Layouts.normal(baseConfig);
     }
-  }, [opts.mode, opts.modeConfig, size, vertical]);
+  }, [dataLength, directionSign, isVertical, layout, size]);
 }

package/src/hooks/useOffsetX.ts

@@ -1,19 +1,19 @@
 import type { SharedValue } from "react-native-reanimated";
 import { Extrapolation, interpolate, useDerivedValue } from "react-native-reanimated";
 
-import type { IVisibleRanges } from "./useVisibleRanges";
+import type { VisibleRangesValue } from "./useVisibleRanges";
 
-export interface IOpts {
+export interface OffsetOptions {
   index: number;
   size: number;
   handlerOffset: SharedValue<number>;
   dataLength: number;
-  type?: "positive" | "negative";
-  viewCount?: number;
-  loop?: boolean;
+  type?: "positive" | "negative" | undefined;
+  viewCount?: number | undefined;
+  loop?: boolean | undefined;
 }
 
-export const useOffsetX = (opts: IOpts, visibleRanges: IVisibleRanges) => {
+export const useOffsetX = (opts: OffsetOptions, visibleRanges: VisibleRangesValue) => {
   const {
     handlerOffset,
     index,