@shopify/flash-list 1.8.0 → 2.0.0-alpha.1

package/src/recyclerview/helpers/EngagedIndicesTracker.ts

@@ -0,0 +1,191 @@
+import { ConsecutiveNumbers } from "./ConsecutiveNumbers";
+import { RVLayoutManager } from "../layout-managers/LayoutManager";
+
+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;
+
+  /**
+   * Updates the scroll offset and calculates which items should be rendered (engaged indices).
+   * @param offset - The new scroll offset position
+   * @param velocity - Current scroll velocity to optimize buffer distribution
+   * @param layoutManager - Layout manager to fetch item positions and dimensions
+   * @returns New engaged indices if changed, undefined if no change
+   */
+  updateScrollOffset: (
+    offset: number,
+    velocity: Velocity | null | undefined,
+    layoutManager: RVLayoutManager
+  ) => ConsecutiveNumbers | undefined;
+  getEngagedIndices: () => ConsecutiveNumbers;
+  computeVisibleIndices: (layoutManager: RVLayoutManager) => ConsecutiveNumbers;
+}
+
+export interface Velocity {
+  x: number;
+  y: number;
+}
+
+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;
+  // 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
+
+  // Circular buffer to track recent scroll velocities for direction detection
+  private velocityHistory = [-1, -1, -1, -1, -1];
+  private velocityIndex = 0;
+
+  /**
+   * Updates scroll position and determines which items should be rendered.
+   * Implements a smart buffer system that:
+   * 1. Calculates the visible viewport
+   * 2. Determines optimal buffer distribution based on scroll direction
+   * 3. Adjusts buffer sizes at list boundaries
+   * 4. Returns new indices that need to be rendered
+   */
+  updateScrollOffset(
+    offset: number,
+    velocity: Velocity | null | undefined,
+    layoutManager: RVLayoutManager
+  ): ConsecutiveNumbers | undefined {
+    // Update current scroll position
+    this.scrollOffset = offset;
+
+    // STEP 1: Determine the currently visible viewport
+    const windowSize = layoutManager.getWindowsSize();
+    const isHorizontal = layoutManager.isHorizontal();
+    const viewportStart = offset;
+    const viewportSize = isHorizontal ? windowSize.width : windowSize.height;
+    const viewportEnd = viewportStart + viewportSize;
+
+    // STEP 2: Determine buffer size and distribution
+    // 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
+    const beforeRatio = isScrollingBackward
+      ? this.largeMultiplier
+      : this.smallMultiplier;
+    const afterRatio = isScrollingBackward
+      ? this.smallMultiplier
+      : this.largeMultiplier;
+
+    let bufferBefore = Math.ceil(totalBuffer * beforeRatio);
+    let bufferAfter = Math.ceil(totalBuffer * afterRatio);
+
+    // STEP 3: Calculate the extended viewport (visible area + buffers)
+    // The start position with buffer (never less than 0)
+    let extendedStart = Math.max(0, viewportStart - bufferBefore);
+
+    // If we couldn't apply full buffer at start, calculate how much was unused
+    const unusedStartBuffer = Math.max(0, bufferBefore - viewportStart);
+
+    // Add any unused start buffer to the end buffer
+    let extendedEnd = viewportEnd + bufferAfter + unusedStartBuffer;
+
+    // STEP 4: Handle end boundary adjustments
+    // Get the total content size to check for end boundary
+    const layoutSize = layoutManager.getLayoutSize();
+    const maxPosition = isHorizontal ? layoutSize.width : layoutSize.height;
+
+    // If we hit the end boundary, redistribute unused buffer to the start
+    if (extendedEnd > maxPosition) {
+      // Calculate unused end buffer and apply it to the start if possible
+      const unusedEndBuffer = extendedEnd - maxPosition;
+      extendedEnd = maxPosition;
+
+      // Try to extend start position further with the unused end buffer
+      extendedStart = Math.max(0, extendedStart - unusedEndBuffer);
+    }
+
+    // STEP 5: Get and return the new engaged indices
+    const newEngagedIndices = layoutManager.getVisibleLayouts(
+      extendedStart,
+      extendedEnd
+    );
+    if (!isHorizontal) {
+      //console.log("newEngagedIndices", newEngagedIndices, this.scrollOffset);
+    }
+    // Only return new indices if they've changed
+    const oldEngagedIndices = this.engagedIndices;
+    this.engagedIndices = newEngagedIndices;
+
+    return newEngagedIndices.equals(oldEngagedIndices)
+      ? undefined
+      : newEngagedIndices;
+  }
+
+  /**
+   * 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
+    let positiveCount = 0;
+    let negativeCount = 0;
+    for (let i = 0; i < this.velocityHistory.length; i++) {
+      if (this.velocityHistory[i] > 0) {
+        positiveCount++;
+      } else if (this.velocityHistory[i] < 0) {
+        negativeCount++;
+      }
+    }
+    return positiveCount < negativeCount;
+  }
+
+  /**
+   * Calculates which items are currently visible in the viewport.
+   * Unlike getEngagedIndices, this doesn't include buffer items.
+   * @param layoutManager - Layout manager to fetch item positions
+   * @returns Indices of items currently visible in the viewport
+   */
+  computeVisibleIndices(layoutManager: RVLayoutManager): ConsecutiveNumbers {
+    const windowSize = layoutManager.getWindowsSize();
+    const isHorizontal = layoutManager.isHorizontal();
+
+    // Calculate viewport boundaries
+    const viewportStart = this.scrollOffset;
+    const viewportSize = isHorizontal ? windowSize.width : windowSize.height;
+    const viewportEnd = viewportStart + viewportSize;
+
+    // Get indices of items currently visible in the viewport
+    const newVisibleIndices = layoutManager.getVisibleLayouts(
+      viewportStart,
+      viewportEnd
+    );
+    return newVisibleIndices;
+  }
+
+  /**
+   * Returns the currently engaged (rendered) indices.
+   * This includes both visible items and buffer items.
+   * @returns The last computed set of engaged indices
+   */
+  getEngagedIndices(): ConsecutiveNumbers {
+    return this.engagedIndices;
+  }
+}

package/src/recyclerview/hooks/useBoundDetection.ts

@@ -0,0 +1,127 @@
+import { useCallback, useEffect, useMemo } from "react";
+import { useRef } from "react";
+import { RecyclerViewManager } from "../RecyclerViewManager";
+import { RecyclerViewProps } from "../RecyclerViewProps";
+import { CompatScroller } from "../components/CompatScroller";
+
+/**
+ * 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:
+ * 1. Detecting when the user scrolls near the end of the list (onEndReached)
+ * 2. Detecting when the user scrolls near the start of the list (onStartReached)
+ * 3. Managing auto-scrolling to bottom when new content is added
+ *
+ * @param recyclerViewManager - The RecyclerViewManager instance that handles the list's core functionality
+ * @param props - The RecyclerViewProps containing configuration and callbacks
+ * @param scrollViewRef - Reference to the scrollable container component
+ */
+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
+  const pendingEndReached = useRef(false);
+  // Track whether we've already triggered the start reached callback to prevent duplicate calls
+  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;
+
+  /**
+   * Checks if the scroll position is near the start or end of the list
+   * and triggers appropriate callbacks if configured.
+   */
+  const checkBounds = useCallback(() => {
+    // Skip all calculations if neither callback is provided and autoscroll is disabled
+    const autoscrollToBottomThreshold =
+      maintainVisibleContentPosition?.autoscrollToBottomThreshold ?? -1;
+
+    if (
+      !props.onEndReached &&
+      !props.onStartReached &&
+      autoscrollToBottomThreshold < 0
+    ) {
+      return;
+    }
+
+    if (recyclerViewManager.getIsFirstLayoutComplete()) {
+      const lastScrollOffset =
+        recyclerViewManager.getAbsoluteLastScrollOffset();
+      const contentSize = recyclerViewManager.getChildContainerDimensions();
+      const windowSize = recyclerViewManager.getWindowSize();
+      const isHorizontal = props.horizontal === true;
+
+      // Calculate dimensions based on scroll direction
+      const visibleLength = isHorizontal ? windowSize.width : windowSize.height;
+      const contentLength =
+        (isHorizontal ? contentSize.width : contentSize.height) +
+        recyclerViewManager.firstItemOffset;
+
+      // Check if we're near the end of the list
+      if (props.onEndReached) {
+        const onEndReachedThreshold = props.onEndReachedThreshold ?? 0.5;
+        const endThresholdDistance = onEndReachedThreshold * visibleLength;
+
+        const isNearEnd =
+          Math.ceil(lastScrollOffset + visibleLength) >=
+          contentLength - endThresholdDistance;
+
+        if (isNearEnd && !pendingEndReached.current) {
+          pendingEndReached.current = true;
+          props.onEndReached();
+        }
+        pendingEndReached.current = isNearEnd;
+      }
+
+      // Check if we're near the start of the list
+      if (props.onStartReached) {
+        const onStartReachedThreshold = props.onStartReachedThreshold ?? 0.2;
+        const startThresholdDistance = onStartReachedThreshold * visibleLength;
+
+        const isNearStart = lastScrollOffset <= startThresholdDistance;
+
+        if (isNearStart && !pendingStartReached.current) {
+          pendingStartReached.current = true;
+          props.onStartReached();
+        }
+        pendingStartReached.current = isNearStart;
+      }
+
+      // Handle auto-scrolling to bottom for vertical lists
+      if (!horizontal) {
+        const autoscrollToBottomThresholdDistance =
+          autoscrollToBottomThreshold * visibleLength;
+
+        const isNearBottom =
+          Math.ceil(lastScrollOffset + visibleLength) >=
+          contentLength - autoscrollToBottomThresholdDistance;
+
+        if (isNearBottom) {
+          pendingAutoscrollToBottom.current = true;
+        } else {
+          pendingAutoscrollToBottom.current = false;
+        }
+      }
+    }
+  }, [recyclerViewManager, props]);
+
+  // Reset end reached state when data changes
+  useMemo(() => {
+    pendingEndReached.current = false;
+  }, [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;
+      });
+    }
+  }, [data]);
+
+  return {
+    checkBounds,
+  };
+}

package/src/recyclerview/hooks/useLayoutState.ts

@@ -0,0 +1,46 @@
+import { useState, useCallback } from "react";
+
+import { useRecyclerViewContext } from "../RecyclerViewContextProvider";
+
+/**
+ * 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,
+ * ensuring that any state changes trigger a layout recalculation.
+ *
+ * @param initialState - The initial state value or a function that returns the initial state
+ * @returns A tuple containing:
+ *   - The current state value
+ *   - 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] {
+  // Initialize state with the provided initial value
+  const [state, setState] = useState<T>(initialState);
+  // Get the RecyclerView context for layout management
+  const recyclerViewContext = useRecyclerViewContext();
+
+  /**
+   * Setter function that updates the state and triggers a layout recalculation.
+   * This ensures that any state changes that affect the layout are properly reflected
+   * in the RecyclerView's visual representation.
+   *
+   * @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)) => {
+      // 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();
+    },
+    [recyclerViewContext]
+  );
+
+  return [state, setLayoutState];
+}

package/src/recyclerview/hooks/useOnLoad.ts

@@ -0,0 +1,78 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { RecyclerViewManager } from "../RecyclerViewManager";
+import { useUnmountFlag } from "./useUnmountFlag";
+//import { ToastAndroid } from "react-native";
+
+/**
+ * Hook to track when the RecyclerView has loaded its items and notify when loading is complete.
+ * Similar to FlashList's onLoad functionality, this hook tracks the time it takes to render
+ * the initial set of items in the RecyclerView and provides performance metrics.
+ *
+ * @param recyclerViewManager - The RecyclerViewManager instance managing the list
+ * @param onLoad - Optional callback function that will be called when the list has loaded with timing information
+ * @returns Object containing isLoaded state indicating whether the list has completed initial rendering
+ */
+export const useOnListLoad = <T>(
+  recyclerViewManager: RecyclerViewManager<T>,
+  onLoad?: (info: { elapsedTimeInMs: number }) => void
+): { isLoaded: boolean } => {
+  const loadStartTimeRef = useRef<number>(Date.now());
+  const [isLoaded, setIsLoaded] = useState<boolean>(false);
+  const dataLength = recyclerViewManager.getDataLength();
+  //const dataCollector = useRef<number[]>([]);
+  const isUnmounted = useUnmountFlag();
+  // Track render cycles by collecting elapsed time on each render
+  // useEffect(() => {
+  //   const elapsedTimeInMs = Date.now() - loadStartTimeRef.current;
+  //   dataCollector.current?.push(elapsedTimeInMs);
+  // });
+
+  useMemo(() => {
+    loadStartTimeRef.current = Date.now();
+  }, [dataLength]);
+
+  useOnLoad(recyclerViewManager, () => {
+    const elapsedTimeInMs = Date.now() - loadStartTimeRef.current;
+    // Commented code below was used for debugging purposes
+    // to display all collected timing data points
+    // const dataCollectorString = dataCollector.current
+    //   ?.map((value) => value.toString())
+    //   .join(", ");
+    // ToastAndroid?.show(
+    //   `onLoad called after ${dataCollectorString}`,
+    //   ToastAndroid.SHORT
+    // );
+    //console.log("----------> dataCollector", dataCollectorString);
+    //console.log("----------> elapsedTimeInMs", elapsedTimeInMs);
+    requestAnimationFrame(() => {
+      if (!isUnmounted.current) {
+        onLoad?.({ elapsedTimeInMs });
+        setIsLoaded(true);
+      }
+    });
+  });
+
+  return { isLoaded };
+};
+
+/**
+ * Core hook that detects when a RecyclerView has completed its initial layout.
+ * This hook monitors the RecyclerViewManager and triggers the provided callback
+ * once the first layout is complete.
+ *
+ * @param recyclerViewManager - The RecyclerViewManager instance to monitor
+ * @param onLoad - Callback function that will be called once when the first layout is complete
+ */
+export const useOnLoad = <T>(
+  recyclerViewManager: RecyclerViewManager<T>,
+  onLoad: () => void
+) => {
+  const isLoaded = useRef<boolean>(false);
+  useEffect(() => {
+    // Only trigger onLoad callback once when first layout is complete
+    if (recyclerViewManager.getIsFirstLayoutComplete() && !isLoaded.current) {
+      isLoaded.current = true;
+      onLoad();
+    }
+  });
+};