@souscheflabs/reanimated-flashlist 0.1.7

package/src/hooks/animations/useListEntryAnimation.ts

@@ -0,0 +1,108 @@
+import { useEffect, useRef } from 'react';
+import {
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import {
+  DEFAULT_ENTRY_ANIMATION,
+  standardEasing,
+} from '../../constants/animations';
+import { useListAnimationOptional } from '../../contexts/ListAnimationContext';
+import type { EntryAnimationConfig } from '../../types';
+
+/**
+ * Hook for managing list item entry animations
+ *
+ * Provides coordinated slide and fade animations for items appearing
+ * in a new list (e.g., after being moved via subscription update).
+ *
+ * PERFORMANCE: Uses shared values with static defaults.
+ * Animation only triggers when an entry animation is claimed.
+ *
+ * IMPORTANT: This hook handles FlashList view recycling by accepting an itemId parameter.
+ * When the itemId changes (view recycled for a different item), animation state is reset.
+ *
+ * @param itemId - Unique identifier for the list item (used to detect view recycling)
+ * @param configOverrides - Optional animation configuration overrides
+ * @returns Animation styles for entry effect
+ *
+ * @example
+ * ```tsx
+ * const { entryAnimatedStyle } = useListEntryAnimation(item.id);
+ *
+ * <Animated.View style={[styles.container, entryAnimatedStyle]}>
+ *   {content}
+ * </Animated.View>
+ * ```
+ */
+export const useListEntryAnimation = (
+  itemId: string,
+  configOverrides?: Partial<EntryAnimationConfig>,
+) => {
+  const animationContext = useListAnimationOptional();
+
+  // Merge config with defaults
+  const config = {
+    fade: { ...DEFAULT_ENTRY_ANIMATION.fade, ...configOverrides?.fade },
+    slide: { ...DEFAULT_ENTRY_ANIMATION.slide, ...configOverrides?.slide },
+  };
+
+  // Shared values for entry animation - start at final position (no animation by default)
+  const translateX = useSharedValue(0);
+  const opacity = useSharedValue(1);
+
+  // Track if we've already checked for entry animation for this item
+  const hasCheckedRef = useRef(false);
+  const lastItemIdRef = useRef(itemId);
+
+  // Reset check flag when item ID changes (view recycled)
+  if (lastItemIdRef.current !== itemId) {
+    lastItemIdRef.current = itemId;
+    hasCheckedRef.current = false;
+    // Reset animation values for new item
+    translateX.value = 0;
+    opacity.value = 1;
+  }
+
+  // Check for pending entry animation on mount
+  useEffect(() => {
+    if (!animationContext || hasCheckedRef.current) return;
+
+    hasCheckedRef.current = true;
+
+    const entry = animationContext.claimEntryAnimation(itemId);
+    if (entry) {
+      // Start from offset position (slide in from direction)
+      translateX.value = entry.direction * config.slide.distance;
+      opacity.value = 0;
+
+      // Animate to final position
+      translateX.value = withTiming(0, {
+        duration: config.slide.duration,
+        easing: standardEasing,
+      });
+      opacity.value = withTiming(1, {
+        duration: config.fade.duration,
+        easing: standardEasing,
+      });
+    }
+  }, [itemId, animationContext, translateX, opacity, config.slide, config.fade]);
+
+  // Animated style for entry effect
+  const entryAnimatedStyle = useAnimatedStyle(() => {
+    // Fast path: no animation active (default state)
+    if (translateX.value === 0 && opacity.value === 1) {
+      return {};
+    }
+
+    return {
+      opacity: opacity.value,
+      transform: [{ translateX: translateX.value }],
+    };
+  });
+
+  return {
+    entryAnimatedStyle,
+  };
+};

package/src/hooks/animations/useListExitAnimation.ts

@@ -0,0 +1,197 @@
+import { useCallback, useRef, useEffect } from 'react';
+import {
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+import {
+  FAST_EXIT_ANIMATION,
+  DEFAULT_EXIT_ANIMATION,
+  standardEasing,
+} from '../../constants/animations';
+import type { AnimationDirection, ExitAnimationPreset } from '../../types';
+
+/**
+ * Configuration for exit animation with layout compensation
+ */
+interface UseListExitAnimationConfig {
+  /** Item index in the list (for layout compensation) */
+  index?: number;
+  /** Measured item height (for layout compensation) */
+  measuredHeight?: number;
+  /** Callback when exit animation starts (for registering with context) */
+  onExitStart?: (index: number, height: number) => void;
+  /** Callback when exit animation completes (for unregistering) */
+  onExitComplete?: () => void;
+}
+
+// Animation configs by preset
+const animationConfigs = {
+  default: DEFAULT_EXIT_ANIMATION,
+  fast: FAST_EXIT_ANIMATION,
+} as const;
+
+/**
+ * Hook for managing list item exit animations
+ *
+ * Provides coordinated slide, fade, and scale animations for items
+ * exiting a list (e.g., moving between sections, being deleted).
+ *
+ * PERFORMANCE: Uses eager shared value creation but defers animation calculations.
+ * The animated style returns static values when exitDirection === 0 (no animation),
+ * avoiding expensive animation calculations until the user actually triggers one.
+ *
+ * IMPORTANT: This hook handles FlashList view recycling by accepting an itemId parameter.
+ * When the itemId changes (view recycled for a different item), all animation state is reset.
+ *
+ * @param itemId - Unique identifier for the list item (used to detect view recycling)
+ * @param config - Optional configuration for layout compensation callbacks
+ * @returns Animation styles and trigger functions
+ *
+ * @example
+ * ```tsx
+ * const { exitAnimatedStyle, triggerExit, resetAnimation } = useListExitAnimation(item.id, {
+ *   index,
+ *   measuredHeight: 80,
+ *   onExitStart: (idx, height) => registerExitingItem(itemId, idx, height),
+ *   onExitComplete: () => unregisterExitingItem(itemId),
+ * });
+ *
+ * // Trigger exit animation
+ * triggerExit(1, () => {
+ *   onItemRemoved(item.id);
+ * });
+ *
+ * // Apply styles
+ * <Animated.View style={exitAnimatedStyle}>
+ *   {content}
+ * </Animated.View>
+ * ```
+ */
+export const useListExitAnimation = (
+  itemId: string,
+  config?: UseListExitAnimationConfig,
+) => {
+  // Shared value for exit direction - created eagerly but idle until animation triggers
+  // Value: 0 = no animation, 1 = animating right, -1 = animating left
+  const exitDirection = useSharedValue(0);
+
+  // Track current animation config on UI thread for smooth animation
+  const slideDistance = useSharedValue<number>(FAST_EXIT_ANIMATION.slide.distance);
+  const scaleToValue = useSharedValue<number>(FAST_EXIT_ANIMATION.scale.toValue);
+
+  // Use useRef instead of useSharedValue for isAnimating flag
+  const isAnimatingRef = useRef(false);
+
+  // Refs for callback management and unmount safety
+  const onCompleteRef = useRef<(() => void) | null>(null);
+  const isMountedRef = useRef(true);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+      onCompleteRef.current = null;
+    };
+  }, []);
+
+  // Reset animation state when view is recycled (item ID changes)
+  useEffect(() => {
+    exitDirection.value = 0;
+    slideDistance.value = FAST_EXIT_ANIMATION.slide.distance;
+    scaleToValue.value = FAST_EXIT_ANIMATION.scale.toValue;
+    isAnimatingRef.current = false;
+  }, [itemId, exitDirection, slideDistance, scaleToValue]);
+
+  // Exit animated style (slide, fade, scale)
+  const exitAnimatedStyle = useAnimatedStyle(() => {
+    // Fast path: no animation active, return static values
+    if (exitDirection.value === 0) {
+      return {
+        opacity: 1,
+        transform: [{ translateX: 0 }, { scale: 1 }],
+      };
+    }
+
+    const progress = Math.abs(exitDirection.value);
+
+    return {
+      opacity: 1 - progress,
+      transform: [
+        { translateX: exitDirection.value * slideDistance.value },
+        { scale: 1 - progress * (1 - scaleToValue.value) },
+      ],
+    };
+  });
+
+  // Helper function to safely call the completion callback
+  const safeCallComplete = useCallback(() => {
+    if (isMountedRef.current && onCompleteRef.current) {
+      onCompleteRef.current();
+      onCompleteRef.current = null;
+    }
+    // Unregister exiting item (layout compensation cleanup)
+    config?.onExitComplete?.();
+    isAnimatingRef.current = false;
+  }, [config]);
+
+  /**
+   * Trigger exit animation with direction, completion callback, and optional preset
+   * @param direction - 1 for forward/right, -1 for backward/left
+   * @param onComplete - Callback fired when animation completes
+   * @param preset - Animation preset: 'default' (300ms) or 'fast' (200ms)
+   */
+  const triggerExit = useCallback(
+    (
+      direction: AnimationDirection,
+      onComplete: () => void,
+      preset: ExitAnimationPreset = 'fast',
+    ) => {
+      // Guard against rapid toggling
+      if (isAnimatingRef.current) return;
+
+      isAnimatingRef.current = true;
+      onCompleteRef.current = onComplete;
+
+      const animConfig = animationConfigs[preset];
+
+      // Register exiting item for layout compensation (if configured)
+      if (config?.onExitStart && config.index !== undefined) {
+        const height = config.measuredHeight ?? animConfig.slide.distance;
+        config.onExitStart(config.index, height);
+      }
+
+      // Set animation config SharedValues BEFORE starting animation
+      slideDistance.value = animConfig.slide.distance;
+      scaleToValue.value = animConfig.scale.toValue;
+
+      // Animate exitDirection.value from 0 to 1 (or -1)
+      exitDirection.value = withTiming(
+        direction,
+        { duration: animConfig.slide.duration, easing: standardEasing },
+        finished => {
+          'worklet';
+          if (finished) {
+            scheduleOnRN(safeCallComplete);
+          }
+        },
+      );
+    },
+    [exitDirection, slideDistance, scaleToValue, safeCallComplete, config],
+  );
+
+  /**
+   * Reset animation state (for reuse or error recovery)
+   */
+  const resetAnimation = useCallback(() => {
+    isAnimatingRef.current = false;
+    exitDirection.value = 0;
+  }, [exitDirection]);
+
+  return {
+    exitAnimatedStyle,
+    triggerExit,
+    resetAnimation,
+  };
+};

package/src/hooks/drag/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Drag-to-reorder hooks
+ *
+ * These hooks encapsulate the complex logic for implementing drag-to-reorder
+ * functionality in a FlashList. They work together with DragStateContext
+ * to coordinate animations across all items.
+ *
+ * Usage:
+ * ```tsx
+ * const { panGesture, isDragging, translateY } = useDragGesture(config, callbacks);
+ * const { shiftY } = useDragShift({ itemId, index });
+ * useDropCompensation({ itemId, index, translateY, shiftY });
+ * const { dragAnimatedStyle } = useDragAnimatedStyle(itemId, isDragging, translateY, shiftY);
+ * ```
+ */
+
+export { useDragGesture } from './useDragGesture';
+export { useDragShift } from './useDragShift';
+export { useDropCompensation } from './useDropCompensation';
+export { useDragAnimatedStyle } from './useDragAnimatedStyle';

package/src/hooks/drag/useDragAnimatedStyle.ts

@@ -0,0 +1,80 @@
+import { useAnimatedStyle, interpolate } from 'react-native-reanimated';
+import type { SharedValue } from 'react-native-reanimated';
+import type { ViewStyle } from 'react-native';
+import { useDragState } from '../../contexts/DragStateContext';
+import type { UseDragAnimatedStyleResult } from '../../types';
+
+/**
+ * Hook that creates animated styles for drag operations.
+ *
+ * Handles both dragged item and non-dragged item styles:
+ * - Dragged item: Uses translateY for position + scale from context
+ * - Non-dragged items: Uses shiftY for displacement animation
+ *
+ * CRITICAL: This hook merges transforms into a single style because React Native
+ * doesn't merge transform arrays (when multiple styles have transforms, the last one wins).
+ *
+ * Also handles:
+ * - zIndex elevation for dragged item
+ * - Shadow opacity animation
+ * - Elevation for Android
+ *
+ * @example
+ * ```tsx
+ * const { dragAnimatedStyle } = useDragAnimatedStyle(
+ *   item.id,
+ *   isDragging,
+ *   translateY,
+ *   shiftY
+ * );
+ *
+ * <Animated.View style={[styles.container, isDragEnabled && dragAnimatedStyle]}>
+ *   ...
+ * </Animated.View>
+ * ```
+ */
+export function useDragAnimatedStyle(
+  itemId: string,
+  isDragging: SharedValue<boolean>,
+  translateY: SharedValue<number>,
+  shiftY: SharedValue<number>,
+): UseDragAnimatedStyleResult {
+  // Global drag state for scale, identity check, and scroll compensation
+  const { draggedItemId, draggedScale, config, scrollOffset, dragStartScrollOffset } =
+    useDragState();
+
+  // Animated style for drag offset with scale and shadow
+  const dragAnimatedStyle = useAnimatedStyle(() => {
+    const isThisItemDragged = draggedItemId.value === itemId;
+
+    // Keep elevated if: actively dragging OR has offset (animating back)
+    const shouldBeElevated =
+      isDragging.value || Math.abs(translateY.value) > 1;
+
+    const shadowOpacity = interpolate(
+      draggedScale.value,
+      [1, config.dragScale],
+      [0.1, config.dragShadowOpacity],
+    );
+
+    // Calculate scroll delta for position compensation during autoscroll
+    const scrollDelta = scrollOffset.value - dragStartScrollOffset.value;
+
+    // Use drag translateY + scroll compensation for dragged item, shiftY for others
+    const yOffset = isThisItemDragged
+      ? translateY.value + scrollDelta
+      : shiftY.value;
+
+    return {
+      transform: [
+        { translateY: yOffset },
+        { scale: isThisItemDragged ? draggedScale.value : 1 },
+      ],
+      zIndex: shouldBeElevated ? 999 : 0,
+      shadowOpacity: isThisItemDragged ? shadowOpacity : 0.1,
+      elevation: isDragging.value ? 12 : 4,
+    } as ViewStyle;
+  });
+
+  return { dragAnimatedStyle };
+}

package/src/hooks/drag/useDragGesture.ts

@@ -0,0 +1,267 @@
+import { useCallback, useRef, useMemo } from 'react';
+import {
+  useSharedValue,
+  measure,
+  withSpring,
+  withTiming,
+  Easing,
+  interpolate,
+} from 'react-native-reanimated';
+import { Gesture } from 'react-native-gesture-handler';
+import { scheduleOnRN } from 'react-native-worklets';
+import { useDragState } from '../../contexts/DragStateContext';
+import type {
+  UseDragGestureConfig,
+  UseDragGestureCallbacks,
+  UseDragGestureResult,
+} from '../../types';
+
+/**
+ * Hook that encapsulates all drag gesture logic.
+ *
+ * Handles:
+ * - Pan gesture with long press activation
+ * - Autoscroll when dragging near viewport edges
+ * - Optional haptic feedback on drag start and drop
+ * - Scale animation for visual feedback
+ * - Drop position calculation based on drag offset
+ *
+ * Uses DragStateContext for global coordination across all items.
+ *
+ * @example
+ * ```tsx
+ * const { panGesture, isDragging, translateY } = useDragGesture(
+ *   { itemId: item.id, index, totalItems, enabled: true, containerRef },
+ *   { onReorderByDelta: handleReorder, onHapticFeedback: triggerHaptic }
+ * );
+ *
+ * // Attach to drag handle
+ * <GestureDetector gesture={panGesture}>
+ *   <Animated.View>
+ *     <DragHandleIcon />
+ *   </Animated.View>
+ * </GestureDetector>
+ * ```
+ */
+export function useDragGesture(
+  config: UseDragGestureConfig,
+  callbacks: UseDragGestureCallbacks,
+): UseDragGestureResult {
+  const { itemId, index, totalItems, enabled, containerRef } = config;
+  const { onReorderByDelta, onHapticFeedback } = callbacks;
+
+  // Local drag state for this item's animation
+  const isDragging = useSharedValue(false);
+  const translateY = useSharedValue(0);
+
+  // Global drag state for coordinating animations across all items
+  const {
+    isDragging: globalIsDragging,
+    draggedIndex,
+    draggedItemId,
+    currentTranslateY,
+    draggedScale,
+    scrollOffset,
+    dragStartScrollOffset,
+    contentHeight,
+    visibleHeight,
+    listTopY,
+    dragUpdateTrigger,
+    measuredItemHeight,
+    isDropping,
+    scrollToOffset,
+    config: dragConfig,
+  } = useDragState();
+
+  // Store current values in refs for stable gesture callbacks
+  const dragContextRef = useRef({
+    index,
+    totalItems,
+    itemId,
+    onReorderByDelta,
+  });
+
+  // Keep ref in sync with current values
+  dragContextRef.current = {
+    index,
+    totalItems,
+    itemId,
+    onReorderByDelta,
+  };
+
+  // Calculate new position and call reorder callback
+  const handleDragEnd = useCallback(
+    (finalTranslateY: number) => {
+      const {
+        index: currentIndex,
+        totalItems: total,
+        itemId: currentItemId,
+        onReorderByDelta: reorder,
+      } = dragContextRef.current;
+
+      // Use dynamically measured height + margins, or fall back to config
+      const itemHeight =
+        measuredItemHeight.value > 0
+          ? measuredItemHeight.value + dragConfig.itemVerticalMargin
+          : dragConfig.itemHeight;
+
+      // Calculate how many positions to move based on drag offset
+      const positionDelta = Math.round(finalTranslateY / itemHeight);
+
+      // Calculate if position actually changes
+      const newIndex = Math.max(
+        0,
+        Math.min(total - 1, currentIndex + positionDelta),
+      );
+      const positionChanged =
+        reorder && positionDelta !== 0 && newIndex !== currentIndex;
+
+      if (positionChanged) {
+        // Position changes - call reorder, let useDropCompensation handle animation
+        isDropping.value = true;
+        onHapticFeedback?.('medium');
+        reorder(currentItemId, positionDelta);
+
+        // Reset translate values
+        currentTranslateY.value = 0;
+        dragStartScrollOffset.value = 0;
+      } else {
+        // Same position - animate back and reset state
+        translateY.value = withTiming(
+          0,
+          { duration: 150, easing: Easing.out(Easing.ease) },
+          finished => {
+            'worklet';
+            if (finished) {
+              globalIsDragging.value = false;
+              draggedIndex.value = -1;
+              draggedItemId.value = '';
+              currentTranslateY.value = 0;
+              dragStartScrollOffset.value = 0;
+              measuredItemHeight.value = 0;
+              dragUpdateTrigger.value = dragUpdateTrigger.value + 1;
+            }
+          },
+        );
+      }
+    },
+    [
+      measuredItemHeight,
+      dragConfig,
+      translateY,
+      globalIsDragging,
+      draggedIndex,
+      draggedItemId,
+      currentTranslateY,
+      dragStartScrollOffset,
+      dragUpdateTrigger,
+      isDropping,
+      onHapticFeedback,
+    ],
+  );
+
+  // Stable haptic callback for drag start
+  const triggerLightHaptic = useCallback(() => {
+    onHapticFeedback?.('light');
+  }, [onHapticFeedback]);
+
+  // Pan gesture for drag-to-reorder
+  const panGesture = useMemo(
+    () =>
+      Gesture.Pan()
+        .activateAfterLongPress(dragConfig.longPressDuration)
+        .enabled(enabled)
+        .onStart(() => {
+          'worklet';
+          // Measure actual item height for accurate drag calculations
+          const measured = measure(containerRef);
+          if (measured) {
+            measuredItemHeight.value = measured.height;
+          }
+
+          // Local drag state
+          isDragging.value = true;
+          // Global drag state for shift animations
+          globalIsDragging.value = true;
+          draggedIndex.value = index;
+          draggedItemId.value = itemId;
+          dragStartScrollOffset.value = scrollOffset.value;
+          currentTranslateY.value = 0;
+          draggedScale.value = withSpring(dragConfig.dragScale, {
+            damping: 15,
+            stiffness: 400,
+          });
+          dragUpdateTrigger.value = dragUpdateTrigger.value + 1;
+          scheduleOnRN(triggerLightHaptic);
+        })
+        .onUpdate(event => {
+          'worklet';
+          translateY.value = event.translationY;
+          currentTranslateY.value = event.translationY;
+          dragUpdateTrigger.value = dragUpdateTrigger.value + 1;
+
+          // Autoscroll when dragging near edges
+          const fingerInList = event.absoluteY - listTopY.value;
+          const topEdge = dragConfig.edgeThreshold;
+          const bottomEdge = visibleHeight.value - dragConfig.edgeThreshold;
+
+          if (fingerInList < topEdge && scrollOffset.value > 0) {
+            const speed = interpolate(
+              fingerInList,
+              [0, topEdge],
+              [dragConfig.maxScrollSpeed, 0],
+              'clamp',
+            );
+            const newOffset = Math.max(0, scrollOffset.value - speed);
+            scrollOffset.value = newOffset;
+            scheduleOnRN(scrollToOffset, newOffset);
+          } else if (fingerInList > bottomEdge) {
+            const maxOffset = Math.max(
+              0,
+              contentHeight.value - visibleHeight.value,
+            );
+            if (scrollOffset.value < maxOffset) {
+              const speed = interpolate(
+                fingerInList,
+                [bottomEdge, visibleHeight.value],
+                [0, dragConfig.maxScrollSpeed],
+                'clamp',
+              );
+              const newOffset = Math.min(maxOffset, scrollOffset.value + speed);
+              scrollOffset.value = newOffset;
+              scheduleOnRN(scrollToOffset, newOffset);
+            }
+          }
+        })
+        .onEnd(event => {
+          'worklet';
+          isDragging.value = false;
+
+          // Include scroll compensation in final position calculation
+          const scrollDelta = scrollOffset.value - dragStartScrollOffset.value;
+          const finalY = event.translationY + scrollDelta;
+
+          draggedScale.value = withSpring(1, { damping: 15, stiffness: 400 });
+          scheduleOnRN(handleDragEnd, finalY);
+        })
+        .onFinalize((_event, success) => {
+          'worklet';
+          if (!success) {
+            isDragging.value = false;
+            translateY.value = withTiming(0, { duration: 150 });
+            isDropping.value = false;
+            globalIsDragging.value = false;
+            draggedIndex.value = -1;
+            draggedItemId.value = '';
+            currentTranslateY.value = 0;
+            draggedScale.value = 1;
+            dragStartScrollOffset.value = 0;
+            measuredItemHeight.value = 0;
+          }
+        }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [enabled, containerRef, triggerLightHaptic, handleDragEnd, index, itemId],
+  );
+
+  return { panGesture, isDragging, translateY };
+}