@shopify/flash-list 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/recyclerview/hooks/useRecyclerViewController.tsx

@@ -7,64 +7,23 @@ import {
   useState,
 } from "react";
 import { I18nManager } from "react-native";
-import { RecyclerViewProps } from "../RecyclerViewProps";
+
+import {
+  ScrollToOffsetParams,
+  ScrollToIndexParams,
+  ScrollToItemParams,
+  ScrollToEdgeParams,
+  FlashListRef,
+} from "../../FlashListRef";
 import { CompatScroller } from "../components/CompatScroller";
 import { RecyclerViewManager } from "../RecyclerViewManager";
 import { adjustOffsetForRTL } from "../utils/adjustOffsetForRTL";
-import { useUnmountFlag } from "./useUnmountFlag";
 import { RVLayout } from "../layout-managers/LayoutManager";
 import { ScrollAnchorRef } from "../components/ScrollAnchor";
+import { PlatformConfig } from "../../native/config/PlatformHelper";
 
-/**
- * Parameters for scrolling to a specific position in the list.
- * Extends ScrollToEdgeParams to include view positioning options.
- */
-export interface ScrollToParams extends ScrollToEdgeParams {
-  /** Position of the target item relative to the viewport (0 = top, 0.5 = center, 1 = bottom) */
-  viewPosition?: number;
-  /** Additional offset to apply after viewPosition calculation */
-  viewOffset?: number;
-}
-
-/**
- * Parameters for scrolling to a specific offset in the list.
- * Used when you want to scroll to an exact pixel position.
- */
-export interface ScrollToOffsetParams extends ScrollToParams {
-  /** The pixel offset to scroll to */
-  offset: number;
-  /**
-   * If true, the first item offset will not be added to the offset calculation.
-   * First offset represents header size or top padding.
-   */
-  skipFirstItemOffset?: boolean;
-}
-
-/**
- * Parameters for scrolling to a specific index in the list.
- * Used when you want to scroll to a specific item by its position in the data array.
- */
-export interface ScrollToIndexParams extends ScrollToParams {
-  /** The index of the item to scroll to */
-  index: number;
-}
-
-/**
- * Parameters for scrolling to a specific item in the list.
- * Used when you want to scroll to a specific item by its data value.
- */
-export interface ScrollToItemParams<T> extends ScrollToParams {
-  /** The item to scroll to */
-  item: T;
-}
-
-/**
- * Base parameters for scrolling to the edges of the list.
- */
-export interface ScrollToEdgeParams {
-  /** Whether the scroll should be animated */
-  animated?: boolean;
-}
+import { useUnmountFlag } from "./useUnmountFlag";
+import { useUnmountAwareTimeout } from "./useUnmountAwareCallbacks";
 
 /**
  * Comprehensive hook that manages RecyclerView scrolling behavior and provides
@@ -84,138 +43,180 @@ export interface ScrollToEdgeParams {
  */
 export function useRecyclerViewController<T>(
   recyclerViewManager: RecyclerViewManager<T>,
-  ref: React.Ref<any>,
+  ref: React.Ref<FlashListRef<T>>,
   scrollViewRef: RefObject<CompatScroller>,
-  scrollAnchorRef: React.RefObject<ScrollAnchorRef>,
-  props: RecyclerViewProps<T>
+  scrollAnchorRef: React.RefObject<ScrollAnchorRef>
 ) {
-  const { horizontal, data } = props;
   const isUnmounted = useUnmountFlag();
   const [_, setRenderId] = useState(0);
-  const pauseAdjustRef = useRef(false);
+  const pauseOffsetCorrection = useRef(false);
   const initialScrollCompletedRef = useRef(false);
+  const lastDataLengthRef = useRef(recyclerViewManager.getDataLength());
+  const { setTimeout } = useUnmountAwareTimeout();
 
   // Track the first visible item for maintaining scroll position
   const firstVisibleItemKey = useRef<string | undefined>(undefined);
   const firstVisibleItemLayout = useRef<RVLayout | undefined>(undefined);
-  const pendingScrollResolves = useRef<(() => void)[]>([]);
-
-  const applyInitialScrollIndex = useCallback(() => {
-    const initialScrollIndex =
-      recyclerViewManager.getInitialScrollIndex() ?? -1;
-    const dataLength = props.data?.length ?? 0;
-    if (
-      initialScrollIndex >= 0 &&
-      initialScrollIndex < dataLength &&
-      !initialScrollCompletedRef.current &&
-      recyclerViewManager.getIsFirstLayoutComplete()
-    ) {
-      // Use setTimeout to ensure that we keep trying to scroll on first few renders
-      setTimeout(() => {
-        initialScrollCompletedRef.current = true;
-        pauseAdjustRef.current = false;
-      }, 100);
 
-      pauseAdjustRef.current = true;
-
-      const offset = horizontal
-        ? recyclerViewManager.getLayout(initialScrollIndex).x
-        : recyclerViewManager.getLayout(initialScrollIndex).y;
-      handlerMethods.scrollToOffset({
-        offset,
-        animated: false,
-      });
-
-      setTimeout(() => {
-        handlerMethods.scrollToOffset({
-          offset,
-          animated: false,
-        });
-      }, 0);
-    }
-  }, [recyclerViewManager, props.data]);
+  // Queue to store callbacks that should be executed after scroll offset updates
+  const pendingScrollCallbacks = useRef<(() => void)[]>([]);
 
   // Handle initial scroll position when the list first loads
   //   useOnLoad(recyclerViewManager, () => {
 
   //   });
   /**
-   * Updates the scroll offset and returns a Promise that resolves
-   * when the update has been applied.
+   * Updates the scroll offset and calls the provided callback
+   * after the update has been applied and the component has re-rendered.
+   *
+   * @param offset - The new scroll offset to apply
+   * @param callback - Optional callback to execute after the update is applied
    */
-  const updateScrollOffsetAsync = useCallback(
-    async (offset: number): Promise<void> => {
-      return new Promise((resolve) => {
-        recyclerViewManager.updateScrollOffset(offset);
-        // Add the resolve function to the queue
-        pendingScrollResolves.current.push(resolve);
+  const updateScrollOffsetWithCallback = useCallback(
+    (offset: number, callback: () => void): void => {
+      // Attempt to update the scroll offset in the RecyclerViewManager
+      // This returns undefined if no update is needed
+      if (recyclerViewManager.updateScrollOffset(offset) !== undefined) {
+        // It will be executed after the next render
+        pendingScrollCallbacks.current.push(callback);
+        // Trigger a re-render to apply the scroll offset update
         setRenderId((prev) => prev + 1);
-      });
+      } else {
+        // No update needed, execute callback immediately
+        callback();
+      }
     },
     [recyclerViewManager]
   );
 
+  const computeFirstVisibleIndexForOffsetCorrection = useCallback(() => {
+    if (
+      recyclerViewManager.getIsFirstLayoutComplete() &&
+      recyclerViewManager.hasStableDataKeys() &&
+      recyclerViewManager.getDataLength() > 0 &&
+      recyclerViewManager.shouldMaintainVisibleContentPosition()
+    ) {
+      // Update the tracked first visible item
+      const firstVisibleIndex = Math.max(
+        0,
+        recyclerViewManager.computeVisibleIndices().startIndex
+      );
+      if (firstVisibleIndex !== undefined && firstVisibleIndex >= 0) {
+        firstVisibleItemKey.current =
+          recyclerViewManager.getDataKey(firstVisibleIndex);
+        firstVisibleItemLayout.current = {
+          ...recyclerViewManager.getLayout(firstVisibleIndex),
+        };
+      }
+    }
+  }, [recyclerViewManager]);
+
   /**
    * Maintains the visible content position when the list updates.
    * This is particularly useful for chat applications where we want to keep
    * the user's current view position when new messages are added.
    */
-  const applyContentOffset = useCallback(async () => {
-    // Resolve all pending scroll updates from previous calls
-    const resolves = pendingScrollResolves.current;
-    pendingScrollResolves.current = [];
-    resolves.forEach((resolve) => resolve());
+  const applyOffsetCorrection = useCallback(() => {
+    const { horizontal, data } = recyclerViewManager.props;
+
+    // Execute all pending callbacks from previous scroll offset updates
+    // This ensures any scroll operations that were waiting for render are completed
+    const callbacks = pendingScrollCallbacks.current;
+    pendingScrollCallbacks.current = [];
+    callbacks.forEach((callback) => callback());
+
+    const currentDataLength = recyclerViewManager.getDataLength();
 
     if (
-      !props.horizontal &&
       recyclerViewManager.getIsFirstLayoutComplete() &&
-      props.keyExtractor &&
-      props.maintainVisibleContentPosition?.disabled !== true
+      recyclerViewManager.hasStableDataKeys() &&
+      currentDataLength > 0 &&
+      recyclerViewManager.shouldMaintainVisibleContentPosition()
     ) {
+      const hasDataChanged = currentDataLength !== lastDataLengthRef.current;
       // If we have a tracked first visible item, maintain its position
       if (firstVisibleItemKey.current) {
-        const currentIndexOfFirstVisibleItem = recyclerViewManager
-          .getEngagedIndices()
-          .findValue(
-            (index) =>
-              props.keyExtractor?.(props.data![index], index) ===
-              firstVisibleItemKey.current
-          );
-
-        if (currentIndexOfFirstVisibleItem !== undefined) {
+        const currentIndexOfFirstVisibleItem =
+          recyclerViewManager
+            .getEngagedIndices()
+            .findValue(
+              (index) =>
+                recyclerViewManager.getDataKey(index) ===
+                firstVisibleItemKey.current
+            ) ??
+          (hasDataChanged
+            ? data?.findIndex(
+                (item, index) =>
+                  recyclerViewManager.getDataKey(index) ===
+                  firstVisibleItemKey.current
+              )
+            : undefined);
+
+        if (
+          currentIndexOfFirstVisibleItem !== undefined &&
+          currentIndexOfFirstVisibleItem >= 0
+        ) {
           // Calculate the difference in position and apply the offset
-          const diff =
-            recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).y -
-            firstVisibleItemLayout.current!.y;
+          const diff = horizontal
+            ? recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).x -
+              firstVisibleItemLayout.current!.x
+            : recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem).y -
+              firstVisibleItemLayout.current!.y;
           firstVisibleItemLayout.current = {
             ...recyclerViewManager.getLayout(currentIndexOfFirstVisibleItem),
           };
-          if (diff !== 0 && !pauseAdjustRef.current) {
-            //console.log("diff", diff, firstVisibleItemKey.current);
-            scrollAnchorRef.current?.scrollBy(diff);
+          if (
+            diff !== 0 &&
+            !pauseOffsetCorrection.current &&
+            !recyclerViewManager.animationOptimizationsEnabled
+          ) {
+            // console.log("diff", diff, firstVisibleItemKey.current);
+            if (PlatformConfig.supportsOffsetCorrection) {
+              // console.log("scrollBy", diff);
+              scrollAnchorRef.current?.scrollBy(diff);
+            } else {
+              const scrollToParams = horizontal
+                ? {
+                    x: recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
+                    animated: false,
+                  }
+                : {
+                    y: recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
+                    animated: false,
+                  };
+              scrollViewRef.current?.scrollTo(scrollToParams);
+            }
+            if (hasDataChanged) {
+              updateScrollOffsetWithCallback(
+                recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
+                () => {}
+              );
+              recyclerViewManager.ignoreScrollEvents = true;
+              setTimeout(() => {
+                recyclerViewManager.ignoreScrollEvents = false;
+              }, 100);
+            }
           }
         }
       }
 
-      // Update the tracked first visible item
-      const firstVisibleIndex =
-        recyclerViewManager.getVisibleIndices().startIndex;
-      if (firstVisibleIndex !== undefined) {
-        firstVisibleItemKey.current =
-          props.keyExtractor?.(
-            props.data![firstVisibleIndex],
-            firstVisibleIndex
-          ) ?? "0";
-        firstVisibleItemLayout.current = {
-          ...recyclerViewManager.getLayout(firstVisibleIndex),
-        };
-      }
+      computeFirstVisibleIndexForOffsetCorrection();
     }
-  }, [props.data, props.keyExtractor, recyclerViewManager]);
-
-  const handlerMethods = useMemo(() => {
+    lastDataLengthRef.current = recyclerViewManager.getDataLength();
+  }, [
+    recyclerViewManager,
+    scrollAnchorRef,
+    scrollViewRef,
+    setTimeout,
+    updateScrollOffsetWithCallback,
+    computeFirstVisibleIndexForOffsetCorrection,
+  ]);
+
+  const handlerMethods: FlashListRef<T> = useMemo(() => {
     return {
-      props,
+      get props() {
+        return recyclerViewManager.props;
+      },
       /**
        * Scrolls the list to a specific offset position.
        * Handles RTL layouts and first item offset adjustments.
@@ -225,14 +226,20 @@ export function useRecyclerViewController<T>(
         animated,
         skipFirstItemOffset = true,
       }: ScrollToOffsetParams) => {
+        const { horizontal } = recyclerViewManager.props;
         if (scrollViewRef.current) {
           // Adjust offset for RTL layouts in horizontal mode
           if (I18nManager.isRTL && horizontal) {
-            offset = adjustOffsetForRTL(
-              offset,
-              recyclerViewManager.getChildContainerDimensions().width,
-              recyclerViewManager.getWindowSize().width
-            );
+            // eslint-disable-next-line no-param-reassign
+            offset =
+              adjustOffsetForRTL(
+                offset,
+                recyclerViewManager.getChildContainerDimensions().width,
+                recyclerViewManager.getWindowSize().width
+              ) +
+              (skipFirstItemOffset
+                ? recyclerViewManager.firstItemOffset
+                : -recyclerViewManager.firstItemOffset);
           }
 
           // Calculate the final offset including first item offset if needed
@@ -248,6 +255,9 @@ export function useRecyclerViewController<T>(
           });
         }
       },
+      clearLayoutCacheOnUpdate: () => {
+        recyclerViewManager.markLayoutManagerDirty();
+      },
 
       // Expose native scroll view methods
       flashScrollIndicators: () => {
@@ -267,13 +277,19 @@ export function useRecyclerViewController<T>(
        * Scrolls to the end of the list.
        */
       scrollToEnd: async ({ animated }: ScrollToEdgeParams = {}) => {
+        const { data } = recyclerViewManager.props;
         if (data && data.length > 0) {
-          await handlerMethods.scrollToIndex({
-            index: data.length - 1,
-            animated,
-          });
+          const lastIndex = data.length - 1;
+          if (!recyclerViewManager.getEngagedIndices().includes(lastIndex)) {
+            await handlerMethods.scrollToIndex({
+              index: lastIndex,
+              animated,
+            });
+          }
         }
-        scrollViewRef.current!.scrollToEnd({ animated });
+        setTimeout(() => {
+          scrollViewRef.current!.scrollToEnd({ animated });
+        }, 0);
       },
 
       /**
@@ -289,38 +305,30 @@ export function useRecyclerViewController<T>(
       /**
        * Scrolls to a specific index in the list.
        * Supports viewPosition and viewOffset for precise positioning.
+       * Returns a Promise that resolves when the scroll is complete.
        */
-      scrollToIndex: async ({
+      scrollToIndex: ({
         index,
         animated,
         viewPosition,
         viewOffset,
-      }: ScrollToIndexParams) => {
-        if (scrollViewRef.current && data && data.length > index) {
-          pauseAdjustRef.current = true;
-          const layout = recyclerViewManager.getLayout(index);
-          let lastScrollOffset = recyclerViewManager.getLastScrollOffset();
-          const bufferForScroll = horizontal
-            ? recyclerViewManager.getWindowSize().width
-            : recyclerViewManager.getWindowSize().height;
-
-          const bufferForCompute = bufferForScroll * 2;
-
-          if (layout) {
-            let prevFinalOffset = Number.POSITIVE_INFINITY;
-            let finalOffset = 0;
-            let attempts = 0;
-            const MAX_ATTEMPTS = 5;
-            const OFFSET_TOLERANCE = 1; // 1px tolerance
-
-            do {
+      }: ScrollToIndexParams): Promise<void> => {
+        return new Promise((resolve) => {
+          const { horizontal } = recyclerViewManager.props;
+          if (
+            scrollViewRef.current &&
+            index >= 0 &&
+            index < recyclerViewManager.getDataLength()
+          ) {
+            // Pause the scroll offset adjustments
+            pauseOffsetCorrection.current = true;
+            recyclerViewManager.setOffsetProjectionEnabled(false);
+
+            const getFinalOffset = () => {
               const layout = recyclerViewManager.getLayout(index);
-              if (!layout || isUnmounted.current) break;
-
               const offset = horizontal ? layout.x : layout.y;
-              finalOffset = offset;
-
-              // Apply viewPosition and viewOffset adjustments if provided
+              let finalOffset = offset;
+              // take viewPosition etc into account
               if (viewPosition !== undefined || viewOffset !== undefined) {
                 const containerSize = horizontal
                   ? recyclerViewManager.getWindowSize().width
@@ -338,77 +346,149 @@ export function useRecyclerViewController<T>(
                   finalOffset += viewOffset;
                 }
               }
+              return finalOffset + recyclerViewManager.firstItemOffset;
+            };
+            const lastAbsoluteScrollOffset =
+              recyclerViewManager.getAbsoluteLastScrollOffset();
+            const bufferForScroll = horizontal
+              ? recyclerViewManager.getWindowSize().width
+              : recyclerViewManager.getWindowSize().height;
+
+            const bufferForCompute = bufferForScroll * 2;
+
+            const getStartScrollOffset = () => {
+              let lastScrollOffset = lastAbsoluteScrollOffset;
+              const finalOffset = getFinalOffset();
 
-              // Check if offset has stabilized
-              if (Math.abs(prevFinalOffset - finalOffset) <= OFFSET_TOLERANCE) {
-                break;
+              if (finalOffset > lastScrollOffset) {
+                lastScrollOffset = Math.max(
+                  finalOffset - bufferForCompute,
+                  lastScrollOffset
+                );
+                recyclerViewManager.setScrollDirection("forward");
+              } else {
+                lastScrollOffset = Math.min(
+                  finalOffset + bufferForCompute,
+                  lastScrollOffset
+                );
+                recyclerViewManager.setScrollDirection("backward");
+              }
+              return lastScrollOffset;
+            };
+            let initialTargetOffset = getFinalOffset();
+            let initialStartScrollOffset = getStartScrollOffset();
+            let finalOffset = initialTargetOffset;
+            let startScrollOffset = initialStartScrollOffset;
+
+            const steps = 5;
+
+            /**
+             * Recursively performs the scroll animation steps.
+             * This function replaces the async/await loop with callback-based execution.
+             *
+             * @param currentStep - The current step in the animation (0 to steps-1)
+             */
+            const performScrollStep = (currentStep: number) => {
+              // Check if component is unmounted or we've completed all steps
+              if (isUnmounted.current) {
+                resolve();
+                return;
+              } else if (currentStep >= steps) {
+                // All steps completed, perform final scroll
+                finishScrollToIndex();
+                return;
               }
 
-              prevFinalOffset = finalOffset;
+              // Calculate the offset for this step
+              // For animated scrolls: interpolate from finalOffset to startScrollOffset
+              // For non-animated: interpolate from startScrollOffset to finalOffset
+              const nextOffset = animated
+                ? finalOffset +
+                  (startScrollOffset - finalOffset) *
+                    (currentStep / (steps - 1))
+                : startScrollOffset +
+                  (finalOffset - startScrollOffset) *
+                    (currentStep / (steps - 1));
+
+              // Update scroll offset with a callback to continue to the next step
+              updateScrollOffsetWithCallback(nextOffset, () => {
+                // Check if the index is still valid after the update
+                if (index >= recyclerViewManager.getDataLength()) {
+                  // Index out of bounds, scroll to end instead
+                  handlerMethods.scrollToEnd({ animated });
+                  resolve(); // Resolve the promise as we're done
+                  return;
+                }
 
-              if (animated) {
-                if (finalOffset > lastScrollOffset) {
-                  lastScrollOffset = Math.max(
-                    finalOffset - bufferForCompute,
-                    lastScrollOffset
-                  );
+                // Check if the target position has changed significantly
+                const newFinalOffset = getFinalOffset();
+                if (
+                  (newFinalOffset < initialTargetOffset &&
+                    newFinalOffset < initialStartScrollOffset) ||
+                  (newFinalOffset > initialTargetOffset &&
+                    newFinalOffset > initialStartScrollOffset)
+                ) {
+                  // Target has moved, recalculate and restart from beginning
+                  finalOffset = newFinalOffset;
+                  startScrollOffset = getStartScrollOffset();
+                  initialTargetOffset = newFinalOffset;
+                  initialStartScrollOffset = startScrollOffset;
+                  performScrollStep(0); // Restart from step 0
                 } else {
-                  lastScrollOffset = Math.min(
-                    finalOffset + bufferForCompute,
-                    lastScrollOffset
-                  );
+                  // Continue to next step
+                  performScrollStep(currentStep + 1);
                 }
+              });
+            };
 
-                await updateScrollOffsetAsync(lastScrollOffset);
-              }
-              await updateScrollOffsetAsync(finalOffset);
-
-              attempts++;
-            } while (attempts < MAX_ATTEMPTS);
-
-            if (animated) {
-              const maxOffset =
-                (horizontal
-                  ? recyclerViewManager.getChildContainerDimensions().width
-                  : recyclerViewManager.getChildContainerDimensions().height) -
-                (horizontal
-                  ? recyclerViewManager.getWindowSize().width
-                  : recyclerViewManager.getWindowSize().height);
+            /**
+             * Completes the scroll to index operation by performing the final scroll
+             * and re-enabling offset correction after a delay.
+             */
+            const finishScrollToIndex = () => {
+              finalOffset = getFinalOffset();
+              const maxOffset = recyclerViewManager.getMaxScrollOffset();
 
               if (finalOffset > maxOffset) {
                 finalOffset = maxOffset;
               }
 
-              if (finalOffset > lastScrollOffset) {
-                lastScrollOffset = Math.max(
-                  finalOffset - bufferForScroll,
-                  lastScrollOffset
-                );
-              } else {
-                lastScrollOffset = Math.min(
-                  finalOffset + bufferForScroll,
-                  lastScrollOffset
-                );
+              if (animated) {
+                // For animated scrolls, first jump to the start position
+                // We don't need to add firstItemOffset here as it's already added
+                handlerMethods.scrollToOffset({
+                  offset: startScrollOffset,
+                  animated: false,
+                  skipFirstItemOffset: true,
+                });
               }
 
-              //We don't need to add firstItemOffset here as it will be added in scrollToOffset
+              // Perform the final scroll to the target position
               handlerMethods.scrollToOffset({
-                offset: lastScrollOffset,
-                animated: false,
-                skipFirstItemOffset: false,
+                offset: finalOffset,
+                animated,
+                skipFirstItemOffset: true,
               });
-            }
 
-            handlerMethods.scrollToOffset({
-              offset: finalOffset,
-              animated,
-              skipFirstItemOffset: false,
-            });
+              // Re-enable offset correction after a delay
+              // Longer delay for animated scrolls to allow animation to complete
+              setTimeout(
+                () => {
+                  pauseOffsetCorrection.current = false;
+                  recyclerViewManager.setOffsetProjectionEnabled(true);
+                  resolve(); // Resolve the promise after re-enabling corrections
+                },
+                animated ? 300 : 200
+              );
+            };
+
+            // Start the scroll animation process
+            performScrollStep(0);
+          } else {
+            // Invalid parameters, resolve immediately
+            resolve();
           }
-          setTimeout(() => {
-            pauseAdjustRef.current = false;
-          }, 200);
-        }
+        });
       },
 
       /**
@@ -421,11 +501,10 @@ export function useRecyclerViewController<T>(
         viewPosition,
         viewOffset,
       }: ScrollToItemParams<T>) => {
+        const { data } = recyclerViewManager.props;
         if (scrollViewRef.current && data) {
           // Find the index of the item in the data array
-          const index = Array.from(data).findIndex(
-            (dataItem) => dataItem === item
-          );
+          const index = data.findIndex((dataItem) => dataItem === item);
           if (index >= 0) {
             handlerMethods.scrollToIndex({
               index,
@@ -445,7 +524,7 @@ export function useRecyclerViewController<T>(
         return recyclerViewManager.getWindowSize();
       },
       getLayout: (index: number) => {
-        return recyclerViewManager.getLayout(index);
+        return recyclerViewManager.tryGetLayout(index);
       },
       getAbsoluteLastScrollOffset: () => {
         return recyclerViewManager.getAbsoluteLastScrollOffset();
@@ -456,11 +535,11 @@ export function useRecyclerViewController<T>(
       recordInteraction: () => {
         recyclerViewManager.recordInteraction();
       },
-      getVisibleIndices: () => {
-        return recyclerViewManager.getVisibleIndices();
+      computeVisibleIndices: () => {
+        return recyclerViewManager.computeVisibleIndices();
       },
       getFirstVisibleIndex: () => {
-        return recyclerViewManager.getVisibleIndices().startIndex;
+        return recyclerViewManager.computeVisibleIndices().startIndex;
       },
       recomputeViewableItems: () => {
         recyclerViewManager.recomputeViewableItems();
@@ -469,19 +548,79 @@ export function useRecyclerViewController<T>(
        * Disables item recycling in preparation for layout animations.
        */
       prepareForLayoutAnimationRender: () => {
-        recyclerViewManager.disableRecycling = true;
+        recyclerViewManager.animationOptimizationsEnabled = true;
       },
     };
-  }, [horizontal, data, recyclerViewManager]);
+  }, [
+    recyclerViewManager,
+    scrollViewRef,
+    setTimeout,
+    isUnmounted,
+    updateScrollOffsetWithCallback,
+  ]);
+
+  const applyInitialScrollIndex = useCallback(() => {
+    const { horizontal, data } = recyclerViewManager.props;
+
+    const initialScrollIndex =
+      recyclerViewManager.getInitialScrollIndex() ?? -1;
+    const dataLength = data?.length ?? 0;
+    if (
+      initialScrollIndex >= 0 &&
+      initialScrollIndex < dataLength &&
+      !initialScrollCompletedRef.current &&
+      recyclerViewManager.getIsFirstLayoutComplete()
+    ) {
+      // Use setTimeout to ensure that we keep trying to scroll on first few renders
+      setTimeout(() => {
+        initialScrollCompletedRef.current = true;
+        pauseOffsetCorrection.current = false;
+      }, 100);
+
+      pauseOffsetCorrection.current = true;
+
+      const offset = horizontal
+        ? recyclerViewManager.getLayout(initialScrollIndex).x
+        : recyclerViewManager.getLayout(initialScrollIndex).y;
+      handlerMethods.scrollToOffset({
+        offset,
+        animated: false,
+        skipFirstItemOffset: false,
+      });
+
+      setTimeout(() => {
+        handlerMethods.scrollToOffset({
+          offset,
+          animated: false,
+          skipFirstItemOffset: false,
+        });
+      }, 0);
+    }
+  }, [handlerMethods, recyclerViewManager, setTimeout]);
 
   // Expose imperative methods through the ref
   useImperativeHandle(
     ref,
     () => {
-      return { ...scrollViewRef.current, ...handlerMethods };
+      const imperativeApi = { ...scrollViewRef.current, ...handlerMethods };
+      // Without this the props getter from handlerMethods is evaluated during spread and
+      // future updates to props are not reflected in the ref
+      Object.defineProperty(imperativeApi, "props", {
+        get() {
+          return recyclerViewManager.props;
+        },
+        enumerable: true,
+        configurable: true,
+      });
+      return imperativeApi;
     },
-    [handlerMethods]
+    [handlerMethods, scrollViewRef, recyclerViewManager]
   );
 
-  return { applyContentOffset, applyInitialScrollIndex };
+  return {
+    applyOffsetCorrection,
+    computeFirstVisibleIndexForOffsetCorrection,
+    applyInitialScrollIndex,
+    handlerMethods,
+  };
 }