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

package/src/recyclerview/components/StickyHeaders.tsx

@@ -13,11 +13,13 @@ import React, {
   useEffect,
 } from "react";
 import { Animated, NativeScrollEvent } from "react-native";
+
 import { FlashListProps } from "../..";
-import { CompatAnimatedView } from "./CompatView";
 import { RecyclerViewManager } from "../RecyclerViewManager";
 import { ViewHolder } from "../ViewHolder";
 
+import { CompatAnimatedView } from "./CompatView";
+
 /**
  * Props for the StickyHeaders component
  * @template TItem - The type of items in the list
@@ -26,7 +28,7 @@ export interface StickyHeaderProps<TItem> {
   /** Array of indices that should have sticky headers */
   stickyHeaderIndices: number[];
   /** The data array being rendered */
-  data: readonly TItem[];
+  data: ReadonlyArray<TItem>;
   /** Animated value tracking scroll position */
   scrollY: Animated.Value;
   /** Function to render each item */
@@ -47,6 +49,11 @@ export interface StickyHeaderRef {
   reportScrollEvent: (event: NativeScrollEvent) => void;
 }
 
+interface StickyHeaderState {
+  currentStickyIndex: number;
+  pushStartsAt: number;
+}
+
 export const StickyHeaders = <TItem,>({
   stickyHeaderIndices,
   renderItem,
@@ -56,29 +63,35 @@ export const StickyHeaders = <TItem,>({
   data,
   extraData,
 }: StickyHeaderProps<TItem>) => {
-  const [stickyIndices, setStickyIndices] = useState<{
-    currentStickyIndex: number;
-    nextStickyIndex: number;
-  }>({ currentStickyIndex: -1, nextStickyIndex: -1 });
+  const [stickyHeaderState, setStickyHeaderState] = useState<StickyHeaderState>(
+    {
+      currentStickyIndex: -1,
+      pushStartsAt: Number.MAX_SAFE_INTEGER,
+    }
+  );
 
-  const { currentStickyIndex, nextStickyIndex } = stickyIndices;
-  const hasLayout = recyclerViewManager.hasLayout();
+  const { currentStickyIndex, pushStartsAt } = stickyHeaderState;
 
-  // Memoize sorted indices based on their Y positions
+  // sort indices and memoize compute
   const sortedIndices = useMemo(() => {
-    if (!hasLayout) {
-      return [];
-    }
-    return stickyHeaderIndices.sort((a, b) => a - b);
-  }, [stickyHeaderIndices, recyclerViewManager, hasLayout]);
+    return [...stickyHeaderIndices].sort((first, second) => first - second);
+  }, [stickyHeaderIndices]);
+
+  const legthInvalid =
+    sortedIndices.length === 0 ||
+    recyclerViewManager.getDataLength() <=
+      sortedIndices[sortedIndices.length - 1];
 
   const compute = useCallback(() => {
-    const adjustedValue = recyclerViewManager.getLastScrollOffset();
+    if (legthInvalid) {
+      return;
+    }
+    const adjustedScrollOffset = recyclerViewManager.getLastScrollOffset();
 
     // Binary search for current sticky index
     const currentIndexInArray = findCurrentStickyIndex(
       sortedIndices,
-      adjustedValue,
+      adjustedScrollOffset,
       (index) => recyclerViewManager.getLayout(index).y
     );
 
@@ -89,16 +102,33 @@ export const StickyHeaders = <TItem,>({
       newNextStickyIndex = -1;
     }
 
+    // To make sure header offset is 0 in the interpolate compute
+    const newNextStickyY =
+      newNextStickyIndex === -1
+        ? Number.MAX_SAFE_INTEGER
+        : (recyclerViewManager.tryGetLayout(newNextStickyIndex)?.y ?? 0) +
+          recyclerViewManager.firstItemOffset;
+    const newCurrentStickyHeight =
+      recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
+
+    const newPushStartsAt = newNextStickyY - newCurrentStickyHeight;
+
     if (
       newStickyIndex !== currentStickyIndex ||
-      newNextStickyIndex !== nextStickyIndex
+      newPushStartsAt !== pushStartsAt
     ) {
-      setStickyIndices({
+      setStickyHeaderState({
         currentStickyIndex: newStickyIndex,
-        nextStickyIndex: newNextStickyIndex,
+        pushStartsAt: newPushStartsAt,
       });
     }
-  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, sortedIndices]);
+  }, [
+    legthInvalid,
+    recyclerViewManager,
+    sortedIndices,
+    currentStickyIndex,
+    pushStartsAt,
+  ]);
 
   useEffect(() => {
     compute();
@@ -112,45 +142,24 @@ export const StickyHeaders = <TItem,>({
         compute();
       },
     }),
-    [
-      stickyHeaderIndices,
-      recyclerViewManager,
-      currentStickyIndex,
-      nextStickyIndex,
-    ]
+    [compute]
   );
 
   const refHolder = useRef(new Map()).current;
 
-  // Memoize translateY calculation
   const translateY = useMemo(() => {
-    if (currentStickyIndex === -1 || nextStickyIndex === -1) {
-      return scrollY.interpolate({
-        inputRange: [0, Infinity],
-        outputRange: [0, 0],
-        extrapolate: "clamp",
-      });
-    }
-
-    const currentLayout = recyclerViewManager.getLayout(currentStickyIndex);
-    const nextLayout = recyclerViewManager.getLayout(nextStickyIndex);
-
-    const pushStartsAt = nextLayout.y - currentLayout.height;
+    const currentStickyHeight =
+      recyclerViewManager.tryGetLayout(currentStickyIndex)?.height ?? 0;
 
     return scrollY.interpolate({
-      inputRange: [
-        pushStartsAt + recyclerViewManager.firstItemOffset,
-        nextLayout.y + recyclerViewManager.firstItemOffset,
-      ],
-      outputRange: [0, -currentLayout.height],
+      inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+      outputRange: [0, -currentStickyHeight],
       extrapolate: "clamp",
     });
-  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, scrollY]);
+  }, [recyclerViewManager, currentStickyIndex, scrollY, pushStartsAt]);
 
   // Memoize header content
   const headerContent = useMemo(() => {
-    if (currentStickyIndex === -1) return null;
-
     return (
       <CompatAnimatedView
         style={{
@@ -158,22 +167,25 @@ export const StickyHeaders = <TItem,>({
           top: 0,
           left: 0,
           right: 0,
+          zIndex: 1,
           transform: [{ translateY }],
         }}
       >
-        <ViewHolder
-          index={currentStickyIndex}
-          item={data[currentStickyIndex]}
-          renderItem={renderItem}
-          layout={{ x: 0, y: 0, width: 0, height: 0 }}
-          refHolder={refHolder}
-          extraData={extraData}
-          trailingItem={null}
-          target="StickyHeader"
-        />
+        {currentStickyIndex !== -1 && currentStickyIndex < data.length ? (
+          <ViewHolder
+            index={currentStickyIndex}
+            item={data[currentStickyIndex]}
+            renderItem={renderItem}
+            layout={{ x: 0, y: 0, width: 0, height: 0 }}
+            refHolder={refHolder}
+            extraData={extraData}
+            trailingItem={null}
+            target="StickyHeader"
+          />
+        ) : null}
       </CompatAnimatedView>
     );
-  }, [currentStickyIndex, data, renderItem, extraData, refHolder, translateY]);
+  }, [translateY, currentStickyIndex, data, renderItem, refHolder, extraData]);
 
   return headerContent;
 };

package/src/recyclerview/helpers/ConsecutiveNumbers.ts

@@ -1,5 +1,5 @@
 /**
- * A simple wrapper for consecutive integer arrays
+ * A simple wrapper for consecutive postive integer arrays
  * Only stores start and end indices for faster computation as numbers are consecutive.
  */
 export class ConsecutiveNumbers {
@@ -8,7 +8,7 @@ export class ConsecutiveNumbers {
     public readonly endIndex: number
   ) {}
 
-  static readonly EMPTY = new ConsecutiveNumbers(0, -1);
+  static readonly EMPTY = new ConsecutiveNumbers(-1, -2);
 
   /**
    * Get the length of the array

package/src/recyclerview/helpers/EngagedIndicesTracker.ts

@@ -1,11 +1,17 @@
-import { ConsecutiveNumbers } from "./ConsecutiveNumbers";
+import { PlatformConfig } from "../../native/config/PlatformHelper";
 import { RVLayoutManager } from "../layout-managers/LayoutManager";
 
+import { ConsecutiveNumbers } from "./ConsecutiveNumbers";
+
 export interface RVEngagedIndicesTracker {
   // Current scroll offset of the list. Directly setting this won't trigger visible indices updates
   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).
@@ -19,8 +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 {
@@ -32,16 +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)
-  public drawDistance: number = 250;
+  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;
 
   /**
@@ -63,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;
 
@@ -71,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
@@ -86,8 +134,8 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
       ? this.smallMultiplier
       : this.largeMultiplier;
 
-    let bufferBefore = Math.ceil(totalBuffer * beforeRatio);
-    let bufferAfter = Math.ceil(totalBuffer * afterRatio);
+    const bufferBefore = Math.ceil(totalBuffer * beforeRatio);
+    const bufferAfter = Math.ceil(totalBuffer * afterRatio);
 
     // STEP 3: Calculate the extended viewport (visible area + buffers)
     // The start position with buffer (never less than 0)
@@ -119,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;
@@ -131,22 +182,25 @@ 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;
-    }
-    //should decide based on whether we have more positive or negative values, use for loop
+  private isScrollingBackward(): boolean {
+    // should decide based on whether we have more positive or negative values, use for loop
     let positiveCount = 0;
     let negativeCount = 0;
+    // eslint-disable-next-line @typescript-eslint/prefer-for-of
     for (let i = 0; i < this.velocityHistory.length; i++) {
       if (this.velocityHistory[i] > 0) {
         positiveCount++;
@@ -157,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.
@@ -188,4 +276,26 @@ export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
   getEngagedIndices(): ConsecutiveNumbers {
     return this.engagedIndices;
   }
+
+  setScrollDirection(scrollDirection: "forward" | "backward") {
+    if (scrollDirection === "forward") {
+      this.velocityHistory = [0, 0, 0, 0.1, 0.1];
+      this.velocityIndex = 0;
+    } else {
+      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;
+    }
+  }
+}