react-native-ultra-carousel 0.1.0

package/src/gestures/PanGestureManager.ts

@@ -0,0 +1,202 @@
+/**
+ * @file Pan gesture manager
+ * @description Handles pan gesture configuration and snap calculations for the carousel
+ */
+
+import { Gesture } from 'react-native-gesture-handler';
+import {
+  useSharedValue,
+  withSpring,
+  runOnJS,
+} from 'react-native-reanimated';
+import { useCallback, useMemo } from 'react';
+import { DEFAULT_SPRING_CONFIG, DEFAULT_VELOCITY_THRESHOLD } from '../utils/constants';
+import { clamp } from '../utils/math';
+import { findNearestSnapIndex } from '../utils/layout';
+
+/** Configuration for the pan gesture hook */
+export interface PanGestureOptions {
+  /** Total number of items */
+  totalItems: number;
+  /** Size of each item (width or height depending on direction) */
+  itemSize: number;
+  /** Gap between items */
+  gap: number;
+  /** All snap point offsets */
+  snapPoints: number[];
+  /** Whether carousel is horizontal */
+  isHorizontal: boolean;
+  /** Whether loop mode is enabled */
+  loop: boolean;
+  /** Whether gesture is enabled */
+  enabled: boolean;
+  /** Active offset X threshold */
+  activeOffsetX: [number, number];
+  /** Active offset Y threshold */
+  activeOffsetY: [number, number];
+  /** Velocity threshold for fling */
+  velocityThreshold: number;
+  /** Callback when index changes */
+  onIndexChange?: (index: number) => void;
+  /** Callback when scroll starts */
+  onScrollStart?: () => void;
+  /** Callback when scroll ends */
+  onScrollEnd?: (index: number) => void;
+  /** Custom gesture configuration callback */
+  onConfigurePanGesture?: (gesture: ReturnType<typeof Gesture.Pan>) => void;
+}
+
+/**
+ * Creates and manages the pan gesture for carousel navigation.
+ *
+ * @param options - Configuration for the gesture
+ * @returns Object containing the gesture, shared values, and control methods
+ */
+export const usePanGesture = (options: PanGestureOptions) => {
+  const {
+    totalItems,
+    itemSize,
+    gap,
+    snapPoints,
+    isHorizontal,
+    loop,
+    enabled,
+    activeOffsetX,
+    activeOffsetY,
+    velocityThreshold,
+    onIndexChange,
+    onScrollStart,
+    onScrollEnd,
+    onConfigurePanGesture,
+  } = options;
+
+  const offset = useSharedValue(0);
+  const activeIndex = useSharedValue(0);
+  const isGestureActive = useSharedValue(false);
+
+  const stepSize = itemSize + gap;
+  const maxOffset = (totalItems - 1) * stepSize;
+
+  const handleIndexChange = useCallback(
+    (index: number) => {
+      onIndexChange?.(index);
+    },
+    [onIndexChange]
+  );
+
+  const handleScrollStart = useCallback(() => {
+    onScrollStart?.();
+  }, [onScrollStart]);
+
+  const handleScrollEnd = useCallback(
+    (index: number) => {
+      onScrollEnd?.(index);
+    },
+    [onScrollEnd]
+  );
+
+  const snapToIndex = useCallback(
+    (index: number, animated = true) => {
+      const targetIndex = loop
+        ? index
+        : clamp(index, 0, totalItems - 1);
+      const targetOffset = snapPoints[targetIndex] ?? targetIndex * stepSize;
+
+      if (animated) {
+        offset.value = withSpring(targetOffset, DEFAULT_SPRING_CONFIG);
+      } else {
+        offset.value = targetOffset;
+      }
+
+      if (activeIndex.value !== targetIndex) {
+        activeIndex.value = targetIndex;
+        runOnJS(handleIndexChange)(targetIndex);
+      }
+    },
+    [loop, totalItems, snapPoints, stepSize, offset, activeIndex, handleIndexChange]
+  );
+
+  const gesture = useMemo(() => {
+    const pan = Gesture.Pan()
+      .activeOffsetX(activeOffsetX)
+      .activeOffsetY(activeOffsetY)
+      .enabled(enabled)
+      .onStart(() => {
+        isGestureActive.value = true;
+        runOnJS(handleScrollStart)();
+      })
+      .onUpdate((event) => {
+        const translation = isHorizontal
+          ? event.translationX
+          : event.translationY;
+        const startOffset = activeIndex.value * stepSize;
+        let newOffset = startOffset - translation;
+
+        if (!loop) {
+          newOffset = clamp(newOffset, 0, maxOffset);
+        }
+
+        offset.value = newOffset;
+      })
+      .onEnd((event) => {
+        isGestureActive.value = false;
+
+        const velocity = isHorizontal ? event.velocityX : event.velocityY;
+        const isFling = Math.abs(velocity) > velocityThreshold;
+
+        let targetIndex: number;
+
+        if (isFling) {
+          targetIndex = velocity < 0
+            ? activeIndex.value + 1
+            : activeIndex.value - 1;
+        } else {
+          targetIndex = findNearestSnapIndex(offset.value, snapPoints);
+        }
+
+        if (!loop) {
+          targetIndex = clamp(targetIndex, 0, totalItems - 1);
+        }
+
+        const targetOffset = snapPoints[targetIndex] ?? targetIndex * stepSize;
+
+        offset.value = withSpring(targetOffset, DEFAULT_SPRING_CONFIG);
+
+        if (activeIndex.value !== targetIndex) {
+          activeIndex.value = targetIndex;
+          runOnJS(handleIndexChange)(targetIndex);
+        }
+        runOnJS(handleScrollEnd)(targetIndex);
+      });
+
+    onConfigurePanGesture?.(pan);
+
+    return pan;
+  }, [
+    activeOffsetX,
+    activeOffsetY,
+    enabled,
+    isHorizontal,
+    loop,
+    maxOffset,
+    stepSize,
+    totalItems,
+    snapPoints,
+    velocityThreshold,
+    offset,
+    activeIndex,
+    isGestureActive,
+    handleIndexChange,
+    handleScrollStart,
+    handleScrollEnd,
+    onConfigurePanGesture,
+  ]);
+
+  return {
+    gesture,
+    offset,
+    activeIndex,
+    isGestureActive,
+    snapToIndex,
+  };
+};

package/src/gestures/ScrollViewCompat.ts

@@ -0,0 +1,28 @@
+/**
+ * @file ScrollView compatibility manager
+ * @description Resolves gesture conflicts between carousel and parent ScrollView
+ */
+
+import { Gesture } from 'react-native-gesture-handler';
+
+/**
+ * Configures a pan gesture for compatibility with a parent ScrollView.
+ * Sets appropriate active offsets so horizontal swipes activate the carousel
+ * while vertical swipes pass through to the ScrollView.
+ *
+ * @param panGesture - The pan gesture to configure
+ * @param isHorizontal - Whether the carousel scrolls horizontally
+ * @returns The configured gesture
+ */
+export const configureScrollViewCompat = (
+  panGesture: ReturnType<typeof Gesture.Pan>,
+  isHorizontal: boolean
+) => {
+  if (isHorizontal) {
+    panGesture.activeOffsetX([-10, 10]).activeOffsetY([-50, 50]);
+  } else {
+    panGesture.activeOffsetY([-10, 10]).activeOffsetX([-50, 50]);
+  }
+
+  return panGesture;
+};

package/src/gestures/types.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Gesture module types
+ * @description Internal types for gesture handling
+ */
+
+export type { GestureState, PanGestureConfig, SnapResult } from '../types/gesture';

package/src/hooks/useAnimationProgress.ts

@@ -0,0 +1,33 @@
+/**
+ * @file useAnimationProgress hook
+ * @description Computes normalized animation progress for each carousel item
+ */
+
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+
+/**
+ * Computes the normalized animation progress for a specific item.
+ * Progress of 0 means the item is fully active/centered.
+ * Progress of -1 means the item is one position to the left (prev).
+ * Progress of +1 means the item is one position to the right (next).
+ *
+ * @param index - The item index
+ * @param scrollOffset - The current scroll offset shared value
+ * @param itemSize - Width or height of each item
+ * @param gap - Gap between items
+ * @returns Shared value containing the normalized progress
+ */
+export const useAnimationProgress = (
+  index: number,
+  scrollOffset: SharedValue<number>,
+  itemSize: number,
+  gap: number
+): SharedValue<number> => {
+  const stepSize = itemSize + gap;
+
+  return useDerivedValue(() => {
+    if (stepSize === 0) return 0;
+    const itemOffset = index * stepSize;
+    return (scrollOffset.value - itemOffset) / stepSize;
+  }, [index, stepSize]);
+};

package/src/hooks/useAutoPlay.ts

@@ -0,0 +1,115 @@
+/**
+ * @file useAutoPlay hook
+ * @description Manages automatic slide advancement with pause/resume controls
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { AutoPlayConfig } from '../types';
+import { DEFAULT_AUTO_PLAY_INTERVAL } from '../utils/constants';
+
+/** Return type of the useAutoPlay hook */
+export interface UseAutoPlayReturn {
+  /** Whether auto play is currently running */
+  isPlaying: boolean;
+  /** Start auto play */
+  start: () => void;
+  /** Stop auto play permanently until start is called */
+  stop: () => void;
+  /** Pause temporarily (e.g., during user interaction) */
+  pause: () => void;
+  /** Resume after a pause */
+  resume: () => void;
+  /** Notify the hook that user interacted (resets pause timer) */
+  onInteraction: () => void;
+}
+
+/**
+ * Manages automatic carousel advancement.
+ *
+ * @param config - Auto play configuration
+ * @param onAdvance - Callback to advance to the next or previous item
+ * @returns Auto play control methods and state
+ */
+export const useAutoPlay = (
+  config: AutoPlayConfig | boolean | undefined,
+  onAdvance: (direction: 'forward' | 'backward') => void
+): UseAutoPlayReturn => {
+  const normalizedConfig: AutoPlayConfig = typeof config === 'boolean'
+    ? { enabled: config }
+    : config ?? { enabled: false };
+
+  const {
+    enabled,
+    interval = DEFAULT_AUTO_PLAY_INTERVAL,
+    pauseOnInteraction = true,
+    direction = 'forward',
+  } = normalizedConfig;
+
+  const [isPlaying, setIsPlaying] = useState(enabled);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const isPausedRef = useRef(false);
+
+  const clearTimer = useCallback(() => {
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+  }, []);
+
+  const startTimer = useCallback(() => {
+    clearTimer();
+    intervalRef.current = setInterval(() => {
+      if (!isPausedRef.current) {
+        onAdvance(direction);
+      }
+    }, interval);
+  }, [clearTimer, interval, direction, onAdvance]);
+
+  const start = useCallback(() => {
+    setIsPlaying(true);
+    isPausedRef.current = false;
+    startTimer();
+  }, [startTimer]);
+
+  const stop = useCallback(() => {
+    setIsPlaying(false);
+    isPausedRef.current = false;
+    clearTimer();
+  }, [clearTimer]);
+
+  const pause = useCallback(() => {
+    isPausedRef.current = true;
+  }, []);
+
+  const resume = useCallback(() => {
+    isPausedRef.current = false;
+  }, []);
+
+  const onInteraction = useCallback(() => {
+    if (pauseOnInteraction && isPlaying) {
+      pause();
+      setTimeout(() => {
+        resume();
+      }, interval);
+    }
+  }, [pauseOnInteraction, isPlaying, pause, resume, interval]);
+
+  useEffect(() => {
+    if (enabled) {
+      start();
+    } else {
+      stop();
+    }
+
+    return clearTimer;
+  }, [enabled, start, stop, clearTimer]);
+
+  return {
+    isPlaying,
+    start,
+    stop,
+    pause,
+    resume,
+    onInteraction,
+  };
+};

package/src/hooks/useCarousel.ts

@@ -0,0 +1,118 @@
+/**
+ * @file useCarousel hook
+ * @description Main hook for external carousel control and state management
+ */
+
+import { useCallback, useRef, useState } from 'react';
+import type { CarouselRef } from '../types';
+
+/** Return type of the useCarousel hook */
+export interface UseCarouselReturn {
+  /** Ref to attach to the Carousel component */
+  ref: React.RefObject<CarouselRef>;
+  /** Current active index (reactive) */
+  activeIndex: number;
+  /** Total number of items (set when carousel mounts) */
+  totalItems: number;
+  /** Scroll to a specific index */
+  scrollTo: (index: number, animated?: boolean) => void;
+  /** Go to next item */
+  next: (animated?: boolean) => void;
+  /** Go to previous item */
+  prev: (animated?: boolean) => void;
+  /** Whether carousel is currently animating */
+  isAnimating: boolean;
+  /** Auto play controls */
+  autoPlay: {
+    start: () => void;
+    stop: () => void;
+    pause: () => void;
+    isPlaying: boolean;
+  };
+  /** Internal: callback for carousel to report index changes */
+  _onIndexChange: (index: number) => void;
+  /** Internal: callback for carousel to report total items */
+  _setTotalItems: (count: number) => void;
+}
+
+/**
+ * External hook for controlling and observing a Carousel component.
+ * Attach the returned ref to a Carousel component for full control.
+ *
+ * @returns Carousel control interface
+ *
+ * @example
+ * ```tsx
+ * const carousel = useCarousel();
+ *
+ * <Carousel ref={carousel.ref} data={data} renderItem={renderItem} />
+ * <Button onPress={carousel.next} title="Next" />
+ * <Text>{carousel.activeIndex + 1} / {carousel.totalItems}</Text>
+ * ```
+ */
+export const useCarousel = (): UseCarouselReturn => {
+  const ref = useRef<CarouselRef>(null);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [totalItems, setTotalItems] = useState(0);
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [isPlaying, setIsPlaying] = useState(false);
+
+  const scrollTo = useCallback((index: number, animated = true) => {
+    setIsAnimating(true);
+    ref.current?.scrollTo(index, animated);
+    setTimeout(() => setIsAnimating(false), 300);
+  }, []);
+
+  const next = useCallback((animated = true) => {
+    setIsAnimating(true);
+    ref.current?.next(animated);
+    setTimeout(() => setIsAnimating(false), 300);
+  }, []);
+
+  const prev = useCallback((animated = true) => {
+    setIsAnimating(true);
+    ref.current?.prev(animated);
+    setTimeout(() => setIsAnimating(false), 300);
+  }, []);
+
+  const startAutoPlay = useCallback(() => {
+    ref.current?.startAutoPlay();
+    setIsPlaying(true);
+  }, []);
+
+  const stopAutoPlay = useCallback(() => {
+    ref.current?.stopAutoPlay();
+    setIsPlaying(false);
+  }, []);
+
+  const pauseAutoPlay = useCallback(() => {
+    ref.current?.pauseAutoPlay();
+    setIsPlaying(false);
+  }, []);
+
+  const _onIndexChange = useCallback((index: number) => {
+    setActiveIndex(index);
+  }, []);
+
+  const _setTotalItems = useCallback((count: number) => {
+    setTotalItems(count);
+  }, []);
+
+  return {
+    ref,
+    activeIndex,
+    totalItems,
+    scrollTo,
+    next,
+    prev,
+    isAnimating,
+    autoPlay: {
+      start: startAutoPlay,
+      stop: stopAutoPlay,
+      pause: pauseAutoPlay,
+      isPlaying,
+    },
+    _onIndexChange,
+    _setTotalItems,
+  };
+};

package/src/hooks/useCarouselGesture.ts

@@ -0,0 +1,109 @@
+/**
+ * @file useCarouselGesture hook
+ * @description Orchestrates gesture handling for the carousel component
+ */
+
+import { useMemo } from 'react';
+import type { GestureConfig, CarouselDirection } from '../types';
+import { usePanGesture, type PanGestureOptions } from '../gestures/PanGestureManager';
+import {
+  DEFAULT_ACTIVE_OFFSET_X,
+  DEFAULT_ACTIVE_OFFSET_Y,
+  DEFAULT_VELOCITY_THRESHOLD,
+} from '../utils/constants';
+
+/** Options for the carousel gesture hook */
+export interface UseCarouselGestureOptions {
+  /** Total items in the carousel */
+  totalItems: number;
+  /** Size of each item */
+  itemSize: number;
+  /** Gap between items */
+  gap: number;
+  /** Snap points array */
+  snapPoints: number[];
+  /** Scroll direction */
+  direction: CarouselDirection;
+  /** Whether loop is enabled */
+  loop: boolean;
+  /** Whether interactions are enabled */
+  enabled: boolean;
+  /** Custom gesture config */
+  gestureConfig?: GestureConfig;
+  /** Index change callback */
+  onIndexChange?: (index: number) => void;
+  /** Scroll start callback */
+  onScrollStart?: () => void;
+  /** Scroll end callback */
+  onScrollEnd?: (index: number) => void;
+}
+
+/**
+ * Sets up gesture handling for the carousel.
+ * Bridges user-facing gesture config with the internal PanGestureManager.
+ *
+ * @param options - Gesture configuration options
+ * @returns Gesture, shared values, and snap control
+ */
+export const useCarouselGesture = (options: UseCarouselGestureOptions) => {
+  const {
+    totalItems,
+    itemSize,
+    gap,
+    snapPoints,
+    direction,
+    loop,
+    enabled,
+    gestureConfig,
+    onIndexChange,
+    onScrollStart,
+    onScrollEnd,
+  } = options;
+
+  const isHorizontal = direction === 'horizontal';
+
+  const panOptions: PanGestureOptions = useMemo(() => {
+    const activeOffsetX = gestureConfig?.activeOffsetX
+      ? (Array.isArray(gestureConfig.activeOffsetX)
+          ? gestureConfig.activeOffsetX
+          : [-gestureConfig.activeOffsetX, gestureConfig.activeOffsetX]) as [number, number]
+      : (isHorizontal ? DEFAULT_ACTIVE_OFFSET_X : DEFAULT_ACTIVE_OFFSET_Y);
+
+    const activeOffsetY = gestureConfig?.activeOffsetY
+      ? (Array.isArray(gestureConfig.activeOffsetY)
+          ? gestureConfig.activeOffsetY
+          : [-gestureConfig.activeOffsetY, gestureConfig.activeOffsetY]) as [number, number]
+      : (isHorizontal ? DEFAULT_ACTIVE_OFFSET_Y : DEFAULT_ACTIVE_OFFSET_X);
+
+    return {
+      totalItems,
+      itemSize,
+      gap,
+      snapPoints,
+      isHorizontal,
+      loop,
+      enabled,
+      activeOffsetX,
+      activeOffsetY,
+      velocityThreshold: gestureConfig?.velocityThreshold ?? DEFAULT_VELOCITY_THRESHOLD,
+      onIndexChange,
+      onScrollStart,
+      onScrollEnd,
+      onConfigurePanGesture: gestureConfig?.onConfigurePanGesture,
+    };
+  }, [
+    totalItems,
+    itemSize,
+    gap,
+    snapPoints,
+    isHorizontal,
+    loop,
+    enabled,
+    gestureConfig,
+    onIndexChange,
+    onScrollStart,
+    onScrollEnd,
+  ]);
+
+  return usePanGesture(panOptions);
+};

package/src/hooks/useItemAnimation.ts

@@ -0,0 +1,44 @@
+/**
+ * @file useItemAnimation hook
+ * @description Applies animation preset to a carousel item based on scroll progress
+ */
+
+import { useAnimatedStyle, type SharedValue } from 'react-native-reanimated';
+import type { AnimationPresetFn, CustomAnimationFn } from '../types';
+import { getPreset } from '../animations/registry';
+
+/**
+ * Applies an animation preset to a carousel item.
+ * Returns an animated style that can be applied to an Animated.View.
+ *
+ * @param progress - Shared value with normalized animation progress
+ * @param preset - Preset name string or custom animation function
+ * @param animationConfig - Optional config overrides for the preset
+ * @param index - Item index (for custom animation functions)
+ * @param totalItems - Total number of items (for custom animation functions)
+ * @returns Animated style for the item
+ */
+export const useItemAnimation = (
+  progress: SharedValue<number>,
+  preset: string | CustomAnimationFn | undefined,
+  animationConfig?: Record<string, number>,
+  index: number = 0,
+  totalItems: number = 0
+) => {
+  return useAnimatedStyle(() => {
+    if (!preset) {
+      return {};
+    }
+
+    if (typeof preset === 'function') {
+      return preset(progress.value, index, totalItems, animationConfig) as Record<string, unknown>;
+    }
+
+    const animFn = getPreset(preset) as AnimationPresetFn | undefined;
+    if (!animFn) {
+      return {};
+    }
+
+    return animFn(progress.value, animationConfig) as Record<string, unknown>;
+  }, [preset, animationConfig, index, totalItems]);
+};

package/src/hooks/usePagination.ts

@@ -0,0 +1,39 @@
+/**
+ * @file usePagination hook
+ * @description Manages pagination state derived from scroll progress
+ */
+
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+
+/** Return type of the pagination hook */
+export interface UsePaginationReturn {
+  /** Current page index as a shared value (for UI thread usage) */
+  currentPage: SharedValue<number>;
+}
+
+/**
+ * Derives the current page index from scroll offset.
+ * Runs on the UI thread for smooth pagination indicator updates.
+ *
+ * @param scrollOffset - Current scroll offset shared value
+ * @param itemSize - Width or height of each item
+ * @param gap - Gap between items
+ * @param totalItems - Total number of items
+ * @returns Current page as shared value
+ */
+export const usePagination = (
+  scrollOffset: SharedValue<number>,
+  itemSize: number,
+  gap: number,
+  totalItems: number
+): UsePaginationReturn => {
+  const stepSize = itemSize + gap;
+
+  const currentPage = useDerivedValue(() => {
+    if (stepSize === 0 || totalItems === 0) return 0;
+    const page = Math.round(scrollOffset.value / stepSize);
+    return Math.max(0, Math.min(page, totalItems - 1));
+  }, [stepSize, totalItems]);
+
+  return { currentPage };
+};