@shopify/flash-list 2.0.0-alpha.9 → 2.0.0-rc.10

package/src/recyclerview/hooks/useRecyclerViewController.tsx

@@ -8,7 +8,13 @@ import {
 } 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";
@@ -17,58 +23,7 @@ import { ScrollAnchorRef } from "../components/ScrollAnchor";
 import { PlatformConfig } from "../../native/config/PlatformHelper";
 
 import { useUnmountFlag } from "./useUnmountFlag";
-import { useUnmountAwareCallbacks } from "./useUnmountAwareCallbacks";
-
-/**
- * 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 { useUnmountAwareTimeout } from "./useUnmountAwareCallbacks";
 
 /**
  * Comprehensive hook that manages RecyclerView scrolling behavior and provides
@@ -88,104 +43,98 @@ 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(data?.length ?? 0);
-  const { setTimeout } = useUnmountAwareCallbacks();
+  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,
-        skipFirstItemOffset: false,
-      });
-
-      setTimeout(() => {
-        handlerMethods.scrollToOffset({
-          offset,
-          animated: false,
-          skipFirstItemOffset: 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) => {
-        // TODO: Make sure we don't scroll beyond content size
-        if (recyclerViewManager.updateScrollOffset(offset) !== undefined) {
-          // Add the resolve function to the queue
-          pendingScrollResolves.current.push(resolve);
-          setRenderId((prev) => prev + 1);
-        } else {
-          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(() => {
+    const { data, keyExtractor } = recyclerViewManager.props;
+    if (
+      recyclerViewManager.getIsFirstLayoutComplete() &&
+      keyExtractor &&
+      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 = keyExtractor(
+          data![firstVisibleIndex],
+          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, keyExtractor } = 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 = props.data?.length ?? 0;
+    const currentDataLength = recyclerViewManager.getDataLength();
 
     if (
-      !props.horizontal &&
       recyclerViewManager.getIsFirstLayoutComplete() &&
-      props.keyExtractor &&
+      keyExtractor &&
       currentDataLength > 0 &&
-      props.maintainVisibleContentPosition?.disabled !== true
+      recyclerViewManager.shouldMaintainVisibleContentPosition()
     ) {
       const hasDataChanged = currentDataLength !== lastDataLengthRef.current;
       // If we have a tracked first visible item, maintain its position
@@ -195,38 +144,54 @@ export function useRecyclerViewController<T>(
             .getEngagedIndices()
             .findValue(
               (index) =>
-                props.keyExtractor?.(props.data![index], index) ===
+                keyExtractor?.(data![index], index) ===
                 firstVisibleItemKey.current
             ) ??
           (hasDataChanged
-            ? props.data?.findIndex(
+            ? data?.findIndex(
                 (item, index) =>
-                  props.keyExtractor?.(item, index) ===
-                  firstVisibleItemKey.current
+                  keyExtractor?.(item, index) === firstVisibleItemKey.current
               )
             : undefined);
 
-        if (currentIndexOfFirstVisibleItem !== 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) {
+          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 {
-              scrollViewRef.current?.scrollTo({
-                y: recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
-                animated: false,
-              });
+              const scrollToParams = horizontal
+                ? {
+                    x: recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
+                    animated: false,
+                  }
+                : {
+                    y: recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
+                    animated: false,
+                  };
+              scrollViewRef.current?.scrollTo(scrollToParams);
             }
             if (hasDataChanged) {
-              updateScrollOffsetAsync(
-                recyclerViewManager.getAbsoluteLastScrollOffset() + diff
+              updateScrollOffsetWithCallback(
+                recyclerViewManager.getAbsoluteLastScrollOffset() + diff,
+                () => {}
               );
               recyclerViewManager.ignoreScrollEvents = true;
               setTimeout(() => {
@@ -237,27 +202,23 @@ export function useRecyclerViewController<T>(
         }
       }
 
-      // Update the tracked first visible item
-      const firstVisibleIndex = Math.max(
-        0,
-        recyclerViewManager.getVisibleIndices().startIndex
-      );
-      if (firstVisibleIndex !== undefined && firstVisibleIndex >= 0) {
-        firstVisibleItemKey.current = props.keyExtractor(
-          props.data![firstVisibleIndex],
-          firstVisibleIndex
-        );
-        firstVisibleItemLayout.current = {
-          ...recyclerViewManager.getLayout(firstVisibleIndex),
-        };
-      }
+      computeFirstVisibleIndexForOffsetCorrection();
     }
-    lastDataLengthRef.current = props.data?.length ?? 0;
-  }, [props.data, props.keyExtractor, recyclerViewManager, setTimeout]);
-
-  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.
@@ -267,6 +228,7 @@ 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) {
@@ -295,6 +257,9 @@ export function useRecyclerViewController<T>(
           });
         }
       },
+      clearLayoutCacheOnUpdate: () => {
+        recyclerViewManager.markLayoutManagerDirty();
+      },
 
       // Expose native scroll view methods
       flashScrollIndicators: () => {
@@ -314,13 +279,16 @@ 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,
           });
         }
-        scrollViewRef.current!.scrollToEnd({ animated });
+        setTimeout(() => {
+          scrollViewRef.current!.scrollToEnd({ animated });
+        }, 0);
       },
 
       /**
@@ -336,107 +304,190 @@ 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 getFinalOffset = () => {
-            const layout = recyclerViewManager.getLayout(index);
-            const offset = horizontal ? layout.x : layout.y;
-            let finalOffset = offset;
-            // take viewPosition etc into account
-            if (viewPosition !== undefined || viewOffset !== undefined) {
-              const containerSize = horizontal
-                ? recyclerViewManager.getWindowSize().width
-                : recyclerViewManager.getWindowSize().height;
-
-              const itemSize = horizontal ? layout.width : layout.height;
-
-              if (viewPosition !== undefined) {
-                // viewPosition: 0 = top, 0.5 = center, 1 = bottom
-                finalOffset =
-                  offset - (containerSize - itemSize) * viewPosition;
+      }: 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);
+              const offset = horizontal ? layout.x : layout.y;
+              let finalOffset = offset;
+              // take viewPosition etc into account
+              if (viewPosition !== undefined || viewOffset !== undefined) {
+                const containerSize = horizontal
+                  ? recyclerViewManager.getWindowSize().width
+                  : recyclerViewManager.getWindowSize().height;
+
+                const itemSize = horizontal ? layout.width : layout.height;
+
+                if (viewPosition !== undefined) {
+                  // viewPosition: 0 = top, 0.5 = center, 1 = bottom
+                  finalOffset =
+                    offset - (containerSize - itemSize) * viewPosition;
+                }
+
+                if (viewOffset !== undefined) {
+                  finalOffset += viewOffset;
+                }
               }
-
-              if (viewOffset !== undefined) {
-                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();
+
+              if (finalOffset > lastScrollOffset) {
+                lastScrollOffset = Math.max(
+                  finalOffset - bufferForCompute,
+                  lastScrollOffset
+                );
+                recyclerViewManager.setScrollDirection("forward");
+              } else {
+                lastScrollOffset = Math.min(
+                  finalOffset + bufferForCompute,
+                  lastScrollOffset
+                );
+                recyclerViewManager.setScrollDirection("backward");
               }
-            }
-            return finalOffset;
-          };
-          let lastScrollOffset = recyclerViewManager.getLastScrollOffset();
-          let finalOffset = getFinalOffset();
-          const bufferForScroll = horizontal
-            ? recyclerViewManager.getWindowSize().width
-            : recyclerViewManager.getWindowSize().height;
-
-          const bufferForCompute = bufferForScroll * 2;
-
-          if (finalOffset > lastScrollOffset) {
-            lastScrollOffset = Math.max(
-              finalOffset - bufferForCompute,
-              lastScrollOffset
-            );
-            recyclerViewManager.setScrollDirection("forward");
-          } else {
-            lastScrollOffset = Math.min(
-              finalOffset + bufferForCompute,
-              lastScrollOffset
-            );
-            recyclerViewManager.setScrollDirection("backward");
-          }
-
-          if (animated) {
-            // go from finalOffset to lastScrollOffset in 5 steps
-            for (let i = 0; i < 5; i++) {
+              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;
-              }
-              await updateScrollOffsetAsync(
-                finalOffset + (lastScrollOffset - finalOffset) * (i / 4)
-              );
-            }
-          } else {
-            // go from lastScrollOffset to finalOffset in 5 steps
-            for (let i = 0; i < 5; i++) {
-              if (isUnmounted.current) {
+              } else if (currentStep >= steps) {
+                // All steps completed, perform final scroll
+                finishScrollToIndex();
                 return;
               }
-              await updateScrollOffsetAsync(
-                lastScrollOffset + (finalOffset - lastScrollOffset) * (i / 4)
+
+              // 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;
+                }
+
+                // 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 {
+                  // Continue to next step
+                  performScrollStep(currentStep + 1);
+                }
+              });
+            };
+
+            /**
+             * 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 (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,
+                });
+              }
+
+              // Perform the final scroll to the target position
+              handlerMethods.scrollToOffset({
+                offset: finalOffset,
+                animated,
+                skipFirstItemOffset: true,
+              });
+
+              // 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
               );
-            }
-          }
-          finalOffset = getFinalOffset();
-          const maxOffset = recyclerViewManager.getMaxScrollOffset();
+            };
 
-          if (finalOffset > maxOffset) {
-            finalOffset = maxOffset;
-          }
-          if (animated) {
-            // We don't need to add firstItemOffset here as it will be added in scrollToOffset
-            handlerMethods.scrollToOffset({
-              offset: lastScrollOffset,
-              animated: false,
-              skipFirstItemOffset: false,
-            });
+            // Start the scroll animation process
+            performScrollStep(0);
+          } else {
+            // Invalid parameters, resolve immediately
+            resolve();
           }
-          handlerMethods.scrollToOffset({
-            offset: finalOffset,
-            animated,
-            skipFirstItemOffset: false,
-          });
-
-          setTimeout(() => {
-            pauseAdjustRef.current = false;
-          }, 200);
-        }
+        });
       },
 
       /**
@@ -449,11 +500,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,
@@ -473,7 +523,7 @@ export function useRecyclerViewController<T>(
         return recyclerViewManager.getWindowSize();
       },
       getLayout: (index: number) => {
-        return recyclerViewManager.getLayout(index);
+        return recyclerViewManager.tryGetLayout(index);
       },
       getAbsoluteLastScrollOffset: () => {
         return recyclerViewManager.getAbsoluteLastScrollOffset();
@@ -484,11 +534,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();
@@ -497,19 +547,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,
+  };
 }