react-native-ultra-carousel 0.1.0

package/src/hooks/useSnapPoints.ts

@@ -0,0 +1,31 @@
+/**
+ * @file useSnapPoints hook
+ * @description Computes snap points for carousel items based on layout parameters
+ */
+
+import { useMemo } from 'react';
+import type { SnapAlignment } from '../types';
+import { calculateSnapPoints } from '../utils/layout';
+
+/**
+ * Computes an array of snap point offsets for the carousel.
+ *
+ * @param totalItems - Number of items
+ * @param itemSize - Width or height of each item
+ * @param gap - Gap between items
+ * @param containerSize - Width or height of the container
+ * @param alignment - Snap alignment mode
+ * @returns Memoized array of snap point offsets
+ */
+export const useSnapPoints = (
+  totalItems: number,
+  itemSize: number,
+  gap: number,
+  containerSize: number,
+  alignment: SnapAlignment
+): number[] => {
+  return useMemo(
+    () => calculateSnapPoints(totalItems, itemSize, gap, containerSize, alignment),
+    [totalItems, itemSize, gap, containerSize, alignment]
+  );
+};

package/src/hooks/useVirtualization.ts

@@ -0,0 +1,63 @@
+/**
+ * @file useVirtualization hook
+ * @description Computes which items should be rendered based on current scroll position
+ */
+
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+import { DEFAULT_RENDER_BUFFER } from '../utils/constants';
+
+/** Return type of the virtualization hook */
+export interface VirtualizationResult {
+  /** Indices of items that should be rendered */
+  visibleIndices: SharedValue<number[]>;
+}
+
+/**
+ * Determines which carousel items should be rendered for performance.
+ * Only items within the visible range + buffer are rendered.
+ *
+ * @param scrollOffset - Current scroll offset shared value
+ * @param totalItems - Total number of items
+ * @param itemSize - Width or height of each item
+ * @param gap - Gap between items
+ * @param containerSize - Width or height of the container
+ * @param maxRenderItems - Max items to render (0 = all)
+ * @param renderBuffer - Extra items outside viewport to render
+ * @returns Object containing the array of visible indices
+ */
+export const useVirtualization = (
+  scrollOffset: SharedValue<number>,
+  totalItems: number,
+  itemSize: number,
+  gap: number,
+  containerSize: number,
+  maxRenderItems: number = 0,
+  renderBuffer: number = DEFAULT_RENDER_BUFFER
+): VirtualizationResult => {
+  const stepSize = itemSize + gap;
+
+  const visibleIndices = useDerivedValue(() => {
+    if (maxRenderItems === 0 || totalItems <= maxRenderItems) {
+      return Array.from({ length: totalItems }, (_, i) => i);
+    }
+
+    if (stepSize === 0) {
+      return [0];
+    }
+
+    const currentIndex = Math.round(scrollOffset.value / stepSize);
+    const visibleCount = Math.ceil(containerSize / stepSize) + 1;
+    const halfVisible = Math.ceil(visibleCount / 2);
+    const start = Math.max(0, currentIndex - halfVisible - renderBuffer);
+    const end = Math.min(totalItems - 1, currentIndex + halfVisible + renderBuffer);
+
+    const indices: number[] = [];
+    for (let i = start; i <= end; i++) {
+      indices.push(i);
+    }
+
+    return indices;
+  }, [totalItems, stepSize, containerSize, maxRenderItems, renderBuffer]);
+
+  return { visibleIndices };
+};

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * @file react-native-ultra-carousel
+ * @description The Ultimate Carousel Ecosystem for React Native
+ * @author toankhontech
+ * @license MIT
+ */
+
+// === Components ===
+export { Carousel } from './components/Carousel';
+export { Pagination } from './components/Pagination';
+export { ParallaxImage } from './components/ParallaxImage';
+
+// === Hooks ===
+export { useCarousel } from './hooks/useCarousel';
+export type { UseCarouselReturn } from './hooks/useCarousel';
+export { useAnimationProgress } from './hooks/useAnimationProgress';
+export { useItemAnimation } from './hooks/useItemAnimation';
+export { useCarouselGesture } from './hooks/useCarouselGesture';
+export { useAutoPlay } from './hooks/useAutoPlay';
+export type { UseAutoPlayReturn } from './hooks/useAutoPlay';
+export { useSnapPoints } from './hooks/useSnapPoints';
+export { usePagination } from './hooks/usePagination';
+
+// === Animations ===
+export {
+  slideAnimation,
+  fadeAnimation,
+  slideFadeAnimation,
+  scaleAnimation,
+  scaleFadeAnimation,
+  verticalAnimation,
+  verticalFadeAnimation,
+  parallaxAnimation,
+  overlapAnimation,
+  peekAnimation,
+  registerPreset,
+  getPreset,
+  getPresetMeta,
+  getAllPresetNames,
+  getAllPresetMeta,
+  isPresetRegistered,
+} from './animations';
+
+// === Plugin System ===
+export { createPlugin, PluginManager } from './plugins/PluginManager';
+
+// === Types ===
+export type {
+  CarouselProps,
+  CarouselRef,
+  PresetName,
+  CarouselDirection,
+  SnapAlignment,
+  RenderItemInfo,
+  GestureConfig,
+  AutoPlayConfig,
+  AnimatedItemStyle,
+  AnimationPresetFn,
+  CustomAnimationFn,
+  AnimationPresetMeta,
+  CarouselPlugin,
+  CreatePluginOptions,
+  PaginationConfig,
+  PaginationRenderInfo,
+  PaginationType,
+  PaginationPosition,
+  BasePaginationProps,
+  GestureState,
+  PanGestureConfig,
+  SnapResult,
+} from './types';

package/src/plugins/PluginManager.ts

@@ -0,0 +1,150 @@
+/**
+ * @file Plugin manager
+ * @description Registry and lifecycle manager for carousel plugins
+ */
+
+import type { CarouselPlugin, CreatePluginOptions } from './types';
+import type { CarouselRef, AnimatedItemStyle } from '../types';
+
+/**
+ * Creates a carousel plugin with the given options.
+ *
+ * @param options - Plugin configuration including lifecycle hooks
+ * @returns A fully typed CarouselPlugin instance
+ *
+ * @example
+ * ```ts
+ * const analyticsPlugin = createPlugin({
+ *   name: 'analytics',
+ *   onIndexChange: (index) => {
+ *     analytics.track('carousel_swipe', { index });
+ *   },
+ * });
+ * ```
+ */
+export const createPlugin = (options: CreatePluginOptions): CarouselPlugin => {
+  return { ...options };
+};
+
+/**
+ * Manages a collection of plugins for a carousel instance.
+ * Handles lifecycle calls and animation composition.
+ */
+export class PluginManager {
+  private plugins: CarouselPlugin[] = [];
+  private initialized = false;
+
+  /**
+   * Creates a new PluginManager instance.
+   *
+   * @param plugins - Initial array of plugins to manage
+   */
+  constructor(plugins: CarouselPlugin[] = []) {
+    this.plugins = [...plugins];
+  }
+
+  /**
+   * Registers a new plugin.
+   *
+   * @param plugin - The plugin to add
+   */
+  register(plugin: CarouselPlugin): void {
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      console.warn(
+        `[ultra-carousel] Plugin "${plugin.name}" is already registered. Skipping.`
+      );
+      return;
+    }
+    this.plugins.push(plugin);
+  }
+
+  /**
+   * Removes a plugin by name.
+   *
+   * @param name - Name of the plugin to remove
+   */
+  unregister(name: string): void {
+    const index = this.plugins.findIndex((p) => p.name === name);
+    if (index !== -1) {
+      this.plugins[index].onDestroy?.();
+      this.plugins.splice(index, 1);
+    }
+  }
+
+  /**
+   * Initializes all registered plugins with the carousel ref.
+   *
+   * @param carousel - The carousel instance ref
+   */
+  init(carousel: CarouselRef): void {
+    if (this.initialized) return;
+    this.plugins.forEach((plugin) => {
+      plugin.onInit?.(carousel);
+    });
+    this.initialized = true;
+  }
+
+  /**
+   * Calls onAnimate on all plugins and merges returned styles.
+   * This runs on the UI thread (worklet context).
+   *
+   * @param progress - Current animation progress
+   * @param index - Current item index
+   * @returns Merged animated style from all plugins
+   */
+  animate(progress: number, index: number): AnimatedItemStyle {
+    'worklet';
+    const mergedStyle: AnimatedItemStyle = {};
+
+    for (const plugin of this.plugins) {
+      if (plugin.onAnimate) {
+        const result = plugin.onAnimate(progress, index);
+        if (result) {
+          if (result.opacity !== undefined) {
+            mergedStyle.opacity = result.opacity;
+          }
+          if (result.zIndex !== undefined) {
+            mergedStyle.zIndex = result.zIndex;
+          }
+          if (result.transform) {
+            mergedStyle.transform = [
+              ...(mergedStyle.transform ?? []),
+              ...result.transform,
+            ];
+          }
+        }
+      }
+    }
+
+    return mergedStyle;
+  }
+
+  /**
+   * Notifies all plugins of an index change.
+   *
+   * @param index - The new active index
+   */
+  notifyIndexChange(index: number): void {
+    this.plugins.forEach((plugin) => {
+      plugin.onIndexChange?.(index);
+    });
+  }
+
+  /**
+   * Destroys all plugins and cleans up.
+   */
+  destroy(): void {
+    this.plugins.forEach((plugin) => {
+      plugin.onDestroy?.();
+    });
+    this.plugins = [];
+    this.initialized = false;
+  }
+
+  /**
+   * Returns the number of registered plugins.
+   */
+  get count(): number {
+    return this.plugins.length;
+  }
+}

package/src/plugins/types.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Plugin module types
+ * @description Re-exports plugin types
+ */
+
+export type { CarouselPlugin, CreatePluginOptions } from '../types/plugin';

package/src/types/animation.ts

@@ -0,0 +1,72 @@
+/**
+ * @file Animation type definitions
+ * @description Types for animation presets, styles, and configuration
+ */
+
+/** Style object returned by animation functions */
+export interface AnimatedItemStyle {
+  transform?: Array<
+    | { translateX: number }
+    | { translateY: number }
+    | { scale: number }
+    | { scaleX: number }
+    | { scaleY: number }
+    | { rotate: string }
+    | { rotateX: string }
+    | { rotateY: string }
+    | { rotateZ: string }
+    | { skewX: string }
+    | { skewY: string }
+    | { perspective: number }
+  >;
+  opacity?: number;
+  zIndex?: number;
+  elevation?: number;
+  borderRadius?: number;
+  overflow?: 'visible' | 'hidden';
+}
+
+/**
+ * Animation preset function signature.
+ * All presets must follow this contract.
+ *
+ * @param progress - Normalized scroll progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional configuration overrides
+ * @returns Animated style to apply to the carousel item
+ */
+export type AnimationPresetFn = (
+  progress: number,
+  config?: Record<string, number>
+) => AnimatedItemStyle;
+
+/**
+ * Custom animation function signature (extended version with more context).
+ *
+ * @param progress - Normalized progress for this item
+ * @param index - Item index in the data array
+ * @param totalItems - Total number of items
+ * @param config - Optional configuration overrides
+ * @returns Animated style to apply to the carousel item
+ */
+export type CustomAnimationFn = (
+  progress: number,
+  index: number,
+  totalItems: number,
+  config?: Record<string, number>
+) => AnimatedItemStyle;
+
+/** Metadata for a registered animation preset */
+export interface AnimationPresetMeta {
+  /** Unique preset name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Difficulty level */
+  difficulty: 'Easy' | 'Medium' | 'Hard';
+  /** Phase when it was added */
+  phase: 1 | 2 | 3;
+  /** The animation function */
+  animation: AnimationPresetFn;
+  /** Default configuration values */
+  defaults: Record<string, number>;
+}

package/src/types/carousel.ts

@@ -0,0 +1,188 @@
+/**
+ * @file Core type definitions for react-native-ultra-carousel
+ * @description All public-facing types used across the carousel ecosystem
+ */
+
+import type { ViewStyle, StyleProp } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import type { PanGesture } from 'react-native-gesture-handler';
+import type { AnimatedItemStyle, CustomAnimationFn } from './animation';
+import type { CarouselPlugin } from './plugin';
+import type { PaginationConfig, PaginationRenderInfo } from './pagination';
+
+/** All available animation preset names */
+export type PresetName =
+  | 'slide'
+  | 'fade'
+  | 'slide-fade'
+  | 'scale'
+  | 'scale-fade'
+  | 'vertical'
+  | 'vertical-fade'
+  | 'parallax'
+  | 'overlap'
+  | 'peek'
+  | 'stack'
+  | 'tinder'
+  | 'coverflow'
+  | 'cube'
+  | 'flip'
+  | 'wheel'
+  | 'accordion'
+  | 'zoom'
+  | 'rotate'
+  | 'depth'
+  | 'newspaper'
+  | 'origami'
+  | 'carousel-3d'
+  | 'wave'
+  | 'spiral'
+  | 'glitch'
+  | 'morph'
+  | 'shutter'
+  | 'domino'
+  | 'elastic'
+  | 'blur-slide'
+  | 'windmill'
+  | 'film-strip'
+  | 'helix'
+  | 'gravity';
+
+/** Direction of carousel scrolling */
+export type CarouselDirection = 'horizontal' | 'vertical';
+
+/** Snap alignment within the container */
+export type SnapAlignment = 'start' | 'center' | 'end';
+
+/** Information passed to renderItem callback */
+export interface RenderItemInfo<T> {
+  /** The data item */
+  item: T;
+  /** Index in the data array */
+  index: number;
+  /** Animated progress value for this item */
+  animationProgress: SharedValue<number>;
+  /** Whether this item is currently active */
+  isActive: boolean;
+}
+
+/** Gesture configuration for fine-tuning */
+export interface GestureConfig {
+  /** Minimum horizontal distance before gesture activates (default: 10) */
+  activeOffsetX?: number | [number, number];
+  /** Minimum vertical distance before gesture activates */
+  activeOffsetY?: number | [number, number];
+  /** Velocity threshold for fling gesture (default: 500) */
+  velocityThreshold?: number;
+  /** Enable/disable fling gesture (default: true) */
+  enableFling?: boolean;
+  /** Callback to customize the pan gesture */
+  onConfigurePanGesture?: (gesture: PanGesture) => void;
+}
+
+/** Auto play configuration */
+export interface AutoPlayConfig {
+  /** Enable auto play (default: false) */
+  enabled: boolean;
+  /** Interval between slides in ms (default: 3000) */
+  interval?: number;
+  /** Pause on user interaction (default: true) */
+  pauseOnInteraction?: boolean;
+  /** Direction: forward or backward (default: 'forward') */
+  direction?: 'forward' | 'backward';
+}
+
+/** Main Carousel component props */
+export interface CarouselProps<T> {
+  /** Array of data items */
+  data: T[];
+  /** Render function for each item */
+  renderItem: (info: RenderItemInfo<T>) => React.ReactNode;
+
+  /** Animation preset name or custom animation function */
+  preset?: PresetName | CustomAnimationFn;
+  /** Animation configuration overrides for the selected preset */
+  animationConfig?: Record<string, number>;
+
+  /** Container width (default: screen width) */
+  width?: number;
+  /** Container height (default: auto) */
+  height?: number;
+  /** Individual item width (default: container width) */
+  itemWidth?: number;
+  /** Individual item height (default: container height) */
+  itemHeight?: number;
+  /** Scroll direction (default: 'horizontal') */
+  direction?: CarouselDirection;
+  /** Number of items visible at once (default: 1) */
+  visibleItems?: number;
+  /** Gap between items in pixels (default: 0) */
+  gap?: number;
+  /** Snap alignment (default: 'center') */
+  snapAlignment?: SnapAlignment;
+
+  /** Enable infinite loop (default: false) */
+  loop?: boolean;
+  /** Initial active index (default: 0) */
+  initialIndex?: number;
+  /** Enable/disable user interaction (default: true) */
+  enabled?: boolean;
+
+  /** Enable auto play (default: false) */
+  autoPlay?: boolean | AutoPlayConfig;
+  /** Auto play interval in ms (default: 3000) */
+  autoPlayInterval?: number;
+
+  /** Enable/configure pagination */
+  pagination?: boolean | PaginationConfig;
+
+  /** Gesture configuration */
+  gestureConfig?: GestureConfig;
+
+  /** Called when active index changes */
+  onIndexChange?: (index: number) => void;
+  /** Called when scroll begins */
+  onScrollStart?: () => void;
+  /** Called when scroll ends */
+  onScrollEnd?: (index: number) => void;
+  /** Shared value updated with scroll progress */
+  scrollProgress?: SharedValue<number>;
+
+  /** Array of plugins to apply */
+  plugins?: CarouselPlugin[];
+
+  /** Max items to render (virtualization). 0 = render all (default: 0) */
+  maxRenderItems?: number;
+  /** Buffer items outside visible area (default: 2) */
+  renderBuffer?: number;
+
+  /** Enable accessibility features (default: true) */
+  accessible?: boolean;
+  /** Carousel label for screen readers */
+  accessibilityLabel?: string;
+
+  /** Container style */
+  style?: StyleProp<ViewStyle>;
+  /** Item container style */
+  itemStyle?: StyleProp<ViewStyle>;
+}
+
+/** Carousel instance methods (exposed via ref) */
+export interface CarouselRef {
+  /** Scroll to specific index */
+  scrollTo: (index: number, animated?: boolean) => void;
+  /** Go to next item */
+  next: (animated?: boolean) => void;
+  /** Go to previous item */
+  prev: (animated?: boolean) => void;
+  /** Get current active index */
+  getCurrentIndex: () => number;
+  /** Start auto play */
+  startAutoPlay: () => void;
+  /** Stop auto play */
+  stopAutoPlay: () => void;
+  /** Pause auto play (resumes on next interaction) */
+  pauseAutoPlay: () => void;
+}
+
+export type { PaginationConfig, PaginationRenderInfo };

package/src/types/gesture.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Gesture type definitions
+ * @description Types for gesture handling and touch interaction
+ */
+
+/** Gesture state during a pan interaction */
+export interface GestureState {
+  /** Current translation in X axis */
+  translationX: number;
+  /** Current translation in Y axis */
+  translationY: number;
+  /** Current velocity in X axis */
+  velocityX: number;
+  /** Current velocity in Y axis */
+  velocityY: number;
+  /** Whether the gesture is currently active */
+  isActive: boolean;
+}
+
+/** Configuration for the pan gesture manager */
+export interface PanGestureConfig {
+  /** Active offset thresholds for X axis */
+  activeOffsetX: [number, number];
+  /** Active offset thresholds for Y axis */
+  activeOffsetY: [number, number];
+  /** Velocity threshold for fling detection */
+  velocityThreshold: number;
+  /** Whether the carousel scrolls horizontally */
+  isHorizontal: boolean;
+  /** Width/height of each item (for snap calculations) */
+  itemSize: number;
+  /** Whether fling gesture is enabled */
+  enableFling: boolean;
+}
+
+/** Result of snap point calculation */
+export interface SnapResult {
+  /** Target index to snap to */
+  targetIndex: number;
+  /** Target offset in pixels */
+  targetOffset: number;
+}

package/src/types/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @file Type re-exports
+ * @description Central export point for all public types
+ */
+
+export type {
+  CarouselProps,
+  CarouselRef,
+  PresetName,
+  CarouselDirection,
+  SnapAlignment,
+  RenderItemInfo,
+  GestureConfig,
+  AutoPlayConfig,
+} from './carousel';
+
+export type {
+  AnimatedItemStyle,
+  AnimationPresetFn,
+  CustomAnimationFn,
+  AnimationPresetMeta,
+} from './animation';
+
+export type {
+  GestureState,
+  PanGestureConfig,
+  SnapResult,
+} from './gesture';
+
+export type {
+  PaginationConfig,
+  PaginationRenderInfo,
+  PaginationType,
+  PaginationPosition,
+  BasePaginationProps,
+} from './pagination';
+
+export type {
+  CarouselPlugin,
+  CreatePluginOptions,
+} from './plugin';