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

package/src/recyclerview/helpers/EngagedIndicesTracker.ts

@@ -8,6 +8,10 @@ export interface RVEngagedIndicesTracker {
   scrollOffset: number;
   // Total distance (in pixels) to pre-render items before and after the visible viewport
   drawDistance: number;
+  // Whether to use offset projection to predict the next scroll offset
+  enableOffsetProjection: boolean;
+  // Average render time of the list
+  averageRenderTime: number;
 
   /**
    * Updates the scroll offset and calculates which items should be rendered (engaged indices).
@@ -21,9 +25,31 @@ export interface RVEngagedIndicesTracker {
     velocity: Velocity | null | undefined,
     layoutManager: RVLayoutManager
   ) => ConsecutiveNumbers | undefined;
+
+  /**
+   * Returns the currently engaged (rendered) indices.
+   * This includes both visible items and buffer items.
+   * @returns The last computed set of engaged indices
+   */
   getEngagedIndices: () => ConsecutiveNumbers;
+
+  /**
+   * Computes the visible indices in the viewport.
+   * @param layoutManager - Layout manager to fetch item positions and dimensions
+   * @returns Indices of items currently visible in the viewport
+   */
   computeVisibleIndices: (layoutManager: RVLayoutManager) => ConsecutiveNumbers;
+
+  /**
+   * Sets the scroll direction for velocity history tracking.
+   * @param scrollDirection - The direction of scrolling ("forward" or "backward")
+   */
   setScrollDirection: (scrollDirection: "forward" | "backward") => void;
+
+  /**
+   * Resets the velocity history based on the current scroll direction.
+   */
+  resetVelocityHistory: () => void;
 }
 
 export interface Velocity {
@@ -35,17 +61,26 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
   // Current scroll position of the list
   public scrollOffset = 0;
   // Distance to pre-render items before and after the visible viewport (in pixels)
-  // TODO: Increase this value for web
   public drawDistance = PlatformConfig.defaultDrawDistance;
+
+  // Whether to use offset projection to predict the next scroll offset
+  public enableOffsetProjection = true;
+
+  // Average render time of the list
+  public averageRenderTime = 16;
+
+  // Internal override to disable offset projection
+  private forceDisableOffsetProjection = false;
+
   // Currently rendered item indices (including buffer items)
   private engagedIndices = ConsecutiveNumbers.EMPTY;
 
   // Buffer distribution multipliers for scroll direction optimization
-  private smallMultiplier = 0.1; // Used for buffer in the opposite direction of scroll
-  private largeMultiplier = 0.9; // Used for buffer in the direction of scroll
+  private smallMultiplier = 0.3; // Used for buffer in the opposite direction of scroll
+  private largeMultiplier = 0.7; // Used for buffer in the direction of scroll
 
   // Circular buffer to track recent scroll velocities for direction detection
-  private velocityHistory = [-1, -1, -1, -1, -1];
+  private velocityHistory = [0, 0, 0, -0.1, -0.1];
   private velocityIndex = 0;
 
   /**
@@ -67,7 +102,21 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
     // STEP 1: Determine the currently visible viewport
     const windowSize = layoutManager.getWindowsSize();
     const isHorizontal = layoutManager.isHorizontal();
-    const viewportStart = offset;
+
+    // Update velocity history
+    if (velocity) {
+      this.updateVelocityHistory(isHorizontal ? velocity.x : velocity.y);
+    }
+
+    // Determine scroll direction to optimize buffer distribution
+    const isScrollingBackward = this.isScrollingBackward();
+    const viewportStart =
+      this.enableOffsetProjection && !this.forceDisableOffsetProjection
+        ? this.getProjectedScrollOffset(offset, this.averageRenderTime)
+        : offset;
+
+    // console.log("timeMs", this.averageRenderTime, offset, viewportStart);
+
     const viewportSize = isHorizontal ? windowSize.width : windowSize.height;
     const viewportEnd = viewportStart + viewportSize;
 
@@ -75,11 +124,6 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
     // The total extra space where items will be pre-rendered
     const totalBuffer = this.drawDistance * 2;
 
-    // Determine scroll direction to optimize buffer distribution
-    const isScrollingBackward = this.isScrollingBackward(
-      isHorizontal ? velocity?.x : velocity?.y
-    );
-
     // Distribute more buffer in the direction of scrolling
     // When scrolling forward: more buffer after viewport
     // When scrolling backward: more buffer before viewport
@@ -123,9 +167,12 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
       extendedStart,
       extendedEnd
     );
-    if (!isHorizontal) {
-      // console.log("newEngagedIndices", newEngagedIndices, this.scrollOffset);
-    }
+    // console.log(
+    //   "newEngagedIndices",
+    //   newEngagedIndices,
+    //   this.scrollOffset,
+    //   viewportStart
+    // );
     // Only return new indices if they've changed
     const oldEngagedIndices = this.engagedIndices;
     this.engagedIndices = newEngagedIndices;
@@ -135,19 +182,21 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
       : newEngagedIndices;
   }
 
+  /**
+   * Updates the velocity history with a new velocity value.
+   * @param velocity - Current scroll velocity component (x or y)
+   */
+  private updateVelocityHistory(velocity: number) {
+    this.velocityHistory[this.velocityIndex] = velocity;
+    this.velocityIndex = (this.velocityIndex + 1) % this.velocityHistory.length;
+  }
+
   /**
    * Determines scroll direction by analyzing recent velocity history.
    * Uses a majority voting system on the last 5 velocity values.
-   * @param velocity - Current scroll velocity component (x or y)
    * @returns true if scrolling backward (negative direction), false otherwise
    */
-  private isScrollingBackward(velocity?: number): boolean {
-    // update velocity history
-    if (velocity) {
-      this.velocityHistory[this.velocityIndex] = velocity;
-      this.velocityIndex =
-        (this.velocityIndex + 1) % this.velocityHistory.length;
-    }
+  private isScrollingBackward(): boolean {
     // should decide based on whether we have more positive or negative values, use for loop
     let positiveCount = 0;
     let negativeCount = 0;
@@ -162,6 +211,40 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
     return positiveCount < negativeCount;
   }
 
+  /**
+   * Calculates the median velocity based on velocity history
+   * Medina works better agains outliers
+   * @returns Median velocity over the recent history
+   */
+  private getMedianVelocity(): number {
+    // Make a copy of velocity history and sort it
+    const sortedVelocities = [...this.velocityHistory].sort(
+      (valueA, valueB) => valueA - valueB
+    );
+    const length = sortedVelocities.length;
+
+    // If length is odd, return the middle element
+    if (length % 2 === 1) {
+      return sortedVelocities[Math.floor(length / 2)];
+    }
+
+    // If length is even, return the average of the two middle elements
+    const midIndex = length / 2;
+    return (sortedVelocities[midIndex - 1] + sortedVelocities[midIndex]) / 2;
+  }
+
+  /**
+   * Projects the next scroll offset based on median velocity
+   * @param timeMs Time in milliseconds to predict ahead
+   * @returns Projected scroll offset
+   */
+  private getProjectedScrollOffset(offset: number, timeMs: number): number {
+    const medianVelocity = this.getMedianVelocity();
+    // Convert time from ms to seconds for velocity calculation
+    // Predict next position: current position + (velocity * time)
+    return offset + medianVelocity * timeMs;
+  }
+
   /**
    * Calculates which items are currently visible in the viewport.
    * Unlike getEngagedIndices, this doesn't include buffer items.
@@ -196,11 +279,23 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
 
   setScrollDirection(scrollDirection: "forward" | "backward") {
     if (scrollDirection === "forward") {
-      this.velocityHistory = [1, 1, 1, 1, 1];
+      this.velocityHistory = [0, 0, 0, 0.1, 0.1];
       this.velocityIndex = 0;
     } else {
-      this.velocityHistory = [-1, -1, -1, -1, -1];
+      this.velocityHistory = [0, 0, 0, -0.1, -0.1];
       this.velocityIndex = 0;
     }
   }
+
+  /**
+   * Resets the velocity history based on the current scroll direction.
+   * This ensures that the velocity history is always in sync with the current scroll direction.
+   */
+  resetVelocityHistory() {
+    if (this.isScrollingBackward()) {
+      this.setScrollDirection("backward");
+    } else {
+      this.setScrollDirection("forward");
+    }
+  }
 }

package/src/recyclerview/helpers/RenderTimeTracker.ts

@@ -0,0 +1,42 @@
+import { PlatformConfig } from "../../native/config/PlatformHelper";
+import { AverageWindow } from "../../utils/AverageWindow";
+
+export class RenderTimeTracker {
+  private renderTimeAvgWindow = new AverageWindow(5);
+  private lastTimerStartedAt = -1;
+  private maxRenderTime = 32; // TODO: Improve this even more
+  private defaultRenderTime = 16;
+
+  startTracking() {
+    if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
+      return;
+    }
+    if (this.lastTimerStartedAt === -1) {
+      this.lastTimerStartedAt = Date.now();
+    }
+  }
+
+  markRenderComplete() {
+    if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
+      return;
+    }
+    if (this.lastTimerStartedAt !== -1) {
+      this.renderTimeAvgWindow.addValue(Date.now() - this.lastTimerStartedAt);
+      this.lastTimerStartedAt = -1;
+    }
+  }
+
+  getRawValue() {
+    return this.renderTimeAvgWindow.currentValue;
+  }
+
+  getAverageRenderTime() {
+    if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
+      return this.defaultRenderTime;
+    }
+    return Math.min(
+      this.maxRenderTime,
+      Math.max(Math.round(this.renderTimeAvgWindow.currentValue), 16)
+    );
+  }
+}

package/src/recyclerview/helpers/VelocityTracker.ts

@@ -0,0 +1,77 @@
+/**
+ * Tracks and calculates velocity for scroll/drag movements
+ * Used to determine momentum scrolling behavior
+ */
+export class VelocityTracker<T> {
+  /** Timestamp of the last velocity update */
+  private lastUpdateTime = Date.now();
+  /** Current velocity vector with x and y components */
+  private velocity = { x: 0, y: 0 };
+
+  /** Reference to the momentum end timeout */
+  private timeoutId: NodeJS.Timeout | null = null;
+
+  /**
+   * Calculates velocity based on position change over time
+   * @param newOffset Current position value
+   * @param oldOffset Previous position value
+   * @param isHorizontal Whether movement is horizontal (true) or vertical (false)
+   * @param isRTL Whether layout direction is right-to-left
+   * @param callback Function to call with velocity updates and momentum end signal
+   */
+  computeVelocity(
+    newOffset: number,
+    oldOffset: number,
+    isHorizontal: boolean,
+    callback: (
+      velocity: { x: number; y: number },
+      isMomentumEnd: boolean
+    ) => void
+  ) {
+    // Clear any pending momentum end timeout
+    this.cleanUp();
+    // Calculate time since last update
+    const currentTime = Date.now();
+    const timeSinceLastUpdate = Math.max(1, currentTime - this.lastUpdateTime);
+
+    // Calculate velocity as distance/time
+    const newVelocity = (newOffset - oldOffset) / timeSinceLastUpdate;
+
+    // console.log(
+    //   "newVelocity",
+    //   newOffset,
+    //   oldOffset,
+    //   currentTime,
+    //   this.lastUpdateTime,
+    //   timeSinceLastUpdate,
+    //   newVelocity
+    // );
+    this.lastUpdateTime = currentTime;
+
+    // Apply velocity to the correct axis
+    this.velocity.x = isHorizontal ? newVelocity : 0;
+    this.velocity.y = isHorizontal ? 0 : newVelocity;
+
+    // Trigger callback with current velocity
+    callback(this.velocity, false);
+
+    // Set timeout to signal momentum end after 100ms of no updates
+    this.timeoutId = setTimeout(() => {
+      this.cleanUp();
+      this.lastUpdateTime = Date.now();
+      this.velocity.x = 0;
+      this.velocity.y = 0;
+      callback(this.velocity, true);
+    }, 100);
+  }
+
+  /**
+   * Cleans up resources by clearing any pending timeout
+   */
+  cleanUp() {
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+  }
+}

package/src/recyclerview/hooks/useBoundDetection.ts

@@ -1,9 +1,10 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
 
 import { RecyclerViewManager } from "../RecyclerViewManager";
-import { RecyclerViewProps } from "../RecyclerViewProps";
 import { CompatScroller } from "../components/CompatScroller";
 
+import { useUnmountAwareAnimationFrame } from "./useUnmountAwareCallbacks";
+
 /**
  * Hook to detect when the scroll position reaches near the start or end of the list
  * and trigger the appropriate callbacks. This hook is responsible for:
@@ -17,7 +18,6 @@ import { CompatScroller } from "../components/CompatScroller";
  */
 export function useBoundDetection<T>(
   recyclerViewManager: RecyclerViewManager<T>,
-  props: RecyclerViewProps<T>,
   scrollViewRef: React.RefObject<CompatScroller>
 ) {
   // Track whether we've already triggered the end reached callback to prevent duplicate calls
@@ -26,22 +26,48 @@ export function useBoundDetection<T>(
   const pendingStartReached = useRef(false);
   // Track whether we should auto-scroll to bottom when new content is added
   const pendingAutoscrollToBottom = useRef(false);
-  const { horizontal, data, maintainVisibleContentPosition } = props;
+
+  const lastCheckBoundsTime = useRef(Date.now());
+
+  const { data } = recyclerViewManager.props;
+  const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
+
+  const windowHeight = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getWindowSize().height
+    : 0;
+
+  const contentHeight = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getChildContainerDimensions().height
+    : 0;
+
+  const windowWidth = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getWindowSize().width
+    : 0;
+
+  const contentWidth = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getChildContainerDimensions().width
+    : 0;
 
   /**
    * Checks if the scroll position is near the start or end of the list
    * and triggers appropriate callbacks if configured.
    */
   const checkBounds = useCallback(() => {
+    lastCheckBoundsTime.current = Date.now();
+
+    const {
+      onEndReached,
+      onStartReached,
+      maintainVisibleContentPosition,
+      horizontal,
+      onEndReachedThreshold: onEndReachedThresholdProp,
+      onStartReachedThreshold: onStartReachedThresholdProp,
+    } = recyclerViewManager.props;
     // Skip all calculations if neither callback is provided and autoscroll is disabled
     const autoscrollToBottomThreshold =
       maintainVisibleContentPosition?.autoscrollToBottomThreshold ?? -1;
 
-    if (
-      !props.onEndReached &&
-      !props.onStartReached &&
-      autoscrollToBottomThreshold < 0
-    ) {
+    if (!onEndReached && !onStartReached && autoscrollToBottomThreshold < 0) {
       return;
     }
 
@@ -50,7 +76,7 @@ export function useBoundDetection<T>(
         recyclerViewManager.getAbsoluteLastScrollOffset();
       const contentSize = recyclerViewManager.getChildContainerDimensions();
       const windowSize = recyclerViewManager.getWindowSize();
-      const isHorizontal = props.horizontal === true;
+      const isHorizontal = horizontal === true;
 
       // Calculate dimensions based on scroll direction
       const visibleLength = isHorizontal ? windowSize.width : windowSize.height;
@@ -59,8 +85,8 @@ export function useBoundDetection<T>(
         recyclerViewManager.firstItemOffset;
 
       // Check if we're near the end of the list
-      if (props.onEndReached) {
-        const onEndReachedThreshold = props.onEndReachedThreshold ?? 0.5;
+      if (onEndReached) {
+        const onEndReachedThreshold = onEndReachedThresholdProp ?? 0.5;
         const endThresholdDistance = onEndReachedThreshold * visibleLength;
 
         const isNearEnd =
@@ -69,27 +95,27 @@ export function useBoundDetection<T>(
 
         if (isNearEnd && !pendingEndReached.current) {
           pendingEndReached.current = true;
-          props.onEndReached();
+          onEndReached();
         }
         pendingEndReached.current = isNearEnd;
       }
 
       // Check if we're near the start of the list
-      if (props.onStartReached) {
-        const onStartReachedThreshold = props.onStartReachedThreshold ?? 0.2;
+      if (onStartReached) {
+        const onStartReachedThreshold = onStartReachedThresholdProp ?? 0.2;
         const startThresholdDistance = onStartReachedThreshold * visibleLength;
 
         const isNearStart = lastScrollOffset <= startThresholdDistance;
 
         if (isNearStart && !pendingStartReached.current) {
           pendingStartReached.current = true;
-          props.onStartReached();
+          onStartReached();
         }
         pendingStartReached.current = isNearStart;
       }
 
       // Handle auto-scrolling to bottom for vertical lists
-      if (!horizontal) {
+      if (!isHorizontal && autoscrollToBottomThreshold >= 0) {
         const autoscrollToBottomThresholdDistance =
           autoscrollToBottomThreshold * visibleLength;
 
@@ -104,22 +130,45 @@ export function useBoundDetection<T>(
         }
       }
     }
-  }, [recyclerViewManager, props]);
+  }, [recyclerViewManager]);
+
+  const runAutoScrollToBottomCheck = useCallback(() => {
+    if (pendingAutoscrollToBottom.current) {
+      pendingAutoscrollToBottom.current = false;
+      requestAnimationFrame(() => {
+        const shouldAnimate =
+          recyclerViewManager.props.maintainVisibleContentPosition
+            ?.animateAutoScrollToBottom ?? true;
+        scrollViewRef.current?.scrollToEnd({
+          animated: shouldAnimate,
+        });
+      });
+    }
+  }, [requestAnimationFrame, scrollViewRef, recyclerViewManager]);
 
   // Reset end reached state when data changes
   useMemo(() => {
     pendingEndReached.current = false;
+    // needs to run only when data changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [data]);
 
   // Auto-scroll to bottom when new content is added and we're near the bottom
   useEffect(() => {
-    if (pendingAutoscrollToBottom.current) {
-      requestAnimationFrame(() => {
-        scrollViewRef.current?.scrollToEnd();
-        pendingAutoscrollToBottom.current = false;
-      });
+    runAutoScrollToBottomCheck();
+  }, [data, runAutoScrollToBottomCheck, windowHeight, windowWidth]);
+
+  // Since content changes frequently, we try and avoid doing the auto scroll during active scrolls
+  useEffect(() => {
+    if (Date.now() - lastCheckBoundsTime.current >= 100) {
+      runAutoScrollToBottomCheck();
     }
-  }, [data]);
+  }, [
+    contentHeight,
+    contentWidth,
+    recyclerViewManager.firstItemOffset,
+    runAutoScrollToBottomCheck,
+  ]);
 
   return {
     checkBounds,

package/src/recyclerview/hooks/useLayoutState.ts

@@ -2,6 +2,13 @@ import { useState, useCallback } from "react";
 
 import { useRecyclerViewContext } from "../RecyclerViewContextProvider";
 
+export type LayoutStateSetter<T> = (
+  newValue: T | ((prevValue: T) => T),
+  skipParentLayout?: boolean
+) => void;
+
+export type LayoutStateInitialValue<T> = T | (() => T);
+
 /**
  * Custom hook that combines state management with RecyclerView layout updates.
  * This hook provides a way to manage state that affects the layout of the RecyclerView,
@@ -13,8 +20,8 @@ import { useRecyclerViewContext } from "../RecyclerViewContextProvider";
  *   - A setter function that updates the state and triggers a layout recalculation
  */
 export function useLayoutState<T>(
-  initialState: T | (() => T)
-): [T, (newValue: T | ((prevValue: T) => T)) => void] {
+  initialState: LayoutStateInitialValue<T>
+): [T, LayoutStateSetter<T>] {
   // Initialize state with the provided initial value
   const [state, setState] = useState<T>(initialState);
   // Get the RecyclerView context for layout management
@@ -28,16 +35,18 @@ export function useLayoutState<T>(
    * @param newValue - Either a new state value or a function that receives the previous state
    *                   and returns the new state
    */
-  const setLayoutState = useCallback(
-    (newValue: T | ((prevValue: T) => T)) => {
+  const setLayoutState: LayoutStateSetter<T> = useCallback(
+    (newValue, skipParentLayout) => {
       // Update the state using either the new value or the result of the updater function
       setState((prevValue) =>
         typeof newValue === "function"
           ? (newValue as (prevValue: T) => T)(prevValue)
           : newValue
       );
-      // Trigger a layout recalculation in the RecyclerView
-      recyclerViewContext?.layout();
+      if (!skipParentLayout) {
+        // Trigger a layout recalculation in the RecyclerView
+        recyclerViewContext?.layout();
+      }
     },
     [recyclerViewContext]
   );

package/src/recyclerview/hooks/useMappingHelper.ts

@@ -10,7 +10,7 @@ import { useRecyclerViewContext } from "../RecyclerViewContextProvider";
 export const useMappingHelper = () => {
   const recyclerViewContext = useRecyclerViewContext();
   const getMappingKey = useCallback(
-    (index: number, itemKey: string | number | bigint) => {
+    (itemKey: string | number | bigint, index: number) => {
       return recyclerViewContext ? index : itemKey;
     },
     [recyclerViewContext]

package/src/recyclerview/hooks/useOnLoad.ts

@@ -2,7 +2,7 @@ import { useEffect, useMemo, useRef, useState } from "react";
 
 import { RecyclerViewManager } from "../RecyclerViewManager";
 
-import { useUnmountFlag } from "./useUnmountFlag";
+import { useUnmountAwareAnimationFrame } from "./useUnmountAwareCallbacks";
 // import { ToastAndroid } from "react-native";
 
 /**
@@ -22,7 +22,7 @@ export const useOnListLoad = <T>(
   const [isLoaded, setIsLoaded] = useState<boolean>(false);
   const dataLength = recyclerViewManager.getDataLength();
   // const dataCollector = useRef<number[]>([]);
-  const isUnmounted = useUnmountFlag();
+  const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
   // Track render cycles by collecting elapsed time on each render
   // useEffect(() => {
   //   const elapsedTimeInMs = Date.now() - loadStartTimeRef.current;
@@ -48,10 +48,8 @@ export const useOnListLoad = <T>(
     // console.log("----------> dataCollector", dataCollectorString);
     // console.log("----------> FlashList v2 load in", `${elapsedTimeInMs} ms`);
     requestAnimationFrame(() => {
-      if (!isUnmounted.current) {
-        onLoad?.({ elapsedTimeInMs });
-        setIsLoaded(true);
-      }
+      onLoad?.({ elapsedTimeInMs });
+      setIsLoaded(true);
     });
   });