@souscheflabs/reanimated-flashlist 0.1.7

package/src/constants/animations.ts

@@ -0,0 +1,107 @@
+import { Easing } from 'react-native-reanimated';
+import type { ExitAnimationConfig, EntryAnimationConfig } from '../types';
+
+/**
+ * Standard cubic bezier easing function for smooth animations
+ * Equivalent to CSS ease-in-out with custom curve
+ */
+export const standardEasing = Easing.bezier(0.25, 0.1, 0.25, 1);
+
+/**
+ * Default exit animation configuration
+ * Used when items are removed/toggled from the list
+ *
+ * Timeline (300ms total):
+ * - 0-300ms: Slide (300px in direction)
+ * - 50-300ms: Scale to 0.95
+ * - 100-300ms: Fade out
+ */
+export const DEFAULT_EXIT_ANIMATION: ExitAnimationConfig = {
+  slide: {
+    duration: 300,
+    distance: 300,
+  },
+  fade: {
+    delay: 100,
+    duration: 200,
+  },
+  scale: {
+    delay: 50,
+    duration: 250,
+    toValue: 0.95,
+  },
+  removalDelay: 300,
+  layoutAnimation: {
+    duration: 200,
+  },
+};
+
+/**
+ * Fast exit animation for quick actions (checkbox toggles)
+ *
+ * Timeline (200ms total):
+ * - 0-200ms: Slide (200px in direction)
+ * - 0-200ms: Fade out (starts immediately)
+ * - 0-200ms: Scale to 0.97
+ */
+export const FAST_EXIT_ANIMATION: ExitAnimationConfig = {
+  slide: {
+    duration: 200,
+    distance: 200,
+  },
+  fade: {
+    delay: 0,
+    duration: 200,
+  },
+  scale: {
+    delay: 0,
+    duration: 200,
+    toValue: 0.97,
+  },
+  removalDelay: 200,
+  layoutAnimation: {
+    duration: 150,
+  },
+};
+
+/**
+ * Default entry animation configuration
+ * Used when items appear in the list
+ */
+export const DEFAULT_ENTRY_ANIMATION: EntryAnimationConfig = {
+  fade: { duration: 250 },
+  slide: { distance: 50, duration: 300 },
+};
+
+/**
+ * Get exit animation config by preset
+ */
+export function getExitAnimationConfig(
+  preset: 'default' | 'fast' = 'fast',
+  overrides?: Partial<ExitAnimationConfig>,
+): ExitAnimationConfig {
+  const base = preset === 'fast' ? FAST_EXIT_ANIMATION : DEFAULT_EXIT_ANIMATION;
+  if (!overrides) return base;
+
+  return {
+    slide: { ...base.slide, ...overrides.slide },
+    fade: { ...base.fade, ...overrides.fade },
+    scale: { ...base.scale, ...overrides.scale },
+    removalDelay: overrides.removalDelay ?? base.removalDelay,
+    layoutAnimation: { ...base.layoutAnimation, ...overrides.layoutAnimation },
+  };
+}
+
+/**
+ * Create a merged entry animation config from defaults and overrides
+ */
+export function createEntryAnimationConfig(
+  overrides?: Partial<EntryAnimationConfig>,
+): EntryAnimationConfig {
+  if (!overrides) return DEFAULT_ENTRY_ANIMATION;
+
+  return {
+    fade: { ...DEFAULT_ENTRY_ANIMATION.fade, ...overrides.fade },
+    slide: { ...DEFAULT_ENTRY_ANIMATION.slide, ...overrides.slide },
+  };
+}

package/src/constants/drag.ts

@@ -0,0 +1,51 @@
+import type { DragConfig } from '../types';
+
+/**
+ * Default drag configuration
+ * All values can be overridden via AnimatedFlashList config prop
+ */
+export const DEFAULT_DRAG_CONFIG: DragConfig = {
+  /**
+   * Fixed height for list items used in drag calculations.
+   * Override this to match your item height + margins
+   */
+  itemHeight: 95,
+
+  /**
+   * Scale factor applied to dragged item for visual feedback
+   */
+  dragScale: 1.03,
+
+  /**
+   * Shadow opacity for dragged item (increases from 0.1 to this value)
+   */
+  dragShadowOpacity: 0.25,
+
+  /**
+   * Vertical margin per item (total margin = 2 * itemVerticalMargin)
+   */
+  itemVerticalMargin: 8,
+
+  /**
+   * Duration (ms) to hold drag handle before drag activates
+   */
+  longPressDuration: 200,
+
+  /**
+   * Pixels from viewport edge to trigger autoscroll
+   */
+  edgeThreshold: 80,
+
+  /**
+   * Maximum scroll speed in pixels per frame at edge
+   */
+  maxScrollSpeed: 10,
+};
+
+/**
+ * Create a merged drag config from defaults and overrides
+ */
+export function createDragConfig(overrides?: Partial<DragConfig>): DragConfig {
+  if (!overrides) return DEFAULT_DRAG_CONFIG;
+  return { ...DEFAULT_DRAG_CONFIG, ...overrides };
+}

package/src/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './drag';
+export * from './animations';

package/src/contexts/DragStateContext.tsx

@@ -0,0 +1,197 @@
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useRef,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+import type { FlashListRef } from '@shopify/flash-list';
+import type { DragConfig } from '../types';
+import { DEFAULT_DRAG_CONFIG } from '../constants';
+
+/**
+ * Centralized drag state for coordinating animations across list items.
+ * All animation values are Reanimated SharedValues for 60fps UI thread performance.
+ *
+ * Architecture:
+ * - Single source of truth for all drag state (no per-item local state)
+ * - Dragged item identified by draggedIndex, reads/writes centralized values
+ * - Non-dragged items read draggedIndex/currentTranslateY to calculate shift
+ * - Scroll state enables viewport-aware hover calculations and autoscroll
+ */
+export interface DragStateContextValue {
+  /** Is any item currently being dragged? */
+  isDragging: SharedValue<boolean>;
+  /** Original index of the item being dragged (-1 if not dragging) */
+  draggedIndex: SharedValue<number>;
+  /** ID of the item being dragged (for stable identity across FlashList recycling) */
+  draggedItemId: SharedValue<string>;
+  /** Current Y translation of the dragged item (for calculating hover position) */
+  currentTranslateY: SharedValue<number>;
+  /** Scale of the dragged item (1.0 = normal, configured = dragging) */
+  draggedScale: SharedValue<number>;
+  /** Current scroll offset of the list (updated via onScroll) */
+  scrollOffset: SharedValue<number>;
+  /** Scroll offset when drag started (for scroll delta calculation during autoscroll) */
+  dragStartScrollOffset: SharedValue<number>;
+  /** Total content height of the list (updated via onContentSizeChange) */
+  contentHeight: SharedValue<number>;
+  /** Visible viewport height (updated via onLayout) */
+  visibleHeight: SharedValue<number>;
+  /** Y position of FlashList top on screen (for autoscroll coordinate conversion) */
+  listTopY: SharedValue<number>;
+  /** Counter incremented on every drag state change to force useDerivedValue re-evaluation */
+  dragUpdateTrigger: SharedValue<number>;
+  /** Measured height of the dragged item (for dynamic height calculations) */
+  measuredItemHeight: SharedValue<number>;
+  /** Flag to freeze shift values during drop transition */
+  isDropping: SharedValue<boolean>;
+  /** Register the FlashList ref for autoscroll operations */
+  setListRef: (ref: FlashListRef<unknown> | null) => void;
+  /** Scroll the list to a specific offset (for autoscroll during drag) */
+  scrollToOffset: (offset: number, animated?: boolean) => void;
+  /** Reset drag state after drop animation completes */
+  resetDragState: () => void;
+  /** Current drag configuration */
+  config: DragConfig;
+}
+
+const DragStateContext = createContext<DragStateContextValue | null>(null);
+
+/**
+ * Hook to access shared drag state from context.
+ * Must be used within DragStateProvider.
+ */
+export const useDragState = (): DragStateContextValue => {
+  const context = useContext(DragStateContext);
+  if (!context) {
+    throw new Error('useDragState must be used within DragStateProvider');
+  }
+  return context;
+};
+
+interface DragStateProviderProps {
+  children: ReactNode;
+  /** Optional drag configuration overrides */
+  config?: Partial<DragConfig>;
+}
+
+/**
+ * Provider that creates shared Reanimated values for drag state.
+ *
+ * These values are shared across all list items:
+ * - The dragged item writes to them during drag gestures
+ * - Non-dragged items read them to calculate their shift offset
+ * - Scroll state enables viewport-aware hover calculations
+ *
+ * Using SharedValues ensures animations run on the UI thread at 60fps.
+ */
+export const DragStateProvider: React.FC<DragStateProviderProps> = ({
+  children,
+  config: configOverrides,
+}) => {
+  // Merge config with defaults
+  const config = useMemo<DragConfig>(
+    () => ({ ...DEFAULT_DRAG_CONFIG, ...configOverrides }),
+    [configOverrides],
+  );
+
+  // Shared values are created once and persist for the lifetime of the provider
+  const isDragging = useSharedValue(false);
+  const draggedIndex = useSharedValue(-1);
+  const draggedItemId = useSharedValue('');
+  const currentTranslateY = useSharedValue(0);
+  const draggedScale = useSharedValue(1);
+
+  // Scroll state for viewport-aware calculations and autoscroll
+  const scrollOffset = useSharedValue(0);
+  const dragStartScrollOffset = useSharedValue(0);
+  const contentHeight = useSharedValue(0);
+  const visibleHeight = useSharedValue(0);
+  const listTopY = useSharedValue(0);
+
+  // Counter to force useDerivedValue re-evaluation on every drag state change
+  const dragUpdateTrigger = useSharedValue(0);
+
+  // Measured height of dragged item (0 = use fallback from config)
+  const measuredItemHeight = useSharedValue(0);
+
+  // Flag to freeze shift values during drop transition
+  const isDropping = useSharedValue(false);
+
+  // Ref to FlashList for autoscroll operations
+  const listRef = useRef<FlashListRef<unknown> | null>(null);
+
+  // Register the FlashList ref
+  const setListRef = useCallback((ref: FlashListRef<unknown> | null) => {
+    listRef.current = ref;
+  }, []);
+
+  // Scroll to offset (called via scheduleOnRN from worklet for autoscroll)
+  const scrollToOffset = useCallback((offset: number, animated = false) => {
+    listRef.current?.scrollToOffset({ offset, animated });
+  }, []);
+
+  // Reset drag state after drop
+  const resetDragState = useCallback(() => {
+    isDragging.value = false;
+    draggedIndex.value = -1;
+    draggedItemId.value = '';
+    currentTranslateY.value = 0;
+    draggedScale.value = 1;
+    dragStartScrollOffset.value = 0;
+    measuredItemHeight.value = 0;
+    isDropping.value = false;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Context value is stable since SharedValue references don't change
+  const value = useMemo<DragStateContextValue>(
+    () => ({
+      isDragging,
+      draggedIndex,
+      draggedItemId,
+      currentTranslateY,
+      draggedScale,
+      scrollOffset,
+      dragStartScrollOffset,
+      contentHeight,
+      visibleHeight,
+      listTopY,
+      dragUpdateTrigger,
+      measuredItemHeight,
+      isDropping,
+      setListRef,
+      scrollToOffset,
+      resetDragState,
+      config,
+    }),
+    [
+      isDragging,
+      draggedIndex,
+      draggedItemId,
+      currentTranslateY,
+      draggedScale,
+      scrollOffset,
+      dragStartScrollOffset,
+      contentHeight,
+      visibleHeight,
+      listTopY,
+      dragUpdateTrigger,
+      measuredItemHeight,
+      isDropping,
+      setListRef,
+      scrollToOffset,
+      resetDragState,
+      config,
+    ],
+  );
+
+  return (
+    <DragStateContext.Provider value={value}>
+      {children}
+    </DragStateContext.Provider>
+  );
+};

package/src/contexts/ListAnimationContext.tsx

@@ -0,0 +1,302 @@
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useRef,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import { LayoutAnimation, Platform } from 'react-native';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+import type {
+  AnimationDirection,
+  ExitAnimationTrigger,
+  PendingEntryAnimation,
+  ExitingItemInfo,
+} from '../types';
+
+/**
+ * Context value for coordinating entry/exit animations across list items.
+ *
+ * This enables:
+ * 1. Direct O(1) animation triggers from subscription handlers
+ * 2. Entry animation coordination when items appear in new locations
+ * 3. Layout animation coordination when items are removed
+ * 4. Decoupled animation state from React render cycle
+ */
+export interface ListAnimationContextValue {
+  /**
+   * Register an exit animation trigger for an item.
+   * Called by useListExitAnimation on mount.
+   */
+  registerAnimationTrigger: (itemId: string, trigger: ExitAnimationTrigger) => void;
+
+  /**
+   * Unregister an exit animation trigger.
+   * Called by useListExitAnimation on unmount.
+   */
+  unregisterAnimationTrigger: (itemId: string) => void;
+
+  /**
+   * Trigger exit animation for a specific item.
+   * Returns true if animation was triggered, false if item not found.
+   */
+  triggerExitAnimation: (
+    itemId: string,
+    direction: AnimationDirection,
+    onComplete: () => void,
+  ) => boolean;
+
+  /**
+   * Queue an entry animation for an item that's about to appear.
+   * Call this before the item is added to the list.
+   */
+  queueEntryAnimation: (itemId: string, direction: AnimationDirection) => void;
+
+  /**
+   * Check and claim a pending entry animation for an item.
+   * Returns the animation info if found, null otherwise.
+   * Calling this consumes the pending animation.
+   */
+  claimEntryAnimation: (itemId: string) => PendingEntryAnimation | null;
+
+  /**
+   * Register an item that is currently exiting (for layout compensation).
+   * Called when exit animation starts.
+   */
+  registerExitingItem: (itemId: string, index: number, height: number) => void;
+
+  /**
+   * Unregister an exiting item (called when removal is complete).
+   */
+  unregisterExitingItem: (itemId: string) => void;
+
+  /**
+   * Get info about items currently exiting above a given index.
+   * Returns the total height of exiting items above.
+   */
+  getExitingHeightAbove: (index: number) => number;
+
+  /**
+   * SharedValue that increments when exiting items change.
+   * Used to trigger useDerivedValue re-evaluation.
+   */
+  exitingItemsVersion: SharedValue<number>;
+
+  /**
+   * Duration for layout animations (ms).
+   */
+  layoutAnimationDuration: number;
+}
+
+const ListAnimationContext = createContext<ListAnimationContextValue | null>(null);
+
+/**
+ * Hook to access list animation context.
+ * Throws if used outside ListAnimationProvider.
+ */
+export const useListAnimation = (): ListAnimationContextValue => {
+  const context = useContext(ListAnimationContext);
+  if (!context) {
+    throw new Error('useListAnimation must be used within ListAnimationProvider');
+  }
+  return context;
+};
+
+/**
+ * Hook to optionally access list animation context.
+ * Returns null if used outside ListAnimationProvider.
+ * Useful for components that can work with or without animations.
+ */
+export const useListAnimationOptional = (): ListAnimationContextValue | null => {
+  return useContext(ListAnimationContext);
+};
+
+interface ListAnimationProviderProps {
+  children: ReactNode;
+  /**
+   * How long pending entry animations are valid (ms)
+   * @default 5000
+   */
+  entryAnimationTimeout?: number;
+  /**
+   * Duration for layout animations when items are removed (ms)
+   * @default 200
+   */
+  layoutAnimationDuration?: number;
+  /**
+   * Whether to enable native LayoutAnimation for remaining items
+   * @default true
+   */
+  enableLayoutAnimation?: boolean;
+}
+
+/**
+ * Provider for coordinating entry/exit animations across list items.
+ *
+ * Features:
+ * - O(1) exit animation triggers via Map lookup
+ * - Entry animation queuing with automatic expiration
+ * - Layout animation coordination when items are removed
+ * - Decoupled from React render cycle for performance
+ */
+export const ListAnimationProvider: React.FC<ListAnimationProviderProps> = ({
+  children,
+  entryAnimationTimeout = 5000,
+  layoutAnimationDuration = 200,
+  enableLayoutAnimation = true,
+}) => {
+  // Map of itemId -> exit animation trigger function
+  const animationTriggersRef = useRef<Map<string, ExitAnimationTrigger>>(new Map());
+
+  // Map of itemId -> pending entry animation
+  const pendingEntriesRef = useRef<Map<string, PendingEntryAnimation>>(new Map());
+
+  // Map of itemId -> exiting item info (for layout compensation)
+  const exitingItemsRef = useRef<Map<string, ExitingItemInfo>>(new Map());
+
+  // SharedValue to trigger re-evaluation when exiting items change
+  const exitingItemsVersion = useSharedValue(0);
+
+  const registerAnimationTrigger = useCallback(
+    (itemId: string, trigger: ExitAnimationTrigger) => {
+      animationTriggersRef.current.set(itemId, trigger);
+    },
+    [],
+  );
+
+  const unregisterAnimationTrigger = useCallback((itemId: string) => {
+    animationTriggersRef.current.delete(itemId);
+  }, []);
+
+  const triggerExitAnimation = useCallback(
+    (
+      itemId: string,
+      direction: AnimationDirection,
+      onComplete: () => void,
+    ): boolean => {
+      const trigger = animationTriggersRef.current.get(itemId);
+      if (trigger) {
+        trigger(direction, onComplete);
+        return true;
+      }
+      return false;
+    },
+    [],
+  );
+
+  const queueEntryAnimation = useCallback(
+    (itemId: string, direction: AnimationDirection) => {
+      const entry: PendingEntryAnimation = {
+        itemId,
+        direction,
+        timestamp: Date.now(),
+      };
+      pendingEntriesRef.current.set(itemId, entry);
+
+      // Auto-expire after timeout
+      setTimeout(() => {
+        const current = pendingEntriesRef.current.get(itemId);
+        if (current && current.timestamp === entry.timestamp) {
+          pendingEntriesRef.current.delete(itemId);
+        }
+      }, entryAnimationTimeout);
+    },
+    [entryAnimationTimeout],
+  );
+
+  const claimEntryAnimation = useCallback(
+    (itemId: string): PendingEntryAnimation | null => {
+      const entry = pendingEntriesRef.current.get(itemId);
+      if (entry) {
+        pendingEntriesRef.current.delete(itemId);
+        // Check if still valid (not expired)
+        if (Date.now() - entry.timestamp < entryAnimationTimeout) {
+          return entry;
+        }
+      }
+      return null;
+    },
+    [entryAnimationTimeout],
+  );
+
+  // Register an exiting item for layout compensation
+  const registerExitingItem = useCallback(
+    (itemId: string, index: number, height: number) => {
+      const info: ExitingItemInfo = {
+        itemId,
+        index,
+        height,
+        timestamp: Date.now(),
+      };
+      exitingItemsRef.current.set(itemId, info);
+      exitingItemsVersion.value = exitingItemsVersion.value + 1;
+
+      // Configure native LayoutAnimation for remaining items
+      if (enableLayoutAnimation) {
+        // Use custom config for smoother animation
+        LayoutAnimation.configureNext({
+          duration: layoutAnimationDuration,
+          update: {
+            type: LayoutAnimation.Types.easeInEaseOut,
+            property: LayoutAnimation.Properties.scaleY,
+          },
+        });
+      }
+    },
+    [enableLayoutAnimation, layoutAnimationDuration, exitingItemsVersion],
+  );
+
+  // Unregister an exiting item
+  const unregisterExitingItem = useCallback(
+    (itemId: string) => {
+      exitingItemsRef.current.delete(itemId);
+      exitingItemsVersion.value = exitingItemsVersion.value + 1;
+    },
+    [exitingItemsVersion],
+  );
+
+  // Get total height of exiting items above a given index
+  const getExitingHeightAbove = useCallback((index: number): number => {
+    let totalHeight = 0;
+    exitingItemsRef.current.forEach(info => {
+      if (info.index < index) {
+        totalHeight += info.height;
+      }
+    });
+    return totalHeight;
+  }, []);
+
+  const value = useMemo<ListAnimationContextValue>(
+    () => ({
+      registerAnimationTrigger,
+      unregisterAnimationTrigger,
+      triggerExitAnimation,
+      queueEntryAnimation,
+      claimEntryAnimation,
+      registerExitingItem,
+      unregisterExitingItem,
+      getExitingHeightAbove,
+      exitingItemsVersion,
+      layoutAnimationDuration,
+    }),
+    [
+      registerAnimationTrigger,
+      unregisterAnimationTrigger,
+      triggerExitAnimation,
+      queueEntryAnimation,
+      claimEntryAnimation,
+      registerExitingItem,
+      unregisterExitingItem,
+      getExitingHeightAbove,
+      exitingItemsVersion,
+      layoutAnimationDuration,
+    ],
+  );
+
+  return (
+    <ListAnimationContext.Provider value={value}>
+      {children}
+    </ListAnimationContext.Provider>
+  );
+};

package/src/contexts/index.ts

@@ -0,0 +1,9 @@
+export { DragStateProvider, useDragState } from './DragStateContext';
+export type { DragStateContextValue } from './DragStateContext';
+
+export {
+  ListAnimationProvider,
+  useListAnimation,
+  useListAnimationOptional,
+} from './ListAnimationContext';
+export type { ListAnimationContextValue } from './ListAnimationContext';

package/src/hooks/animations/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Animation hooks for list items
+ *
+ * These hooks provide entry and exit animations for items
+ * being added to or removed from the list.
+ */
+
+export { useListExitAnimation } from './useListExitAnimation';
+export { useListEntryAnimation } from './useListEntryAnimation';