@souscheflabs/reanimated-flashlist 0.1.7

package/lib/types/list.d.ts

@@ -0,0 +1,136 @@
+import type { ReactElement, ComponentType, JSXElementConstructor } from 'react';
+import type { ViewStyle } from 'react-native';
+import type { FlashListProps } from '@shopify/flash-list';
+import type { SharedValue } from 'react-native-reanimated';
+import type { GestureType } from 'react-native-gesture-handler';
+import type { DragConfig } from './drag';
+import type { AnimationDirection, ExitAnimationPreset, ExitAnimationConfig, EntryAnimationConfig, HapticFeedbackType } from './animations';
+/**
+ * Base item interface - consumers extend this
+ */
+export interface AnimatedListItem {
+    id: string;
+}
+/**
+ * Props passed to drag handle wrapper
+ */
+export interface DragHandleProps {
+    /** The pan gesture to attach */
+    gesture: GestureType;
+    /** Whether dragging is currently active */
+    isDragging: SharedValue<boolean>;
+}
+/**
+ * Render item info passed to renderItem callback
+ */
+export interface AnimatedRenderItemInfo<T extends AnimatedListItem> {
+    /** The item data */
+    item: T;
+    /** Current index in list */
+    index: number;
+    /** Total number of items */
+    totalItems: number;
+    /** Combined animated style (drag + entry/exit) - apply to outer Animated.View */
+    animatedStyle: ViewStyle;
+    /** Drag handle props - spread onto GestureDetector wrapping your drag handle */
+    dragHandleProps: DragHandleProps | null;
+    /** Whether this item is currently being dragged */
+    isDragging: boolean;
+    /** Whether drag is enabled for this item */
+    isDragEnabled: boolean;
+    /** Trigger exit animation programmatically */
+    triggerExitAnimation: (direction: AnimationDirection, onComplete: () => void, preset?: ExitAnimationPreset) => void;
+    /** Reset exit animation state */
+    resetExitAnimation: () => void;
+}
+/**
+ * Configuration for the AnimatedFlashList
+ */
+export interface AnimatedFlashListConfig {
+    /** Drag behavior configuration */
+    drag?: Partial<DragConfig>;
+    /** Exit animation configuration */
+    exitAnimation?: Partial<ExitAnimationConfig>;
+    /** Entry animation configuration */
+    entryAnimation?: Partial<EntryAnimationConfig>;
+}
+/**
+ * Props for AnimatedFlashList component
+ */
+export interface AnimatedFlashListProps<T extends AnimatedListItem> extends Omit<FlashListProps<T>, 'data' | 'renderItem' | 'keyExtractor' | 'ref'> {
+    /** List data */
+    data: T[];
+    /** Key extractor function */
+    keyExtractor: (item: T, index: number) => string;
+    /**
+     * Render function for each item
+     * Receives item data and animation utilities
+     */
+    renderItem: (info: AnimatedRenderItemInfo<T>) => ReactElement;
+    /**
+     * Whether drag-to-reorder is enabled
+     * @default false
+     */
+    dragEnabled?: boolean;
+    /**
+     * Callback when an item is reordered
+     * @param itemId - ID of the moved item
+     * @param fromIndex - Original index
+     * @param toIndex - New index
+     */
+    onReorder?: (itemId: string, fromIndex: number, toIndex: number) => void;
+    /**
+     * Callback with neighbor-based reorder info (for fractional indexing)
+     * @param itemId - ID of the moved item
+     * @param afterItemId - ID of item that should come before (null if moving to start)
+     * @param beforeItemId - ID of item that should come after (null if moving to end)
+     */
+    onReorderByNeighbors?: (itemId: string, afterItemId: string | null, beforeItemId: string | null) => void;
+    /**
+     * Function to determine if an item can be dragged
+     * @default () => true when dragEnabled is true
+     */
+    canDrag?: (item: T, index: number) => boolean;
+    /**
+     * Optional haptic feedback callback
+     * Called during drag operations
+     */
+    onHapticFeedback?: (type: HapticFeedbackType) => void;
+    /**
+     * Configuration overrides
+     */
+    config?: AnimatedFlashListConfig;
+    /**
+     * Called when FlashList needs to prepare for layout animation
+     * (before items are added/removed)
+     */
+    onPrepareLayoutAnimation?: () => void;
+    /** Footer component */
+    ListFooterComponent?: ReactElement<unknown, string | JSXElementConstructor<unknown>> | ComponentType<unknown> | null;
+    /** Refresh callback */
+    onRefresh?: () => void | Promise<void>;
+    /** Whether currently refreshing */
+    refreshing?: boolean;
+    /** Pagination callback */
+    onEndReached?: () => void;
+    /** Pagination threshold */
+    onEndReachedThreshold?: number;
+}
+/**
+ * Ref handle for AnimatedFlashList
+ */
+export interface AnimatedFlashListRef {
+    /**
+     * Prepare FlashList for layout animation before items are removed/added
+     */
+    prepareForLayoutAnimation: () => void;
+    /**
+     * Scroll to a specific offset
+     */
+    scrollToOffset: (offset: number, animated?: boolean) => void;
+    /**
+     * Scroll to a specific index
+     */
+    scrollToIndex: (index: number, animated?: boolean) => void;
+}
+//# sourceMappingURL=list.d.ts.map

package/lib/types/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/types/list.ts"],"names":[],"mappings":"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"}

package/lib/types/list.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@souscheflabs/reanimated-flashlist",
+  "version": "0.1.7",
+  "description": "A high-performance animated FlashList with drag-to-reorder and entry/exit animations (New Architecture)",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "source": "src/index.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "tag": "./scripts/tag.sh",
+    "release:patch": "./scripts/release.sh patch",
+    "release:minor": "./scripts/release.sh minor",
+    "release:major": "./scripts/release.sh major",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@shopify/flash-list": "^2.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0",
+    "react-native-gesture-handler": ">=2.14.0",
+    "react-native-reanimated": "^4.0.0",
+    "react-native-worklets": ">=0.7.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-react": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "@shopify/flash-list": "^2.0.0",
+    "@testing-library/react-native": "^12.4.0",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "react": "^18.2.0",
+    "react-native": "^0.76.0",
+    "react-native-gesture-handler": "^2.14.0",
+    "react-native-reanimated": "^4.0.0",
+    "react-test-renderer": "^18.2.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "react-native",
+    "flashlist",
+    "animated",
+    "drag-to-reorder",
+    "reanimated",
+    "layout-animation",
+    "new-architecture",
+    "turbomodules"
+  ],
+  "author": "SousChef Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SousChefLabs/reanimated-flashlist.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SousChefLabs/reanimated-flashlist/issues"
+  },
+  "homepage": "https://github.com/SousChefLabs/reanimated-flashlist#readme"
+}

package/src/AnimatedFlashList.tsx

@@ -0,0 +1,411 @@
+import React, {
+  useCallback,
+  useRef,
+  useMemo,
+  forwardRef,
+  useImperativeHandle,
+  useEffect,
+} from 'react';
+import {
+  View,
+  RefreshControl,
+  type NativeSyntheticEvent,
+  type NativeScrollEvent,
+  type LayoutChangeEvent,
+  type ViewStyle,
+} from 'react-native';
+import { FlashList, type ListRenderItemInfo, type FlashListRef } from '@shopify/flash-list';
+import { DragStateProvider, ListAnimationProvider, useDragState } from './contexts';
+import { AnimatedFlashListItem } from './AnimatedFlashListItem';
+import { DEFAULT_DRAG_CONFIG } from './constants';
+import type {
+  AnimatedListItem,
+  AnimatedFlashListProps,
+  AnimatedFlashListRef,
+  HapticFeedbackType,
+} from './types';
+
+/**
+ * Item wrapper component for FlashList
+ * Uses ref for totalItems to avoid renderItem callback recreation
+ */
+interface ItemWrapperProps<T extends AnimatedListItem> {
+  item: T;
+  index: number;
+  totalItemsRef: React.RefObject<number>;
+  renderItem: AnimatedFlashListProps<T>['renderItem'];
+  canDrag?: (item: T, index: number) => boolean;
+  dragEnabled: boolean;
+  onReorderByDelta?: (itemId: string, delta: number) => void;
+  onHapticFeedback?: (type: HapticFeedbackType) => void;
+}
+
+const ItemWrapper = React.memo(function ItemWrapper<T extends AnimatedListItem>({
+  item,
+  index,
+  totalItemsRef,
+  renderItem,
+  canDrag,
+  dragEnabled,
+  onReorderByDelta,
+  onHapticFeedback,
+}: ItemWrapperProps<T>) {
+  const isDragEnabled = dragEnabled && (canDrag ? canDrag(item, index) : true);
+
+  return (
+    <AnimatedFlashListItem
+      item={item}
+      index={index}
+      totalItems={totalItemsRef.current ?? 0}
+      isDragEnabled={isDragEnabled}
+      renderItem={renderItem}
+      onReorderByDelta={onReorderByDelta}
+      onHapticFeedback={onHapticFeedback}
+    />
+  );
+}) as <T extends AnimatedListItem>(props: ItemWrapperProps<T>) => React.ReactElement;
+
+/**
+ * Inner FlashList component that uses DragStateContext for scroll tracking
+ */
+interface InnerFlashListProps<T extends AnimatedListItem> {
+  data: T[];
+  totalItemsRef: React.RefObject<number>;
+  flashListRef: React.RefObject<FlashListRef<T> | null>;
+  renderItem: AnimatedFlashListProps<T>['renderItem'];
+  keyExtractor: (item: T, index: number) => string;
+  canDrag?: (item: T, index: number) => boolean;
+  dragEnabled: boolean;
+  onReorderByDelta?: (itemId: string, delta: number) => void;
+  onHapticFeedback?: (type: HapticFeedbackType) => void;
+  itemHeight: number;
+  ListFooterComponent?: AnimatedFlashListProps<T>['ListFooterComponent'];
+  onEndReached?: () => void;
+  onEndReachedThreshold?: number;
+  onRefresh?: () => void | Promise<void>;
+  refreshing?: boolean;
+  refreshTintColor?: string;
+  contentContainerStyle?: AnimatedFlashListProps<T>['contentContainerStyle'];
+  drawDistance?: number;
+  showsVerticalScrollIndicator?: boolean;
+}
+
+function InnerFlashList<T extends AnimatedListItem>({
+  data,
+  totalItemsRef,
+  flashListRef,
+  renderItem,
+  keyExtractor,
+  canDrag,
+  dragEnabled,
+  onReorderByDelta,
+  onHapticFeedback,
+  itemHeight,
+  ListFooterComponent,
+  onEndReached,
+  onEndReachedThreshold,
+  onRefresh,
+  refreshing,
+  refreshTintColor,
+  contentContainerStyle,
+  drawDistance = 500,
+  showsVerticalScrollIndicator = true,
+}: InnerFlashListProps<T>): React.ReactElement {
+  // Get drag state context for scroll tracking
+  const { scrollOffset, contentHeight, visibleHeight, listTopY, setListRef } =
+    useDragState();
+
+  // Register FlashList ref with drag context for autoscroll
+  useEffect(() => {
+    // Cast to unknown to satisfy the generic constraint
+    setListRef(flashListRef.current as FlashListRef<unknown> | null);
+    return () => setListRef(null);
+  }, [setListRef, flashListRef]);
+
+  // Update scroll offset on scroll
+  const handleScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      scrollOffset.value = event.nativeEvent.contentOffset.y;
+    },
+    [scrollOffset],
+  );
+
+  // Update content height when list content changes
+  const handleContentSizeChange = useCallback(
+    (_width: number, height: number) => {
+      contentHeight.value = height;
+    },
+    [contentHeight],
+  );
+
+  // Update visible height and list position when layout changes
+  const handleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      visibleHeight.value = event.nativeEvent.layout.height;
+      const nativeRef = flashListRef.current?.getNativeScrollRef?.() as
+        | { measureInWindow?: (cb: (x: number, y: number) => void) => void }
+        | undefined;
+      if (nativeRef?.measureInWindow) {
+        nativeRef.measureInWindow((_x, y) => {
+          listTopY.value = y;
+        });
+      }
+    },
+    [visibleHeight, listTopY, flashListRef],
+  );
+
+  // Render item for FlashList
+  const flashListRenderItem = useCallback(
+    ({ item, index }: ListRenderItemInfo<T>) => (
+      <ItemWrapper
+        item={item}
+        index={index}
+        totalItemsRef={totalItemsRef}
+        renderItem={renderItem}
+        canDrag={canDrag}
+        dragEnabled={dragEnabled}
+        onReorderByDelta={onReorderByDelta}
+        onHapticFeedback={onHapticFeedback}
+      />
+    ),
+    [
+      totalItemsRef,
+      renderItem,
+      canDrag,
+      dragEnabled,
+      onReorderByDelta,
+      onHapticFeedback,
+    ],
+  );
+
+  // getItemType for FlashList recycling optimization
+  const getItemType = useCallback(() => 'animated-item', []);
+
+  // Override item layout for consistent drag calculations
+  // Note: We cast the layout to include size for drag calculations
+  const overrideItemLayout = useCallback(
+    (layout: { span?: number }, _item: T, _index: number) => {
+      // FlashList v2 uses this for span, but we extend for size in drag calculations
+      (layout as { size?: number }).size = itemHeight;
+    },
+    [itemHeight],
+  );
+
+  return (
+    <FlashList
+      ref={flashListRef as React.RefObject<FlashListRef<T>>}
+      data={data}
+      renderItem={flashListRenderItem}
+      keyExtractor={keyExtractor}
+      getItemType={getItemType}
+      overrideItemLayout={overrideItemLayout}
+      onScroll={handleScroll}
+      onContentSizeChange={handleContentSizeChange}
+      onLayout={handleLayout}
+      scrollEventThrottle={16}
+      drawDistance={drawDistance}
+      maintainVisibleContentPosition={{ disabled: true }}
+      showsVerticalScrollIndicator={showsVerticalScrollIndicator}
+      contentContainerStyle={contentContainerStyle}
+      ListFooterComponent={ListFooterComponent ?? undefined}
+      onEndReached={onEndReached}
+      onEndReachedThreshold={onEndReachedThreshold}
+      refreshControl={
+        onRefresh ? (
+          <RefreshControl
+            refreshing={refreshing ?? false}
+            onRefresh={onRefresh}
+            tintColor={refreshTintColor}
+            colors={refreshTintColor ? [refreshTintColor] : undefined}
+          />
+        ) : undefined
+      }
+    />
+  );
+}
+
+/**
+ * AnimatedFlashList - High-performance animated list with drag-to-reorder
+ *
+ * A wrapper around @shopify/flash-list that provides:
+ * - Smooth drag-to-reorder with autoscroll
+ * - Entry animations for new items
+ * - Exit animations for removed items
+ * - Full TypeScript generics support
+ *
+ * @example
+ * ```tsx
+ * <AnimatedFlashList<MyItem>
+ *   data={items}
+ *   keyExtractor={(item) => item.id}
+ *   renderItem={({ item, animatedStyle, dragHandleProps }) => (
+ *     <Animated.View style={animatedStyle}>
+ *       <MyItem item={item} />
+ *       {dragHandleProps && (
+ *         <GestureDetector gesture={dragHandleProps.gesture}>
+ *           <DragHandle />
+ *         </GestureDetector>
+ *       )}
+ *     </Animated.View>
+ *   )}
+ *   dragEnabled
+ *   onReorder={(itemId, from, to) => reorderItems(itemId, from, to)}
+ * />
+ * ```
+ */
+function AnimatedFlashListInner<T extends AnimatedListItem>(
+  props: AnimatedFlashListProps<T>,
+  ref: React.ForwardedRef<AnimatedFlashListRef>,
+): React.ReactElement | null {
+  const {
+    data,
+    keyExtractor,
+    renderItem,
+    dragEnabled = false,
+    onReorder,
+    onReorderByNeighbors,
+    canDrag,
+    onHapticFeedback,
+    config,
+    onPrepareLayoutAnimation,
+    ListFooterComponent,
+    onRefresh,
+    refreshing = false,
+    onEndReached,
+    onEndReachedThreshold = 0.5,
+    contentContainerStyle,
+    ...flashListProps
+  } = props;
+
+  // Merge config with defaults
+  const dragConfig = useMemo(
+    () => ({
+      ...DEFAULT_DRAG_CONFIG,
+      ...config?.drag,
+    }),
+    [config?.drag],
+  );
+
+  // Ref to FlashList
+  const flashListRef = useRef<FlashListRef<T>>(null);
+
+  // Expose methods to parent via ref
+  useImperativeHandle(ref, () => ({
+    prepareForLayoutAnimation: () => {
+      flashListRef.current?.prepareForLayoutAnimationRender();
+      onPrepareLayoutAnimation?.();
+    },
+    scrollToOffset: (offset: number, animated = true) => {
+      flashListRef.current?.scrollToOffset({ offset, animated });
+    },
+    scrollToIndex: (index: number, animated = true) => {
+      flashListRef.current?.scrollToIndex({ index, animated });
+    },
+  }));
+
+  // Keep valid items in ref for reorder callback
+  const dataRef = useRef<T[]>([]);
+  dataRef.current = data;
+
+  // Handle reorder by index delta - converts to various callback formats
+  const handleReorderByDelta = useCallback(
+    (itemId: string, indexDelta: number) => {
+      if (indexDelta === 0) return;
+
+      const currentItems = dataRef.current;
+      const currentIndex = currentItems.findIndex(item => item.id === itemId);
+      if (currentIndex === -1) return;
+
+      const newIndex = Math.max(
+        0,
+        Math.min(currentItems.length - 1, currentIndex + indexDelta),
+      );
+      if (newIndex === currentIndex) return;
+
+      // Call onReorder if provided
+      if (onReorder) {
+        onReorder(itemId, currentIndex, newIndex);
+      }
+
+      // Call onReorderByNeighbors if provided (for fractional indexing)
+      if (onReorderByNeighbors) {
+        let afterItemId: string | null = null;
+        let beforeItemId: string | null = null;
+
+        if (indexDelta > 0) {
+          afterItemId = currentItems[newIndex]?.id ?? null;
+          beforeItemId =
+            newIndex < currentItems.length - 1
+              ? currentItems[newIndex + 1]?.id ?? null
+              : null;
+        } else {
+          afterItemId =
+            newIndex > 0 ? currentItems[newIndex - 1]?.id ?? null : null;
+          beforeItemId = currentItems[newIndex]?.id ?? null;
+        }
+
+        onReorderByNeighbors(itemId, afterItemId, beforeItemId);
+      }
+    },
+    [onReorder, onReorderByNeighbors],
+  );
+
+  // Use ref for totalItems to avoid renderItem callback recreation
+  const totalItemsRef = useRef(data.length);
+  totalItemsRef.current = data.length;
+
+  // Early return for empty data
+  if (!data || !Array.isArray(data) || data.length === 0) {
+    if (ListFooterComponent) {
+      return (
+        <View style={containerStyle}>
+          {React.isValidElement(ListFooterComponent)
+            ? ListFooterComponent
+            : React.createElement(ListFooterComponent as React.ComponentType)}
+        </View>
+      );
+    }
+    return null;
+  }
+
+  return (
+    <ListAnimationProvider>
+      <DragStateProvider config={dragConfig}>
+        <View style={containerStyle}>
+          <InnerFlashList
+            data={data}
+            totalItemsRef={totalItemsRef}
+            flashListRef={flashListRef}
+            renderItem={renderItem}
+            keyExtractor={keyExtractor}
+            canDrag={canDrag}
+            dragEnabled={dragEnabled}
+            onReorderByDelta={
+              onReorder || onReorderByNeighbors ? handleReorderByDelta : undefined
+            }
+            onHapticFeedback={onHapticFeedback}
+            itemHeight={dragConfig.itemHeight}
+            ListFooterComponent={ListFooterComponent}
+            onEndReached={onEndReached}
+            onEndReachedThreshold={onEndReachedThreshold}
+            onRefresh={onRefresh}
+            refreshing={refreshing}
+            contentContainerStyle={contentContainerStyle}
+            {...flashListProps}
+          />
+        </View>
+      </DragStateProvider>
+    </ListAnimationProvider>
+  );
+}
+
+const containerStyle: ViewStyle = {
+  flex: 1,
+};
+
+// Forward ref with generic support
+export const AnimatedFlashList = forwardRef(AnimatedFlashListInner) as <
+  T extends AnimatedListItem,
+>(
+  props: AnimatedFlashListProps<T> & { ref?: React.ForwardedRef<AnimatedFlashListRef> },
+) => React.ReactElement | null;