@souscheflabs/reanimated-flashlist 0.4.4 → 0.5.0

package/lib/AnimatedFlashList.d.ts

@@ -1,5 +1,5 @@
-import React from 'react';
-import type { AnimatedListItem, AnimatedFlashListProps, AnimatedFlashListRef } from './types';
+import React from "react";
+import type { AnimatedListItem, AnimatedFlashListProps, AnimatedFlashListRef } from "./types";
 export declare const AnimatedFlashList: <T extends AnimatedListItem>(props: AnimatedFlashListProps<T> & {
     ref?: React.ForwardedRef<AnimatedFlashListRef>;
 }) => React.ReactElement | null;

package/lib/AnimatedFlashList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimatedFlashList.d.ts","sourceRoot":"","sources":["../src/AnimatedFlashList.tsx"],"names":[],"mappings":"AAAA,OAAO,KAQN,MAAM,OAAO,CAAC;AAaf,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EAErB,MAAM,SAAS,CAAC;AAggBjB,eAAO,MAAM,iBAAiB,EAAyC,CACrE,CAAC,SAAS,gBAAgB,EAE1B,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAA;CAAE,KAClF,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC"}
+{"version":3,"file":"AnimatedFlashList.d.ts","sourceRoot":"","sources":["../src/AnimatedFlashList.tsx"],"names":[],"mappings":"AAAA,OAAO,KASN,MAAM,OAAO,CAAC;AA2Bf,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EAErB,MAAM,SAAS,CAAC;AA65BjB,eAAO,MAAM,iBAAiB,EAAyC,CACrE,CAAC,SAAS,gBAAgB,EAE1B,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG;IACjC,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC;CAChD,KACE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC"}

package/lib/AnimatedFlashList.js

@@ -36,10 +36,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnimatedFlashList = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
+const react_native_reanimated_1 = __importStar(require("react-native-reanimated"));
+const react_native_gesture_handler_1 = require("react-native-gesture-handler");
+const react_native_worklets_1 = require("react-native-worklets");
 const flash_list_1 = require("@shopify/flash-list");
-const contexts_1 = require("./contexts");
+const DragStateContext_1 = require("./contexts/DragStateContext");
+const useOverlayCrossfade_1 = require("./hooks/drag/useOverlayCrossfade");
+const ListAnimationContext_1 = require("./contexts/ListAnimationContext");
 const AnimatedFlashListItem_1 = require("./AnimatedFlashListItem");
-const constants_1 = require("./constants");
+const drag_1 = require("./constants/drag");
 class AnimationErrorBoundary extends react_1.default.Component {
     state = { hasError: false };
     static getDerivedStateFromError() {
@@ -47,8 +52,8 @@ class AnimationErrorBoundary extends react_1.default.Component {
     }
     componentDidCatch(error) {
         if (__DEV__) {
-            console.warn('[AnimatedFlashList] Animation error caught by error boundary. ' +
-                'Falling back to non-animated list.', error);
+            console.warn("[AnimatedFlashList] Animation error caught by error boundary. " +
+                "Falling back to non-animated list.", error);
         }
     }
     render() {
@@ -58,23 +63,270 @@ class AnimationErrorBoundary extends react_1.default.Component {
         return this.props.children;
     }
 }
+const DragOverlay = react_1.default.memo(function DragOverlay({ data, totalItemsRef, renderItem }) {
+    const { overlayActive, overlayItemId, overlayBaseX, overlayBaseY, overlayWidth, overlayHeight, overlayTranslateY, overlayReady, overlayVisible, scrollOffset, dragStartScrollOffset, draggedScale, isDragging, overlayTouchOffset, overlayAbsoluteY, overlayContainerY, dragOverlayOpacity, overlayFrozenItemId, overlayRenderedOnUI, } = (0, DragStateContext_1.useDragState)();
+    // Drive overlay crossfade animation on UI thread
+    // This ensures smooth visibility transitions without JS scheduling races
+    (0, useOverlayCrossfade_1.useOverlayCrossfade)();
+    const [overlayId, setOverlayId] = (0, react_1.useState)(null);
+    const [frozenId, setFrozenId] = (0, react_1.useState)(null);
+    const setOverlayIdSafe = (0, react_1.useCallback)((nextId) => {
+        setOverlayId(nextId);
+    }, []);
+    const setFrozenIdSafe = (0, react_1.useCallback)((nextId) => {
+        setFrozenId(nextId);
+    }, []);
+    (0, react_native_reanimated_1.useAnimatedReaction)(() => overlayItemId.value, (current, prev) => {
+        "worklet";
+        if (current === prev)
+            return;
+        (0, react_native_worklets_1.scheduleOnRN)(setOverlayIdSafe, current || null);
+    }, [setOverlayIdSafe]);
+    // Track frozen ID for rendering during fade-out
+    (0, react_native_reanimated_1.useAnimatedReaction)(() => overlayFrozenItemId.value, (current, prev) => {
+        "worklet";
+        if (current === prev)
+            return;
+        (0, react_native_worklets_1.scheduleOnRN)(setFrozenIdSafe, current || null);
+    }, [setFrozenIdSafe]);
+    (0, react_1.useEffect)(() => {
+        overlayVisible.value = Boolean(overlayId);
+    }, [overlayId, overlayVisible]);
+    // Use frozenId to keep overlay rendered during fade-out
+    const overlayItem = (0, react_1.useMemo)(() => {
+        const id = frozenId || overlayId;
+        if (!id)
+            return null;
+        return data.find((item) => item.id === id) ?? null;
+    }, [data, frozenId, overlayId]);
+    // Create disabled gesture and false isDragging for overlay rendering
+    // This allows renderItem to show drag handle UI without functional gesture
+    const disabledGesture = (0, react_1.useMemo)(() => react_native_gesture_handler_1.Gesture.Pan().enabled(false), []);
+    const falseIsDragging = (0, react_native_reanimated_1.useSharedValue)(false);
+    const overlayStyle = (0, react_native_reanimated_1.useAnimatedStyle)(() => {
+        // Use frozenItemId so overlay stays renderable during fade-out
+        const itemId = overlayFrozenItemId.value || overlayItemId.value;
+        // Keep rendering if frozenItemId is set (crossfade in progress) even if overlayReady is false.
+        // This prevents the overlay from becoming invisible before the crossfade completes,
+        // which would cause a brief moment where both overlay AND original are invisible.
+        // FIXED: Also require overlayVisible to ensure JS-side overlayItem exists before fading.
+        // overlayVisible is only cleared AFTER fade-out completes (in useOverlayCrossfade),
+        // so this doesn't break fade-out.
+        if (!itemId || (!overlayFrozenItemId.value && !overlayReady.value) || !overlayVisible.value) {
+            // Mark overlay as NOT rendered when returning invisible style
+            overlayRenderedOnUI.value = false;
+            return { opacity: 0, position: "absolute" };
+        }
+        // Mark overlay as rendered on UI thread - this is the KEY fix for the vanish bug.
+        // Setting this here (in useAnimatedStyle, which runs on UI thread) instead of
+        // in useEffect (JS thread) ensures the original item knows the overlay has
+        // actually rendered BEFORE the crossfade starts. This prevents the race condition
+        // where the original starts fading out before the overlay appears.
+        overlayRenderedOnUI.value = true;
+        const scale = isDragging.value ? draggedScale.value : 1;
+        // During active drag, use absolute finger position for reliable overlay tracking.
+        // This avoids lag from JS-thread scroll offset updates during simultaneous scroll+drag.
+        // Formula: top = absoluteY - touchOffset - containerY
+        // Where:
+        // - absoluteY = finger's current screen Y position
+        // - touchOffset = how far down in the item the finger started
+        // - containerY = overlay container's screen Y position
+        //
+        // During drop animation (isDropping), switch back to slot-based positioning
+        // since the finger is no longer tracking and we need to animate to final slot.
+        let top;
+        if (isDragging.value) {
+            // Active drag: follow finger precisely
+            top = overlayAbsoluteY.value - overlayTouchOffset.value - overlayContainerY.value;
+        }
+        else {
+            // Drop animation: use slot-based positioning with scroll compensation
+            // Note: scrollDelta is SUBTRACTED because overlayBaseY was measured at drag start
+            // (when scroll was dragStartScrollOffset). As user scrolls down (scrollDelta > 0),
+            // the target slot moves UP visually, so we subtract.
+            const scrollDelta = scrollOffset.value - dragStartScrollOffset.value;
+            top = overlayBaseY.value + overlayTranslateY.value - scrollDelta;
+        }
+        return {
+            position: "absolute",
+            left: overlayBaseX.value,
+            top,
+            width: overlayWidth.value,
+            height: overlayHeight.value,
+            zIndex: 1000,
+            transform: [{ scale }],
+            opacity: dragOverlayOpacity.value, // Uses shared crossfade value
+        };
+    });
+    // Only return null when BOTH overlayItem is null AND frozenId is empty
+    // This keeps the Animated.View mounted during fade-out (while frozenId is set)
+    if (!overlayItem && !frozenId)
+        return null;
+    const overlayIndex = overlayItem
+        ? data.findIndex((item) => item.id === overlayItem.id)
+        : -1;
+    const totalItems = totalItemsRef.current ?? data.length;
+    return (<react_native_reanimated_1.default.View pointerEvents="none" style={overlayStyle}>
+      {overlayItem &&
+            renderItem({
+                item: overlayItem,
+                index: overlayIndex,
+                totalItems,
+                animatedStyle: {},
+                dragHandleProps: {
+                    gesture: disabledGesture,
+                    isDragging: falseIsDragging,
+                },
+                isDragging: false,
+                isDragEnabled: false,
+                triggerExitAnimation: () => { },
+                resetExitAnimation: () => { },
+            })}
+    </react_native_reanimated_1.default.View>);
+});
+const ShiftedItemOverlays = react_1.default.memo(function ShiftedItemOverlays({ data, totalItemsRef, renderItem }) {
+    const { shiftedOverlays, shiftedOverlaysActive, shiftedOverlaysRendered } = (0, DragStateContext_1.useDragState)();
+    // State to hold overlay items on JS thread
+    const [overlayItems, setOverlayItems] = (0, react_1.useState)([]);
+    // Callback to update overlay items from JS thread
+    // v40.1: Y position is now viewport-relative (captured with scroll offset subtracted)
+    const updateOverlayItems = (0, react_1.useCallback)((overlays, active) => {
+        if (active && Object.keys(overlays).length > 0) {
+            const items = Object.entries(overlays)
+                .map(([id, pos]) => ({
+                item: data.find((d) => d.id === id),
+                position: { y: pos.baseY, height: pos.height },
+            }))
+                .filter((x) => x.item !== undefined);
+            setOverlayItems(items);
+        }
+        else {
+            setOverlayItems([]);
+        }
+    }, [data]);
+    // Watch for overlay changes
+    (0, react_native_reanimated_1.useAnimatedReaction)(() => ({
+        active: shiftedOverlaysActive.value,
+        overlays: shiftedOverlays.value,
+    }), (state, prev) => {
+        "worklet";
+        // Only update when state changes
+        if (prev !== null &&
+            state.active === prev.active &&
+            Object.keys(state.overlays).length === Object.keys(prev.overlays).length) {
+            return;
+        }
+        (0, react_native_worklets_1.scheduleOnRN)(updateOverlayItems, state.overlays, state.active);
+    }, [updateOverlayItems]);
+    // v41.6: Use useLayoutEffect for earlier signal (runs after commit, before paint)
+    // This reduces the timing gap between overlay render and originals being hidden
+    (0, react_1.useLayoutEffect)(() => {
+        shiftedOverlaysRendered.value = overlayItems.length > 0;
+    }, [overlayItems.length, shiftedOverlaysRendered]);
+    // Create disabled gesture and false isDragging for overlay rendering
+    const disabledGesture = (0, react_1.useMemo)(() => react_native_gesture_handler_1.Gesture.Pan().enabled(false), []);
+    const falseIsDragging = (0, react_native_reanimated_1.useSharedValue)(false);
+    if (overlayItems.length === 0)
+        return null;
+    const totalItems = totalItemsRef.current ?? data.length;
+    return (<>
+      {overlayItems.map(({ item, position }) => (<react_native_1.View key={`shifted-overlay-${item.id}`} style={{
+                position: "absolute",
+                top: position.y,
+                left: 0,
+                right: 0,
+                height: position.height,
+                zIndex: 999,
+            }} pointerEvents="none">
+          {renderItem({
+                item,
+                index: data.findIndex((d) => d.id === item.id),
+                totalItems,
+                animatedStyle: {},
+                dragHandleProps: {
+                    gesture: disabledGesture,
+                    isDragging: falseIsDragging,
+                },
+                isDragging: false,
+                isDragEnabled: false,
+                triggerExitAnimation: () => { },
+                resetExitAnimation: () => { },
+            })}
+        </react_native_1.View>))}
+    </>);
+});
+const DragContainer = react_1.default.memo(function DragContainer({ children, }) {
+    const { overlayContainerX, overlayContainerY, overlayContainerYLayout, overlayContainerReady, dragContainerRef, } = (0, DragStateContext_1.useDragState)();
+    const handleLayout = (0, react_1.useCallback)(() => {
+        const node = dragContainerRef.current;
+        if (!node)
+            return;
+        node.measureInWindow((x, y) => {
+            overlayContainerX.value = x;
+            overlayContainerY.value = y;
+            overlayContainerYLayout.value = y; // Keep measureInWindow value for shifted overlay calculations
+            overlayContainerReady.value = true;
+        });
+    }, [
+        overlayContainerX,
+        overlayContainerY,
+        overlayContainerYLayout,
+        overlayContainerReady,
+        dragContainerRef,
+    ]);
+    return (<react_native_reanimated_1.default.View ref={dragContainerRef} style={containerStyle} onLayout={handleLayout}>
+      {children}
+    </react_native_reanimated_1.default.View>);
+});
 const ItemWrapper = react_1.default.memo(function ItemWrapper({ item, index, totalItemsRef, renderItem, canDrag, dragEnabled, onReorderByDelta, onHapticFeedback, }) {
     const isDragEnabled = dragEnabled && (canDrag ? canDrag(item, index) : true);
     return (<AnimatedFlashListItem_1.AnimatedFlashListItem item={item} index={index} totalItems={totalItemsRef.current ?? 0} isDragEnabled={isDragEnabled} renderItem={renderItem} onReorderByDelta={onReorderByDelta} onHapticFeedback={onHapticFeedback}/>);
 });
 function InnerFlashList({ data, totalItemsRef, flashListRef, renderItem, keyExtractor, canDrag, dragEnabled, onReorderByDelta, onHapticFeedback, itemHeight, ListFooterComponent, ListEmptyComponent, onEndReached, onEndReachedThreshold, onRefresh, refreshing, refreshTintColor, contentContainerStyle, drawDistance = 500, showsVerticalScrollIndicator = true, extraData, onCommitLayoutEffect, }) {
     // Get drag state context for scroll tracking
-    const { scrollOffset, contentHeight, visibleHeight, listTopY, setListRef, totalItems, notifyLayoutCommit, } = (0, contexts_1.useDragState)();
-    // Register FlashList ref with drag context for autoscroll
-    (0, react_1.useEffect)(() => {
-        // Cast to unknown to satisfy the generic constraint
-        setListRef(flashListRef.current);
-        return () => setListRef(null);
-    }, [setListRef, flashListRef]);
+    const { scrollOffset, contentHeight, visibleHeight, listTopY, listLeftX, setListRef, totalItems, notifyLayoutCommit, isDragging, isDropping, itemIndexRegistry, } = (0, DragStateContext_1.useDragState)();
+    // v40.1: Disable scroll while dropping to prevent overlay drift
+    // FlashList needs scrollEnabled as a regular boolean, not a SharedValue
+    const [scrollEnabled, setScrollEnabled] = (0, react_1.useState)(true);
+    const setScrollEnabledSafe = (0, react_1.useCallback)((enabled) => {
+        setScrollEnabled(enabled);
+    }, []);
+    (0, react_native_reanimated_1.useAnimatedReaction)(() => isDragging.value || isDropping.value, (draggingOrDropping, prevDraggingOrDropping) => {
+        "worklet";
+        if (draggingOrDropping !== prevDraggingOrDropping) {
+            (0, react_native_worklets_1.scheduleOnRN)(setScrollEnabledSafe, !draggingOrDropping);
+        }
+    }, [setScrollEnabledSafe]);
+    // Callback ref that notifies DragStateContext when FlashList is available.
+    // This fires immediately when FlashList sets the ref, unlike useEffect which
+    // would run after render with flashListRef.current potentially still null.
+    const handleFlashListRef = (0, react_1.useCallback)((instance) => {
+        // Update the ref object for other uses (scrollToOffset, prepareForLayoutAnimationRender, etc.)
+        flashListRef.current =
+            instance;
+        // Notify DragStateContext - this triggers native layout observation setup
+        setListRef(instance);
+    }, [flashListRef, setListRef]);
     // Sync totalItems SharedValue with data.length for worklet access
     (0, react_1.useEffect)(() => {
         totalItems.value = data.length;
     }, [data.length, totalItems]);
+    // Prune stale entries from itemIndexRegistry when data changes.
+    // Skip during active drag/drop to avoid corrupting indices mid-operation.
+    (0, react_1.useEffect)(() => {
+        if (isDragging.value || isDropping.value)
+            return;
+        const currentIds = new Set(data.map((item) => item.id));
+        const registry = itemIndexRegistry.value;
+        const staleIds = Object.keys(registry).filter((id) => !currentIds.has(id));
+        if (staleIds.length > 0) {
+            const pruned = { ...registry };
+            for (const id of staleIds) {
+                delete pruned[id];
+            }
+            itemIndexRegistry.value = pruned;
+        }
+    }, [data, itemIndexRegistry, isDragging, isDropping]);
     // Update scroll offset on scroll
     const handleScroll = (0, react_1.useCallback)((event) => {
         scrollOffset.value = event.nativeEvent.contentOffset.y;
@@ -89,14 +341,15 @@ function InnerFlashList({ data, totalItemsRef, flashListRef, renderItem, keyExtr
         // Get native scroll ref and validate it has measureInWindow before using
         const nativeRef = flashListRef.current?.getNativeScrollRef?.();
         if (nativeRef &&
-            typeof nativeRef === 'object' &&
-            'measureInWindow' in nativeRef &&
-            typeof nativeRef.measureInWindow === 'function') {
-            nativeRef.measureInWindow((_x, y) => {
+            typeof nativeRef === "object" &&
+            "measureInWindow" in nativeRef &&
+            typeof nativeRef.measureInWindow === "function") {
+            nativeRef.measureInWindow((x, y) => {
                 listTopY.value = y;
+                listLeftX.value = x;
             });
         }
-    }, [visibleHeight, listTopY, flashListRef]);
+    }, [visibleHeight, listTopY, listLeftX, flashListRef]);
     const handleCommitLayoutEffect = (0, react_1.useCallback)(() => {
         notifyLayoutCommit();
         onCommitLayoutEffect?.();
@@ -111,14 +364,14 @@ function InnerFlashList({ data, totalItemsRef, flashListRef, renderItem, keyExtr
         onHapticFeedback,
     ]);
     // getItemType for FlashList recycling optimization
-    const getItemType = (0, react_1.useCallback)(() => 'animated-item', []);
+    const getItemType = (0, react_1.useCallback)(() => "animated-item", []);
     // Override item layout for consistent drag calculations
     // Note: We cast the layout to include size for drag calculations
     const overrideItemLayout = (0, react_1.useCallback)((layout, _item, _index) => {
         // FlashList v2 uses this for span, but we extend for size in drag calculations
         layout.size = itemHeight;
     }, [itemHeight]);
-    return (<flash_list_1.FlashList ref={flashListRef} 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} onCommitLayoutEffect={handleCommitLayoutEffect} extraData={extraData} contentContainerStyle={contentContainerStyle} ListFooterComponent={ListFooterComponent ?? undefined} ListEmptyComponent={ListEmptyComponent ?? undefined} onEndReached={onEndReached} onEndReachedThreshold={onEndReachedThreshold} refreshControl={onRefresh ? (<react_native_1.RefreshControl refreshing={refreshing ?? false} onRefresh={onRefresh} tintColor={refreshTintColor} colors={refreshTintColor ? [refreshTintColor] : undefined}/>) : undefined}/>);
+    return (<flash_list_1.FlashList ref={handleFlashListRef} 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} onCommitLayoutEffect={handleCommitLayoutEffect} extraData={extraData} contentContainerStyle={contentContainerStyle} ListFooterComponent={ListFooterComponent ?? undefined} ListEmptyComponent={ListEmptyComponent ?? undefined} onEndReached={onEndReached} onEndReachedThreshold={onEndReachedThreshold} scrollEnabled={scrollEnabled} refreshControl={onRefresh ? (<react_native_1.RefreshControl refreshing={refreshing ?? false} onRefresh={onRefresh} tintColor={refreshTintColor} colors={refreshTintColor ? [refreshTintColor] : undefined}/>) : undefined}/>);
 }
 /**
  * AnimatedFlashList - High-performance animated list with drag-to-reorder
@@ -150,15 +403,15 @@ function InnerFlashList({ data, totalItemsRef, flashListRef, renderItem, keyExtr
  * ```
  */
 function AnimatedFlashListInner(props, ref) {
-    const { data, keyExtractor, renderItem, dragEnabled = false, onReorder, onReorderByNeighbors, canDrag, onHapticFeedback, config, onPrepareLayoutAnimation, ListFooterComponent, ListEmptyComponent, onRefresh, refreshing = false, onEndReached, onEndReachedThreshold = 0.5, contentContainerStyle, estimatedItemSize, ...flashListProps } = props;
+    const { data, keyExtractor, renderItem, dragEnabled = false, onReorder, onReorderByNeighbors, canDrag, onHapticFeedback, config, onPrepareLayoutAnimation, ListFooterComponent, ListEmptyComponent, onRefresh, refreshing = false, onEndReached, onEndReachedThreshold = 0.5, contentContainerStyle, ...flashListProps } = props;
     const { extraData: userExtraData, onCommitLayoutEffect: userOnCommitLayoutEffect, ...restFlashListProps } = flashListProps;
     // Merge config with defaults
-    // Use estimatedItemSize as default itemHeight if not explicitly configured
+    // Note: estimatedItemSize was removed in FlashList v2
+    // Users should configure itemHeight via config.drag.itemHeight
     const dragConfig = (0, react_1.useMemo)(() => ({
-        ...constants_1.DEFAULT_DRAG_CONFIG,
+        ...drag_1.DEFAULT_DRAG_CONFIG,
         ...config?.drag,
-        itemHeight: config?.drag?.itemHeight ?? estimatedItemSize ?? constants_1.DEFAULT_DRAG_CONFIG.itemHeight,
-    }), [config?.drag, estimatedItemSize]);
+    }), [config?.drag]);
     // Ref to FlashList
     const flashListRef = (0, react_1.useRef)(null);
     // Expose methods to parent via ref
@@ -184,11 +437,12 @@ function AnimatedFlashListInner(props, ref) {
         setLayoutVersion((version) => version + 1);
     }, []);
     // Handle reorder by index delta - converts to various callback formats
+    // NOTE: No LayoutAnimation needed - layout commit compensation handles visual transitions
     const handleReorderByDelta = (0, react_1.useCallback)((itemId, indexDelta) => {
         if (indexDelta === 0)
             return;
         const currentItems = dataRef.current;
-        const currentIndex = currentItems.findIndex(item => item.id === itemId);
+        const currentIndex = currentItems.findIndex((item) => item.id === itemId);
         if (currentIndex === -1)
             return;
         const newIndex = Math.max(0, Math.min(currentItems.length - 1, currentIndex + indexDelta));
@@ -206,12 +460,12 @@ function AnimatedFlashListInner(props, ref) {
                 afterItemId = currentItems[newIndex]?.id ?? null;
                 beforeItemId =
                     newIndex < currentItems.length - 1
-                        ? currentItems[newIndex + 1]?.id ?? null
+                        ? (currentItems[newIndex + 1]?.id ?? null)
                         : null;
             }
             else {
                 afterItemId =
-                    newIndex > 0 ? currentItems[newIndex - 1]?.id ?? null : null;
+                    newIndex > 0 ? (currentItems[newIndex - 1]?.id ?? null) : null;
                 beforeItemId = currentItems[newIndex]?.id ?? null;
             }
             onReorderByNeighbors(itemId, afterItemId, beforeItemId);
@@ -256,13 +510,17 @@ function AnimatedFlashListInner(props, ref) {
         })} keyExtractor={keyExtractor} contentContainerStyle={contentContainerStyle} ListFooterComponent={ListFooterComponent ?? undefined} onEndReached={onEndReached} onEndReachedThreshold={onEndReachedThreshold}/>
     </react_native_1.View>);
     return (<AnimationErrorBoundary fallback={plainFlashListFallback}>
-      <contexts_1.ListAnimationProvider>
-        <contexts_1.DragStateProvider config={dragConfig}>
-          <react_native_1.View style={containerStyle}>
-            <InnerFlashList {...restFlashListProps} 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} ListEmptyComponent={ListEmptyComponent} onEndReached={onEndReached} onEndReachedThreshold={onEndReachedThreshold} onRefresh={onRefresh} refreshing={refreshing} contentContainerStyle={contentContainerStyle} extraData={combinedExtraData} onCommitLayoutEffect={userOnCommitLayoutEffect}/>
-          </react_native_1.View>
-        </contexts_1.DragStateProvider>
-      </contexts_1.ListAnimationProvider>
+      <ListAnimationContext_1.ListAnimationProvider>
+        <DragStateContext_1.DragStateProvider config={dragConfig}>
+          <DragContainer>
+            <InnerFlashList {...restFlashListProps} 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} ListEmptyComponent={ListEmptyComponent} onEndReached={onEndReached} onEndReachedThreshold={onEndReachedThreshold} onRefresh={onRefresh} refreshing={refreshing} contentContainerStyle={contentContainerStyle} extraData={combinedExtraData} onCommitLayoutEffect={userOnCommitLayoutEffect}/>
+            <DragOverlay data={data} totalItemsRef={totalItemsRef} renderItem={renderItem}/>
+            <ShiftedItemOverlays data={data} totalItemsRef={totalItemsRef} renderItem={renderItem}/>
+          </DragContainer>
+        </DragStateContext_1.DragStateProvider>
+      </ListAnimationContext_1.ListAnimationProvider>
     </AnimationErrorBoundary>);
 }
 const containerStyle = {

package/lib/AnimatedFlashListItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimatedFlashListItem.d.ts","sourceRoot":"","sources":["../src/AnimatedFlashListItem.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAaxF,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAMjB,UAAU,0BAA0B,CAAC,CAAC,SAAS,gBAAgB;IAC7D,oBAAoB;IACpB,IAAI,EAAE,CAAC,CAAC;IACR,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,UAAU,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,YAAY,CAAC;IACpE,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,iBAAS,0BAA0B,CAAC,CAAC,SAAS,gBAAgB,EAAE,EAC9D,IAAI,EACJ,KAAK,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAqO3D;AAGD,eAAO,MAAM,qBAAqB,EAE7B,OAAO,0BAA0B,CAAC"}
+{"version":3,"file":"AnimatedFlashListItem.d.ts","sourceRoot":"","sources":["../src/AnimatedFlashListItem.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAWxF,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,UAAU,0BAA0B,CAAC,CAAC,SAAS,gBAAgB;IAC7D,oBAAoB;IACpB,IAAI,EAAE,CAAC,CAAC;IACR,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,UAAU,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,YAAY,CAAC;IACpE,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,iBAAS,0BAA0B,CAAC,CAAC,SAAS,gBAAgB,EAAE,EAC9D,IAAI,EACJ,KAAK,EACL,UAAU,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAwP3D;AAGD,eAAO,MAAM,qBAAqB,EAE7B,OAAO,0BAA0B,CAAC"}

package/lib/AnimatedFlashListItem.js

@@ -36,12 +36,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnimatedFlashListItem = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_reanimated_1 = __importStar(require("react-native-reanimated"));
-const hooks_1 = require("./hooks");
-const contexts_1 = require("./contexts");
-const constants_1 = require("./constants");
-// Debug: Track component instances to detect recycling.
-// Note: IDs are not stable across hot reloads (counter persists at module scope).
-let instanceCounter = 0;
+const useDragGesture_1 = require("./hooks/drag/useDragGesture");
+const useDragShift_1 = require("./hooks/drag/useDragShift");
+const useDragAnimatedStyle_1 = require("./hooks/drag/useDragAnimatedStyle");
+const useDropCompensation_1 = require("./hooks/drag/useDropCompensation");
+const useListExitAnimation_1 = require("./hooks/animations/useListExitAnimation");
+const useListEntryAnimation_1 = require("./hooks/animations/useListEntryAnimation");
+const ListAnimationContext_1 = require("./contexts/ListAnimationContext");
+const DragStateContext_1 = require("./contexts/DragStateContext");
 /**
  * Internal item wrapper that provides all animation functionality.
  *
@@ -54,41 +56,17 @@ let instanceCounter = 0;
  * @internal
  */
 function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, renderItem, onReorderByDelta, onHapticFeedback, }) {
-    // Debug: Track this component instance (only incremented in DEV)
-    const instanceIdRef = (0, react_1.useRef)(null);
-    if (__DEV__ && instanceIdRef.current === null) {
-        instanceIdRef.current = ++instanceCounter;
-    }
-    const instanceId = instanceIdRef.current;
-    // Track previous itemId to detect recycling
-    const prevItemIdRef = (0, react_1.useRef)(item.id);
-    // Log every render with instance tracking (verbose only - fires per render per item)
-    if (__DEV__ && constants_1.VERBOSE_DRAG_DEBUG) {
-        const isRecycled = prevItemIdRef.current !== item.id;
-        console.log(`[FlashListItem:inst${instanceId}] RENDER: itemId=${item.id}, index=${index}` +
-            (isRecycled ? ` (RECYCLED from ${prevItemIdRef.current})` : ''));
-        prevItemIdRef.current = item.id;
-    }
-    // Track mount/unmount
-    (0, react_1.useEffect)(() => {
-        if (__DEV__) {
-            console.log(`[FlashListItem:inst${instanceId}] MOUNT: itemId=${item.id}, index=${index}`);
-        }
-        return () => {
-            if (__DEV__) {
-                console.log(`[FlashListItem:inst${instanceId}] UNMOUNT: was itemId=${item.id}`);
-            }
-        };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []); // Empty deps - only track actual mount/unmount
     // Create shared value for index (for UI-thread access in animations)
     // This allows worklets to read the current index without closure stale capture
     const indexShared = (0, react_native_reanimated_1.useSharedValue)(index);
-    const layoutSignal = (0, react_native_reanimated_1.useSharedValue)(0);
     // Register this item's index in the central registry
     // This handles FlashList's recycling behavior where components may not re-render
     // after data changes, leaving their index props stale
-    const { updateItemIndex, isDragging: globalIsDragging, isDropping } = (0, contexts_1.useDragState)();
+    const { updateItemIndex, isDragging: globalIsDragging, isDropping, draggedItemId, 
+    // v40.7: For shifted item overlay hiding
+    shiftedOverlaysActive, shiftedOverlays, shiftedOverlaysRendered, // v41.4: Wait for React render before hiding
+    // Crossfade support
+    dragOverlayOpacity, overlayFrozenItemId, overlayRenderedOnUI, } = (0, DragStateContext_1.useDragState)();
     // Sync index to SharedValue on every render, but skip during active drag/drop
     // This prevents stale React props from corrupting the index during the drop phase
     // when FlashList re-renders with new data order
@@ -112,9 +90,6 @@ function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, re
     (0, react_1.useEffect)(() => {
         if (globalIsDragging.value || isDropping.value || indexShared.value === index)
             return;
-        if (__DEV__ && constants_1.VERBOSE_DRAG_DEBUG) {
-            console.log(`[FlashListItem:${item.id}] Secondary sync: indexShared ${indexShared.value} → ${index}`);
-        }
         indexShared.value = index;
     });
     // Update item index in useLayoutEffect to avoid side effects during render
@@ -128,11 +103,11 @@ function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, re
     // Track measured height for layout compensation
     const measuredHeightRef = (0, react_1.useRef)(0);
     // List animation context for subscription-triggered animations and layout compensation
-    const animationContext = (0, contexts_1.useListAnimationOptional)();
+    const animationContext = (0, ListAnimationContext_1.useListAnimationOptional)();
     // === DRAG HOOKS ===
     // Pan gesture for drag-to-reorder
     // Note: totalItems is now accessed via SharedValue from DragStateContext
-    const { panGesture, isDragging, translateY } = (0, hooks_1.useDragGesture)({
+    const { panGesture, isDragging, translateY } = (0, useDragGesture_1.useDragGesture)({
         itemId: item.id,
         index,
         enabled: isDragEnabled,
@@ -142,11 +117,46 @@ function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, re
         onHapticFeedback,
     });
     // Shift animation for non-dragged items
-    const { shiftY } = (0, hooks_1.useDragShift)({ itemId: item.id, index, containerRef, layoutSignal });
+    const { shiftY } = (0, useDragShift_1.useDragShift)({ itemId: item.id, index });
     // Handle index changes after cache updates (drop compensation)
-    (0, hooks_1.useDropCompensation)({ itemId: item.id, index, translateY });
+    (0, useDropCompensation_1.useDropCompensation)({ itemId: item.id, index, translateY });
     // Animated style for drag transforms
-    const { dragAnimatedStyle } = (0, hooks_1.useDragAnimatedStyle)(item.id, isDragging, translateY, shiftY, containerRef);
+    const { dragAnimatedStyle } = (0, useDragAnimatedStyle_1.useDragAnimatedStyle)(item.id, isDragging, translateY, shiftY, containerRef);
+    const hideOriginalStyle = (0, react_native_reanimated_1.useAnimatedStyle)(() => {
+        // Crossfade visibility: use inverse of overlay opacity for smooth transition
+        // This ensures the original and overlay opacity always sum to 1, preventing
+        // any frame where both are invisible (the "vanish" bug).
+        const isThisDragged = draggedItemId.value === item.id;
+        const isThisFrozenOverlay = overlayFrozenItemId.value === item.id;
+        // Crossfade path: applies during drag/drop OR while frozen overlay fades out
+        if (isThisDragged || isThisFrozenOverlay) {
+            // During drag/drop or while overlay is fading out, crossfade with overlay
+            if (globalIsDragging.value || isDropping.value || overlayFrozenItemId.value === item.id) {
+                // FIX: Don't start fading out until overlay has rendered ON THE UI THREAD.
+                // overlayRenderedOnUI is set from useAnimatedStyle (UI thread) in DragOverlay,
+                // unlike overlayVisible which is set from useEffect (JS thread) causing races.
+                // Without this guard, the original fades out before overlay appears = vanish.
+                if (!overlayRenderedOnUI.value) {
+                    return { opacity: 1 }; // Stay fully visible until overlay renders
+                }
+                // Always use crossfade - when overlay is at opacity X,
+                // the original is at opacity (1-X), so they always sum to 1.
+                return { opacity: 1 - dragOverlayOpacity.value };
+            }
+        }
+        // v41.4: Hide shifted items during drop ONLY after overlays have rendered.
+        // Previously (v41.2) we hid immediately when shiftedOverlaysActive=true,
+        // but overlays take ~2-5ms to render (React async), causing a blank flash.
+        // The shift values are FROZEN during drop (v41.1), so originals stay correctly
+        // positioned until overlays are ready.
+        if (isDropping.value &&
+            shiftedOverlaysActive.value &&
+            shiftedOverlaysRendered.value && // Wait for React render
+            shiftedOverlays.value[item.id] !== undefined) {
+            return { opacity: 0 };
+        }
+        return { opacity: 1 };
+    });
     // === ANIMATION HOOKS ===
     // Callbacks for layout compensation (register/unregister exiting items)
     const onExitStart = (0, react_1.useCallback)((exitIndex, height) => {
@@ -156,14 +166,14 @@ function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, re
         animationContext?.unregisterExitingItem(item.id);
     }, [animationContext, item.id]);
     // Exit animation for smooth slide-out (with layout compensation callbacks)
-    const { exitAnimatedStyle, triggerExit, resetAnimation } = (0, hooks_1.useListExitAnimation)(item.id, {
+    const { exitAnimatedStyle, triggerExit, resetAnimation } = (0, useListExitAnimation_1.useListExitAnimation)(item.id, {
         index,
         measuredHeight: measuredHeightRef.current,
         onExitStart,
         onExitComplete,
     });
     // Entry animation for items appearing
-    const { entryAnimatedStyle } = (0, hooks_1.useListEntryAnimation)(item.id);
+    const { entryAnimatedStyle } = (0, useListEntryAnimation_1.useListEntryAnimation)(item.id);
     // Register exit animation trigger (O(1) direct calls from subscriptions)
     (0, react_1.useLayoutEffect)(() => {
         if (!animationContext)
@@ -173,9 +183,9 @@ function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, re
     }, [item.id, triggerExit, animationContext]);
     // Track measured height for layout compensation
     const handleLayout = (0, react_1.useCallback)((event) => {
-        measuredHeightRef.current = event.nativeEvent.layout.height;
-        layoutSignal.value += 1;
-    }, [layoutSignal]);
+        const { height } = event.nativeEvent.layout;
+        measuredHeightRef.current = height;
+    }, []);
     // Create drag handle props
     const dragHandleProps = (0, react_1.useMemo)(() => isDragEnabled
         ? {
@@ -215,6 +225,7 @@ function AnimatedFlashListItemInner({ item, index, totalItems, isDragEnabled, re
     return (<react_native_reanimated_1.default.View ref={containerRef} onLayout={handleLayout} style={[
             exitAnimatedStyle,
             entryAnimatedStyle,
+            hideOriginalStyle,
             isDragEnabled && dragAnimatedStyle,
         ]}>
       {renderedItem}