react-native-ultra-carousel 0.1.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "react-native-ultra-carousel",
+  "version": "0.1.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",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__"
+  ],
+  "scripts": {
+    "build": "bob build",
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts,.tsx",
+    "clean": "del-cli lib"
+  },
+  "keywords": [
+    "react-native",
+    "carousel",
+    "slider",
+    "swiper",
+    "animation",
+    "reanimated",
+    "expo",
+    "ios",
+    "android",
+    "typescript",
+    "gesture",
+    "3d",
+    "parallax",
+    "coverflow",
+    "tinder",
+    "stack"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toankhontech/react-native-ultra-carousel"
+  },
+  "author": "toankhontech",
+  "license": "MIT",
+  "homepage": "https://github.com/toankhontech/react-native-ultra-carousel",
+  "bugs": {
+    "url": "https://github.com/toankhontech/react-native-ultra-carousel/issues"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-gesture-handler": ">=2.9.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "react-native": "^0.73.0",
+    "react-native-reanimated": "^3.6.0",
+    "react-native-gesture-handler": "^2.14.0",
+    "react-native-builder-bob": "^0.23.0",
+    "jest": "^29.7.0",
+    "@testing-library/react-native": "^12.0.0",
+    "typescript": "^5.4.0",
+    "del-cli": "^5.1.0",
+    "@types/jest": "^29.5.0",
+    "react-test-renderer": "^18.2.0"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      ["typescript", { "project": "tsconfig.build.json" }]
+    ]
+  }
+}

package/src/animations/basic/fade.ts

@@ -0,0 +1,51 @@
+/**
+ * @file Fade animation preset
+ * @description Crossfade transition between items — items stack and opacity changes
+ * @preset fade
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+import { computeZIndex } from '../utils';
+
+/** Configuration for the fade animation */
+export interface FadeConfig {
+  /** Minimum opacity for inactive items (default: 0) */
+  minOpacity: number;
+}
+
+/** Default fade configuration */
+export const FADE_DEFAULTS: FadeConfig = {
+  minOpacity: 0,
+};
+
+/**
+ * Fade animation worklet.
+ * Items stack on top of each other, only opacity transitions.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const fadeAnimation = (
+  progress: number,
+  config?: Partial<FadeConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...FADE_DEFAULTS, ...config };
+
+  const opacity = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minOpacity],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    opacity,
+    zIndex: computeZIndex(progress),
+  };
+};

package/src/animations/basic/overlap.ts

@@ -0,0 +1,69 @@
+/**
+ * @file Overlap animation preset
+ * @description Items overlap each other by 30%, creating a stacked card appearance
+ * @preset overlap
+ * @difficulty Medium
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+import { computeZIndex } from '../utils';
+
+/** Configuration for the overlap animation */
+export interface OverlapConfig {
+  /** Overlap ratio — 0.7 means 30% overlap (default: 0.7) */
+  overlapRatio: number;
+  /** Scale of non-active items (default: 0.95) */
+  minScale: number;
+  /** Item width for offset calculations (default: 300) */
+  itemWidth: number;
+}
+
+/** Default overlap configuration */
+export const OVERLAP_DEFAULTS: OverlapConfig = {
+  overlapRatio: 0.7,
+  minScale: 0.95,
+  itemWidth: 300,
+};
+
+/**
+ * Overlap animation worklet.
+ * Items translate at a reduced distance so they overlap.
+ * Active item sits on top with highest zIndex.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const overlapAnimation = (
+  progress: number,
+  config?: Partial<OverlapConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...OVERLAP_DEFAULTS, ...config };
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-(c.itemWidth * c.overlapRatio), 0, c.itemWidth * c.overlapRatio],
+    Extrapolation.CLAMP
+  );
+
+  const scale = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minScale],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [
+      { translateX },
+      { scale },
+    ],
+    zIndex: computeZIndex(progress),
+    opacity: 1,
+  };
+};

package/src/animations/basic/parallax.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Parallax animation preset
+ * @description Multi-layer parallax effect with foreground and background moving at different speeds
+ * @preset parallax
+ * @difficulty Medium
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the parallax animation */
+export interface ParallaxConfig {
+  /** Speed ratio for parallax layers (default: 0.3) — lower = more parallax */
+  parallaxFactor: number;
+  /** Slide distance in pixels (default: 300) */
+  distance: number;
+  /** Minimum opacity for inactive items (default: 0.8) */
+  minOpacity: number;
+}
+
+/** Default parallax configuration */
+export const PARALLAX_DEFAULTS: ParallaxConfig = {
+  parallaxFactor: 0.3,
+  distance: 300,
+  minOpacity: 0.8,
+};
+
+/**
+ * Parallax animation worklet.
+ * Background content moves slower than the container for a depth effect.
+ * The foreground (item container) translates at full speed while the inner
+ * content translates at a reduced rate (parallaxFactor).
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const parallaxAnimation = (
+  progress: number,
+  config?: Partial<ParallaxConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...PARALLAX_DEFAULTS, ...config };
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-c.distance * c.parallaxFactor, 0, c.distance * c.parallaxFactor],
+    Extrapolation.CLAMP
+  );
+
+  const opacity = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minOpacity],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [{ translateX }],
+    opacity,
+  };
+};

package/src/animations/basic/peek.ts

@@ -0,0 +1,79 @@
+/**
+ * @file Peek animation preset
+ * @description Active item centered with adjacent items peeking from the sides
+ * @preset peek
+ * @difficulty Medium
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the peek animation */
+export interface PeekConfig {
+  /** How much of the adjacent item is visible — 0.2 = 20% (default: 0.2) */
+  peekAmount: number;
+  /** Scale of peeking items (default: 0.85) */
+  peekScale: number;
+  /** Opacity of peeking items (default: 0.7) */
+  peekOpacity: number;
+  /** Item width for peek offset calculations (default: 300) */
+  itemWidth: number;
+}
+
+/** Default peek configuration */
+export const PEEK_DEFAULTS: PeekConfig = {
+  peekAmount: 0.2,
+  peekScale: 0.85,
+  peekOpacity: 0.7,
+  itemWidth: 300,
+};
+
+/**
+ * Peek animation worklet.
+ * Centers the active item while showing edges of adjacent items.
+ * Peeking items are scaled down and slightly faded.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const peekAnimation = (
+  progress: number,
+  config?: Partial<PeekConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...PEEK_DEFAULTS, ...config };
+
+  const peekOffset = c.itemWidth * (1 - c.peekAmount);
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-peekOffset, 0, peekOffset],
+    Extrapolation.CLAMP
+  );
+
+  const scale = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.peekScale],
+    Extrapolation.CLAMP
+  );
+
+  const opacity = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.peekOpacity],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [
+      { translateX },
+      { scale },
+    ],
+    opacity,
+  };
+};

package/src/animations/basic/scale.ts

@@ -0,0 +1,63 @@
+/**
+ * @file Scale animation preset
+ * @description Active item at full scale, neighbors shrink — creates depth emphasis
+ * @preset scale
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the scale animation */
+export interface ScaleConfig {
+  /** Scale of inactive items (default: 0.8) */
+  minScale: number;
+  /** Horizontal spacing between items (default: 50) */
+  spacing: number;
+}
+
+/** Default scale configuration */
+export const SCALE_DEFAULTS: ScaleConfig = {
+  minScale: 0.8,
+  spacing: 50,
+};
+
+/**
+ * Scale animation worklet.
+ * Active item is full size, adjacent items scale down to create a size hierarchy.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const scaleAnimation = (
+  progress: number,
+  config?: Partial<ScaleConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...SCALE_DEFAULTS, ...config };
+
+  const scale = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minScale],
+    Extrapolation.CLAMP
+  );
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-c.spacing, 0, c.spacing],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [
+      { translateX },
+      { scale },
+    ],
+    opacity: 1,
+  };
+};

package/src/animations/basic/scaleFade.ts

@@ -0,0 +1,73 @@
+/**
+ * @file Scale-fade animation preset
+ * @description Combines scale and opacity for an elegant depth + fade effect
+ * @preset scale-fade
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the scale-fade animation */
+export interface ScaleFadeConfig {
+  /** Scale of inactive items (default: 0.85) */
+  minScale: number;
+  /** Minimum opacity for inactive items (default: 0.5) */
+  minOpacity: number;
+  /** Horizontal spacing (default: 40) */
+  spacing: number;
+}
+
+/** Default scale-fade configuration */
+export const SCALE_FADE_DEFAULTS: ScaleFadeConfig = {
+  minScale: 0.85,
+  minOpacity: 0.5,
+  spacing: 40,
+};
+
+/**
+ * Scale-fade animation worklet.
+ * Combines scale reduction with opacity fade for a polished transition.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const scaleFadeAnimation = (
+  progress: number,
+  config?: Partial<ScaleFadeConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...SCALE_FADE_DEFAULTS, ...config };
+
+  const scale = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minScale],
+    Extrapolation.CLAMP
+  );
+
+  const opacity = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minOpacity],
+    Extrapolation.CLAMP
+  );
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-c.spacing, 0, c.spacing],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [
+      { translateX },
+      { scale },
+    ],
+    opacity,
+  };
+};

package/src/animations/basic/slide.ts

@@ -0,0 +1,53 @@
+/**
+ * @file Slide animation preset
+ * @description Standard horizontal slide transition — the default carousel behavior
+ * @preset slide
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the slide animation */
+export interface SlideConfig {
+  /** Slide distance multiplier relative to item width (default: 1) */
+  distance: number;
+}
+
+/** Default slide configuration */
+export const SLIDE_DEFAULTS: SlideConfig = {
+  distance: 1,
+};
+
+/** Default item width used for slide calculations */
+const DEFAULT_ITEM_WIDTH = 300;
+
+/**
+ * Slide animation worklet.
+ * Translates items horizontally based on scroll progress.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const slideAnimation = (
+  progress: number,
+  config?: Partial<SlideConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...SLIDE_DEFAULTS, ...config };
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-DEFAULT_ITEM_WIDTH * c.distance, 0, DEFAULT_ITEM_WIDTH * c.distance],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [{ translateX }],
+    opacity: 1,
+  };
+};

package/src/animations/basic/slideFade.ts

@@ -0,0 +1,60 @@
+/**
+ * @file Slide-fade animation preset
+ * @description Combines horizontal slide with opacity fade for an elegant transition
+ * @preset slide-fade
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the slide-fade animation */
+export interface SlideFadeConfig {
+  /** Slide distance in pixels (default: 200) */
+  distance: number;
+  /** Minimum opacity for inactive items (default: 0.3) */
+  minOpacity: number;
+}
+
+/** Default slide-fade configuration */
+export const SLIDE_FADE_DEFAULTS: SlideFadeConfig = {
+  distance: 200,
+  minOpacity: 0.3,
+};
+
+/**
+ * Slide-fade animation worklet.
+ * Combines translateX movement with opacity reduction for smooth transitions.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const slideFadeAnimation = (
+  progress: number,
+  config?: Partial<SlideFadeConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...SLIDE_FADE_DEFAULTS, ...config };
+
+  const translateX = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-c.distance, 0, c.distance],
+    Extrapolation.CLAMP
+  );
+
+  const opacity = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [1, c.minOpacity],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [{ translateX }],
+    opacity,
+  };
+};

package/src/animations/basic/vertical.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Vertical animation preset
+ * @description Vertical slide transition for vertical carousels
+ * @preset vertical
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the vertical animation */
+export interface VerticalConfig {
+  /** Vertical distance multiplier (default: 250) */
+  distance: number;
+}
+
+/** Default vertical configuration */
+export const VERTICAL_DEFAULTS: VerticalConfig = {
+  distance: 250,
+};
+
+/**
+ * Vertical animation worklet.
+ * Translates items vertically instead of horizontally.
+ *
+ * @param progress - Normalized item progress: 0 = active, -1 = prev, +1 = next
+ * @param config - Optional overrides for default configuration
+ * @returns Animated style to apply to the carousel item
+ */
+export const verticalAnimation = (
+  progress: number,
+  config?: Partial<VerticalConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...VERTICAL_DEFAULTS, ...config };
+
+  const translateY = interpolate(
+    progress,
+    [-1, 0, 1],
+    [-c.distance, 0, c.distance],
+    Extrapolation.CLAMP
+  );
+
+  return {
+    transform: [{ translateY }],
+    opacity: 1,
+  };
+};