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

package/src/hooks/useOnProgressChange.ts

@@ -2,57 +2,32 @@ import type { SharedValue } from "react-native-reanimated";
 import { useAnimatedReaction } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 
-import type { TCarouselProps } from "../types";
-import { computedOffsetXValueWithAutoFillData } from "../utils/computed-with-auto-fill-data";
-
-export function useOnProgressChange(
-  opts: {
-    size: number;
-    sizeReady: SharedValue<boolean>;
-    autoFillData: boolean;
-    loop: boolean;
-    offsetX: SharedValue<number>;
-    rawDataLength: number;
-  } & Pick<TCarouselProps, "onProgressChange">
-) {
-  const { autoFillData, loop, offsetX, size, rawDataLength, onProgressChange, sizeReady } = opts;
-
-  // remember `isFunc` here because we can't accurately check typeof
-  // from within useAnimatedReaction because its code has been workletized;
-  // the `onProgressChange` value will be typeof "object" from within
-  // the worklet code even if it's a function.
-  const isFunc = typeof onProgressChange === "function";
+import type { CarouselProgressChangeHandler } from "../types";
+import { getLogicalProgress } from "../utils/carousel-math";
+
+export function useOnProgressChange(options: {
+  loop: boolean;
+  offset: SharedValue<number>;
+  onProgressChange?: CarouselProgressChangeHandler;
+  progress?: SharedValue<number>;
+  rawDataLength: number;
+  size: number;
+  sizeReady: SharedValue<boolean>;
+}) {
+  const { loop, offset, onProgressChange, progress, rawDataLength, size, sizeReady } = options;
 
   useAnimatedReaction(
-    () => ({ offset: offsetX.value, ready: sizeReady.value }),
-    ({ offset, ready }) => {
-      const safeSize = size > 0 ? size : 0;
-      if (!ready || safeSize <= 0) return;
-
-      let value = computedOffsetXValueWithAutoFillData({
-        value: offset,
-        rawDataLength,
-        size: safeSize,
-        autoFillData,
-        loop,
-      });
-
-      if (!loop) {
-        value = Math.max(-((rawDataLength - 1) * safeSize), Math.min(value, 0));
-      }
+    () => {
+      if (!sizeReady.value || size <= 0 || rawDataLength <= 0) return null;
 
-      let absoluteProgress = Math.abs(value / safeSize);
-
-      if (value > 0) absoluteProgress = rawDataLength - absoluteProgress;
-
-      if (onProgressChange) {
-        if (isFunc) {
-          scheduleOnRN(onProgressChange, value, absoluteProgress);
-        } else {
-          (onProgressChange as SharedValue<number>).value = absoluteProgress;
-        }
-      }
+      const logicalProgress = getLogicalProgress(offset.value, size);
+      return loop ? logicalProgress : Math.max(0, Math.min(rawDataLength - 1, logicalProgress));
+    },
+    (nextProgress) => {
+      if (nextProgress == null) return;
+      if (progress) progress.value = nextProgress;
+      if (onProgressChange) scheduleOnRN(onProgressChange, nextProgress);
     },
-    [loop, autoFillData, rawDataLength, onProgressChange, size, offsetX, sizeReady]
+    [loop, offset, onProgressChange, progress, rawDataLength, size, sizeReady]
   );
 }

package/src/hooks/usePanGestureProxy.ts

@@ -2,16 +2,16 @@ import { useMemo } from "react";
 import type {
   GestureStateChangeEvent,
   GestureUpdateEvent,
-  PanGesture,
   PanGestureHandlerEventPayload,
 } from "react-native-gesture-handler";
 import { Gesture } from "react-native-gesture-handler";
 
+import type { CarouselPanGesture } from "../types";
 import type { GestureConfig } from "./useUpdateGestureConfig";
 import { useUpdateGestureConfig } from "./useUpdateGestureConfig";
 
 export const usePanGestureProxy = (customization: {
-  onConfigurePanGesture?: (gesture: PanGesture) => void;
+  onConfigurePanGesture?: (gesture: CarouselPanGesture) => void;
   onGestureStart: (event: GestureStateChangeEvent<PanGestureHandlerEventPayload>) => void;
   onGestureUpdate: (event: GestureUpdateEvent<PanGestureHandlerEventPayload>) => void;
   onGestureEnd: (

package/src/hooks/usePropsErrorBoundary.ts

@@ -1,99 +1,41 @@
 import React from "react";
-import { StyleSheet } from "react-native";
+import { type StyleProp, StyleSheet, type ViewStyle } from "react-native";
 
-import type { TCarouselProps } from "../types";
+import type { InitializedCarouselProps } from "./useInitProps";
 
-export function usePropsErrorBoundary(props: TCarouselProps & { dataLength: number }) {
-  React.useEffect(() => {
-    const { defaultIndex, dataLength: viewCount } = props;
+export function usePropsErrorBoundary(props: InitializedCarouselProps<unknown>) {
+  const warned = React.useRef({
+    contentStyle: false,
+    missingMainAxisSize: false,
+  });
 
-    if (typeof defaultIndex === "number" && viewCount > 0) {
-      if (defaultIndex < 0 || defaultIndex >= viewCount) {
-        throw new Error("DefaultIndex must be in the range of data length.");
-      }
+  React.useEffect(() => {
+    if (!__DEV__) return;
+
+    const { contentContainerStyle, orientation, style } = props;
+    const flattenedContentStyle =
+      StyleSheet.flatten(contentContainerStyle as StyleProp<ViewStyle>) || {};
+    if (
+      (flattenedContentStyle.opacity !== undefined ||
+        flattenedContentStyle.transform !== undefined) &&
+      !warned.current.contentStyle
+    ) {
+      console.warn(
+        "[react-native-reanimated-carousel] `contentContainerStyle` cannot set `opacity` or `transform`; those fields are owned by Carousel and were ignored."
+      );
+      warned.current.contentStyle = true;
     }
 
-    if (__DEV__) {
-      const { style, vertical, width, height, itemWidth, itemHeight, contentContainerStyle } =
-        props;
-      const { width: styleWidth, height: styleHeight, flex } = StyleSheet.flatten(style) || {};
-
-      // Deprecation warnings for width/height props
-      if (typeof width === "number" && !warnedRefs.width) {
-        console.warn(
-          "[react-native-reanimated-carousel] The `width` prop is deprecated. Please use `style={{ width: ... }}` instead."
-        );
-        warnedRefs.width = true;
-      }
-      if (typeof height === "number" && !warnedRefs.height) {
-        console.warn(
-          "[react-native-reanimated-carousel] The `height` prop is deprecated. Please use `style={{ height: ... }}` instead."
-        );
-        warnedRefs.height = true;
-      }
-
-      // Conflict warning for contentContainerStyle
-      const { opacity, transform } = StyleSheet.flatten(contentContainerStyle) || {};
-      if ((opacity !== undefined || transform !== undefined) && !warnedRefs.conflict) {
-        console.warn(
-          "[react-native-reanimated-carousel] Do not set 'opacity' or 'transform' on 'contentContainerStyle' as it may conflict with animations."
-        );
-        warnedRefs.conflict = true;
-      }
-
-      // Updated missing size warnings
-      const hasFlexibleContainerSize = typeof flex === "number" && flex > 0;
-      const hasHorizontalContainerSize =
-        styleWidth != null || typeof width === "number" || hasFlexibleContainerSize;
-      const hasVerticalContainerSize =
-        styleHeight != null || typeof height === "number" || hasFlexibleContainerSize;
-
-      if (!vertical && !hasHorizontalContainerSize && !warnedRefs.horizontal) {
-        console.warn(
-          "[react-native-reanimated-carousel] Horizontal mode did not specify `width` in `style`, will fall back to automatic measurement mode."
-        );
-        warnedRefs.horizontal = true;
-      }
-      if (vertical && !hasVerticalContainerSize && !warnedRefs.vertical) {
-        console.warn(
-          "[react-native-reanimated-carousel] Vertical mode did not specify `height` in `style`, will fall back to automatic measurement mode."
-        );
-        warnedRefs.vertical = true;
-      }
-
-      // Page-size guidance (common pitfall): setting itemWidth/itemHeight without container size.
-      if (
-        !vertical &&
-        typeof itemWidth === "number" &&
-        !hasHorizontalContainerSize &&
-        !warnedRefs.itemWidth
-      ) {
-        console.warn(
-          "[react-native-reanimated-carousel] `itemWidth` sets the snapping page size, not the container width. Consider setting container width via `style` (e.g. `style={{ width: '100%' }}` or `flex: 1`)."
-        );
-        warnedRefs.itemWidth = true;
-      }
-      if (
-        vertical &&
-        typeof itemHeight === "number" &&
-        !hasVerticalContainerSize &&
-        !warnedRefs.itemHeight
-      ) {
-        console.warn(
-          "[react-native-reanimated-carousel] `itemHeight` sets the snapping page size, not the container height. Consider setting container height via `style` (e.g. `style={{ height: '100%' }}` or `flex: 1`)."
-        );
-        warnedRefs.itemHeight = true;
-      }
+    const flattenedStyle = StyleSheet.flatten(style) || {};
+    const mainAxisSize = orientation === "vertical" ? flattenedStyle.height : flattenedStyle.width;
+    const hasFlexibleSize =
+      (typeof flattenedStyle.flex === "number" && flattenedStyle.flex > 0) ||
+      mainAxisSize !== undefined;
+    if (!hasFlexibleSize && !warned.current.missingMainAxisSize) {
+      console.warn(
+        `[react-native-reanimated-carousel] ${orientation} Carousel has no main-axis size in \`style\`; automatic layout measurement will be used.`
+      );
+      warned.current.missingMainAxisSize = true;
     }
   }, [props]);
 }
-
-const warnedRefs: { [key: string]: boolean } = {
-  horizontal: false,
-  vertical: false,
-  width: false,
-  height: false,
-  conflict: false,
-  itemWidth: false,
-  itemHeight: false,
-};

package/src/hooks/useUpdateGestureConfig.ts

@@ -1,11 +1,14 @@
 import { useEffect } from "react";
-import type { PanGesture } from "react-native-gesture-handler";
 
 export interface GestureConfig {
   enabled?: boolean;
 }
 
-export const useUpdateGestureConfig = (gesture: PanGesture, config: GestureConfig) => {
+type ConfigurablePanGesture = {
+  enabled(enabled: boolean): unknown;
+};
+
+export const useUpdateGestureConfig = (gesture: ConfigurablePanGesture, config: GestureConfig) => {
   const { enabled } = config;
 
   useEffect(() => {

package/src/hooks/useVisibleRanges.tsx

@@ -9,7 +9,7 @@ export interface VisibleRanges {
   positiveRange: Range;
 }
 
-export type IVisibleRanges = SharedValue<VisibleRanges>;
+export type VisibleRangesValue = SharedValue<VisibleRanges>;
 
 function normalizeWindowSize(total: number, windowSize?: number) {
   "worklet";
@@ -94,7 +94,7 @@ export function useVisibleRanges(options: {
   windowSize?: number;
   translation: SharedValue<number>;
   loop?: boolean;
-}): IVisibleRanges {
+}): VisibleRangesValue {
   const { total = 0, viewSize, translation, windowSize: _windowSize, loop } = options;
 
   const windowSize = normalizeWindowSize(total, _windowSize);

package/src/index.tsx

@@ -1,13 +1,18 @@
-import Carousel from "./components/Carousel";
+export { Carousel } from "./components/Carousel";
 export { Pagination } from "./components/Pagination";
 
 export type {
-  TCarouselProps,
-  ICarouselInstance,
-  IComputedDirectionTypes,
+  CarouselAnimation,
+  CarouselItemAnimation,
+  CarouselLayout,
+  CarouselPanGesture,
+  CarouselProgressChangeHandler,
+  CarouselProps,
+  CarouselRef,
   CarouselRenderItem,
-} from "./types";
-export type { TAnimationStyle } from "./components/ItemLayout";
-export type { ILayoutConfig } from "./layouts/stack";
-
-export default Carousel;
+  CarouselRenderItemInfo,
+  CarouselScrollToOptions,
+  CarouselStepOptions,
+  PaginationDotStyle,
+  PaginationProps,
+} from "./public-types";

package/src/layouts/index.tsx

@@ -2,8 +2,6 @@ import { normalLayout } from "./normal";
 import { parallaxLayout } from "./parallax";
 import { horizontalStackLayout, verticalStackLayout } from "./stack";
 
-export type TMode = "parallax" | "horizontal-stack" | "vertical-stack";
-
 export const Layouts = {
   normal: normalLayout,
   parallax: parallaxLayout,

package/src/layouts/normal.ts

@@ -1,15 +1,25 @@
 import { interpolate } from "react-native-reanimated";
 
-export function normalLayout(opts: { size: number; vertical: boolean }) {
-  const { size, vertical } = opts;
+import type { CarouselDirectionSign } from "../utils/carousel-direction";
+import { toPhysicalHorizontalValue } from "../utils/carousel-direction";
+
+export function normalLayout(opts: {
+  size: number;
+  isVertical: boolean;
+  directionSign: CarouselDirectionSign;
+}) {
+  const { size, isVertical, directionSign } = opts;
 
   return (value: number) => {
     "worklet";
-    const translate = interpolate(value, [-1, 0, 1], [-size, 0, size]);
+    const logicalTranslate = interpolate(value, [-1, 0, 1], [-size, 0, size]);
+    const translate = isVertical
+      ? logicalTranslate
+      : toPhysicalHorizontalValue(logicalTranslate, directionSign);
 
     return {
       transform: [
-        vertical
+        isVertical
           ? {
               translateY: translate,
             }

package/src/layouts/parallax.ts

@@ -1,75 +1,48 @@
 import { Extrapolation, interpolate } from "react-native-reanimated";
 
-import type { IComputedDirectionTypes } from "../types";
-
-interface TBaseConfig {
-  size: number;
-  vertical: boolean;
-}
-
-export interface ILayoutConfig {
-  /**
-   * control prev/next item offset.
-   * @default 100
-   */
-  parallaxScrollingOffset?: number;
-  /**
-   * control prev/current/next item offset.
-   * @default 0.8
-   */
-  parallaxScrollingScale?: number;
-  /**
-   * control prev/next item offset.
-   * @default Math.pow(parallaxScrollingScale, 2)
-   */
-  parallaxAdjacentItemScale?: number;
-}
-
-export type TParallaxModeProps = IComputedDirectionTypes<{
-  /**
-   * Carousel Animated transitions.
-   */
-  mode?: "parallax";
-  modeConfig?: ILayoutConfig;
-}>;
-
-export function parallaxLayout(baseConfig: TBaseConfig, modeConfig: ILayoutConfig = {}) {
-  const { size, vertical } = baseConfig;
-  const {
-    parallaxScrollingOffset = 100,
-    parallaxScrollingScale = 0.8,
-    parallaxAdjacentItemScale = parallaxScrollingScale ** 2,
-  } = modeConfig;
-
-  return (value: number) => {
+import type { CarouselLayout } from "../types";
+import type { CarouselDirectionSign } from "../utils/carousel-direction";
+import { toPhysicalHorizontalValue } from "../utils/carousel-direction";
+
+type ParallaxLayout = Extract<CarouselLayout, { type: "parallax" }>;
+
+export function parallaxLayout(
+  baseConfig: {
+    size: number;
+    isVertical: boolean;
+    directionSign: CarouselDirectionSign;
+  },
+  config: ParallaxLayout
+) {
+  const { size, isVertical, directionSign } = baseConfig;
+  const { offset = 100, scale = 0.8, adjacentScale = scale ** 2 } = config;
+
+  return (relativeProgress: number) => {
     "worklet";
-    const translate = interpolate(
-      value,
+    const logicalTranslate = interpolate(
+      relativeProgress,
       [-1, 0, 1],
-      [-size + parallaxScrollingOffset, 0, size - parallaxScrollingOffset]
+      [-size + offset, 0, size - offset]
     );
+    const translate = isVertical
+      ? logicalTranslate
+      : toPhysicalHorizontalValue(logicalTranslate, directionSign);
 
-    const zIndex = Math.round(interpolate(value, [-1, 0, 1], [0, size, 0], Extrapolation.CLAMP));
+    const zIndex = Math.round(
+      interpolate(relativeProgress, [-1, 0, 1], [0, size, 0], Extrapolation.CLAMP)
+    );
 
-    const scale = interpolate(
-      value,
+    const animatedScale = interpolate(
+      relativeProgress,
       [-1, 0, 1],
-      [parallaxAdjacentItemScale, parallaxScrollingScale, parallaxAdjacentItemScale],
+      [adjacentScale, scale, adjacentScale],
       Extrapolation.CLAMP
     );
 
     return {
       transform: [
-        vertical
-          ? {
-              translateY: translate,
-            }
-          : {
-              translateX: translate,
-            },
-        {
-          scale,
-        },
+        isVertical ? { translateY: translate } : { translateX: translate },
+        { scale: animatedScale },
       ],
       zIndex,
     };

package/src/layouts/stack.ts

@@ -1,57 +1,36 @@
-import { useMemo } from "react";
 import type { TransformsStyle, ViewStyle } from "react-native";
 import { Dimensions } from "react-native";
 import { Extrapolation, interpolate } from "react-native-reanimated";
 
-import type { CustomConfig, IComputedDirectionTypes } from "../types";
+import type { CarouselLayout } from "../types";
+import type { CarouselDirectionSign } from "../utils/carousel-direction";
+import { toPhysicalHorizontalValue } from "../utils/carousel-direction";
 
 const screen = Dimensions.get("window");
 
-export interface ILayoutConfig {
-  showLength?: number;
-  moveSize?: number;
-  stackInterval?: number;
-  scaleInterval?: number;
-  opacityInterval?: number;
-  rotateZDeg?: number;
-  snapDirection?: "left" | "right";
-}
-
-export type TStackModeProps = IComputedDirectionTypes<{
-  /**
-   * Carousel Animated transitions.
-   */
-  mode?: "horizontal-stack" | "vertical-stack";
-  /**
-   * Stack animation style.
-   * @default
-   *     snapDirection: 'right',
-   *     moveSize: window.width,
-   *     stackInterval: 30,
-   *     scaleInterval: 0.08,
-   *     rotateZDeg: 135,
-   *     opacityInterval: 0.1,
-   */
-  modeConfig?: ILayoutConfig;
-}>;
+type StackLayout = Extract<CarouselLayout, { type: "horizontal-stack" | "vertical-stack" }>;
 
-export function horizontalStackLayout(modeConfig: ILayoutConfig = {}) {
+export function horizontalStackLayout(
+  config: StackLayout,
+  directionSign: CarouselDirectionSign = 1
+) {
   return (_value: number) => {
     "worklet";
 
     const {
-      showLength,
-      snapDirection = "left",
-      moveSize = screen.width,
-      stackInterval = 18,
-      scaleInterval = 0.04,
-      opacityInterval = 0.1,
-      rotateZDeg = 30,
-    } = modeConfig;
-
+      visibleCount,
+      exitDirection: snapDirection = "left",
+      exitDistance: moveSize = screen.width,
+      spacing: stackInterval = 18,
+      scaleStep: scaleInterval = 0.04,
+      opacityStep: opacityInterval = 0.1,
+      rotation: rotateZDeg = 30,
+    } = config;
+
+    const physicalProgress = toPhysicalHorizontalValue(_value, directionSign);
     const { validLength, value, inputRange } = getCommonVariables({
-      showLength: showLength!,
-      value: _value,
+      showLength: visibleCount!,
+      value: physicalProgress,
       snapDirection,
     });
     const { zIndex, opacity } = getCommonStyles({
@@ -117,41 +96,22 @@ export function horizontalStackLayout(modeConfig: ILayoutConfig = {}) {
   };
 }
 
-export function useHorizontalStackLayout(
-  customAnimationConfig: ILayoutConfig = {},
-  customConfig: CustomConfig = {}
-) {
-  const config = useMemo(
-    () => ({
-      type: customAnimationConfig.snapDirection === "right" ? "negative" : "positive",
-      viewCount: customAnimationConfig.showLength,
-      ...customConfig,
-    }),
-    [customAnimationConfig, customConfig]
-  );
-
-  return {
-    layout: horizontalStackLayout(customAnimationConfig),
-    config,
-  };
-}
-
-export function verticalStackLayout(modeConfig: ILayoutConfig = {}) {
+export function verticalStackLayout(config: StackLayout) {
   return (_value: number) => {
     "worklet";
 
     const {
-      showLength,
-      snapDirection = "left",
-      moveSize = screen.width,
-      stackInterval = 18,
-      scaleInterval = 0.04,
-      opacityInterval = 0.1,
-      rotateZDeg = 30,
-    } = modeConfig;
+      visibleCount,
+      exitDirection: snapDirection = "left",
+      exitDistance: moveSize = screen.width,
+      spacing: stackInterval = 18,
+      scaleStep: scaleInterval = 0.04,
+      opacityStep: opacityInterval = 0.1,
+      rotation: rotateZDeg = 30,
+    } = config;
 
     const { validLength, value, inputRange } = getCommonVariables({
-      showLength: showLength!,
+      showLength: visibleCount!,
       value: _value,
       snapDirection,
     });