@souscheflabs/reanimated-flashlist 0.1.7

package/src/hooks/drag/useDragShift.ts

@@ -0,0 +1,119 @@
+import {
+  useSharedValue,
+  useDerivedValue,
+  useAnimatedReaction,
+  withTiming,
+  Easing,
+} from 'react-native-reanimated';
+import { useDragState } from '../../contexts/DragStateContext';
+import type { UseDragShiftConfig, UseDragShiftResult } from '../../types';
+
+/**
+ * Hook that calculates shift animation for non-dragged items.
+ *
+ * When an item is being dragged, other items need to shift up or down
+ * to make room for the dragged item at its new position. This hook
+ * calculates the target shift based on:
+ * - The current drag position (from context)
+ * - The scroll delta (accounting for autoscroll)
+ * - The item's index relative to the dragged item
+ *
+ * The shift is animated with timing for smooth transitions.
+ *
+ * @example
+ * ```tsx
+ * const { shiftY } = useDragShift({ itemId: item.id, index });
+ * // Use shiftY.value in animated style
+ * ```
+ */
+export function useDragShift(config: UseDragShiftConfig): UseDragShiftResult {
+  const { itemId, index } = config;
+
+  // Global drag state for coordinating animations across all items
+  const {
+    isDragging: globalIsDragging,
+    draggedIndex,
+    draggedItemId,
+    currentTranslateY,
+    scrollOffset,
+    dragStartScrollOffset,
+    dragUpdateTrigger,
+    measuredItemHeight,
+    isDropping,
+    config: dragConfig,
+  } = useDragState();
+
+  // Shift animation SharedValue
+  const shiftY = useSharedValue(0);
+
+  // Calculate target shift using useDerivedValue
+  const targetShiftY = useDerivedValue(() => {
+    'worklet';
+    // Force re-evaluation on every drag state change
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    dragUpdateTrigger.value;
+
+    // During drop transition, freeze shift values
+    if (isDropping.value) {
+      return shiftY.value;
+    }
+
+    const currentDraggedIndex = draggedIndex.value;
+    const isDraggingNow = globalIsDragging.value;
+    const translateYNow = currentTranslateY.value;
+    const currentDraggedItemId = draggedItemId.value;
+
+    // If I'm the dragged item, no shift needed
+    if (currentDraggedItemId === itemId) return 0;
+
+    // If not dragging, reset to 0
+    if (!isDraggingNow) return 0;
+
+    // Use dynamically measured height + margins, or fall back to config
+    const itemHeight =
+      measuredItemHeight.value > 0
+        ? measuredItemHeight.value + dragConfig.itemVerticalMargin
+        : dragConfig.itemHeight;
+
+    // Calculate effective translateY including scroll delta
+    const scrollDelta = scrollOffset.value - dragStartScrollOffset.value;
+    const effectiveTranslateY = translateYNow + scrollDelta;
+
+    // Calculate which index the dragged item is hovering over
+    const offset =
+      effectiveTranslateY > 0 ? 0.2 : effectiveTranslateY < 0 ? -0.2 : 0;
+    const hoveredIndex =
+      currentDraggedIndex + Math.round(effectiveTranslateY / itemHeight + offset);
+
+    // Moving DOWN: items between original and hovered positions shift UP
+    if (hoveredIndex > currentDraggedIndex) {
+      if (index > currentDraggedIndex && index <= hoveredIndex) {
+        return -itemHeight;
+      }
+    }
+    // Moving UP: items between hovered and original positions shift DOWN
+    else if (hoveredIndex < currentDraggedIndex) {
+      if (index < currentDraggedIndex && index >= hoveredIndex) {
+        return itemHeight;
+      }
+    }
+
+    return 0;
+  }, [index, itemId]);
+
+  // Animate shift when target changes
+  useAnimatedReaction(
+    () => targetShiftY.value,
+    (target, prev) => {
+      'worklet';
+      if (target !== prev) {
+        shiftY.value = withTiming(target, {
+          duration: 100,
+          easing: Easing.out(Easing.ease),
+        });
+      }
+    },
+  );
+
+  return { shiftY };
+}

package/src/hooks/drag/useDropCompensation.ts

@@ -0,0 +1,120 @@
+import { useLayoutEffect } from 'react';
+import {
+  useSharedValue,
+  useAnimatedReaction,
+  withTiming,
+  Easing,
+} from 'react-native-reanimated';
+import { useRecyclingState } from '@shopify/flash-list';
+import { useDragState } from '../../contexts/DragStateContext';
+import type { UseDropCompensationConfig } from '../../types';
+
+/**
+ * Hook that handles index change compensation after drag reorder.
+ *
+ * When an item is dropped and the data updates, React re-renders with new indices.
+ * This causes a visual jump because items suddenly have different positions.
+ * This hook compensates by:
+ * 1. Detecting index changes (via useRecyclingState for FlashList recycling)
+ * 2. Adjusting translateY to compensate for the position delta
+ * 3. Animating the dragged item back to 0 (settle animation)
+ * 4. Resetting global drag state after animation completes
+ * 5. Resetting shiftY on UI thread via useAnimatedReaction
+ *
+ * useLayoutEffect runs synchronously before paint to prevent visual flash.
+ *
+ * @example
+ * ```tsx
+ * useDropCompensation({
+ *   itemId: item.id,
+ *   index,
+ *   translateY,
+ *   shiftY,
+ * });
+ * ```
+ */
+export function useDropCompensation(config: UseDropCompensationConfig): void {
+  const { itemId, index, translateY, shiftY } = config;
+
+  // Track index on UI thread for synchronized shift reset
+  const indexShared = useSharedValue(index);
+
+  // Global drag state
+  const {
+    isDragging: globalIsDragging,
+    draggedIndex,
+    draggedItemId,
+    measuredItemHeight,
+    isDropping,
+    dragUpdateTrigger,
+    config: dragConfig,
+  } = useDragState();
+
+  // Use FlashList's useRecyclingState for automatic reset on view recycling
+  const [prevIndex, setPrevIndex] = useRecyclingState(index, [itemId]);
+
+  // Handle index changes after data updates (drop compensation)
+  useLayoutEffect(() => {
+    if (index !== prevIndex) {
+      // Compensate for index change by adjusting translateY
+      const indexDelta = index - prevIndex;
+      const heightDelta = indexDelta * dragConfig.itemHeight;
+
+      // Check if this is the dragged item completing its drop
+      const isTheDraggedItem = draggedItemId.value === itemId;
+
+      // Compensate translateY for position change
+      const compensatedY = translateY.value - heightDelta;
+
+      if (isTheDraggedItem) {
+        // Dragged item: animate smoothly to 0 from compensated position
+        translateY.value = compensatedY;
+        translateY.value = withTiming(
+          0,
+          { duration: 150, easing: Easing.out(Easing.ease) },
+          finished => {
+            'worklet';
+            if (finished) {
+              // Reset ALL global state after settle animation
+              isDropping.value = false;
+              globalIsDragging.value = false;
+              draggedIndex.value = -1;
+              draggedItemId.value = '';
+              measuredItemHeight.value = 0;
+              dragUpdateTrigger.value = withTiming(dragUpdateTrigger.value + 1, {
+                duration: 1,
+              });
+            }
+          },
+        );
+      } else if (Math.abs(translateY.value) > 1) {
+        // Non-dragged item: just compensate without animation
+        translateY.value = compensatedY;
+      }
+
+      // Update tracked index
+      setPrevIndex(index);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [index, prevIndex, translateY, setPrevIndex, itemId]);
+
+  // Sync JS index to SharedValue for UI thread access
+  useLayoutEffect(() => {
+    indexShared.value = index;
+  }, [index, indexShared]);
+
+  // Reset shiftY on UI thread when index changes
+  useAnimatedReaction(
+    () => indexShared.value,
+    (currentIndex, prevIdx) => {
+      'worklet';
+      if (
+        prevIdx !== null &&
+        currentIndex !== prevIdx &&
+        Math.abs(shiftY.value) > 1
+      ) {
+        shiftY.value = 0;
+      }
+    },
+  );
+}

package/src/hooks/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Hooks for AnimatedFlashList
+ *
+ * Re-exports all hooks for both drag and animation functionality.
+ */
+
+// Drag hooks
+export {
+  useDragGesture,
+  useDragShift,
+  useDragAnimatedStyle,
+  useDropCompensation,
+} from './drag';
+
+// Animation hooks
+export { useListExitAnimation, useListEntryAnimation } from './animations';

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @souschef/reanimated-flashlist
+ *
+ * A high-performance animated FlashList with drag-to-reorder and entry/exit animations.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   AnimatedFlashList,
+ *   type AnimatedListItem,
+ * } from '@souschef/reanimated-flashlist';
+ *
+ * interface MyItem extends AnimatedListItem {
+ *   title: string;
+ * }
+ *
+ * <AnimatedFlashList<MyItem>
+ *   data={items}
+ *   keyExtractor={(item) => item.id}
+ *   renderItem={({ item, dragHandleProps, triggerExitAnimation }) => (
+ *     <View>
+ *       <Text>{item.title}</Text>
+ *       {dragHandleProps && (
+ *         <GestureDetector gesture={dragHandleProps.gesture}>
+ *           <DragIcon />
+ *         </GestureDetector>
+ *       )}
+ *     </View>
+ *   )}
+ *   dragEnabled
+ *   onReorder={(itemId, from, to) => handleReorder(itemId, from, to)}
+ * />
+ * ```
+ */
+
+// Main component
+export { AnimatedFlashList } from './AnimatedFlashList';
+export { AnimatedFlashListItem } from './AnimatedFlashListItem';
+
+// Contexts (for advanced usage)
+export {
+  DragStateProvider,
+  useDragState,
+  ListAnimationProvider,
+  useListAnimation,
+  useListAnimationOptional,
+} from './contexts';
+
+// Hooks (for advanced/custom implementations)
+export {
+  // Drag hooks
+  useDragGesture,
+  useDragShift,
+  useDragAnimatedStyle,
+  useDropCompensation,
+  // Animation hooks
+  useListExitAnimation,
+  useListEntryAnimation,
+} from './hooks';
+
+// Constants (for customization)
+export {
+  DEFAULT_DRAG_CONFIG,
+  createDragConfig,
+  DEFAULT_EXIT_ANIMATION,
+  FAST_EXIT_ANIMATION,
+  DEFAULT_ENTRY_ANIMATION,
+  getExitAnimationConfig,
+  createEntryAnimationConfig,
+  standardEasing,
+} from './constants';
+
+// Types
+export type {
+  // List types
+  AnimatedListItem,
+  AnimatedFlashListProps,
+  AnimatedFlashListRef,
+  AnimatedFlashListConfig,
+  AnimatedRenderItemInfo,
+  DragHandleProps,
+  // Drag types
+  DragConfig,
+  UseDragGestureConfig,
+  UseDragGestureCallbacks,
+  UseDragGestureResult,
+  UseDragShiftConfig,
+  UseDragShiftResult,
+  UseDropCompensationConfig,
+  UseDragAnimatedStyleResult,
+  // Animation types
+  AnimationDirection,
+  ExitAnimationPreset,
+  ExitAnimationConfig,
+  EntryAnimationConfig,
+  PendingEntryAnimation,
+  ExitAnimationTrigger,
+  HapticFeedbackType,
+} from './types';
+
+// Context types
+export type {
+  DragStateContextValue,
+  ListAnimationContextValue,
+} from './contexts';

package/src/types/animations.ts

@@ -0,0 +1,76 @@
+/**
+ * Animation direction for entry/exit animations
+ * 1 = forward/right, -1 = backward/left
+ */
+export type AnimationDirection = 1 | -1;
+
+/**
+ * Animation preset type for exit animations
+ * - 'default': Standard exit animation (for swipe/delete actions)
+ * - 'fast': Quick exit animation (for checkbox toggles)
+ */
+export type ExitAnimationPreset = 'default' | 'fast';
+
+/**
+ * Haptic feedback types that can be triggered during animations
+ */
+export type HapticFeedbackType = 'light' | 'medium' | 'heavy' | 'selection';
+
+/**
+ * Configuration for exit animations
+ */
+export interface ExitAnimationConfig {
+  slide: {
+    duration: number;
+    distance: number;
+  };
+  fade: {
+    delay: number;
+    duration: number;
+  };
+  scale: {
+    delay: number;
+    duration: number;
+    toValue: number;
+  };
+  removalDelay: number;
+  layoutAnimation: {
+    duration: number;
+  };
+}
+
+/**
+ * Configuration for entry animations
+ */
+export interface EntryAnimationConfig {
+  fade: { duration: number };
+  slide: { distance: number; duration: number };
+}
+
+/**
+ * Pending entry animation info
+ */
+export interface PendingEntryAnimation {
+  itemId: string;
+  direction: AnimationDirection;
+  timestamp: number;
+}
+
+/**
+ * Exit animation trigger function type
+ */
+export type ExitAnimationTrigger = (
+  direction: AnimationDirection,
+  onComplete: () => void,
+  preset?: ExitAnimationPreset,
+) => void;
+
+/**
+ * Info about an item currently exiting (for layout compensation)
+ */
+export interface ExitingItemInfo {
+  itemId: string;
+  index: number;
+  height: number;
+  timestamp: number;
+}

package/src/types/drag.ts

@@ -0,0 +1,101 @@
+import type { SharedValue, AnimatedRef } from 'react-native-reanimated';
+import type { GestureType } from 'react-native-gesture-handler';
+import type Animated from 'react-native-reanimated';
+
+/**
+ * Configuration for drag behavior
+ */
+export interface DragConfig {
+  /** Fixed height for list items (used for drag calculations) */
+  itemHeight: number;
+  /** Scale factor applied to dragged item */
+  dragScale: number;
+  /** Shadow opacity for dragged item */
+  dragShadowOpacity: number;
+  /** Vertical margin per item */
+  itemVerticalMargin: number;
+  /** Duration (ms) to hold drag handle before drag activates */
+  longPressDuration: number;
+  /** Pixels from viewport edge to trigger autoscroll */
+  edgeThreshold: number;
+  /** Maximum scroll speed in pixels per frame */
+  maxScrollSpeed: number;
+}
+
+/**
+ * Configuration for useDragGesture hook
+ */
+export interface UseDragGestureConfig {
+  /** Item ID for stable identity */
+  itemId: string;
+  /** Current index in list */
+  index: number;
+  /** Total number of items in the list */
+  totalItems: number;
+  /** Whether drag is enabled for this item */
+  enabled: boolean;
+  /** Ref to measure item container */
+  containerRef: AnimatedRef<Animated.View>;
+}
+
+/**
+ * Callbacks for drag gesture events
+ */
+export interface UseDragGestureCallbacks {
+  /** Called when reorder should occur (with index delta) */
+  onReorderByDelta?: (itemId: string, delta: number) => void;
+  /** Optional haptic feedback callback */
+  onHapticFeedback?: (type: 'light' | 'medium') => void;
+}
+
+/**
+ * Return value from useDragGesture hook
+ */
+export interface UseDragGestureResult {
+  /** The pan gesture to attach to drag handle */
+  panGesture: GestureType;
+  /** Whether this item is currently being dragged */
+  isDragging: SharedValue<boolean>;
+  /** Current translateY of this item */
+  translateY: SharedValue<number>;
+}
+
+/**
+ * Configuration for useDragShift hook
+ */
+export interface UseDragShiftConfig {
+  /** Item ID for identity check (to skip shift for the dragged item) */
+  itemId: string;
+  /** Current index in list */
+  index: number;
+}
+
+/**
+ * Return value from useDragShift hook
+ */
+export interface UseDragShiftResult {
+  /** Animated shift value for non-dragged items */
+  shiftY: SharedValue<number>;
+}
+
+/**
+ * Configuration for useDropCompensation hook
+ */
+export interface UseDropCompensationConfig {
+  /** Item ID for stable identity check */
+  itemId: string;
+  /** Current index in list */
+  index: number;
+  /** This item's translateY SharedValue (from useDragGesture) */
+  translateY: SharedValue<number>;
+  /** This item's shiftY SharedValue (from useDragShift) */
+  shiftY: SharedValue<number>;
+}
+
+/**
+ * Return value from useDragAnimatedStyle hook
+ */
+export interface UseDragAnimatedStyleResult {
+  /** Animated style for the dragged item (transform, zIndex, shadow) */
+  dragAnimatedStyle: ReturnType<typeof import('react-native-reanimated').useAnimatedStyle>;
+}

package/src/types/index.ts

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