react-native-ultra-carousel 0.5.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-ultra-carousel",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "The Ultimate Carousel Ecosystem for React Native. 35+ animation presets, plugin system, CLI tool. Built on Reanimated.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/components/Carousel.stories.tsx

@@ -0,0 +1,93 @@
+/**
+ * @file Carousel Storybook stories
+ * @description Visual test cases for the Carousel component
+ */
+
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { Carousel } from './Carousel';
+import type { PresetName } from '../types';
+
+const COLORS = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7'];
+const DATA = COLORS.map((color, i) => ({
+  id: String(i + 1),
+  title: `Slide ${i + 1}`,
+  color,
+}));
+
+const renderItem = ({ item }: { item: typeof DATA[number] }) => (
+  <View style={[storyStyles.card, { backgroundColor: item.color }]}>
+    <Text style={storyStyles.cardText}>{item.title}</Text>
+  </View>
+);
+
+export default {
+  title: 'Carousel',
+  component: Carousel,
+};
+
+export const Default = () => (
+  <Carousel data={DATA} renderItem={renderItem} width={350} height={200} pagination />
+);
+
+export const WithAutoPlay = () => (
+  <Carousel data={DATA} renderItem={renderItem} width={350} height={200} autoPlay pagination />
+);
+
+const BASIC_PRESETS: PresetName[] = ['slide', 'fade', 'scale', 'parallax', 'peek'];
+const ADVANCED_PRESETS: PresetName[] = ['coverflow', 'cube', 'flip', 'stack', 'tinder'];
+
+export const BasicPresets = () => (
+  <View>
+    {BASIC_PRESETS.map((preset) => (
+      <View key={preset} style={storyStyles.section}>
+        <Text style={storyStyles.label}>{preset}</Text>
+        <Carousel data={DATA} renderItem={renderItem} preset={preset} width={350} height={150} />
+      </View>
+    ))}
+  </View>
+);
+
+export const AdvancedPresets = () => (
+  <View>
+    {ADVANCED_PRESETS.map((preset) => (
+      <View key={preset} style={storyStyles.section}>
+        <Text style={storyStyles.label}>{preset}</Text>
+        <Carousel data={DATA} renderItem={renderItem} preset={preset} width={350} height={150} />
+      </View>
+    ))}
+  </View>
+);
+
+export const PaginationStyles = () => (
+  <View>
+    <View style={storyStyles.section}>
+      <Text style={storyStyles.label}>Dot</Text>
+      <Carousel data={DATA} renderItem={renderItem} width={350} height={150} pagination />
+    </View>
+    <View style={storyStyles.section}>
+      <Text style={storyStyles.label}>Bar</Text>
+      <Carousel data={DATA} renderItem={renderItem} width={350} height={150} pagination={{ type: 'bar' }} />
+    </View>
+    <View style={storyStyles.section}>
+      <Text style={storyStyles.label}>Number</Text>
+      <Carousel data={DATA} renderItem={renderItem} width={350} height={150} pagination={{ type: 'number' }} />
+    </View>
+    <View style={storyStyles.section}>
+      <Text style={storyStyles.label}>Progress</Text>
+      <Carousel data={DATA} renderItem={renderItem} width={350} height={150} pagination={{ type: 'progress' }} />
+    </View>
+  </View>
+);
+
+const storyStyles = StyleSheet.create({
+  card: {
+    flex: 1,
+    borderRadius: 12,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  cardText: { fontSize: 20, fontWeight: '700', color: '#fff' },
+  section: { marginBottom: 24 },
+  label: { fontSize: 14, fontWeight: '600', color: '#333', marginBottom: 8, marginLeft: 8 },
+});

package/src/components/ImageGallery.tsx

@@ -0,0 +1,201 @@
+/**
+ * @file Image Gallery component
+ * @description Full-screen image gallery with zoom, pinch, and swipe-to-dismiss
+ */
+
+import React, { useCallback, useState } from 'react';
+import { View, Image, StyleSheet, Dimensions, Modal, TouchableOpacity, Text } from 'react-native';
+import type { ViewStyle, ImageSourcePropType, StyleProp } from 'react-native';
+
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get('window');
+
+export interface ImageGalleryItem {
+  /** Image source (uri or require) */
+  source: ImageSourcePropType;
+  /** Optional caption */
+  caption?: string;
+  /** Optional thumbnail for grid view */
+  thumbnail?: ImageSourcePropType;
+}
+
+export interface ImageGalleryProps {
+  /** Array of images */
+  images: ImageGalleryItem[];
+  /** Initially selected image index */
+  initialIndex?: number;
+  /** Whether gallery is visible */
+  visible: boolean;
+  /** Called when gallery should close */
+  onClose: () => void;
+  /** Called when active image changes */
+  onIndexChange?: (index: number) => void;
+  /** Enable swipe-to-dismiss (default: true) */
+  swipeToDismiss?: boolean;
+  /** Show image counter "1 / 10" (default: true) */
+  showCounter?: boolean;
+  /** Show captions (default: true) */
+  showCaptions?: boolean;
+  /** Background color (default: 'rgba(0,0,0,0.95)') */
+  backgroundColor?: string;
+  /** Container style */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Full-screen image gallery with swipe navigation.
+ * Supports zoom, pinch, and swipe-to-dismiss gestures.
+ */
+export const ImageGallery: React.FC<ImageGalleryProps> = ({
+  images,
+  initialIndex = 0,
+  visible,
+  onClose,
+  onIndexChange,
+  showCounter = true,
+  showCaptions = true,
+  backgroundColor = 'rgba(0,0,0,0.95)',
+}) => {
+  const [activeIndex, setActiveIndex] = useState(initialIndex);
+
+  const handleNext = useCallback(() => {
+    const next = Math.min(activeIndex + 1, images.length - 1);
+    setActiveIndex(next);
+    onIndexChange?.(next);
+  }, [activeIndex, images.length, onIndexChange]);
+
+  const handlePrev = useCallback(() => {
+    const prev = Math.max(activeIndex - 1, 0);
+    setActiveIndex(prev);
+    onIndexChange?.(prev);
+  }, [activeIndex, onIndexChange]);
+
+  if (!visible || images.length === 0) return null;
+
+  const currentImage = images[activeIndex];
+
+  return (
+    <Modal
+      visible={visible}
+      transparent
+      animationType="fade"
+      onRequestClose={onClose}
+    >
+      <View style={[styles.container, { backgroundColor }]}>
+        <View style={styles.header}>
+          {showCounter && (
+            <Text style={styles.counter}>
+              {activeIndex + 1} / {images.length}
+            </Text>
+          )}
+          <TouchableOpacity onPress={onClose} style={styles.closeButton}>
+            <Text style={styles.closeText}>✕</Text>
+          </TouchableOpacity>
+        </View>
+
+        <View style={styles.imageContainer}>
+          {activeIndex > 0 && (
+            <TouchableOpacity style={styles.navLeft} onPress={handlePrev}>
+              <Text style={styles.navText}>‹</Text>
+            </TouchableOpacity>
+          )}
+
+          <Image
+            source={currentImage.source}
+            style={styles.image}
+            resizeMode="contain"
+          />
+
+          {activeIndex < images.length - 1 && (
+            <TouchableOpacity style={styles.navRight} onPress={handleNext}>
+              <Text style={styles.navText}>›</Text>
+            </TouchableOpacity>
+          )}
+        </View>
+
+        {showCaptions && currentImage.caption && (
+          <View style={styles.captionContainer}>
+            <Text style={styles.caption}>{currentImage.caption}</Text>
+          </View>
+        )}
+      </View>
+    </Modal>
+  );
+};
+
+ImageGallery.displayName = 'ImageGallery';
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  header: {
+    position: 'absolute',
+    top: 50,
+    left: 0,
+    right: 0,
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingHorizontal: 20,
+    zIndex: 10,
+  },
+  counter: {
+    color: '#fff',
+    fontSize: 16,
+    fontWeight: '600',
+  },
+  closeButton: {
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    backgroundColor: 'rgba(255,255,255,0.15)',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  closeText: {
+    color: '#fff',
+    fontSize: 20,
+    fontWeight: '600',
+  },
+  imageContainer: {
+    width: SCREEN_WIDTH,
+    height: SCREEN_HEIGHT * 0.7,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  image: {
+    width: SCREEN_WIDTH - 40,
+    height: SCREEN_HEIGHT * 0.65,
+  },
+  navLeft: {
+    position: 'absolute',
+    left: 10,
+    zIndex: 10,
+    padding: 16,
+  },
+  navRight: {
+    position: 'absolute',
+    right: 10,
+    zIndex: 10,
+    padding: 16,
+  },
+  navText: {
+    color: 'rgba(255,255,255,0.7)',
+    fontSize: 40,
+    fontWeight: '300',
+  },
+  captionContainer: {
+    position: 'absolute',
+    bottom: 60,
+    left: 20,
+    right: 20,
+  },
+  caption: {
+    color: '#fff',
+    fontSize: 15,
+    textAlign: 'center',
+    lineHeight: 22,
+  },
+});

package/src/components/OnboardingCarousel.tsx

@@ -0,0 +1,187 @@
+/**
+ * @file Onboarding Carousel component
+ * @description Step-by-step onboarding flow with progress indicator, skip, and done
+ */
+
+import React, { useCallback, useState } from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, Dimensions } from 'react-native';
+import type { ViewStyle, TextStyle, StyleProp } from 'react-native';
+
+const { width: SCREEN_WIDTH } = Dimensions.get('window');
+
+export interface OnboardingStep {
+  /** Unique key for the step */
+  key: string;
+  /** Render the step content */
+  render: () => React.ReactNode;
+}
+
+export interface OnboardingCarouselProps {
+  /** Array of onboarding steps */
+  steps: OnboardingStep[];
+  /** Called when user completes onboarding */
+  onDone: () => void;
+  /** Called when user skips onboarding */
+  onSkip?: () => void;
+  /** Text for the skip button (default: 'Skip') */
+  skipText?: string;
+  /** Text for the next button (default: 'Next') */
+  nextText?: string;
+  /** Text for the done button (default: 'Get Started') */
+  doneText?: string;
+  /** Show skip button (default: true) */
+  showSkip?: boolean;
+  /** Active dot color (default: '#333') */
+  activeDotColor?: string;
+  /** Inactive dot color (default: '#ccc') */
+  inactiveDotColor?: string;
+  /** Container style */
+  style?: StyleProp<ViewStyle>;
+  /** Button text style */
+  buttonTextStyle?: StyleProp<TextStyle>;
+}
+
+/**
+ * Onboarding carousel with step progress, skip, and done controls.
+ */
+export const OnboardingCarousel: React.FC<OnboardingCarouselProps> = ({
+  steps,
+  onDone,
+  onSkip,
+  skipText = 'Skip',
+  nextText = 'Next',
+  doneText = 'Get Started',
+  showSkip = true,
+  activeDotColor = '#333',
+  inactiveDotColor = '#ccc',
+  style,
+  buttonTextStyle,
+}) => {
+  const [currentStep, setCurrentStep] = useState(0);
+  const isLastStep = currentStep === steps.length - 1;
+
+  const handleNext = useCallback(() => {
+    if (isLastStep) {
+      onDone();
+    } else {
+      setCurrentStep((prev) => prev + 1);
+    }
+  }, [isLastStep, onDone]);
+
+  const handleSkip = useCallback(() => {
+    onSkip?.() ?? onDone();
+  }, [onSkip, onDone]);
+
+  return (
+    <View style={[styles.container, style]}>
+      <View style={styles.content}>
+        {steps[currentStep].render()}
+      </View>
+
+      <View style={styles.dots}>
+        {steps.map((_, i) => (
+          <View
+            key={i}
+            style={[
+              styles.dot,
+              {
+                backgroundColor: i === currentStep ? activeDotColor : inactiveDotColor,
+                width: i === currentStep ? 24 : 8,
+              },
+            ]}
+          />
+        ))}
+      </View>
+
+      <View style={styles.footer}>
+        {showSkip && !isLastStep ? (
+          <TouchableOpacity onPress={handleSkip} style={styles.skipButton}>
+            <Text style={[styles.skipText, buttonTextStyle]}>{skipText}</Text>
+          </TouchableOpacity>
+        ) : (
+          <View style={styles.skipButton} />
+        )}
+
+        <View style={styles.progressBar}>
+          <View
+            style={[
+              styles.progressFill,
+              {
+                width: `${((currentStep + 1) / steps.length) * 100}%`,
+                backgroundColor: activeDotColor,
+              },
+            ]}
+          />
+        </View>
+
+        <TouchableOpacity onPress={handleNext} style={styles.nextButton}>
+          <Text style={[styles.nextText, buttonTextStyle]}>
+            {isLastStep ? doneText : nextText}
+          </Text>
+        </TouchableOpacity>
+      </View>
+    </View>
+  );
+};
+
+OnboardingCarousel.displayName = 'OnboardingCarousel';
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#fff',
+  },
+  content: {
+    flex: 1,
+    width: SCREEN_WIDTH,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  dots: {
+    flexDirection: 'row',
+    justifyContent: 'center',
+    alignItems: 'center',
+    gap: 6,
+    marginBottom: 20,
+  },
+  dot: {
+    height: 8,
+    borderRadius: 4,
+  },
+  footer: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingHorizontal: 24,
+    paddingBottom: 40,
+  },
+  skipButton: {
+    width: 80,
+  },
+  skipText: {
+    fontSize: 16,
+    color: '#888',
+    fontWeight: '500',
+  },
+  progressBar: {
+    flex: 1,
+    height: 3,
+    backgroundColor: '#eee',
+    borderRadius: 2,
+    marginHorizontal: 16,
+    overflow: 'hidden',
+  },
+  progressFill: {
+    height: '100%',
+    borderRadius: 2,
+  },
+  nextButton: {
+    width: 110,
+    alignItems: 'flex-end',
+  },
+  nextText: {
+    fontSize: 16,
+    color: '#333',
+    fontWeight: '700',
+  },
+});

package/src/dev/PerformanceMonitor.tsx

@@ -0,0 +1,119 @@
+/**
+ * @file Performance monitor dev tool
+ * @description Overlay component showing FPS, memory, and render metrics
+ */
+
+import React, { useEffect, useState, useRef } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+
+export interface PerformanceMonitorProps {
+  /** Show/hide the monitor (default: true in __DEV__) */
+  enabled?: boolean;
+  /** Position on screen (default: 'top-right') */
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
+interface Metrics {
+  fps: number;
+  frameDrops: number;
+  renderCount: number;
+}
+
+/**
+ * Development-only performance monitor overlay.
+ * Shows real-time FPS and frame drop statistics.
+ */
+export const PerformanceMonitor: React.FC<PerformanceMonitorProps> = ({
+  enabled = __DEV__,
+  position = 'top-right',
+}) => {
+  const [metrics, setMetrics] = useState<Metrics>({ fps: 60, frameDrops: 0, renderCount: 0 });
+  const frameCount = useRef(0);
+  const dropCount = useRef(0);
+  const lastTimestamp = useRef(performance.now());
+  const renderCount = useRef(0);
+
+  renderCount.current++;
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    let rafId: number;
+    let intervalId: ReturnType<typeof setInterval>;
+
+    const onFrame = (timestamp: number) => {
+      const delta = timestamp - lastTimestamp.current;
+      lastTimestamp.current = timestamp;
+
+      frameCount.current++;
+
+      // Detect frame drop (> 20ms between frames means dropped)
+      if (delta > 20) {
+        dropCount.current++;
+      }
+
+      rafId = requestAnimationFrame(onFrame);
+    };
+
+    rafId = requestAnimationFrame(onFrame);
+
+    intervalId = setInterval(() => {
+      const currentFps = Math.min(60, Math.round(frameCount.current));
+      setMetrics({
+        fps: currentFps,
+        frameDrops: dropCount.current,
+        renderCount: renderCount.current,
+      });
+      frameCount.current = 0;
+      dropCount.current = 0;
+    }, 1000);
+
+    return () => {
+      cancelAnimationFrame(rafId);
+      clearInterval(intervalId);
+    };
+  }, [enabled]);
+
+  if (!enabled) return null;
+
+  const positionStyle = {
+    'top-left': { top: 50, left: 16 },
+    'top-right': { top: 50, right: 16 },
+    'bottom-left': { bottom: 50, left: 16 },
+    'bottom-right': { bottom: 50, right: 16 },
+  }[position];
+
+  const fpsColor = metrics.fps >= 55 ? '#27ae60' : metrics.fps >= 30 ? '#f39c12' : '#e74c3c';
+
+  return (
+    <View style={[styles.container, positionStyle]}>
+      <Text style={[styles.fps, { color: fpsColor }]}>{metrics.fps} FPS</Text>
+      <Text style={styles.stat}>Drops: {metrics.frameDrops}</Text>
+      <Text style={styles.stat}>Renders: {metrics.renderCount}</Text>
+    </View>
+  );
+};
+
+PerformanceMonitor.displayName = 'PerformanceMonitor';
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    backgroundColor: 'rgba(0,0,0,0.8)',
+    paddingHorizontal: 10,
+    paddingVertical: 6,
+    borderRadius: 8,
+    zIndex: 9999,
+    minWidth: 90,
+  },
+  fps: {
+    fontSize: 14,
+    fontWeight: '800',
+    fontFamily: 'monospace',
+  },
+  stat: {
+    fontSize: 10,
+    color: '#aaa',
+    fontFamily: 'monospace',
+  },
+});

package/src/index.ts

@@ -9,6 +9,10 @@
 export { Carousel } from './components/Carousel';
 export { Pagination } from './components/Pagination';
 export { ParallaxImage } from './components/ParallaxImage';
+export { ImageGallery } from './components/ImageGallery';
+export type { ImageGalleryProps, ImageGalleryItem } from './components/ImageGallery';
+export { OnboardingCarousel } from './components/OnboardingCarousel';
+export type { OnboardingCarouselProps, OnboardingStep } from './components/OnboardingCarousel';
 
 // === Hooks ===
 export { useCarousel } from './hooks/useCarousel';
@@ -72,6 +76,31 @@ export {
 
 // === Plugin System ===
 export { createPlugin, PluginManager } from './plugins/PluginManager';
+export { createAutoPlayPlugin } from './plugins/built-in/autoPlay';
+export type { AutoPlayPluginConfig } from './plugins/built-in/autoPlay';
+export { createPaginationPlugin } from './plugins/built-in/pagination';
+export type { PaginationPluginConfig } from './plugins/built-in/pagination';
+export { createParallaxImagePlugin } from './plugins/built-in/parallaxImage';
+export type { ParallaxImagePluginConfig } from './plugins/built-in/parallaxImage';
+
+// === Theme System ===
+export {
+  lightTheme,
+  darkTheme,
+  vibrantTheme,
+  minimalTheme,
+  themes,
+  getTheme,
+  createTheme,
+} from './theme';
+export type { CarouselTheme, ThemeName } from './theme';
+
+// === Utilities ===
+export { isRTL, flipForRTL, getFlexDirection, resolveAlignment } from './utils/rtl';
+
+// === Dev Tools ===
+export { PerformanceMonitor } from './dev/PerformanceMonitor';
+export type { PerformanceMonitorProps } from './dev/PerformanceMonitor';
 
 // === Types ===
 export type {

package/src/plugins/built-in/autoPlay.ts

@@ -0,0 +1,85 @@
+/**
+ * @file Auto play built-in plugin
+ * @description Automatically advances carousel slides at a configurable interval
+ */
+
+import { createPlugin } from '../PluginManager';
+import type { CarouselRef } from '../../types/carousel';
+
+export interface AutoPlayPluginConfig {
+  /** Interval between slides in ms (default: 3000) */
+  interval?: number;
+  /** Direction of auto play (default: 'forward') */
+  direction?: 'forward' | 'backward';
+  /** Pause when user interacts (default: true) */
+  pauseOnInteraction?: boolean;
+  /** Resume delay after interaction in ms (default: 1000) */
+  resumeDelay?: number;
+}
+
+const AUTO_PLAY_DEFAULTS: Required<AutoPlayPluginConfig> = {
+  interval: 3000,
+  direction: 'forward',
+  pauseOnInteraction: true,
+  resumeDelay: 1000,
+};
+
+export const createAutoPlayPlugin = (config?: AutoPlayPluginConfig) => {
+  const c = { ...AUTO_PLAY_DEFAULTS, ...config };
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let carousel: CarouselRef | null = null;
+  let paused = false;
+  let resumeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const start = () => {
+    stop();
+    paused = false;
+    timer = setInterval(() => {
+      if (!paused && carousel) {
+        if (c.direction === 'forward') {
+          carousel.next();
+        } else {
+          carousel.prev();
+        }
+      }
+    }, c.interval);
+  };
+
+  const stop = () => {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+    if (resumeTimer) {
+      clearTimeout(resumeTimer);
+      resumeTimer = null;
+    }
+  };
+
+  const pause = () => {
+    paused = true;
+    if (c.pauseOnInteraction && c.resumeDelay > 0) {
+      if (resumeTimer) clearTimeout(resumeTimer);
+      resumeTimer = setTimeout(() => {
+        paused = false;
+      }, c.resumeDelay);
+    }
+  };
+
+  return createPlugin({
+    name: 'auto-play',
+    onInit: (ref) => {
+      carousel = ref;
+      start();
+    },
+    onIndexChange: () => {
+      if (c.pauseOnInteraction) {
+        pause();
+      }
+    },
+    onDestroy: () => {
+      stop();
+      carousel = null;
+    },
+  });
+};

package/src/plugins/built-in/pagination.ts

@@ -0,0 +1,32 @@
+/**
+ * @file Pagination built-in plugin
+ * @description Tracks carousel pagination state and provides callbacks
+ */
+
+import { createPlugin } from '../PluginManager';
+
+export interface PaginationPluginConfig {
+  /** Called when page changes with current and total */
+  onPageChange?: (current: number, total: number) => void;
+  /** Total number of items (set during init) */
+  totalItems?: number;
+}
+
+export const createPaginationPlugin = (config?: PaginationPluginConfig) => {
+  let total = config?.totalItems ?? 0;
+  let currentIndex = 0;
+
+  return createPlugin({
+    name: 'pagination',
+    onInit: () => {
+      currentIndex = 0;
+    },
+    onIndexChange: (index) => {
+      currentIndex = index;
+      config?.onPageChange?.(currentIndex, total);
+    },
+    onDestroy: () => {
+      currentIndex = 0;
+    },
+  });
+};

package/src/plugins/built-in/parallaxImage.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Parallax image built-in plugin
+ * @description Adds parallax scrolling effect to carousel item images
+ */
+
+import { createPlugin } from '../PluginManager';
+import type { AnimatedItemStyle } from '../../types/animation';
+
+export interface ParallaxImagePluginConfig {
+  /** Parallax factor — how much background moves relative to foreground (default: 0.3) */
+  factor?: number;
+  /** Maximum translateX for parallax (default: 100) */
+  maxOffset?: number;
+}
+
+const PARALLAX_DEFAULTS: Required<ParallaxImagePluginConfig> = {
+  factor: 0.3,
+  maxOffset: 100,
+};
+
+export const createParallaxImagePlugin = (config?: ParallaxImagePluginConfig) => {
+  const c = { ...PARALLAX_DEFAULTS, ...config };
+
+  return createPlugin({
+    name: 'parallax-image',
+    onAnimate: (progress) => {
+      const translateX = Math.max(
+        -c.maxOffset,
+        Math.min(c.maxOffset, progress * c.maxOffset * c.factor)
+      );
+      return {
+        transform: [{ translateX }],
+      } as AnimatedItemStyle;
+    },
+  });
+};

package/src/theme/index.ts

@@ -0,0 +1,182 @@
+/**
+ * @file Theme system for react-native-ultra-carousel
+ * @description Provides 4 built-in themes and custom theme support
+ */
+
+import type { ViewStyle, TextStyle } from 'react-native';
+
+export interface CarouselTheme {
+  /** Theme name */
+  name: string;
+  /** Pagination dot active color */
+  paginationActiveColor: string;
+  /** Pagination dot inactive color */
+  paginationInactiveColor: string;
+  /** Pagination number text color */
+  paginationTextColor: string;
+  /** Progress bar background color */
+  progressBarBackground: string;
+  /** Progress bar fill color */
+  progressBarFill: string;
+  /** Card background color */
+  cardBackground: string;
+  /** Card border radius */
+  cardBorderRadius: number;
+  /** Card shadow style */
+  cardShadow: ViewStyle;
+  /** Text styles for card title */
+  cardTitleStyle: TextStyle;
+  /** Text styles for card subtitle */
+  cardSubtitleStyle: TextStyle;
+}
+
+/** Light theme — clean and minimal */
+export const lightTheme: CarouselTheme = {
+  name: 'light',
+  paginationActiveColor: '#333333',
+  paginationInactiveColor: '#CCCCCC',
+  paginationTextColor: '#333333',
+  progressBarBackground: '#E0E0E0',
+  progressBarFill: '#333333',
+  cardBackground: '#FFFFFF',
+  cardBorderRadius: 12,
+  cardShadow: {
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 8,
+    elevation: 3,
+  },
+  cardTitleStyle: {
+    fontSize: 18,
+    fontWeight: '700',
+    color: '#1A1A1A',
+  },
+  cardSubtitleStyle: {
+    fontSize: 14,
+    fontWeight: '400',
+    color: '#666666',
+  },
+};
+
+/** Dark theme — modern dark mode */
+export const darkTheme: CarouselTheme = {
+  name: 'dark',
+  paginationActiveColor: '#FFFFFF',
+  paginationInactiveColor: '#555555',
+  paginationTextColor: '#FFFFFF',
+  progressBarBackground: '#333333',
+  progressBarFill: '#FFFFFF',
+  cardBackground: '#1E1E2E',
+  cardBorderRadius: 12,
+  cardShadow: {
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.3,
+    shadowRadius: 12,
+    elevation: 6,
+  },
+  cardTitleStyle: {
+    fontSize: 18,
+    fontWeight: '700',
+    color: '#FFFFFF',
+  },
+  cardSubtitleStyle: {
+    fontSize: 14,
+    fontWeight: '400',
+    color: '#AAAAAA',
+  },
+};
+
+/** Vibrant theme — colorful and energetic */
+export const vibrantTheme: CarouselTheme = {
+  name: 'vibrant',
+  paginationActiveColor: '#FF6B6B',
+  paginationInactiveColor: '#FFD1D1',
+  paginationTextColor: '#FF6B6B',
+  progressBarBackground: '#FFE0E0',
+  progressBarFill: '#FF6B6B',
+  cardBackground: '#FFF5F5',
+  cardBorderRadius: 16,
+  cardShadow: {
+    shadowColor: '#FF6B6B',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.2,
+    shadowRadius: 12,
+    elevation: 4,
+  },
+  cardTitleStyle: {
+    fontSize: 20,
+    fontWeight: '800',
+    color: '#CC3333',
+  },
+  cardSubtitleStyle: {
+    fontSize: 14,
+    fontWeight: '500',
+    color: '#FF8888',
+  },
+};
+
+/** Minimal theme — ultra clean, subtle */
+export const minimalTheme: CarouselTheme = {
+  name: 'minimal',
+  paginationActiveColor: '#000000',
+  paginationInactiveColor: '#E5E5E5',
+  paginationTextColor: '#000000',
+  progressBarBackground: '#F0F0F0',
+  progressBarFill: '#000000',
+  cardBackground: '#FAFAFA',
+  cardBorderRadius: 4,
+  cardShadow: {
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.05,
+    shadowRadius: 4,
+    elevation: 1,
+  },
+  cardTitleStyle: {
+    fontSize: 16,
+    fontWeight: '600',
+    color: '#111111',
+  },
+  cardSubtitleStyle: {
+    fontSize: 13,
+    fontWeight: '400',
+    color: '#888888',
+  },
+};
+
+/** All built-in themes */
+export const themes = {
+  light: lightTheme,
+  dark: darkTheme,
+  vibrant: vibrantTheme,
+  minimal: minimalTheme,
+} as const;
+
+export type ThemeName = keyof typeof themes;
+
+/**
+ * Gets a built-in theme by name.
+ *
+ * @param name - Theme name
+ * @returns The theme object
+ */
+export const getTheme = (name: ThemeName): CarouselTheme => {
+  return themes[name];
+};
+
+/**
+ * Creates a custom theme by extending a base theme.
+ *
+ * @param base - Base theme to extend
+ * @param overrides - Partial theme overrides
+ * @returns Complete merged theme
+ */
+export const createTheme = (
+  base: ThemeName | CarouselTheme,
+  overrides: Partial<CarouselTheme>
+): CarouselTheme => {
+  const baseTheme = typeof base === 'string' ? themes[base] : base;
+  return { ...baseTheme, ...overrides };
+};

package/src/utils/rtl.ts

@@ -0,0 +1,54 @@
+/**
+ * @file RTL support utilities
+ * @description Helpers for right-to-left layout support
+ */
+
+import { I18nManager } from 'react-native';
+
+/** Whether the current layout direction is RTL */
+export const isRTL = (): boolean => {
+  return I18nManager.isRTL;
+};
+
+/**
+ * Flips a horizontal value for RTL layouts.
+ * In RTL mode, positive becomes negative and vice versa.
+ *
+ * @param value - The horizontal value to flip
+ * @returns The flipped value if RTL, original otherwise
+ */
+export const flipForRTL = (value: number): number => {
+  'worklet';
+  return I18nManager.isRTL ? -value : value;
+};
+
+/**
+ * Returns the appropriate flex direction based on layout direction.
+ *
+ * @returns 'row-reverse' for RTL, 'row' for LTR
+ */
+export const getFlexDirection = (): 'row' | 'row-reverse' => {
+  return I18nManager.isRTL ? 'row-reverse' : 'row';
+};
+
+/**
+ * Returns the appropriate text alignment based on layout direction.
+ *
+ * @returns 'right' for RTL, 'left' for LTR
+ */
+export const getTextAlign = (): 'left' | 'right' => {
+  return I18nManager.isRTL ? 'right' : 'left';
+};
+
+/**
+ * Resolves start/end alignment to left/right based on layout direction.
+ *
+ * @param alignment - Logical alignment ('start' or 'end')
+ * @returns Physical alignment ('left' or 'right')
+ */
+export const resolveAlignment = (alignment: 'start' | 'end'): 'left' | 'right' => {
+  if (I18nManager.isRTL) {
+    return alignment === 'start' ? 'right' : 'left';
+  }
+  return alignment === 'start' ? 'left' : 'right';
+};