@leonsilicon/react-native-reanimated-carousel 0.0.0

package/src/components/Carousel.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { useCommonVariables } from "../hooks/useCommonVariables";
+import { useInitProps } from "../hooks/useInitProps";
+import { usePropsErrorBoundary } from "../hooks/usePropsErrorBoundary";
+import { useSizeResolver } from "../hooks/useSizeResolver";
+import { GlobalStateProvider } from "../store";
+import type { ICarouselInstance, TCarouselProps } from "../types";
+import { CarouselLayout } from "./CarouselLayout";
+
+const Carousel = React.forwardRef<ICarouselInstance, TCarouselProps<any>>((_props, ref) => {
+  const props = useInitProps(_props);
+  const { dataLength, getItemSize } = props;
+  const commonVariables = useCommonVariables(props);
+  usePropsErrorBoundary({ ...props, dataLength });
+
+  const sizeResolver = useSizeResolver({
+    dataLength,
+    getItemSize,
+    uniformSize: commonVariables.resolvedSize,
+  });
+
+  return (
+    <GlobalStateProvider value={{ props, common: commonVariables, sizeResolver }}>
+      <CarouselLayout ref={ref} />
+    </GlobalStateProvider>
+  );
+});
+
+type CarouselComponent = <T>(
+  props: React.PropsWithChildren<TCarouselProps<T>> & {
+    ref?: React.Ref<ICarouselInstance>;
+  }
+) => React.ReactElement;
+
+export default Carousel as CarouselComponent;

package/src/components/CarouselLayout.tsx

@@ -0,0 +1,231 @@
+import React from "react";
+import { StyleSheet, type ViewStyle } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { useAnimatedReaction, useAnimatedStyle, useDerivedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useAutoPlay } from "../hooks/useAutoPlay";
+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 { ItemRenderer } from "./ItemRenderer";
+import { ScrollViewGesture } from "./ScrollViewGesture";
+
+export type TAnimationStyle = (value: number) => ViewStyle;
+
+export const CarouselLayout = React.forwardRef<ICarouselInstance>((_props, ref) => {
+  const { props, common, sizeResolver } = useGlobalState();
+
+  const {
+    testID,
+    loop,
+    autoFillData,
+    // Fill data with autoFillData
+    data,
+    // Length of fill data
+    dataLength,
+    // Length of raw data
+    rawDataLength,
+    mode,
+    style,
+    contentContainerStyle,
+    vertical,
+    autoPlay,
+    windowSize,
+    autoPlayReverse,
+    autoPlayInterval,
+    scrollAnimationDuration,
+    withAnimation,
+    fixedDirection,
+    renderItem,
+    onScrollEnd,
+    onSnapToItem,
+    onScrollStart,
+    onProgressChange,
+    customAnimation,
+    defaultIndex,
+    variableSize,
+  } = props;
+
+  const { size, handlerOffset, resolvedSize, sizePhase } = common;
+  const layoutConfig = useLayoutConfig({ ...props, size, sizeResolver });
+
+  const isSizeReady = useDerivedValue(() => {
+    if (variableSize) return sizeResolver.total.value > 0;
+    const currentSize = resolvedSize.value ?? 0;
+    return sizePhase.value === "ready" && currentSize > 0;
+  }, [resolvedSize, sizePhase, variableSize, sizeResolver]);
+
+  const offsetX = useDerivedValue(() => {
+    const totalSize = variableSize
+      ? sizeResolver.total.value
+      : (resolvedSize.value ?? 0) * dataLength;
+    if (totalSize <= 0) return 0;
+
+    const value = handlerOffset.value;
+    if (!loop || totalSize === 0) {
+      return value;
+    }
+
+    const x = value % totalSize;
+    return Number.isNaN(x) ? 0 : x;
+  }, [loop, dataLength, handlerOffset, resolvedSize, variableSize, sizeResolver]);
+
+  useOnProgressChange({
+    autoFillData,
+    loop,
+    size,
+    sizeReady: isSizeReady,
+    offsetX,
+    rawDataLength,
+    onProgressChange,
+    sizeResolver,
+    variableSize,
+  });
+
+  const carouselController = useCarouselController({
+    ref,
+    loop,
+    size,
+    dataLength,
+    autoFillData,
+    handlerOffset,
+    withAnimation,
+    defaultIndex,
+    fixedDirection,
+    duration: scrollAnimationDuration,
+    onScrollEnd: () => scheduleOnRN(_onScrollEnd),
+    onScrollStart: () => !!onScrollStart && scheduleOnRN(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,
+    carouselController,
+  });
+
+  useAnimatedReaction(
+    () => ({ ready: isSizeReady.value }),
+    (state, previous) => {
+      if (!autoPlay) return;
+      if (state.ready === previous?.ready) return;
+
+      if (state.ready) scheduleOnRN(triggerAutoPlay);
+      else scheduleOnRN(pauseAutoPlay);
+    },
+    [autoPlay]
+  );
+
+  const scrollViewGestureOnScrollStart = React.useCallback(() => {
+    pauseAutoPlay();
+    onScrollStart?.();
+  }, [onScrollStart, pauseAutoPlay]);
+
+  const scrollViewGestureOnScrollEnd = React.useCallback(() => {
+    startAutoPlay();
+    _onScrollEnd();
+  }, [_onScrollEnd, startAutoPlay]);
+
+  const scrollViewGestureOnTouchBegin = React.useCallback(pauseAutoPlay, [pauseAutoPlay]);
+
+  const scrollViewGestureOnTouchEnd = React.useCallback(startAutoPlay, [startAutoPlay]);
+
+  const { opacity, transform, ...restContentContainerStyle } =
+    StyleSheet.flatten(contentContainerStyle) || {};
+  const flattenedStyle = StyleSheet.flatten(style) || {};
+
+  const layoutStyle = useAnimatedStyle(() => {
+    const { width, height } = flattenedStyle;
+    const measuredSize = resolvedSize.value ?? 0;
+
+    const computedWidth = width ?? (vertical ? "100%" : measuredSize || "100%");
+    const computedHeight = height ?? (vertical ? measuredSize || "100%" : "100%");
+
+    return {
+      width: computedWidth,
+      height: computedHeight,
+      opacity: isSizeReady.value ? 1 : 0,
+    };
+  }, [flattenedStyle, isSizeReady, vertical, resolvedSize, sizePhase]);
+
+  return (
+    <GestureHandlerRootView testID={testID} style={[styles.layoutContainer, style]}>
+      <ScrollViewGesture
+        size={size}
+        key={mode}
+        translation={handlerOffset}
+        style={[
+          styles.contentContainer,
+          layoutStyle,
+          restContentContainerStyle,
+          vertical ? styles.itemsVertical : styles.itemsHorizontal,
+        ]}
+        testID="carousel-content-container"
+        onLayout={props.onLayout}
+        onScrollStart={scrollViewGestureOnScrollStart}
+        onScrollEnd={scrollViewGestureOnScrollEnd}
+        onTouchBegin={scrollViewGestureOnTouchBegin}
+        onTouchEnd={scrollViewGestureOnTouchEnd}
+      >
+        <ItemRenderer
+          data={data}
+          dataLength={dataLength}
+          rawDataLength={rawDataLength}
+          loop={loop}
+          size={size}
+          windowSize={windowSize}
+          autoFillData={autoFillData}
+          offsetX={offsetX}
+          handlerOffset={handlerOffset}
+          layoutConfig={layoutConfig}
+          renderItem={renderItem}
+          customAnimation={customAnimation}
+          sizeResolver={sizeResolver}
+        />
+      </ScrollViewGesture>
+    </GestureHandlerRootView>
+  );
+});
+
+const styles = StyleSheet.create({
+  layoutContainer: {
+    display: "flex",
+    overflow: "hidden",
+  },
+  contentContainer: {
+    overflow: "hidden",
+  },
+  itemsHorizontal: {
+    flexDirection: "row",
+  },
+  itemsVertical: {
+    flexDirection: "column",
+  },
+});

package/src/components/ItemLayout.tsx

@@ -0,0 +1,217 @@
+import React from "react";
+import type { LayoutChangeEvent, ViewStyle } from "react-native";
+import { StyleSheet } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import Animated, {
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+} from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+
+import type { IOpts } from "../hooks/useOffsetX";
+import { useOffsetX } from "../hooks/useOffsetX";
+import type { IVisibleRanges } from "../hooks/useVisibleRanges";
+import type { ILayoutConfig } from "../layouts/stack";
+import { useGlobalState } from "../store";
+import type { TCarouselProps } from "../types";
+import { sanitizeAnimationStyle } from "../utils/sanitize-animation-style";
+
+export type TAnimationStyle = NonNullable<TCarouselProps["customAnimation"]>;
+
+export const ItemLayout: React.FC<{
+  index: number;
+  handlerOffset: SharedValue<number>;
+  visibleRanges: IVisibleRanges;
+  animationStyle: TAnimationStyle;
+  children: (ctx: {
+    animationValue: SharedValue<number>;
+  }) => React.ReactElement;
+}> = (props) => {
+  const { handlerOffset, index, children, visibleRanges, animationStyle } = props;
+
+  const {
+    props: {
+      loop,
+      dataLength,
+      width,
+      height,
+      vertical,
+      customConfig,
+      mode,
+      modeConfig,
+      style,
+      itemWidth,
+      itemHeight,
+      variableSize,
+    },
+    common,
+    sizeResolver,
+    layout: { updateItemDimensions },
+  } = useGlobalState();
+
+  const measuredSize = useSharedValue<{ width: number | null; height: number | null }>({
+    width: null,
+    height: null,
+  });
+
+  const fallbackSize = common.size;
+  // Prefer size from `style` (v5), then fallback to deprecated `width`/`height` for v4 compatibility.
+  const { width: styleWidth, height: styleHeight } = StyleSheet.flatten(style) || {};
+  const styleWidthNumber = typeof styleWidth === "number" ? styleWidth : undefined;
+  const styleHeightNumber = typeof styleHeight === "number" ? styleHeight : undefined;
+
+  // Variable-size mode reads each item's size from the resolver up-front; the
+  // measurement plumbing below is bypassed so onLayout never overrides the
+  // user's declaration.
+  const variableItemSize = variableSize ? sizeResolver.itemSize(index) : 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);
+  // Variable mode → per-item size; uniform fallback to itemWidth/Height or container.
+  const size = (variableItemSize ?? explicitItemSize ?? explicitAxisSize ?? fallbackSize) || 0;
+  const effectivePageSize = size > 0 ? size : undefined;
+
+  const dimensionsStyle = useAnimatedStyle<ViewStyle>(() => {
+    if (variableSize) {
+      const itemPx = sizeResolver.itemSize(index);
+      const w = vertical ? (typeof width === "number" ? width : "100%") : itemPx;
+      const h = vertical ? itemPx : typeof height === "number" ? height : "100%";
+      return { width: w, height: h };
+    }
+    // When itemWidth/itemHeight is provided, use it for item width/height
+    const widthCandidate = vertical ? width : (explicitItemSize ?? explicitAxisSize);
+    const heightCandidate = vertical ? (explicitItemSize ?? explicitAxisSize) : height;
+
+    const computedWidth =
+      typeof widthCandidate === "number"
+        ? widthCandidate
+        : (measuredSize.value.width ?? (vertical ? "100%" : (effectivePageSize ?? "100%")));
+
+    const computedHeight =
+      typeof heightCandidate === "number"
+        ? heightCandidate
+        : (measuredSize.value.height ?? (vertical ? (effectivePageSize ?? "100%") : "100%"));
+
+    return {
+      width: computedWidth,
+      height: computedHeight,
+    };
+  }, [
+    vertical,
+    width,
+    height,
+    explicitAxisSize,
+    explicitItemSize,
+    effectivePageSize,
+    variableSize,
+    sizeResolver,
+    index,
+  ]);
+
+  let offsetXConfig: IOpts = {
+    handlerOffset,
+    index,
+    size,
+    dataLength,
+    loop,
+    resolver: variableSize ? sizeResolver : undefined,
+    ...(typeof customConfig === "function" ? customConfig() : {}),
+  };
+
+  if (mode === "horizontal-stack") {
+    const { snapDirection, showLength } = modeConfig as ILayoutConfig;
+
+    offsetXConfig = {
+      handlerOffset,
+      index,
+      size,
+      dataLength,
+      loop,
+      type: snapDirection === "right" ? "negative" : "positive",
+      viewCount: showLength,
+      resolver: variableSize ? sizeResolver : undefined,
+    };
+  }
+
+  const x = useOffsetX(offsetXConfig, visibleRanges);
+  const animationValue = useDerivedValue(() => {
+    // In variable mode each item normalises `x` by its own size, so the
+    // animation `value` keeps the same [-1, 0, 1] meaning every item has in
+    // uniform mode (-1 = one item-width left of center).
+    const itemSize = variableSize ? sizeResolver.itemSize(index) : size;
+    if (!itemSize) return 0;
+    return x.value / itemSize;
+  }, [x, size, variableSize, sizeResolver, index]);
+  const animatedStyle = useAnimatedStyle<ViewStyle>(() => {
+    const itemSize = variableSize ? sizeResolver.itemSize(index) : size;
+    const safeSize = itemSize || 1;
+    return sanitizeAnimationStyle(animationStyle(x.value / safeSize, index));
+  }, [animationStyle, index, x, size, variableSize, sizeResolver]);
+
+  // TODO: For dynamic dimension in the future
+  // function handleLayout(e: LayoutChangeEvent) {
+  //   const { width, height } = e.nativeEvent.layout;
+  //   updateItemDimensions(index, { width, height });
+  // }
+
+  const child = children({ animationValue });
+
+  type LayoutableProps = {
+    collapsable?: boolean;
+    onLayout?: (event: LayoutChangeEvent) => void;
+  };
+
+  const enhancedChild = React.isValidElement<LayoutableProps>(child)
+    ? variableSize
+      ? // Variable-size mode: per-item dimensions are authoritative (declared
+        // by getItemWidth/getItemHeight), so onLayout measurements must not
+        // overwrite them. Forward the user's original onLayout if any.
+        React.cloneElement(child, { collapsable: false })
+      : React.cloneElement(child, {
+          collapsable: false,
+          onLayout: (event: LayoutChangeEvent) => {
+            const { width: layoutWidth, height: layoutHeight } = event.nativeEvent.layout;
+            if (layoutWidth > 0 && layoutHeight > 0) {
+              scheduleOnUI(() => {
+                const { width: prevWidth, height: prevHeight } = measuredSize.value;
+                if (prevWidth === layoutWidth && prevHeight === layoutHeight) return;
+
+                measuredSize.value = {
+                  width: layoutWidth,
+                  height: layoutHeight,
+                };
+                updateItemDimensions(index, {
+                  width: layoutWidth,
+                  height: layoutHeight,
+                });
+              });
+            }
+
+            child.props?.onLayout?.(event);
+          },
+        })
+    : child;
+
+  return (
+    <Animated.View
+      style={[
+        {
+          position: "absolute",
+          pointerEvents: "box-none",
+        },
+        dimensionsStyle,
+        animatedStyle,
+      ]}
+      /**
+       * We use this testID to know when the carousel item is ready to be tested in test.
+       * e.g.
+       *  The testID of first item will be changed to __CAROUSEL_ITEM_0_READY__ from __CAROUSEL_ITEM_0_NOT_READY__ when the item is ready.
+       * */
+      testID={`__CAROUSEL_ITEM_${index}__`}
+    >
+      {enhancedChild}
+    </Animated.View>
+  );
+};

package/src/components/ItemRenderer.tsx

@@ -0,0 +1,114 @@
+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 { ItemLayout } from "./ItemLayout";
+
+import type { VisibleRanges } from "../hooks/useVisibleRanges";
+import { useVisibleRanges } from "../hooks/useVisibleRanges";
+import type { CarouselRenderItem } from "../types";
+import { computedRealIndexWithAutoFillData } from "../utils/computed-with-auto-fill-data";
+import type { SizeResolver } from "../utils/size-resolver";
+
+interface Props {
+  data: any[];
+  dataLength: number;
+  rawDataLength: number;
+  loop: boolean;
+  size: number;
+  windowSize?: number;
+  autoFillData: boolean;
+  offsetX: SharedValue<number>;
+  handlerOffset: SharedValue<number>;
+  layoutConfig: TAnimationStyle;
+  renderItem: CarouselRenderItem<any>;
+  customAnimation?: (value: number, index: number) => ViewStyle;
+  sizeResolver: SizeResolver;
+}
+
+export const ItemRenderer: FC<Props> = (props) => {
+  const {
+    data,
+    size,
+    windowSize,
+    handlerOffset,
+    offsetX,
+    dataLength,
+    rawDataLength,
+    loop,
+    autoFillData,
+    layoutConfig,
+    renderItem,
+    customAnimation,
+    sizeResolver,
+  } = props;
+
+  const visibleRanges = useVisibleRanges({
+    total: dataLength,
+    viewSize: size,
+    translation: handlerOffset,
+    windowSize,
+    loop,
+    resolver: sizeResolver,
+  });
+
+  // Initialize with a sensible default to avoid blank render on first frame
+  const initialRanges: VisibleRanges = React.useMemo(
+    () => ({
+      negativeRange: [0, 0],
+      positiveRange: [0, Math.min(dataLength - 1, (windowSize ?? dataLength) - 1)],
+    }),
+    [dataLength, windowSize]
+  );
+
+  const [displayedItems, setDisplayedItems] = React.useState<VisibleRanges>(initialRanges);
+
+  useAnimatedReaction(
+    () => visibleRanges.value,
+    (ranges) => scheduleOnRN(setDisplayedItems, ranges),
+    [visibleRanges]
+  );
+
+  return (
+    <>
+      {data.map((item, index) => {
+        const realIndex = computedRealIndexWithAutoFillData({
+          index,
+          dataLength: rawDataLength,
+          loop,
+          autoFillData,
+        });
+
+        const { negativeRange, positiveRange } = displayedItems;
+
+        const shouldRender =
+          (index >= negativeRange[0] && index <= negativeRange[1]) ||
+          (index >= positiveRange[0] && index <= positiveRange[1]);
+
+        if (!shouldRender) return null;
+
+        return (
+          <ItemLayout
+            key={index}
+            index={index}
+            handlerOffset={offsetX}
+            visibleRanges={visibleRanges}
+            animationStyle={customAnimation || layoutConfig}
+          >
+            {({ animationValue }) =>
+              renderItem({
+                item,
+                index: realIndex,
+                animationValue,
+              })
+            }
+          </ItemLayout>
+        );
+      })}
+    </>
+  );
+};

package/src/components/LazyView.test.tsx

@@ -0,0 +1,61 @@
+import { render } from "@testing-library/react-native";
+import React from "react";
+import { Text } from "react-native";
+
+import { LazyView } from "./LazyView";
+
+describe("LazyView", () => {
+  it("should render children when shouldUpdate is true", () => {
+    const { getByText } = render(
+      <LazyView shouldUpdate={true}>
+        <Text>Test Child</Text>
+      </LazyView>
+    );
+
+    expect(getByText("Test Child")).toBeTruthy();
+  });
+
+  it("should not render children when shouldUpdate is false", () => {
+    const { queryByText } = render(
+      <LazyView shouldUpdate={false}>
+        <Text>Test Child</Text>
+      </LazyView>
+    );
+
+    expect(queryByText("Test Child")).toBeNull();
+  });
+
+  it("should render empty fragment when shouldUpdate is false", () => {
+    const { toJSON } = render(
+      <LazyView shouldUpdate={false}>
+        <Text>Test Child</Text>
+      </LazyView>
+    );
+
+    expect(toJSON()).toBeNull();
+  });
+
+  it("should handle multiple children when shouldUpdate is true", () => {
+    const { getByText } = render(
+      <LazyView shouldUpdate={true}>
+        <Text>First Child</Text>
+        <Text>Second Child</Text>
+      </LazyView>
+    );
+
+    expect(getByText("First Child")).toBeTruthy();
+    expect(getByText("Second Child")).toBeTruthy();
+  });
+
+  it("should not render multiple children when shouldUpdate is false", () => {
+    const { queryByText } = render(
+      <LazyView shouldUpdate={false}>
+        <Text>First Child</Text>
+        <Text>Second Child</Text>
+      </LazyView>
+    );
+
+    expect(queryByText("First Child")).toBeNull();
+    expect(queryByText("Second Child")).toBeNull();
+  });
+});

package/src/components/LazyView.tsx

@@ -0,0 +1,14 @@
+import type { PropsWithChildren } from "react";
+import React from "react";
+
+interface Props {
+  shouldUpdate: boolean;
+}
+
+export const LazyView: React.FC<PropsWithChildren<Props>> = (props) => {
+  const { shouldUpdate, children } = props;
+
+  if (!shouldUpdate) return <></>;
+
+  return <>{children}</>;
+};