react-native-ultra-carousel 0.1.0

package/src/components/Pagination/DotPagination.tsx

@@ -0,0 +1,137 @@
+/**
+ * @file DotPagination component
+ * @description Animated dot indicators for carousel pagination
+ */
+
+import React, { memo } from 'react';
+import { StyleSheet, Pressable, View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  interpolate,
+  Extrapolation,
+  type SharedValue,
+} from 'react-native-reanimated';
+import type { BasePaginationProps } from '../../types';
+
+/**
+ * Dot-based pagination indicator.
+ * Active dot scales up and changes color smoothly based on scroll progress.
+ */
+const DotPaginationComponent: React.FC<BasePaginationProps> = ({
+  totalItems,
+  progress,
+  activeColor,
+  inactiveColor,
+  size,
+  gap,
+  goToIndex,
+  style,
+}) => {
+  return (
+    <View style={[styles.container, style]} accessibilityRole="tablist">
+      {Array.from({ length: totalItems }).map((_, index) => (
+        <DotIndicator
+          key={index}
+          index={index}
+          progress={progress}
+          activeColor={activeColor}
+          inactiveColor={inactiveColor}
+          size={size}
+          gap={gap}
+          goToIndex={goToIndex}
+        />
+      ))}
+    </View>
+  );
+};
+
+DotPaginationComponent.displayName = 'DotPagination';
+
+/** Props for an individual dot */
+interface DotIndicatorProps {
+  index: number;
+  progress: SharedValue<number>;
+  activeColor: string;
+  inactiveColor: string;
+  size: number;
+  gap: number;
+  goToIndex: (index: number) => void;
+}
+
+/** Individual animated dot indicator */
+const DotIndicator: React.FC<DotIndicatorProps> = memo(({
+  index,
+  progress,
+  activeColor,
+  inactiveColor,
+  size,
+  gap,
+  goToIndex,
+}) => {
+  const ACTIVE_SCALE = 1.4;
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const distance = Math.abs(progress.value - index);
+
+    const scale = interpolate(
+      distance,
+      [0, 1],
+      [ACTIVE_SCALE, 1],
+      Extrapolation.CLAMP
+    );
+
+    const opacity = interpolate(
+      distance,
+      [0, 1],
+      [1, 0.5],
+      Extrapolation.CLAMP
+    );
+
+    return {
+      transform: [{ scale }],
+      opacity,
+    };
+  });
+
+  const isActive = Math.round(progress.value) === index;
+
+  return (
+    <Pressable
+      onPress={() => goToIndex(index)}
+      accessibilityRole="tab"
+      accessibilityLabel={`Page ${index + 1}`}
+      accessibilityState={{ selected: isActive }}
+      hitSlop={8}
+    >
+      <Animated.View
+        style={[
+          styles.dot,
+          {
+            width: size,
+            height: size,
+            borderRadius: size / 2,
+            marginHorizontal: gap / 2,
+            backgroundColor: isActive ? activeColor : inactiveColor,
+          },
+          animatedStyle,
+        ]}
+      />
+    </Pressable>
+  );
+});
+
+DotIndicator.displayName = 'DotIndicator';
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: 12,
+  },
+  dot: {
+    // dynamic styles applied inline
+  },
+});
+
+export const DotPagination = memo(DotPaginationComponent);

package/src/components/Pagination/NumberPagination.tsx

@@ -0,0 +1,117 @@
+/**
+ * @file NumberPagination component
+ * @description Numeric page indicator in "X / Y" format
+ */
+
+import React, { memo } from 'react';
+import { StyleSheet, View, Text } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  interpolate,
+  Extrapolation,
+  type SharedValue,
+} from 'react-native-reanimated';
+import type { BasePaginationProps } from '../../types';
+
+/**
+ * Number-based pagination indicator.
+ * Displays current page and total in "X / Y" format with animated transitions.
+ */
+const NumberPaginationComponent: React.FC<BasePaginationProps> = ({
+  totalItems,
+  progress,
+  activeColor,
+  size,
+  style,
+}) => {
+  const fontSize = size * 2;
+
+  return (
+    <View
+      style={[styles.container, style]}
+      accessibilityRole="text"
+      accessibilityLabel={`Page ${Math.round(progress.value) + 1} of ${totalItems}`}
+    >
+      <NumberDisplay
+        progress={progress}
+        totalItems={totalItems}
+        color={activeColor}
+        fontSize={fontSize}
+      />
+    </View>
+  );
+};
+
+NumberPaginationComponent.displayName = 'NumberPagination';
+
+/** Props for the number display */
+interface NumberDisplayProps {
+  progress: SharedValue<number>;
+  totalItems: number;
+  color: string;
+  fontSize: number;
+}
+
+/** Animated number display showing current/total */
+const NumberDisplay: React.FC<NumberDisplayProps> = memo(({
+  progress,
+  totalItems,
+  color,
+  fontSize,
+}) => {
+  const animatedStyle = useAnimatedStyle(() => {
+    const opacity = interpolate(
+      Math.abs(progress.value - Math.round(progress.value)),
+      [0, 0.5],
+      [1, 0.5],
+      Extrapolation.CLAMP
+    );
+
+    return { opacity };
+  });
+
+  const currentPage = Math.round(progress.value) + 1;
+
+  return (
+    <Animated.View style={[styles.numberContainer, animatedStyle]}>
+      <Text style={[styles.currentNumber, { color, fontSize }]}>
+        {currentPage}
+      </Text>
+      <Text style={[styles.separator, { color, fontSize: fontSize * 0.8 }]}>
+        {' / '}
+      </Text>
+      <Text style={[styles.totalNumber, { color, fontSize: fontSize * 0.8 }]}>
+        {totalItems}
+      </Text>
+    </Animated.View>
+  );
+});
+
+NumberDisplay.displayName = 'NumberDisplay';
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: 12,
+  },
+  numberContainer: {
+    flexDirection: 'row',
+    alignItems: 'baseline',
+  },
+  currentNumber: {
+    fontWeight: '700',
+    fontVariant: ['tabular-nums'],
+  },
+  separator: {
+    fontWeight: '400',
+    opacity: 0.6,
+  },
+  totalNumber: {
+    fontWeight: '400',
+    opacity: 0.6,
+    fontVariant: ['tabular-nums'],
+  },
+});
+
+export const NumberPagination = memo(NumberPaginationComponent);

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,82 @@
+/**
+ * @file Pagination component
+ * @description Main pagination component that dispatches to the correct pagination style
+ */
+
+import React, { memo } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+import type { PaginationConfig } from '../../types';
+import { DotPagination } from './DotPagination';
+import { BarPagination } from './BarPagination';
+import { NumberPagination } from './NumberPagination';
+import { ProgressPagination } from './ProgressPagination';
+import { CustomPagination } from './CustomPagination';
+import {
+  DEFAULT_PAGINATION_ACTIVE_COLOR,
+  DEFAULT_PAGINATION_INACTIVE_COLOR,
+  DEFAULT_PAGINATION_SIZE,
+  DEFAULT_PAGINATION_GAP,
+} from '../../utils/constants';
+
+/** Props for the main Pagination component */
+export interface PaginationProps {
+  /** Pagination configuration */
+  config: PaginationConfig;
+  /** Total number of items */
+  totalItems: number;
+  /** Current page progress shared value */
+  progress: SharedValue<number>;
+  /** Navigate to specific index */
+  goToIndex: (index: number) => void;
+}
+
+/**
+ * Main pagination component.
+ * Renders the appropriate pagination style based on configuration.
+ */
+const PaginationComponent: React.FC<PaginationProps> = ({
+  config,
+  totalItems,
+  progress,
+  goToIndex,
+}) => {
+  const baseProps = {
+    totalItems,
+    progress,
+    activeColor: config.activeColor ?? DEFAULT_PAGINATION_ACTIVE_COLOR,
+    inactiveColor: config.inactiveColor ?? DEFAULT_PAGINATION_INACTIVE_COLOR,
+    size: config.size ?? DEFAULT_PAGINATION_SIZE,
+    gap: config.gap ?? DEFAULT_PAGINATION_GAP,
+    goToIndex,
+    style: config.style,
+  };
+
+  switch (config.type) {
+    case 'dot':
+      return <DotPagination {...baseProps} />;
+    case 'bar':
+      return <BarPagination {...baseProps} />;
+    case 'number':
+      return <NumberPagination {...baseProps} />;
+    case 'progress':
+      return <ProgressPagination {...baseProps} />;
+    case 'custom':
+      if (config.renderCustom) {
+        return (
+          <CustomPagination
+            totalItems={totalItems}
+            progress={progress}
+            goToIndex={goToIndex}
+            renderCustom={config.renderCustom}
+          />
+        );
+      }
+      return null;
+    default:
+      return <DotPagination {...baseProps} />;
+  }
+};
+
+PaginationComponent.displayName = 'Pagination';
+
+export const Pagination = memo(PaginationComponent);

package/src/components/Pagination/ProgressPagination.tsx

@@ -0,0 +1,70 @@
+/**
+ * @file ProgressPagination component
+ * @description Progress bar pagination indicator
+ */
+
+import React, { memo } from 'react';
+import { StyleSheet, View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated';
+import type { BasePaginationProps } from '../../types';
+
+/** Progress bar height */
+const PROGRESS_HEIGHT = 3;
+
+/**
+ * Progress bar pagination indicator.
+ * Shows overall carousel progress as a horizontal bar.
+ */
+const ProgressPaginationComponent: React.FC<BasePaginationProps> = ({
+  totalItems,
+  progress,
+  activeColor,
+  inactiveColor,
+  style,
+}) => {
+  const animatedStyle = useAnimatedStyle(() => {
+    const fraction = totalItems > 1
+      ? (progress.value / (totalItems - 1)) * 100
+      : 0;
+    return {
+      width: `${Math.max(0, Math.min(100, fraction))}%`,
+    };
+  });
+
+  return (
+    <View style={[styles.container, style]}>
+      <View style={[styles.track, { backgroundColor: inactiveColor }]}>
+        <Animated.View
+          style={[
+            styles.fill,
+            { backgroundColor: activeColor },
+            animatedStyle,
+          ]}
+        />
+      </View>
+    </View>
+  );
+};
+
+ProgressPaginationComponent.displayName = 'ProgressPagination';
+
+const styles = StyleSheet.create({
+  container: {
+    paddingVertical: 12,
+    paddingHorizontal: 16,
+  },
+  track: {
+    height: PROGRESS_HEIGHT,
+    borderRadius: PROGRESS_HEIGHT / 2,
+    overflow: 'hidden',
+  },
+  fill: {
+    height: '100%',
+    borderRadius: PROGRESS_HEIGHT / 2,
+  },
+});
+
+export const ProgressPagination = memo(ProgressPaginationComponent);

package/src/components/Pagination/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @file Pagination module exports
+ * @description Re-exports pagination components
+ */
+
+export { Pagination } from './Pagination';
+export { DotPagination } from './DotPagination';
+export { BarPagination } from './BarPagination';
+export { NumberPagination } from './NumberPagination';
+export { ProgressPagination } from './ProgressPagination';
+export { CustomPagination } from './CustomPagination';

package/src/components/ParallaxImage.tsx

@@ -0,0 +1,89 @@
+/**
+ * @file ParallaxImage component
+ * @description Image component with built-in parallax scrolling effect
+ */
+
+import React, { memo } from 'react';
+import { StyleSheet, type ImageSourcePropType, type ViewStyle, type StyleProp } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  interpolate,
+  Extrapolation,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+/** Props for the ParallaxImage component */
+export interface ParallaxImageProps {
+  /** Image source */
+  source: ImageSourcePropType;
+  /** Container width */
+  width: number;
+  /** Container height */
+  height: number;
+  /** Animated scroll progress for this item */
+  progress: SharedValue<number>;
+  /** Parallax movement factor (default: 0.3) */
+  parallaxFactor?: number;
+  /** Custom container style */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Parallax-aware image component for carousel items.
+ * The image moves at a different speed than the container
+ * to create a depth parallax effect.
+ */
+const ParallaxImageComponent: React.FC<ParallaxImageProps> = ({
+  source,
+  width,
+  height,
+  progress,
+  parallaxFactor = 0.3,
+  style,
+}) => {
+  const PARALLAX_OFFSET = width * parallaxFactor;
+
+  const animatedImageStyle = useAnimatedStyle(() => {
+    const translateX = interpolate(
+      progress.value,
+      [-1, 0, 1],
+      [-PARALLAX_OFFSET, 0, PARALLAX_OFFSET],
+      Extrapolation.CLAMP
+    );
+
+    return {
+      transform: [{ translateX }],
+    };
+  });
+
+  return (
+    <Animated.View style={[styles.container, { width, height }, style]}>
+      <Animated.Image
+        source={source}
+        style={[
+          styles.image,
+          {
+            width: width + PARALLAX_OFFSET * 2,
+            height,
+            left: -PARALLAX_OFFSET,
+          },
+          animatedImageStyle,
+        ]}
+        resizeMode="cover"
+      />
+    </Animated.View>
+  );
+};
+
+ParallaxImageComponent.displayName = 'ParallaxImage';
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+  },
+  image: {
+    position: 'absolute',
+  },
+});
+
+export const ParallaxImage = memo(ParallaxImageComponent);

package/src/gestures/FlingGestureManager.ts

@@ -0,0 +1,49 @@
+/**
+ * @file Fling gesture manager
+ * @description Handles fling gesture for quick navigation between carousel items
+ */
+
+import { Gesture } from 'react-native-gesture-handler';
+import { useMemo } from 'react';
+
+/** Options for fling gesture configuration */
+export interface FlingGestureOptions {
+  /** Whether the carousel scrolls horizontally */
+  isHorizontal: boolean;
+  /** Whether fling gesture is enabled */
+  enabled: boolean;
+  /** Callback when fling is detected in forward direction */
+  onFlingForward: () => void;
+  /** Callback when fling is detected in backward direction */
+  onFlingBackward: () => void;
+}
+
+/**
+ * Creates fling gestures for quick carousel navigation.
+ *
+ * @param options - Fling gesture configuration
+ * @returns Composed fling gesture
+ */
+export const useFlingGesture = (options: FlingGestureOptions) => {
+  const { isHorizontal, enabled, onFlingForward, onFlingBackward } = options;
+
+  const flingForward = useMemo(() => {
+    return Gesture.Fling()
+      .direction(isHorizontal ? 1 : 8)
+      .enabled(enabled)
+      .onEnd(() => {
+        onFlingBackward();
+      });
+  }, [isHorizontal, enabled, onFlingBackward]);
+
+  const flingBackward = useMemo(() => {
+    return Gesture.Fling()
+      .direction(isHorizontal ? 2 : 4)
+      .enabled(enabled)
+      .onEnd(() => {
+        onFlingForward();
+      });
+  }, [isHorizontal, enabled, onFlingForward]);
+
+  return { flingForward, flingBackward };
+};