react-native-ultra-carousel 0.1.0

package/src/animations/basic/verticalFade.ts

@@ -0,0 +1,60 @@
+/**
+ * @file Vertical-fade animation preset
+ * @description Combines vertical slide with opacity fade
+ * @preset vertical-fade
+ * @difficulty Easy
+ * @phase 1
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+import type { AnimatedItemStyle } from '../types';
+
+/** Configuration for the vertical-fade animation */
+export interface VerticalFadeConfig {
+  /** Vertical distance in pixels (default: 200) */
+  distance: number;
+  /** Minimum opacity for inactive items (default: 0.3) */
+  minOpacity: number;
+}
+
+/** Default vertical-fade configuration */
+export const VERTICAL_FADE_DEFAULTS: VerticalFadeConfig = {
+  distance: 200,
+  minOpacity: 0.3,
+};
+
+/**
+ * Vertical-fade animation worklet.
+ * Combines vertical translation with opacity reduction.
+ *
+ * @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 verticalFadeAnimation = (
+  progress: number,
+  config?: Partial<VerticalFadeConfig>
+): AnimatedItemStyle => {
+  'worklet';
+
+  const c = { ...VERTICAL_FADE_DEFAULTS, ...config };
+
+  const translateY = 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: [{ translateY }],
+    opacity,
+  };
+};

package/src/animations/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Animation presets public exports
+ * @description Export all animation presets and registry utilities
+ */
+
+export { slideAnimation, SLIDE_DEFAULTS } from './basic/slide';
+export type { SlideConfig } from './basic/slide';
+
+export { fadeAnimation, FADE_DEFAULTS } from './basic/fade';
+export type { FadeConfig } from './basic/fade';
+
+export { slideFadeAnimation, SLIDE_FADE_DEFAULTS } from './basic/slideFade';
+export type { SlideFadeConfig } from './basic/slideFade';
+
+export { scaleAnimation, SCALE_DEFAULTS } from './basic/scale';
+export type { ScaleConfig } from './basic/scale';
+
+export { scaleFadeAnimation, SCALE_FADE_DEFAULTS } from './basic/scaleFade';
+export type { ScaleFadeConfig } from './basic/scaleFade';
+
+export { verticalAnimation, VERTICAL_DEFAULTS } from './basic/vertical';
+export type { VerticalConfig } from './basic/vertical';
+
+export { verticalFadeAnimation, VERTICAL_FADE_DEFAULTS } from './basic/verticalFade';
+export type { VerticalFadeConfig } from './basic/verticalFade';
+
+export { parallaxAnimation, PARALLAX_DEFAULTS } from './basic/parallax';
+export type { ParallaxConfig } from './basic/parallax';
+
+export { overlapAnimation, OVERLAP_DEFAULTS } from './basic/overlap';
+export type { OverlapConfig } from './basic/overlap';
+
+export { peekAnimation, PEEK_DEFAULTS } from './basic/peek';
+export type { PeekConfig } from './basic/peek';
+
+export {
+  registerPreset,
+  getPreset,
+  getPresetMeta,
+  getAllPresetNames,
+  getAllPresetMeta,
+  isPresetRegistered,
+} from './registry';
+
+export type { AnimatedItemStyle, AnimationPresetFn, AnimationPresetMeta } from './types';

package/src/animations/registry.ts

@@ -0,0 +1,175 @@
+/**
+ * @file Animation preset registry
+ * @description Central registry for all animation presets — lookup by name
+ */
+
+import type { AnimationPresetFn, AnimationPresetMeta } from './types';
+import { slideAnimation } from './basic/slide';
+import { fadeAnimation } from './basic/fade';
+import { slideFadeAnimation } from './basic/slideFade';
+import { scaleAnimation } from './basic/scale';
+import { scaleFadeAnimation } from './basic/scaleFade';
+import { verticalAnimation } from './basic/vertical';
+import { verticalFadeAnimation } from './basic/verticalFade';
+import { parallaxAnimation } from './basic/parallax';
+import { overlapAnimation } from './basic/overlap';
+import { peekAnimation } from './basic/peek';
+
+/** Internal registry map of preset names to animation functions */
+const registry = new Map<string, AnimationPresetFn>();
+
+/** Internal metadata registry */
+const metaRegistry = new Map<string, AnimationPresetMeta>();
+
+/**
+ * Registers a preset in the animation registry.
+ *
+ * @param meta - Full metadata for the preset including the animation function
+ */
+export const registerPreset = (meta: AnimationPresetMeta): void => {
+  registry.set(meta.name, meta.animation);
+  metaRegistry.set(meta.name, meta);
+};
+
+/**
+ * Retrieves an animation function by preset name.
+ *
+ * @param name - The preset name to look up
+ * @returns The animation function, or undefined if not found
+ */
+export const getPreset = (name: string): AnimationPresetFn | undefined => {
+  return registry.get(name);
+};
+
+/**
+ * Retrieves metadata for a preset by name.
+ *
+ * @param name - The preset name to look up
+ * @returns The preset metadata, or undefined if not found
+ */
+export const getPresetMeta = (name: string): AnimationPresetMeta | undefined => {
+  return metaRegistry.get(name);
+};
+
+/**
+ * Returns all registered preset names.
+ *
+ * @returns Array of registered preset names
+ */
+export const getAllPresetNames = (): string[] => {
+  return Array.from(registry.keys());
+};
+
+/**
+ * Returns all registered preset metadata.
+ *
+ * @returns Array of all preset metadata
+ */
+export const getAllPresetMeta = (): AnimationPresetMeta[] => {
+  return Array.from(metaRegistry.values());
+};
+
+/**
+ * Checks whether a preset name is registered.
+ *
+ * @param name - The preset name to check
+ * @returns True if the preset is registered
+ */
+export const isPresetRegistered = (name: string): boolean => {
+  return registry.has(name);
+};
+
+/** Register all built-in basic presets */
+const registerBuiltInPresets = (): void => {
+  registerPreset({
+    name: 'slide',
+    description: 'Standard horizontal slide transition',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: slideAnimation,
+    defaults: { distance: 1 },
+  });
+
+  registerPreset({
+    name: 'fade',
+    description: 'Crossfade transition between stacked items',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: fadeAnimation,
+    defaults: { minOpacity: 0 },
+  });
+
+  registerPreset({
+    name: 'slide-fade',
+    description: 'Horizontal slide combined with opacity fade',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: slideFadeAnimation,
+    defaults: { distance: 200, minOpacity: 0.3 },
+  });
+
+  registerPreset({
+    name: 'scale',
+    description: 'Active item full size, neighbors scale down',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: scaleAnimation,
+    defaults: { minScale: 0.8, spacing: 50 },
+  });
+
+  registerPreset({
+    name: 'scale-fade',
+    description: 'Scale reduction combined with opacity fade',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: scaleFadeAnimation,
+    defaults: { minScale: 0.85, minOpacity: 0.5, spacing: 40 },
+  });
+
+  registerPreset({
+    name: 'vertical',
+    description: 'Vertical slide transition',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: verticalAnimation,
+    defaults: { distance: 250 },
+  });
+
+  registerPreset({
+    name: 'vertical-fade',
+    description: 'Vertical slide combined with opacity fade',
+    difficulty: 'Easy',
+    phase: 1,
+    animation: verticalFadeAnimation,
+    defaults: { distance: 200, minOpacity: 0.3 },
+  });
+
+  registerPreset({
+    name: 'parallax',
+    description: 'Multi-layer parallax depth effect',
+    difficulty: 'Medium',
+    phase: 1,
+    animation: parallaxAnimation,
+    defaults: { parallaxFactor: 0.3, distance: 300, minOpacity: 0.8 },
+  });
+
+  registerPreset({
+    name: 'overlap',
+    description: 'Items overlap each other with stacked appearance',
+    difficulty: 'Medium',
+    phase: 1,
+    animation: overlapAnimation,
+    defaults: { overlapRatio: 0.7, minScale: 0.95, itemWidth: 300 },
+  });
+
+  registerPreset({
+    name: 'peek',
+    description: 'Active item centered with adjacent items peeking from sides',
+    difficulty: 'Medium',
+    phase: 1,
+    animation: peekAnimation,
+    defaults: { peekAmount: 0.2, peekScale: 0.85, peekOpacity: 0.7, itemWidth: 300 },
+  });
+};
+
+registerBuiltInPresets();

package/src/animations/types.ts

@@ -0,0 +1,11 @@
+/**
+ * @file Animation module types
+ * @description Re-exports animation types for internal use
+ */
+
+export type {
+  AnimatedItemStyle,
+  AnimationPresetFn,
+  CustomAnimationFn,
+  AnimationPresetMeta,
+} from '../types/animation';

package/src/animations/utils.ts

@@ -0,0 +1,75 @@
+/**
+ * @file Shared animation utility functions
+ * @description Common helpers used across animation presets
+ */
+
+import { interpolate, Extrapolation } from 'react-native-reanimated';
+
+/**
+ * Symmetric interpolation helper for common animation patterns.
+ * Maps progress [-1, 0, 1] to [edge, center, edge] values.
+ *
+ * @param progress - Normalized progress value
+ * @param center - Value at progress = 0 (active)
+ * @param edge - Value at progress = -1 or 1
+ * @returns Interpolated value
+ */
+export const symmetricInterpolate = (
+  progress: number,
+  center: number,
+  edge: number
+): number => {
+  'worklet';
+  return interpolate(
+    progress,
+    [-1, 0, 1],
+    [edge, center, edge],
+    Extrapolation.CLAMP
+  );
+};
+
+/**
+ * Directional interpolation for left-center-right patterns.
+ *
+ * @param progress - Normalized progress value
+ * @param left - Value at progress = -1
+ * @param center - Value at progress = 0
+ * @param right - Value at progress = 1
+ * @returns Interpolated value
+ */
+export const directionalInterpolate = (
+  progress: number,
+  left: number,
+  center: number,
+  right: number
+): number => {
+  'worklet';
+  return interpolate(
+    progress,
+    [-1, 0, 1],
+    [left, center, right],
+    Extrapolation.CLAMP
+  );
+};
+
+/**
+ * Computes zIndex based on distance from active item.
+ * Active item gets highest zIndex.
+ *
+ * @param progress - Normalized progress value
+ * @param maxZIndex - Maximum zIndex for active item
+ * @returns Rounded zIndex value
+ */
+export const computeZIndex = (
+  progress: number,
+  maxZIndex: number = 100
+): number => {
+  'worklet';
+  const z = interpolate(
+    Math.abs(progress),
+    [0, 1],
+    [maxZIndex, 0],
+    Extrapolation.CLAMP
+  );
+  return Math.round(z);
+};

package/src/components/AutoPlayController.tsx

@@ -0,0 +1,38 @@
+/**
+ * @file AutoPlayController component
+ * @description Headless component that manages auto play lifecycle
+ */
+
+import { useEffect } from 'react';
+import type { AutoPlayConfig } from '../types';
+import { useAutoPlay, type UseAutoPlayReturn } from '../hooks/useAutoPlay';
+
+/** Props for the AutoPlayController */
+export interface AutoPlayControllerProps {
+  /** Auto play configuration */
+  config: AutoPlayConfig | boolean | undefined;
+  /** Callback to advance carousel */
+  onAdvance: (direction: 'forward' | 'backward') => void;
+  /** Callback to expose auto play controls to parent */
+  onControlsReady?: (controls: UseAutoPlayReturn) => void;
+}
+
+/**
+ * Headless component that manages carousel auto play.
+ * Renders nothing — all logic is in hooks.
+ */
+export const AutoPlayController: React.FC<AutoPlayControllerProps> = ({
+  config,
+  onAdvance,
+  onControlsReady,
+}) => {
+  const controls = useAutoPlay(config, onAdvance);
+
+  useEffect(() => {
+    onControlsReady?.(controls);
+  }, [controls, onControlsReady]);
+
+  return null;
+};
+
+AutoPlayController.displayName = 'AutoPlayController';