react-native-ultra-carousel 0.1.0

package/src/types/pagination.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Pagination type definitions
+ * @description Types for pagination indicators and controls
+ */
+
+import type { ViewStyle, StyleProp } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+
+/** Pagination display type */
+export type PaginationType = 'dot' | 'bar' | 'number' | 'progress' | 'custom';
+
+/** Pagination position relative to the carousel */
+export type PaginationPosition = 'top' | 'bottom' | 'left' | 'right';
+
+/** Information passed to custom pagination renderer */
+export interface PaginationRenderInfo {
+  /** Current active index */
+  currentIndex: number;
+  /** Total number of items */
+  totalItems: number;
+  /** Animated scroll progress */
+  progress: SharedValue<number>;
+  /** Navigate to specific index */
+  goToIndex: (index: number) => void;
+}
+
+/** Pagination configuration */
+export interface PaginationConfig {
+  /** Type of pagination indicator */
+  type: PaginationType;
+  /** Position relative to carousel */
+  position?: PaginationPosition;
+  /** Color of active indicator */
+  activeColor?: string;
+  /** Color of inactive indicators */
+  inactiveColor?: string;
+  /** Size of indicator elements */
+  size?: number;
+  /** Gap between indicators */
+  gap?: number;
+  /** Custom style for pagination container */
+  style?: StyleProp<ViewStyle>;
+  /** Custom render function for pagination */
+  renderCustom?: (info: PaginationRenderInfo) => React.ReactNode;
+}
+
+/** Props shared across all pagination components */
+export interface BasePaginationProps {
+  /** Total number of items */
+  totalItems: number;
+  /** Animated scroll progress value */
+  progress: SharedValue<number>;
+  /** Active indicator color */
+  activeColor: string;
+  /** Inactive indicator color */
+  inactiveColor: string;
+  /** Indicator size */
+  size: number;
+  /** Gap between indicators */
+  gap: number;
+  /** Navigate to specific index */
+  goToIndex: (index: number) => void;
+  /** Container style */
+  style?: StyleProp<ViewStyle>;
+}

package/src/types/plugin.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Plugin type definitions
+ * @description Types for the carousel plugin system
+ */
+
+import type { AnimatedItemStyle } from './animation';
+import type { CarouselRef } from './carousel';
+
+/** Plugin interface for extending carousel behavior */
+export interface CarouselPlugin {
+  /** Unique plugin name */
+  name: string;
+  /** Called when carousel initializes */
+  onInit?: (carousel: CarouselRef) => void;
+  /** Called on each animation frame (MUST be a worklet) */
+  onAnimate?: (progress: number, index: number) => AnimatedItemStyle | void;
+  /** Called when active index changes */
+  onIndexChange?: (index: number) => void;
+  /** Called when carousel is destroyed */
+  onDestroy?: () => void;
+}
+
+/** Options for creating a plugin */
+export type CreatePluginOptions = Omit<CarouselPlugin, 'name'> & {
+  /** Unique plugin name */
+  name: string;
+};

package/src/utils/accessibility.ts

@@ -0,0 +1,71 @@
+/**
+ * @file Accessibility utility functions
+ * @description Helpers for building accessible carousel experiences
+ */
+
+import type { AccessibilityProps } from 'react-native';
+
+/**
+ * Generates accessibility props for the carousel container.
+ *
+ * @param label - Custom accessibility label
+ * @param currentIndex - Current active index
+ * @param totalItems - Total number of items
+ * @returns Accessibility props object
+ */
+export const getCarouselAccessibilityProps = (
+  label: string | undefined,
+  currentIndex: number,
+  totalItems: number
+): AccessibilityProps => ({
+  accessible: true,
+  accessibilityRole: 'adjustable',
+  accessibilityLabel: label ?? 'Carousel',
+  accessibilityValue: {
+    text: `Item ${currentIndex + 1} of ${totalItems}`,
+    min: 0,
+    max: totalItems - 1,
+    now: currentIndex,
+  },
+  accessibilityActions: [
+    { name: 'increment', label: 'Next item' },
+    { name: 'decrement', label: 'Previous item' },
+  ],
+});
+
+/**
+ * Generates accessibility props for a carousel item.
+ *
+ * @param index - Item index
+ * @param totalItems - Total number of items
+ * @param isActive - Whether this item is currently active
+ * @returns Accessibility props for the item
+ */
+export const getItemAccessibilityProps = (
+  index: number,
+  totalItems: number,
+  isActive: boolean
+): AccessibilityProps => ({
+  accessible: true,
+  accessibilityRole: 'button',
+  accessibilityLabel: `Item ${index + 1} of ${totalItems}`,
+  accessibilityState: {
+    selected: isActive,
+  },
+});
+
+/**
+ * Generates accessibility props for pagination.
+ *
+ * @param currentIndex - Current active page
+ * @param totalItems - Total number of pages
+ * @returns Accessibility props for pagination container
+ */
+export const getPaginationAccessibilityProps = (
+  currentIndex: number,
+  totalItems: number
+): AccessibilityProps => ({
+  accessible: true,
+  accessibilityRole: 'tablist' as AccessibilityProps['accessibilityRole'],
+  accessibilityLabel: `Page ${currentIndex + 1} of ${totalItems}`,
+});

package/src/utils/constants.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Default constants and configuration values
+ * @description Central location for all magic numbers and default settings
+ */
+
+import { Dimensions } from 'react-native';
+
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get('window');
+
+/** Default carousel dimensions */
+export const DEFAULT_WIDTH = SCREEN_WIDTH;
+export const DEFAULT_HEIGHT = 250;
+
+/** Default animation spring config */
+export const DEFAULT_SPRING_CONFIG = {
+  damping: 20,
+  stiffness: 200,
+  mass: 1,
+  overshootClamping: false,
+  restDisplacementThreshold: 0.01,
+  restSpeedThreshold: 0.01,
+} as const;
+
+/** Default gesture thresholds */
+export const DEFAULT_ACTIVE_OFFSET_X: [number, number] = [-10, 10];
+export const DEFAULT_ACTIVE_OFFSET_Y: [number, number] = [-50, 50];
+export const DEFAULT_VELOCITY_THRESHOLD = 500;
+
+/** Default auto play settings */
+export const DEFAULT_AUTO_PLAY_INTERVAL = 3000;
+
+/** Default pagination settings */
+export const DEFAULT_PAGINATION_ACTIVE_COLOR = '#007AFF';
+export const DEFAULT_PAGINATION_INACTIVE_COLOR = '#C7C7CC';
+export const DEFAULT_PAGINATION_SIZE = 8;
+export const DEFAULT_PAGINATION_GAP = 6;
+
+/** Virtualization defaults */
+export const DEFAULT_RENDER_BUFFER = 2;
+
+/** Accessibility minimum touch target size */
+export const MIN_TOUCH_TARGET = 44;
+
+/** Screen dimensions for reference */
+export { SCREEN_WIDTH, SCREEN_HEIGHT };

package/src/utils/layout.ts

@@ -0,0 +1,115 @@
+/**
+ * @file Layout calculation utilities
+ * @description Helpers for carousel layout, snap points, and item positioning
+ */
+
+import type { SnapAlignment } from '../types';
+import { DEFAULT_WIDTH } from './constants';
+
+/**
+ * Calculates the offset for snap alignment.
+ *
+ * @param containerSize - Container width or height
+ * @param itemSize - Item width or height
+ * @param alignment - Snap alignment mode
+ * @returns Alignment offset in pixels
+ */
+export const getAlignmentOffset = (
+  containerSize: number,
+  itemSize: number,
+  alignment: SnapAlignment
+): number => {
+  'worklet';
+  switch (alignment) {
+    case 'start':
+      return 0;
+    case 'center':
+      return (containerSize - itemSize) / 2;
+    case 'end':
+      return containerSize - itemSize;
+  }
+};
+
+/**
+ * Calculates snap point for a given index.
+ *
+ * @param index - Item index
+ * @param itemSize - Item width or height
+ * @param gap - Gap between items
+ * @param alignmentOffset - Offset from alignment calculation
+ * @returns Snap point offset in pixels
+ */
+export const getSnapPoint = (
+  index: number,
+  itemSize: number,
+  gap: number,
+  alignmentOffset: number
+): number => {
+  'worklet';
+  return index * (itemSize + gap) - alignmentOffset;
+};
+
+/**
+ * Calculates all snap points for the carousel.
+ *
+ * @param totalItems - Number of items
+ * @param itemSize - Item width or height
+ * @param gap - Gap between items
+ * @param containerSize - Container width or height
+ * @param alignment - Snap alignment
+ * @returns Array of snap point offsets
+ */
+export const calculateSnapPoints = (
+  totalItems: number,
+  itemSize: number,
+  gap: number,
+  containerSize: number,
+  alignment: SnapAlignment
+): number[] => {
+  const offset = getAlignmentOffset(containerSize, itemSize, alignment);
+  const points: number[] = [];
+  for (let i = 0; i < totalItems; i++) {
+    points.push(getSnapPoint(i, itemSize, gap, offset));
+  }
+  return points;
+};
+
+/**
+ * Finds the nearest snap point index for a given offset.
+ *
+ * @param offset - Current scroll offset
+ * @param snapPoints - Array of snap point offsets
+ * @returns Index of the nearest snap point
+ */
+export const findNearestSnapIndex = (
+  offset: number,
+  snapPoints: number[]
+): number => {
+  'worklet';
+  let nearestIndex = 0;
+  let nearestDistance = Math.abs(offset - snapPoints[0]);
+
+  for (let i = 1; i < snapPoints.length; i++) {
+    const distance = Math.abs(offset - snapPoints[i]);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearestIndex = i;
+    }
+  }
+
+  return nearestIndex;
+};
+
+/**
+ * Calculates effective item size, defaulting to container width.
+ *
+ * @param itemSize - Explicit item size (or undefined)
+ * @param containerSize - Container size as fallback
+ * @returns Effective item size
+ */
+export const getEffectiveItemSize = (
+  itemSize: number | undefined,
+  containerSize: number | undefined
+): number => {
+  return itemSize ?? containerSize ?? DEFAULT_WIDTH;
+};

package/src/utils/math.ts

@@ -0,0 +1,78 @@
+/**
+ * @file Math utility functions
+ * @description Shared mathematical helpers for animations and layout
+ */
+
+/**
+ * Clamps a value between a minimum and maximum.
+ *
+ * @param value - The value to clamp
+ * @param min - Minimum bound
+ * @param max - Maximum bound
+ * @returns Clamped value
+ */
+export const clamp = (value: number, min: number, max: number): number => {
+  'worklet';
+  return Math.min(Math.max(value, min), max);
+};
+
+/**
+ * Linearly interpolates between two values.
+ *
+ * @param from - Start value
+ * @param to - End value
+ * @param progress - Interpolation factor (0 to 1)
+ * @returns Interpolated value
+ */
+export const lerp = (from: number, to: number, progress: number): number => {
+  'worklet';
+  return from + (to - from) * progress;
+};
+
+/**
+ * Normalizes a value from one range to another.
+ *
+ * @param value - Input value
+ * @param inputMin - Input range minimum
+ * @param inputMax - Input range maximum
+ * @param outputMin - Output range minimum
+ * @param outputMax - Output range maximum
+ * @returns Normalized value
+ */
+export const normalize = (
+  value: number,
+  inputMin: number,
+  inputMax: number,
+  outputMin: number = 0,
+  outputMax: number = 1
+): number => {
+  'worklet';
+  const inputRange = inputMax - inputMin;
+  if (inputRange === 0) return outputMin;
+  const normalized = (value - inputMin) / inputRange;
+  return outputMin + normalized * (outputMax - outputMin);
+};
+
+/**
+ * Converts degrees to radians.
+ *
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ */
+export const toRadians = (degrees: number): number => {
+  'worklet';
+  return (degrees * Math.PI) / 180;
+};
+
+/**
+ * Wraps an index within bounds (for loop mode).
+ *
+ * @param index - The index to wrap
+ * @param total - Total number of items
+ * @returns Wrapped index
+ */
+export const wrapIndex = (index: number, total: number): number => {
+  'worklet';
+  if (total === 0) return 0;
+  return ((index % total) + total) % total;
+};

package/src/utils/platform.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Platform-specific utility helpers
+ * @description Abstractions for platform differences between iOS and Android
+ */
+
+import { Platform, AccessibilityInfo } from 'react-native';
+
+/** Whether the current platform is iOS */
+export const isIOS = Platform.OS === 'ios';
+
+/** Whether the current platform is Android */
+export const isAndroid = Platform.OS === 'android';
+
+/** Whether the current platform is web */
+export const isWeb = Platform.OS === 'web';
+
+/**
+ * Checks if a screen reader is currently active.
+ *
+ * @returns Promise resolving to true if screen reader is enabled
+ */
+export const isScreenReaderEnabled = async (): Promise<boolean> => {
+  return AccessibilityInfo.isScreenReaderEnabled();
+};
+
+/**
+ * Checks if reduce motion is enabled in system settings.
+ *
+ * @returns Promise resolving to true if reduce motion is on
+ */
+export const isReduceMotionEnabled = async (): Promise<boolean> => {
+  return AccessibilityInfo.isReduceMotionEnabled();
+};