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

package/src/components/CarouselLayout.tsx

@@ -1,6 +1,5 @@
 import React from "react";
-import { StyleSheet, type ViewStyle } from "react-native";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { type StyleProp, StyleSheet, View, type ViewStyle } from "react-native";
 import { useAnimatedReaction, useAnimatedStyle, useDerivedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import { useAutoPlay } from "../hooks/useAutoPlay";
@@ -8,42 +7,29 @@ import { useCarouselController } from "../hooks/useCarouselController";
 import { useLayoutConfig } from "../hooks/useLayoutConfig";
 import { useOnProgressChange } from "../hooks/useOnProgressChange";
 import { useGlobalState } from "../store";
-import { ICarouselInstance } from "../types";
-import { computedRealIndexWithAutoFillData } from "../utils/computed-with-auto-fill-data";
+import type { CarouselRef } from "../types";
 import { ItemRenderer } from "./ItemRenderer";
 import { ScrollViewGesture } from "./ScrollViewGesture";
 
-export type TAnimationStyle = (value: number) => ViewStyle;
-
 export function resolveCarouselLayoutStyle(params: {
   flattenedStyle: Partial<ViewStyle>;
-  vertical: boolean;
+  isVertical: boolean;
   measuredSize: number;
   sizeExplicit: boolean;
-  legacyWidth?: number;
-  legacyHeight?: number;
 }) {
   "worklet";
 
-  const { flattenedStyle, vertical, measuredSize, sizeExplicit, legacyWidth, legacyHeight } =
-    params;
+  const { flattenedStyle, isVertical, measuredSize, sizeExplicit } = params;
   const { width, height } = flattenedStyle;
-  const hasLegacyMainAxisSize = vertical
-    ? typeof legacyHeight === "number" && legacyHeight > 0
-    : typeof legacyWidth === "number" && legacyWidth > 0;
-  const shouldUseMeasuredMainAxisSize = sizeExplicit || hasLegacyMainAxisSize;
   const resolvedMainAxisSize = measuredSize || "100%";
 
   return {
-    width:
-      width ?? (vertical ? "100%" : shouldUseMeasuredMainAxisSize ? resolvedMainAxisSize : "100%"),
-    height:
-      height ??
-      (vertical ? (shouldUseMeasuredMainAxisSize ? resolvedMainAxisSize : "100%") : "100%"),
+    width: width ?? (isVertical ? "100%" : sizeExplicit ? resolvedMainAxisSize : "100%"),
+    height: height ?? (isVertical ? (sizeExplicit ? resolvedMainAxisSize : "100%") : "100%"),
   };
 }
 
-export const CarouselLayout = React.forwardRef<ICarouselInstance>((_props, ref) => {
+export const CarouselLayout = React.forwardRef<CarouselRef>((_props, ref) => {
   const { props, common } = useGlobalState();
 
   const {
@@ -52,31 +38,30 @@ export const CarouselLayout = React.forwardRef<ICarouselInstance>((_props, ref)
     autoFillData,
     // Fill data with autoFillData
     data,
+    rawData,
     // Length of fill data
     dataLength,
     // Length of raw data
     rawDataLength,
-    mode,
+    layout,
     style,
     contentContainerStyle,
-    vertical,
-    autoPlay,
-    windowSize,
-    autoPlayReverse,
-    autoPlayInterval,
-    scrollAnimationDuration,
-    withAnimation,
-    fixedDirection,
+    orientation,
+    autoplay,
+    renderWindowSize,
+    autoplayDirection,
+    autoplayInterval,
+    animation,
     renderItem,
-    onScrollEnd,
     onSnapToItem,
     onScrollStart,
     onProgressChange,
-    customAnimation,
+    progress,
+    itemAnimation,
     defaultIndex,
-    width: legacyWidth,
-    height: legacyHeight,
+    keyExtractor,
   } = props;
+  const isVertical = orientation === "vertical";
 
   const { size, handlerOffset, resolvedSize, sizePhase, sizeExplicit } = common;
   const layoutConfig = useLayoutConfig({ ...props, size });
@@ -101,100 +86,85 @@ export const CarouselLayout = React.forwardRef<ICarouselInstance>((_props, ref)
   }, [loop, dataLength, handlerOffset, resolvedSize]);
 
   useOnProgressChange({
-    autoFillData,
     loop,
+    offset: handlerOffset,
+    progress,
     size,
     sizeReady: isSizeReady,
-    offsetX,
     rawDataLength,
     onProgressChange,
   });
 
+  const _onScrollEnd = React.useCallback(
+    (realIndex: number) => {
+      if (onSnapToItem) onSnapToItem(realIndex);
+    },
+    [onSnapToItem]
+  );
+
   const carouselController = useCarouselController({
     ref,
     loop,
     size,
     dataLength,
-    autoFillData,
+    rawDataLength,
     handlerOffset,
-    withAnimation,
+    animation,
     defaultIndex,
-    fixedDirection,
-    duration: scrollAnimationDuration,
-    onScrollEnd: () => scheduleOnRN(_onScrollEnd),
-    onScrollStart: () => !!onScrollStart && scheduleOnRN(onScrollStart),
+    onMovementEnd: _onScrollEnd,
+    onScrollStart,
   });
 
-  const {
-    getSharedIndex,
-    // index, // Animated index. Could be used for dynamic dimension
-  } = carouselController;
-
-  const _onScrollEnd = React.useCallback(() => {
-    const _sharedIndex = Math.round(getSharedIndex());
-
-    const realIndex = computedRealIndexWithAutoFillData({
-      index: _sharedIndex,
-      dataLength: rawDataLength,
-      loop,
-      autoFillData,
-    });
-
-    if (onSnapToItem) onSnapToItem(realIndex);
-
-    if (onScrollEnd) onScrollEnd(realIndex);
-  }, [loop, autoFillData, rawDataLength, getSharedIndex, onSnapToItem, onScrollEnd]);
-
   const {
     start: startAutoPlay,
     pause: pauseAutoPlay,
     trigger: triggerAutoPlay,
   } = useAutoPlay({
-    autoPlay,
-    autoPlayInterval,
-    autoPlayReverse,
+    autoplay,
+    autoplayDirection,
+    autoplayInterval,
     carouselController,
   });
 
   useAnimatedReaction(
     () => ({ ready: isSizeReady.value }),
     (state, previous) => {
-      if (!autoPlay) return;
+      if (!autoplay) return;
       if (state.ready === previous?.ready) return;
 
       if (state.ready) scheduleOnRN(triggerAutoPlay);
       else scheduleOnRN(pauseAutoPlay);
     },
-    [autoPlay]
+    [autoplay]
   );
 
   const scrollViewGestureOnScrollStart = React.useCallback(() => {
+    carouselController.startMovement();
     pauseAutoPlay();
     onScrollStart?.();
-  }, [onScrollStart, pauseAutoPlay]);
+  }, [carouselController, onScrollStart, pauseAutoPlay]);
 
   const scrollViewGestureOnScrollEnd = React.useCallback(() => {
+    const settledIndex = carouselController.settle();
     startAutoPlay();
-    _onScrollEnd();
-  }, [_onScrollEnd, startAutoPlay]);
+    _onScrollEnd(settledIndex);
+  }, [_onScrollEnd, carouselController, startAutoPlay]);
 
   const scrollViewGestureOnTouchBegin = React.useCallback(pauseAutoPlay, [pauseAutoPlay]);
 
   const scrollViewGestureOnTouchEnd = React.useCallback(startAutoPlay, [startAutoPlay]);
 
   const { opacity, transform, ...restContentContainerStyle } =
-    StyleSheet.flatten(contentContainerStyle) || {};
+    StyleSheet.flatten(contentContainerStyle as StyleProp<ViewStyle>) || {};
   const flattenedStyle = StyleSheet.flatten(style) || {};
 
   const layoutStyle = useAnimatedStyle(() => {
     const measuredSize = resolvedSize.value ?? 0;
     const { width, height } = resolveCarouselLayoutStyle({
       flattenedStyle,
-      vertical: !!vertical,
+      isVertical,
       measuredSize,
       sizeExplicit,
-      legacyWidth,
-      legacyHeight,
     });
 
     return {
@@ -202,31 +172,21 @@ export const CarouselLayout = React.forwardRef<ICarouselInstance>((_props, ref)
       height,
       opacity: isSizeReady.value ? 1 : 0,
     };
-  }, [
-    flattenedStyle,
-    isSizeReady,
-    vertical,
-    resolvedSize,
-    sizePhase,
-    sizeExplicit,
-    legacyWidth,
-    legacyHeight,
-  ]);
+  }, [flattenedStyle, isSizeReady, isVertical, resolvedSize, sizePhase, sizeExplicit]);
 
   return (
-    <GestureHandlerRootView testID={testID} style={[styles.layoutContainer, style]}>
+    <View testID={testID} style={[styles.layoutContainer, style]} onLayout={props.onLayout}>
       <ScrollViewGesture
         size={size}
-        key={mode}
+        key={layout?.type}
         translation={handlerOffset}
         style={[
           styles.contentContainer,
           layoutStyle,
           restContentContainerStyle,
-          vertical ? styles.itemsVertical : styles.itemsHorizontal,
+          isVertical ? styles.itemsVertical : styles.itemsHorizontal,
         ]}
         testID="carousel-content-container"
-        onLayout={props.onLayout}
         onScrollStart={scrollViewGestureOnScrollStart}
         onScrollEnd={scrollViewGestureOnScrollEnd}
         onTouchBegin={scrollViewGestureOnTouchBegin}
@@ -234,21 +194,23 @@ export const CarouselLayout = React.forwardRef<ICarouselInstance>((_props, ref)
       >
         <ItemRenderer
           data={data}
+          rawData={rawData}
           dataLength={dataLength}
           rawDataLength={rawDataLength}
           loop={loop}
           size={size}
-          windowSize={windowSize}
+          renderWindowSize={renderWindowSize}
           defaultIndex={defaultIndex}
           autoFillData={autoFillData}
           offsetX={offsetX}
           handlerOffset={handlerOffset}
           layoutConfig={layoutConfig}
           renderItem={renderItem}
-          customAnimation={customAnimation}
+          itemAnimation={itemAnimation}
+          keyExtractor={keyExtractor}
         />
       </ScrollViewGesture>
-    </GestureHandlerRootView>
+    </View>
   );
 });
 

package/src/components/ItemLayout.tsx

@@ -3,21 +3,23 @@ import type { LayoutChangeEvent, ViewStyle } from "react-native";
 import { StyleSheet } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 import Animated, {
+  useAnimatedReaction,
   useAnimatedStyle,
   useDerivedValue,
   useSharedValue,
 } from "react-native-reanimated";
-import { scheduleOnUI } from "react-native-worklets";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
 
-import type { IOpts } from "../hooks/useOffsetX";
+import type { OffsetOptions } from "../hooks/useOffsetX";
 import { useOffsetX } from "../hooks/useOffsetX";
-import type { IVisibleRanges } from "../hooks/useVisibleRanges";
-import type { ILayoutConfig } from "../layouts/stack";
+import type { VisibleRangesValue } from "../hooks/useVisibleRanges";
 import { useGlobalState } from "../store";
-import type { TCarouselProps } from "../types";
+import type { CarouselItemAnimation } from "../types";
+import { getHorizontalStackOffsetType } from "../utils/carousel-direction";
+import { positiveModulo } from "../utils/carousel-math";
 import { sanitizeAnimationStyle } from "../utils/sanitize-animation-style";
 
-export type TAnimationStyle = NonNullable<TCarouselProps["customAnimation"]>;
+export type ItemAnimationStyle = CarouselItemAnimation;
 
 export function resolveItemMainAxisSize(params: {
   explicitSize?: number;
@@ -35,29 +37,18 @@ export function resolveItemMainAxisSize(params: {
 
 export const ItemLayout: React.FC<{
   index: number;
+  rawIndex: number;
   handlerOffset: SharedValue<number>;
-  visibleRanges: IVisibleRanges;
-  animationStyle: TAnimationStyle;
+  visibleRanges: VisibleRangesValue;
+  animationStyle: ItemAnimationStyle;
   children: (ctx: {
-    animationValue: SharedValue<number>;
+    relativeProgress: SharedValue<number>;
   }) => React.ReactElement;
 }> = (props) => {
-  const { handlerOffset, index, children, visibleRanges, animationStyle } = props;
+  const { handlerOffset, index, rawIndex, children, visibleRanges, animationStyle } = props;
 
   const {
-    props: {
-      loop,
-      dataLength,
-      width,
-      height,
-      vertical,
-      customConfig,
-      mode,
-      modeConfig,
-      style,
-      itemWidth,
-      itemHeight,
-    },
+    props: { loop, dataLength, directionSign, orientation, layout, style, itemSize },
     common,
     layout: { updateItemDimensions },
   } = useGlobalState();
@@ -68,24 +59,19 @@ export const ItemLayout: React.FC<{
   });
 
   const fallbackSize = common.size;
-  // Prefer size from `style` (v5), then fallback to deprecated `width`/`height` for v4 compatibility.
+  const isVertical = orientation === "vertical";
   const { width: styleWidth, height: styleHeight } = StyleSheet.flatten(style) || {};
   const styleWidthNumber = typeof styleWidth === "number" ? styleWidth : undefined;
   const styleHeightNumber = typeof styleHeight === "number" ? styleHeight : undefined;
 
-  // When itemWidth/itemHeight is provided, use it for item dimensions (not container style)
-  const explicitItemSize = vertical ? itemHeight : itemWidth;
-  const explicitAxisSize = vertical ? (styleHeightNumber ?? height) : (styleWidthNumber ?? width);
-  // Use itemWidth/itemHeight if provided, otherwise fall back to container size
-  const size = (explicitItemSize ?? explicitAxisSize ?? fallbackSize) || 0;
+  const size = (itemSize ?? fallbackSize) || 0;
   const effectivePageSize = size > 0 ? size : undefined;
 
   const dimensionsStyle = useAnimatedStyle<ViewStyle>(() => {
-    // When itemWidth/itemHeight is provided, use it for item width/height
-    const widthCandidate = vertical ? width : (explicitItemSize ?? explicitAxisSize);
-    const heightCandidate = vertical ? (explicitItemSize ?? explicitAxisSize) : height;
+    const widthCandidate = isVertical ? styleWidthNumber : itemSize;
+    const heightCandidate = isVertical ? itemSize : styleHeightNumber;
 
-    const computedWidth = vertical
+    const computedWidth = isVertical
       ? typeof widthCandidate === "number"
         ? widthCandidate
         : (measuredSize.value.width ?? "100%")
@@ -95,7 +81,7 @@ export const ItemLayout: React.FC<{
           measuredSize: measuredSize.value.width,
         });
 
-    const computedHeight = vertical
+    const computedHeight = isVertical
       ? resolveItemMainAxisSize({
           explicitSize: heightCandidate,
           effectivePageSize,
@@ -109,40 +95,59 @@ export const ItemLayout: React.FC<{
       width: computedWidth,
       height: computedHeight,
     };
-  }, [vertical, width, height, explicitAxisSize, explicitItemSize, effectivePageSize]);
+  }, [effectivePageSize, isVertical, itemSize, styleHeightNumber, styleWidthNumber]);
 
-  let offsetXConfig: IOpts = {
+  let offsetXConfig: OffsetOptions = {
     handlerOffset,
     index,
     size,
     dataLength,
     loop,
-    ...(typeof customConfig === "function" ? customConfig() : {}),
   };
 
-  if (mode === "horizontal-stack") {
-    const { snapDirection, showLength } = modeConfig as ILayoutConfig;
-
+  if (layout?.type === "horizontal-stack") {
     offsetXConfig = {
       handlerOffset,
       index,
       size,
       dataLength,
       loop,
-      type: snapDirection === "right" ? "negative" : "positive",
-      viewCount: showLength,
+      type: getHorizontalStackOffsetType(layout.exitDirection ?? "left", directionSign),
+      viewCount: layout.visibleCount,
     };
   }
 
   const x = useOffsetX(offsetXConfig, visibleRanges);
-  const animationValue = useDerivedValue(() => {
+  const isCurrentForAccessibility = React.useCallback(() => {
+    "worklet";
+
+    return (
+      size > 0 &&
+      dataLength > 0 &&
+      positiveModulo(Math.round(-handlerOffset.value / size), dataLength) === index
+    );
+  }, [dataLength, handlerOffset, index, size]);
+  const [isAccessibilityCurrent, setIsAccessibilityCurrent] =
+    React.useState(isCurrentForAccessibility);
+
+  useAnimatedReaction(
+    isCurrentForAccessibility,
+    (isCurrent, wasCurrent) => {
+      if (isCurrent !== wasCurrent) {
+        scheduleOnRN(setIsAccessibilityCurrent, isCurrent);
+      }
+    },
+    [isCurrentForAccessibility]
+  );
+
+  const relativeProgress = useDerivedValue(() => {
     if (!size) return 0;
     return x.value / size;
   }, [x, size]);
   const animatedStyle = useAnimatedStyle<ViewStyle>(() => {
     const safeSize = size || 1;
-    return sanitizeAnimationStyle(animationStyle(x.value / safeSize, index));
-  }, [animationStyle, index, x, size]);
+    return sanitizeAnimationStyle(animationStyle(x.value / safeSize, rawIndex));
+  }, [animationStyle, rawIndex, x, size]);
 
   // TODO: For dynamic dimension in the future
   // function handleLayout(e: LayoutChangeEvent) {
@@ -150,7 +155,7 @@ export const ItemLayout: React.FC<{
   //   updateItemDimensions(index, { width, height });
   // }
 
-  const child = children({ animationValue });
+  const child = children({ relativeProgress });
 
   type LayoutableProps = {
     collapsable?: boolean;
@@ -185,6 +190,10 @@ export const ItemLayout: React.FC<{
 
   return (
     <Animated.View
+      accessibilityElementsHidden={!isAccessibilityCurrent}
+      accessible={isAccessibilityCurrent ? undefined : false}
+      aria-hidden={!isAccessibilityCurrent}
+      importantForAccessibility={isAccessibilityCurrent ? "auto" : "no-hide-descendants"}
       style={[
         {
           position: "absolute",

package/src/components/ItemRenderer.tsx

@@ -1,39 +1,41 @@
 import React from "react";
 import type { FC } from "react";
-import type { ViewStyle } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 import { useAnimatedReaction } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 
-import type { TAnimationStyle } from "./ItemLayout";
+import type { ItemAnimationStyle } from "./ItemLayout";
 import { ItemLayout } from "./ItemLayout";
 
 import type { VisibleRanges } from "../hooks/useVisibleRanges";
 import { computeVisibleRanges, useVisibleRanges } from "../hooks/useVisibleRanges";
-import type { CarouselRenderItem } from "../types";
+import type { CarouselItemAnimation, CarouselRenderItem } from "../types";
 import { computedRealIndexWithAutoFillData } from "../utils/computed-with-auto-fill-data";
 
 interface Props {
-  data: any[];
+  data: unknown[];
+  rawData: unknown[];
   dataLength: number;
   rawDataLength: number;
   loop: boolean;
   size: number;
-  windowSize?: number;
+  renderWindowSize?: number;
   defaultIndex: number;
   autoFillData: boolean;
   offsetX: SharedValue<number>;
   handlerOffset: SharedValue<number>;
-  layoutConfig: TAnimationStyle;
-  renderItem: CarouselRenderItem<any>;
-  customAnimation?: (value: number, index: number) => ViewStyle;
+  layoutConfig: ItemAnimationStyle;
+  renderItem: CarouselRenderItem<unknown>;
+  itemAnimation?: CarouselItemAnimation;
+  keyExtractor?: (item: unknown, index: number) => string;
 }
 
 export const ItemRenderer: FC<Props> = (props) => {
   const {
     data,
+    rawData,
     size,
-    windowSize,
+    renderWindowSize,
     defaultIndex,
     handlerOffset,
     offsetX,
@@ -43,14 +45,15 @@ export const ItemRenderer: FC<Props> = (props) => {
     autoFillData,
     layoutConfig,
     renderItem,
-    customAnimation,
+    itemAnimation,
+    keyExtractor,
   } = props;
 
   const visibleRanges = useVisibleRanges({
     total: dataLength,
     viewSize: size,
     translation: handlerOffset,
-    windowSize,
+    windowSize: renderWindowSize,
     loop,
   });
 
@@ -59,11 +62,11 @@ export const ItemRenderer: FC<Props> = (props) => {
     () =>
       computeVisibleRanges({
         total: dataLength,
-        windowSize,
+        windowSize: renderWindowSize,
         currentIndex: defaultIndex,
         loop,
       }),
-    [dataLength, defaultIndex, loop, windowSize]
+    [dataLength, defaultIndex, loop, renderWindowSize]
   );
 
   const [displayedItems, setDisplayedItems] = React.useState<VisibleRanges>(initialRanges);
@@ -92,19 +95,27 @@ export const ItemRenderer: FC<Props> = (props) => {
 
         if (!shouldRender) return null;
 
+        const rawItem = rawData[realIndex] ?? item;
+        const key = keyExtractor
+          ? `${keyExtractor(rawItem, realIndex)}::rnrc-copy-${Math.floor(
+              index / Math.max(rawDataLength, 1)
+            )}`
+          : String(index);
+
         return (
           <ItemLayout
-            key={index}
+            key={key}
             index={index}
+            rawIndex={realIndex}
             handlerOffset={offsetX}
             visibleRanges={visibleRanges}
-            animationStyle={customAnimation || layoutConfig}
+            animationStyle={itemAnimation || layoutConfig}
           >
-            {({ animationValue }) =>
+            {({ relativeProgress }) =>
               renderItem({
-                item,
+                item: rawItem,
                 index: realIndex,
-                animationValue,
+                relativeProgress,
               })
             }
           </ItemLayout>