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

package/src/public-types.ts

@@ -0,0 +1,209 @@
+import type * as React from "react";
+import type { ColorValue, LayoutChangeEvent, StyleProp, ViewStyle } from "react-native";
+import type {
+  GestureStateChangeEvent,
+  GestureType,
+  GestureUpdateEvent,
+  MouseButton,
+  PanGesture,
+  PanGestureChangeEventPayload,
+  PanGestureHandlerEventPayload,
+  PanGestureHandlerProps,
+} from "react-native-gesture-handler";
+import type { SharedValue, WithSpringConfig, WithTimingConfig } from "react-native-reanimated";
+
+type CarouselOrientation = "horizontal" | "vertical";
+type CarouselSnapMode = "page" | "nearest" | "none";
+type CarouselAutoplayDirection = "forward" | "backward";
+type CarouselExitDirection = "left" | "right";
+
+type CarouselContentContainerStyle = Omit<ViewStyle, "opacity" | "transform">;
+
+type CarouselExternalGestureRef =
+  | GestureType
+  | React.RefObject<GestureType | undefined>
+  | React.RefObject<React.ComponentType | undefined>;
+
+type CarouselPanStateEvent = GestureStateChangeEvent<PanGestureHandlerEventPayload>;
+type CarouselPanUpdateEvent = GestureUpdateEvent<PanGestureHandlerEventPayload>;
+type CarouselPanChangeEvent = GestureUpdateEvent<
+  PanGestureHandlerEventPayload & PanGestureChangeEventPayload
+>;
+
+type CarouselLayoutSelection =
+  | {
+      layout?: CarouselLayout;
+      itemAnimation?: never;
+    }
+  | {
+      layout?: never;
+      itemAnimation: CarouselItemAnimation;
+    };
+
+type InteractivePaginationProps = {
+  onPress: (index: number) => void;
+  getItemAccessibilityLabel?: (index: number, count: number) => string;
+};
+
+type DecorativePaginationProps = {
+  onPress?: never;
+  getItemAccessibilityLabel?: never;
+};
+
+type ReadonlyProgressValue = Omit<SharedValue<number>, "modify" | "set" | "value"> & {
+  readonly value: number;
+};
+
+type PaginationBaseProps = {
+  count: number;
+  progress: ReadonlyProgressValue;
+  orientation?: CarouselOrientation;
+  containerStyle?: StyleProp<Omit<ViewStyle, "direction" | "flexDirection">>;
+  dotStyle?: PaginationDotStyle;
+  activeDotStyle?: PaginationDotStyle;
+};
+
+export type CarouselProps<Item> = {
+  data: Item[];
+  renderItem: CarouselRenderItem<Item>;
+  keyExtractor?: (item: Item, index: number) => string;
+  defaultIndex?: number;
+  loop?: boolean;
+  autoplay?: boolean;
+  autoplayInterval?: number;
+  autoplayDirection?: CarouselAutoplayDirection;
+  orientation?: CarouselOrientation;
+  itemSize?: number;
+  scrollEnabled?: boolean;
+  snapMode?: CarouselSnapMode;
+  overscrollEnabled?: boolean;
+  renderWindowSize?: number;
+  animation?: CarouselAnimation;
+  progress?: SharedValue<number>;
+  onProgressChange?: CarouselProgressChangeHandler;
+  scrollOffsetValue?: SharedValue<number>;
+  style?: StyleProp<ViewStyle>;
+  contentContainerStyle?: StyleProp<CarouselContentContainerStyle>;
+  testID?: string;
+  onLayout?: (event: LayoutChangeEvent) => void;
+  onConfigurePanGesture?: (gesture: CarouselPanGesture) => void;
+  onScrollStart?: () => void;
+  onSnapToItem?: (index: number) => void;
+} & CarouselLayoutSelection;
+
+export interface CarouselRef {
+  prev(options?: CarouselStepOptions): void;
+  next(options?: CarouselStepOptions): void;
+  getCurrentIndex(): number;
+  scrollTo(options: CarouselScrollToOptions): void;
+}
+
+export type CarouselRenderItem<Item> = (info: CarouselRenderItemInfo<Item>) => React.ReactElement;
+
+export interface CarouselRenderItemInfo<Item> {
+  item: Item;
+  index: number;
+  relativeProgress: SharedValue<number>;
+}
+
+export type CarouselProgressChangeHandler = (progress: number) => void;
+
+export type CarouselLayout =
+  | {
+      type: "parallax";
+      offset?: number;
+      scale?: number;
+      adjacentScale?: number;
+    }
+  | {
+      type: "horizontal-stack";
+      visibleCount?: number;
+      exitDistance?: number;
+      spacing?: number;
+      scaleStep?: number;
+      opacityStep?: number;
+      rotation?: number;
+      exitDirection?: CarouselExitDirection;
+    }
+  | {
+      type: "vertical-stack";
+      visibleCount?: number;
+      exitDistance?: number;
+      spacing?: number;
+      scaleStep?: number;
+      opacityStep?: number;
+      rotation?: number;
+      exitDirection?: CarouselExitDirection;
+    };
+
+export type CarouselAnimation =
+  | ({ type: "timing" } & WithTimingConfig)
+  | ({ type: "spring" } & WithSpringConfig);
+
+export type CarouselItemAnimation = (relativeProgress: number, index: number) => ViewStyle;
+
+/**
+ * Supported configuration surface for Carousel's real RNGH pan gesture.
+ *
+ * Methods return this facade so chaining never exposes ownership-changing RNGH
+ * methods such as `enabled`, `runOnJS`, or `manualActivation`.
+ */
+export interface CarouselPanGesture {
+  /**
+   * Controlled view of the underlying RNGH pan gesture configuration.
+   *
+   * Exposes the web-only `touchAction` option (e.g. `"pan-y"` so a
+   * horizontal carousel nested in a vertically scrollable page keeps native
+   * vertical scrolling on mobile web) without casting away the facade.
+   * Ownership-changing options such as `enabled`, `runOnJS`, or
+   * `manualActivation` intentionally stay hidden.
+   */
+  readonly config: Pick<PanGesture["config"], "touchAction">;
+  activeOffsetX(offset: number | [start: number, end: number]): this;
+  activeOffsetY(offset: number | [start: number, end: number]): this;
+  failOffsetX(offset: number | [start: number, end: number]): this;
+  failOffsetY(offset: number | [start: number, end: number]): this;
+  minPointers(count: number): this;
+  maxPointers(count: number): this;
+  minDistance(distance: number): this;
+  minVelocity(velocity: number): this;
+  minVelocityX(velocity: number): this;
+  minVelocityY(velocity: number): this;
+  averageTouches(value: boolean): this;
+  enableTrackpadTwoFingerGesture(value: boolean): this;
+  activateAfterLongPress(duration: number): this;
+  hitSlop(value: PanGestureHandlerProps["hitSlop"]): this;
+  mouseButton(button: MouseButton): this;
+  simultaneousWithExternalGesture(...gestures: CarouselExternalGestureRef[]): this;
+  requireExternalGestureToFail(...gestures: CarouselExternalGestureRef[]): this;
+  blocksExternalGesture(...gestures: CarouselExternalGestureRef[]): this;
+  onBegin(callback: (event: CarouselPanStateEvent) => void): this;
+  onStart(callback: (event: CarouselPanStateEvent) => void): this;
+  onUpdate(callback: (event: CarouselPanUpdateEvent) => void): this;
+  onChange(callback: (event: CarouselPanChangeEvent) => void): this;
+  onEnd(callback: (event: CarouselPanStateEvent, success: boolean) => void): this;
+  onFinalize(callback: (event: CarouselPanStateEvent, success: boolean) => void): this;
+}
+
+export interface CarouselStepOptions {
+  count?: number;
+  animated?: boolean;
+}
+
+export interface CarouselScrollToOptions {
+  index: number;
+  animated?: boolean;
+}
+
+export type PaginationProps = PaginationBaseProps &
+  (InteractivePaginationProps | DecorativePaginationProps);
+
+export interface PaginationDotStyle {
+  width?: number;
+  height?: number;
+  borderRadius?: number;
+  borderWidth?: number;
+  borderColor?: ColorValue;
+  backgroundColor?: ColorValue;
+  opacity?: number;
+}

package/src/store/index.tsx

@@ -1,14 +1,14 @@
 import React from "react";
 
 import { SharedValue, useSharedValue } from "react-native-reanimated";
-import type { ICommonVariables } from "../hooks/useCommonVariables";
-import type { TInitializeCarouselProps } from "../hooks/useInitProps";
+import type { CarouselCommonVariables } from "../hooks/useCommonVariables";
+import type { InitializedCarouselProps } from "../hooks/useInitProps";
 
 type ItemDimensions = Record<number, { width: number; height: number }>;
 
-export interface IContext {
-  props: TInitializeCarouselProps<any>;
-  common: ICommonVariables;
+export interface CarouselContext {
+  props: InitializedCarouselProps<unknown>;
+  common: CarouselCommonVariables;
   layout: {
     containerSize: SharedValue<{ width: number; height: number }>;
     updateContainerSize: (dimensions: { width: number; height: number }) => void;
@@ -17,14 +17,14 @@ export interface IContext {
   };
 }
 
-export const GlobalStateContext = React.createContext<IContext>({} as IContext);
+export const GlobalStateContext = React.createContext<CarouselContext>({} as CarouselContext);
 
 export const GlobalStateProvider = ({
   children,
   value,
 }: {
   children: React.ReactNode;
-  value: Pick<IContext, "props" | "common">;
+  value: Pick<CarouselContext, "props" | "common">;
 }) => {
   const containerSize = useSharedValue<{ width: number; height: number }>({ width: 0, height: 0 });
   const itemDimensions = useSharedValue<ItemDimensions>({});

package/src/types.ts

@@ -1,324 +1,32 @@
-import type { LayoutChangeEvent, StyleProp, ViewStyle } from "react-native";
-import type { PanGesture } from "react-native-gesture-handler";
-import type { SharedValue, WithSpringConfig, WithTimingConfig } from "react-native-reanimated";
-
-import type { TParallaxModeProps } from "./layouts/parallax";
-import type { TStackModeProps } from "./layouts/stack";
-
-// biome-ignore lint/complexity/noBannedTypes: <explanation>
-export type IComputedDirectionTypes<T, VP = {}, HP = {}> =
-  | (T &
-      VP & {
-        /**
-         * Layout items vertically instead of horizontally
-         */
-        vertical: true;
-        /**
-         * Specified carousel container width.
-         * @deprecated Use `style={{ width: ... }}` instead.
-         */
-        width?: number;
-        /**
-         * Specified carousel container height.
-         * @deprecated Use `style={{ height: ... }}` instead.
-         */
-        height?: number;
-      })
-  | (T &
-      HP & {
-        /**
-         * Layout items vertically instead of horizontally
-         */
-        vertical?: false;
-        /**
-         * Specified carousel container width.
-         * @deprecated Use `style={{ width: ... }}` instead.
-         */
-        width?: number;
-        /**
-         * Specified carousel container height.
-         * @deprecated Use `style={{ height: ... }}` instead.
-         */
-        height?: number;
-      });
-
-export interface CustomConfig {
-  type?: "negative" | "positive";
-  viewCount?: number;
-}
-
-export interface WithSpringAnimation {
-  type: "spring";
-  config: WithSpringConfig;
-}
-
-export interface WithTimingAnimation {
-  type: "timing";
-  config: WithTimingConfig;
-}
-
-export type WithAnimation = WithSpringAnimation | WithTimingAnimation;
-
-export type TOnProgressChange =
-  | ((offsetProgress: number, absoluteProgress: number) => void)
-  /**
-   * When a SharedValue is provided, the carousel will write `absoluteProgress` into it.
-   */
-  | SharedValue<number>;
-
-export type TCarouselProps<T = any> = {
-  /**
-   * @test_coverage ✅ tested in Carousel.test.tsx > should handle the ref props
-   */
-  ref?: React.Ref<ICarouselInstance>;
-  /**
-   * A shared value used internally as the carousel's translation (scroll offset) state.
-   *
-   * Prefer using `scrollOffsetValue` (same behavior, clearer name). This prop remains
-   * for backwards compatibility.
-   * @test_coverage ✅ tested in Carousel.test.tsx > should render the correct progress value with the defaultScrollOffsetValue props
-   */
-  /**
-   * @deprecated Use `scrollOffsetValue` instead.
-   */
-  defaultScrollOffsetValue?: SharedValue<number>;
-  /**
-   * A shared value used internally as the carousel's translation (scroll offset) state.
-   *
-   * - If provided, the carousel will **mutate** it during gestures/animations.
-   * - This is useful when you want to observe the scroll offset outside the carousel.
-   */
-  scrollOffsetValue?: SharedValue<number>;
-  /**
-   * Carousel loop playback.
-   * @default true
-   * @test_coverage ✅ tested in Carousel.test.tsx > should swipe back to the first item when loop is true
-   */
-  loop?: boolean;
-  /**
-   * Carousel items data set.
-   * @test_coverage ✅ tested in Carousel.test.tsx > should render correctly
-   */
-  data: T[];
-  /**
-   * Auto fill data array to allow loop playback when the loop props is true.
-   * @default true
-   * @example
-   * [1] => [1, 1, 1]
-   * [1, 2] => [1, 2, 1, 2]
-   * @test_coverage ✅ tested in Carousel.test.tsx > should auto fill data array to allow loop playback when the loop props is true
-   */
-  autoFillData?: boolean;
-  /**
-   * Default index
-   * @default 0
-   * @test_coverage ✅ tested in Carousel.test.tsx > should render the correct item with the defaultIndex props
-   */
-  defaultIndex?: number;
-  /**
-   * Auto play
-   * @test_coverage ✅ tested in Carousel.test.tsx > should swipe automatically when autoPlay is true
-   */
-  autoPlay?: boolean;
-  /**
-   * Auto play
-   * @description reverse playback
-   * @test_coverage ✅ tested in Carousel.test.tsx > should swipe automatically in reverse when autoPlayReverse is true
-   */
-  autoPlayReverse?: boolean;
-  /**
-   * Auto play
-   * @description playback interval
-   */
-  autoPlayInterval?: number;
-  /**
-   * Time a scroll animation takes to finish
-   * @default 500 (ms)
-   */
-  scrollAnimationDuration?: number;
-  /**
-   * Carousel container style.
-   */
-  style?: StyleProp<ViewStyle>;
-  /**
-   * Carousel content container style.
-   */
-  contentContainerStyle?: StyleProp<ViewStyle>;
-  /**
-   * Horizontal **page size** used for snapping and animations.
-   *
-   * This is NOT the same as the container width:
-   * - **Container size** comes from `style` (recommended) / deprecated `width` / layout measurement.
-   * - **Page size** controls snap distance & animation progress per page.
-   *
-   * Use this when you want multiple items visible in a single viewport (page size < container width).
-   * If not provided, the page size falls back to the carousel container width.
-   */
-  itemWidth?: number;
-  /**
-   * Vertical **page size** used for snapping and animations.
-   *
-   * See `itemWidth` for the container-size vs page-size distinction.
-   * If not provided, the page size falls back to the carousel container height.
-   */
-  itemHeight?: number;
-
-  // Other props...
-
-  /**
-   * @deprecated Previously controlled the outer container width (v4 behaviour).
-   *               Move this value into `style`, e.g. `style={{ width: 300 }}`.
-   */
-  width?: number;
-  /**
-   * @deprecated Previously controlled the outer container height (v4 behaviour).
-   *               Move this value into `style`, e.g. `style={{ height: 200 }}`.
-   */
-  height?: number;
-  /**
-   * PanGesture config
-   * @test_coverage ✅ tested in Carousel.test.tsx > should call the onConfigurePanGesture callback
-   */
-  onConfigurePanGesture?: (panGesture: PanGesture) => void;
-  /**
-   * Determines the maximum number of items will respond to pan gesture events,
-   * windowSize={11} will active visible item plus up to 5 items above and 5 below the viewpor,
-   * Reducing this number will reduce the calculation of the animation value and may improve performance.
-   * @default 0 all items will respond to pan gesture events.
-   */
-  windowSize?: number;
-  /**
-   * When true, the scroll view stops on multiples of the scroll view's size when scrolling.
-   * @default true
-   * @test_coverage ✅ tested in Carousel.test.tsx > should swipe to the next item when pagingEnabled is true
-   */
-  pagingEnabled?: boolean;
-  /**
-   * If enabled, releasing the touch will scroll to the nearest item.
-   * valid when pagingEnabled=false
-   * @default true
-   */
-  snapEnabled?: boolean;
-  /**
-   * If enabled, items will scroll to the first placement when scrolling past the edge rather than closing to the last. (previous conditions: loop=false)
-   * @default true
-   * @test_coverage ✅ tested in Carousel.test.tsx > should respect overscrollEnabled=false and prevent scrolling beyond bounds
-   */
-  overscrollEnabled?: boolean;
-  /**
-   * If false, Carousel will not respond to any gestures.
-   * @default true
-   */
-  enabled?: boolean;
-  /**
-   * Specifies the scrolling animation effect.
-   *
-   * If provided, it takes precedence over `scrollAnimationDuration`.
-   */
-  withAnimation?: WithAnimation;
-  /**
-   * Used to locate this view in end-to-end tests.
-   */
-  testID?: string;
-  /**
-   * Maximum offset value for once scroll.
-   * Carousel cannot scroll over than this value.
-   * */
-  maxScrollDistancePerSwipe?: number;
-  /**
-   * Minimum offset value for once scroll.
-   * If the translation value is less than this value, the carousel will not scroll.
-   * */
-  minScrollDistancePerSwipe?: number;
-  /**
-   * @experimental This API will be changed in the future.
-   * If positive, the carousel will scroll to the positive direction and vice versa.
-   * @test_coverage ✅ tested in Carousel.test.tsx > should swipe to the correct direction when fixedDirection is positive
-   * */
-  fixedDirection?: "positive" | "negative";
-  /**
-   * Custom carousel config.
-   */
-  customConfig?: CustomConfig | (() => CustomConfig);
-  /**
-   * Custom animations.
-   * Must be worklet-compatible. See https://docs.swmansion.com/react-native-reanimated/docs/guides/worklets/
-   * @test_coverage ✅ tested in Carousel.test.tsx > should apply the custom animation
-   */
-  customAnimation?: (value: number, index: number) => ViewStyle;
-  /**
-   * Render carousel item.
-   * @test_coverage ✅ tested in Carousel.test.tsx > should render items correctly
-   */
-  renderItem: CarouselRenderItem<T>;
-  /**
-   * Callback fired when navigating to an item.
-   * @test_coverage ✅ tested in Carousel.test.tsx > should call the onSnapToItem callback
-   */
-  onSnapToItem?: (index: number) => void;
-  /**
-   * On scroll start
-   * @test_coverage ✅ tested in Carousel.test.tsx > should call the onScrollStart callback
-   */
-  onScrollStart?: () => void;
-  /**
-   * On scroll end
-   * @test_coverage ✅ tested in Carousel.test.tsx > should call the onScrollEnd callback
-   */
-  onScrollEnd?: (index: number) => void;
-  /**
-   * On progress change
-   * @param offsetProgress Total of offset distance (0 390 780 ...)
-   * @param absoluteProgress Convert to index (0 1 2 ...)
-   * @test_coverage ✅ tested in Carousel.test.tsx > should call the onProgressChange callback
-   *
-   * If you want to update a shared value automatically, you can use the shared value as a parameter directly.
-   */
-  onProgressChange?: TOnProgressChange;
-  onLayout?: (event: LayoutChangeEvent) => void;
-
-  // ============================== deprecated props ==============================
-  /**
-   * If enabled, releasing the touch will scroll to the nearest item.
-   * valid when pagingEnabled=false
-   * @deprecated please use snapEnabled instead
-   */
-  enableSnap?: boolean;
-} & (TParallaxModeProps | TStackModeProps);
-
-export interface ICarouselInstance {
-  /**
-   * Scroll to previous item, it takes one optional argument (count),
-   * which allows you to specify how many items to cross
-   */
-  prev: (opts?: Omit<TCarouselActionOptions, "index">) => void;
-  /**
-   * Scroll to next item, it takes one optional argument (count),
-   * which allows you to specify how many items to cross
-   */
-  next: (opts?: Omit<TCarouselActionOptions, "index">) => void;
-  /**
-   * Get current item index
-   */
-  getCurrentIndex: () => number;
-  /**
-   * Use value to scroll to a position where relative to the current position,
-   * scrollTo({count: -2}) is equivalent to prev(2), scrollTo({count: 2}) is equivalent to next(2)
-   */
-  scrollTo: (opts?: TCarouselActionOptions) => void;
-}
-
-export interface CarouselRenderItemInfo<ItemT> {
-  item: ItemT;
-  index: number;
-  animationValue: SharedValue<number>;
-}
-
-export type CarouselRenderItem<ItemT> = (info: CarouselRenderItemInfo<ItemT>) => React.ReactElement;
+import type { CarouselProps, CarouselScrollToOptions, CarouselStepOptions } from "./public-types";
+
+export type {
+  CarouselAnimation,
+  CarouselItemAnimation,
+  CarouselLayout,
+  CarouselPanGesture,
+  CarouselProgressChangeHandler,
+  CarouselProps,
+  CarouselRef,
+  CarouselRenderItem,
+  CarouselRenderItemInfo,
+  CarouselScrollToOptions,
+  CarouselStepOptions,
+  PaginationDotStyle,
+  PaginationProps,
+} from "./public-types";
+
+/**
+ * Internal command options retain a completion hook so autoplay can schedule
+ * the next dwell period after a transition settles. This is never exported
+ * from the package root.
+ */
+export type InternalCarouselStepOptions = CarouselStepOptions & {
+  onFinished?: () => void;
+};
 
-export interface TCarouselActionOptions {
-  index?: number;
-  count?: number;
-  animated?: boolean;
+export type InternalCarouselScrollToOptions = CarouselScrollToOptions & {
   onFinished?: () => void;
-}
+};
+
+export type InternalCarouselProps<Item> = CarouselProps<Item>;

package/src/utils/carousel-direction.ts

@@ -0,0 +1,39 @@
+export type CarouselDirectionSign = -1 | 1;
+
+export function getCarouselDirectionSign(options: {
+  isRTL: boolean;
+  orientation: "horizontal" | "vertical";
+}): CarouselDirectionSign {
+  "worklet";
+
+  return options.orientation === "horizontal" && options.isRTL ? -1 : 1;
+}
+
+export function toLogicalGestureValue(
+  physicalValue: number,
+  directionSign: CarouselDirectionSign
+): number {
+  "worklet";
+
+  return physicalValue * directionSign;
+}
+
+export function toPhysicalHorizontalValue(
+  logicalValue: number,
+  directionSign: CarouselDirectionSign
+): number {
+  "worklet";
+
+  return logicalValue * directionSign;
+}
+
+export function getHorizontalStackOffsetType(
+  exitDirection: "left" | "right",
+  directionSign: CarouselDirectionSign
+): "positive" | "negative" {
+  "worklet";
+
+  const ltrType = exitDirection === "right" ? "negative" : "positive";
+  if (directionSign === 1) return ltrType;
+  return ltrType === "positive" ? "negative" : "positive";
+}