react-native-ultra-carousel 0.1.0

package/src/components/Carousel.tsx

@@ -0,0 +1,371 @@
+/**
+ * @file Carousel component
+ * @description Main carousel component with gesture handling, animations, and accessibility
+ */
+
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { StyleSheet, View } from 'react-native';
+import { GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler';
+import { useSharedValue, runOnJS } from 'react-native-reanimated';
+import type { CarouselProps, CarouselRef, CustomAnimationFn } from '../types';
+import { CarouselItem } from './CarouselItem';
+import { Pagination } from './Pagination';
+import { AutoPlayController } from './AutoPlayController';
+import { useCarouselGesture } from '../hooks/useCarouselGesture';
+import { useSnapPoints } from '../hooks/useSnapPoints';
+import { usePagination } from '../hooks/usePagination';
+import type { UseAutoPlayReturn } from '../hooks/useAutoPlay';
+import { getEffectiveItemSize } from '../utils/layout';
+import { getCarouselAccessibilityProps } from '../utils/accessibility';
+import {
+  DEFAULT_WIDTH,
+  DEFAULT_HEIGHT,
+  DEFAULT_PAGINATION_ACTIVE_COLOR,
+  DEFAULT_PAGINATION_INACTIVE_COLOR,
+  DEFAULT_PAGINATION_SIZE,
+  DEFAULT_PAGINATION_GAP,
+} from '../utils/constants';
+import { clamp } from '../utils/math';
+
+/**
+ * The main Carousel component.
+ * Provides gesture-driven navigation, animation presets, pagination, and auto play.
+ *
+ * @example
+ * ```tsx
+ * <Carousel
+ *   data={items}
+ *   renderItem={({ item }) => <Card item={item} />}
+ *   preset="coverflow"
+ *   pagination
+ *   autoPlay
+ * />
+ * ```
+ */
+const CarouselComponent = <T,>(
+  props: CarouselProps<T>,
+  ref: React.Ref<CarouselRef>
+) => {
+  const {
+    data,
+    renderItem,
+    preset = 'slide',
+    animationConfig,
+    width: containerWidth = DEFAULT_WIDTH,
+    height: containerHeight = DEFAULT_HEIGHT,
+    itemWidth: itemWidthProp,
+    itemHeight: itemHeightProp,
+    direction = 'horizontal',
+    gap = 0,
+    snapAlignment = 'center',
+    loop = false,
+    initialIndex = 0,
+    enabled = true,
+    autoPlay,
+    autoPlayInterval,
+    pagination,
+    gestureConfig,
+    onIndexChange,
+    onScrollStart,
+    onScrollEnd,
+    scrollProgress: externalScrollProgress,
+    plugins,
+    maxRenderItems = 0,
+    renderBuffer = 2,
+    accessible = true,
+    accessibilityLabel,
+    style,
+    itemStyle,
+  } = props;
+
+  const isHorizontal = direction === 'horizontal';
+  const containerSize = isHorizontal ? containerWidth : containerHeight;
+  const itemWidth = getEffectiveItemSize(itemWidthProp, containerWidth);
+  const itemHeight = getEffectiveItemSize(itemHeightProp, containerHeight);
+  const itemSize = isHorizontal ? itemWidth : itemHeight;
+  const totalItems = data.length;
+
+  const [currentIndex, setCurrentIndex] = useState(initialIndex);
+  const autoPlayRef = useRef<UseAutoPlayReturn | null>(null);
+
+  const snapPoints = useSnapPoints(
+    totalItems,
+    itemSize,
+    gap,
+    containerSize,
+    snapAlignment
+  );
+
+  const handleIndexChange = useCallback(
+    (index: number) => {
+      setCurrentIndex(index);
+      onIndexChange?.(index);
+
+      plugins?.forEach((plugin) => {
+        plugin.onIndexChange?.(index);
+      });
+    },
+    [onIndexChange, plugins]
+  );
+
+  const {
+    gesture,
+    offset,
+    activeIndex,
+    snapToIndex,
+  } = useCarouselGesture({
+    totalItems,
+    itemSize,
+    gap,
+    snapPoints,
+    direction,
+    loop,
+    enabled,
+    gestureConfig,
+    onIndexChange: handleIndexChange,
+    onScrollStart,
+    onScrollEnd,
+  });
+
+  const { currentPage } = usePagination(offset, itemSize, gap, totalItems);
+
+  useEffect(() => {
+    if (externalScrollProgress) {
+      externalScrollProgress.value = offset.value;
+    }
+  });
+
+  useEffect(() => {
+    if (initialIndex > 0 && initialIndex < totalItems) {
+      snapToIndex(initialIndex, false);
+    }
+  }, []);
+
+  useEffect(() => {
+    plugins?.forEach((plugin) => {
+      plugin.onInit?.(carouselRef);
+    });
+
+    return () => {
+      plugins?.forEach((plugin) => {
+        plugin.onDestroy?.();
+      });
+    };
+  }, [plugins]);
+
+  const carouselRef: CarouselRef = useMemo(
+    () => ({
+      scrollTo: (index: number, animated = true) => {
+        const clampedIndex = loop ? index : clamp(index, 0, totalItems - 1);
+        snapToIndex(clampedIndex, animated);
+      },
+      next: (animated = true) => {
+        const nextIndex = loop
+          ? (currentIndex + 1) % totalItems
+          : Math.min(currentIndex + 1, totalItems - 1);
+        snapToIndex(nextIndex, animated);
+      },
+      prev: (animated = true) => {
+        const prevIndex = loop
+          ? (currentIndex - 1 + totalItems) % totalItems
+          : Math.max(currentIndex - 1, 0);
+        snapToIndex(prevIndex, animated);
+      },
+      getCurrentIndex: () => currentIndex,
+      startAutoPlay: () => autoPlayRef.current?.start(),
+      stopAutoPlay: () => autoPlayRef.current?.stop(),
+      pauseAutoPlay: () => autoPlayRef.current?.pause(),
+    }),
+    [currentIndex, totalItems, loop, snapToIndex]
+  );
+
+  useImperativeHandle(ref, () => carouselRef, [carouselRef]);
+
+  const handleAutoPlayAdvance = useCallback(
+    (advanceDirection: 'forward' | 'backward') => {
+      if (advanceDirection === 'forward') {
+        carouselRef.next();
+      } else {
+        carouselRef.prev();
+      }
+    },
+    [carouselRef]
+  );
+
+  const handleAutoPlayControlsReady = useCallback(
+    (controls: UseAutoPlayReturn) => {
+      autoPlayRef.current = controls;
+    },
+    []
+  );
+
+  const autoPlayConfig = useMemo(() => {
+    if (typeof autoPlay === 'boolean') {
+      return {
+        enabled: autoPlay,
+        interval: autoPlayInterval,
+      };
+    }
+    return autoPlay;
+  }, [autoPlay, autoPlayInterval]);
+
+  const a11yProps = accessible
+    ? getCarouselAccessibilityProps(accessibilityLabel, currentIndex, totalItems)
+    : {};
+
+  const handleAccessibilityAction = useCallback(
+    (event: { nativeEvent: { actionName: string } }) => {
+      switch (event.nativeEvent.actionName) {
+        case 'increment':
+          carouselRef.next();
+          break;
+        case 'decrement':
+          carouselRef.prev();
+          break;
+      }
+    },
+    [carouselRef]
+  );
+
+  const paginationConfig = useMemo(() => {
+    if (!pagination) return null;
+    if (typeof pagination === 'boolean') {
+      return {
+        type: 'dot' as const,
+        activeColor: DEFAULT_PAGINATION_ACTIVE_COLOR,
+        inactiveColor: DEFAULT_PAGINATION_INACTIVE_COLOR,
+        size: DEFAULT_PAGINATION_SIZE,
+        gap: DEFAULT_PAGINATION_GAP,
+      };
+    }
+    return {
+      ...pagination,
+      activeColor: pagination.activeColor ?? DEFAULT_PAGINATION_ACTIVE_COLOR,
+      inactiveColor: pagination.inactiveColor ?? DEFAULT_PAGINATION_INACTIVE_COLOR,
+      size: pagination.size ?? DEFAULT_PAGINATION_SIZE,
+      gap: pagination.gap ?? DEFAULT_PAGINATION_GAP,
+    };
+  }, [pagination]);
+
+  const goToIndex = useCallback(
+    (index: number) => {
+      carouselRef.scrollTo(index);
+    },
+    [carouselRef]
+  );
+
+  const renderItems = useMemo(() => {
+    return data.map((item, index) => {
+      const isActive = index === currentIndex;
+      const progress = useSharedValue(0);
+
+      return (
+        <CarouselItem
+          key={index}
+          index={index}
+          totalItems={totalItems}
+          scrollOffset={offset}
+          itemWidth={itemWidth}
+          itemHeight={itemHeight}
+          gap={gap}
+          preset={preset as string | CustomAnimationFn}
+          animationConfig={animationConfig}
+          isActive={isActive}
+          accessible={accessible}
+          style={itemStyle}
+        >
+          {renderItem({
+            item,
+            index,
+            animationProgress: progress,
+            isActive,
+          })}
+        </CarouselItem>
+      );
+    });
+  }, [
+    data,
+    currentIndex,
+    totalItems,
+    offset,
+    itemWidth,
+    itemHeight,
+    gap,
+    preset,
+    animationConfig,
+    accessible,
+    itemStyle,
+    renderItem,
+  ]);
+
+  return (
+    <GestureHandlerRootView style={styles.root}>
+      <View
+        style={[
+          styles.container,
+          {
+            width: containerWidth,
+            height: containerHeight,
+            flexDirection: isHorizontal ? 'row' : 'column',
+          },
+          style,
+        ]}
+        {...a11yProps}
+        onAccessibilityAction={handleAccessibilityAction}
+      >
+        <GestureDetector gesture={gesture}>
+          <View style={styles.gestureContainer}>
+            {renderItems}
+          </View>
+        </GestureDetector>
+
+        {paginationConfig && (
+          <Pagination
+            config={paginationConfig}
+            totalItems={totalItems}
+            progress={currentPage}
+            goToIndex={goToIndex}
+          />
+        )}
+
+        {autoPlayConfig && (
+          <AutoPlayController
+            config={autoPlayConfig}
+            onAdvance={handleAutoPlayAdvance}
+            onControlsReady={handleAutoPlayControlsReady}
+          />
+        )}
+      </View>
+    </GestureHandlerRootView>
+  );
+};
+
+CarouselComponent.displayName = 'Carousel';
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 0,
+  },
+  container: {
+    overflow: 'hidden',
+    position: 'relative',
+  },
+  gestureContainer: {
+    flex: 1,
+    position: 'relative',
+  },
+});
+
+export const Carousel = forwardRef(CarouselComponent) as <T>(
+  props: CarouselProps<T> & { ref?: React.Ref<CarouselRef> }
+) => React.ReactElement;
+
+(Carousel as React.FC).displayName = 'Carousel';

package/src/components/CarouselItem.tsx

@@ -0,0 +1,98 @@
+/**
+ * @file CarouselItem component
+ * @description Wraps each carousel item with animation and accessibility
+ */
+
+import React, { memo } from 'react';
+import { StyleSheet, type ViewStyle, type StyleProp } from 'react-native';
+import Animated, { type SharedValue } from 'react-native-reanimated';
+import type { CustomAnimationFn } from '../types';
+import { useAnimationProgress } from '../hooks/useAnimationProgress';
+import { useItemAnimation } from '../hooks/useItemAnimation';
+import { getItemAccessibilityProps } from '../utils/accessibility';
+
+/** Props for the CarouselItem component */
+export interface CarouselItemProps {
+  /** Item index in the data array */
+  index: number;
+  /** Total number of items */
+  totalItems: number;
+  /** Current scroll offset shared value */
+  scrollOffset: SharedValue<number>;
+  /** Item width in pixels */
+  itemWidth: number;
+  /** Item height in pixels */
+  itemHeight: number;
+  /** Gap between items */
+  gap: number;
+  /** Animation preset name or custom function */
+  preset?: string | CustomAnimationFn;
+  /** Animation config overrides */
+  animationConfig?: Record<string, number>;
+  /** Whether this item is currently active */
+  isActive: boolean;
+  /** Whether accessibility features are enabled */
+  accessible: boolean;
+  /** Custom item container style */
+  style?: StyleProp<ViewStyle>;
+  /** Content to render inside the item */
+  children: React.ReactNode;
+}
+
+/**
+ * Individual carousel item wrapper component.
+ * Applies animation transforms based on scroll progress.
+ */
+const CarouselItemComponent: React.FC<CarouselItemProps> = ({
+  index,
+  totalItems,
+  scrollOffset,
+  itemWidth,
+  itemHeight,
+  gap,
+  preset,
+  animationConfig,
+  isActive,
+  accessible,
+  style,
+  children,
+}) => {
+  const progress = useAnimationProgress(index, scrollOffset, itemWidth, gap);
+  const animatedStyle = useItemAnimation(
+    progress,
+    preset,
+    animationConfig,
+    index,
+    totalItems
+  );
+
+  const a11yProps = accessible
+    ? getItemAccessibilityProps(index, totalItems, isActive)
+    : {};
+
+  return (
+    <Animated.View
+      style={[
+        styles.item,
+        { width: itemWidth, height: itemHeight },
+        animatedStyle,
+        style,
+      ]}
+      {...a11yProps}
+    >
+      {children}
+    </Animated.View>
+  );
+};
+
+CarouselItemComponent.displayName = 'CarouselItem';
+
+const styles = StyleSheet.create({
+  item: {
+    justifyContent: 'center',
+    alignItems: 'center',
+    overflow: 'hidden',
+  },
+});
+
+export const CarouselItem = memo(CarouselItemComponent);

package/src/components/Pagination/BarPagination.tsx

@@ -0,0 +1,141 @@
+/**
+ * @file BarPagination component
+ * @description Thin bar indicators with animated active width
+ */
+
+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';
+
+/** Width multiplier for active bar */
+const ACTIVE_WIDTH_MULTIPLIER = 2.5;
+/** Bar height in pixels */
+const BAR_HEIGHT = 3;
+
+/**
+ * Bar-based pagination indicator.
+ * Active bar stretches wider with smooth animation.
+ */
+const BarPaginationComponent: 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) => (
+        <BarIndicator
+          key={index}
+          index={index}
+          progress={progress}
+          activeColor={activeColor}
+          inactiveColor={inactiveColor}
+          size={size}
+          gap={gap}
+          goToIndex={goToIndex}
+        />
+      ))}
+    </View>
+  );
+};
+
+BarPaginationComponent.displayName = 'BarPagination';
+
+/** Props for an individual bar */
+interface BarIndicatorProps {
+  index: number;
+  progress: SharedValue<number>;
+  activeColor: string;
+  inactiveColor: string;
+  size: number;
+  gap: number;
+  goToIndex: (index: number) => void;
+}
+
+/** Individual animated bar indicator */
+const BarIndicator: React.FC<BarIndicatorProps> = memo(({
+  index,
+  progress,
+  activeColor,
+  inactiveColor,
+  size,
+  gap,
+  goToIndex,
+}) => {
+  const baseWidth = size * 2;
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const distance = Math.abs(progress.value - index);
+
+    const width = interpolate(
+      distance,
+      [0, 1],
+      [baseWidth * ACTIVE_WIDTH_MULTIPLIER, baseWidth],
+      Extrapolation.CLAMP
+    );
+
+    const opacity = interpolate(
+      distance,
+      [0, 1],
+      [1, 0.4],
+      Extrapolation.CLAMP
+    );
+
+    return {
+      width,
+      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.bar,
+          {
+            height: BAR_HEIGHT,
+            borderRadius: BAR_HEIGHT / 2,
+            marginHorizontal: gap / 2,
+            backgroundColor: isActive ? activeColor : inactiveColor,
+          },
+          animatedStyle,
+        ]}
+      />
+    </Pressable>
+  );
+});
+
+BarIndicator.displayName = 'BarIndicator';
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: 12,
+  },
+  bar: {
+    // dynamic styles applied inline
+  },
+});
+
+export const BarPagination = memo(BarPaginationComponent);

package/src/components/Pagination/CustomPagination.tsx

@@ -0,0 +1,48 @@
+/**
+ * @file CustomPagination component
+ * @description Renders user-provided custom pagination via render function
+ */
+
+import React, { memo } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+import type { PaginationRenderInfo } from '../../types';
+
+/** Props for the CustomPagination component */
+export interface CustomPaginationProps {
+  /** Total number of items */
+  totalItems: number;
+  /** Animated scroll progress */
+  progress: SharedValue<number>;
+  /** Navigate to specific index */
+  goToIndex: (index: number) => void;
+  /** User-provided render function */
+  renderCustom: (info: PaginationRenderInfo) => React.ReactNode;
+}
+
+/**
+ * Custom pagination that delegates rendering to a user-provided function.
+ * Passes all pagination state to the render function.
+ */
+const CustomPaginationComponent: React.FC<CustomPaginationProps> = ({
+  totalItems,
+  progress,
+  goToIndex,
+  renderCustom,
+}) => {
+  const currentIndex = Math.round(progress.value);
+
+  return (
+    <>
+      {renderCustom({
+        currentIndex,
+        totalItems,
+        progress,
+        goToIndex,
+      })}
+    </>
+  );
+};
+
+CustomPaginationComponent.displayName = 'CustomPagination';
+
+export const CustomPagination = memo(CustomPaginationComponent);