@shopify/flash-list 2.0.0-alpha.15 → 2.0.0-alpha.17

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/useRecyclingState.ts

@@ -1,6 +1,10 @@
-import { Dispatch, SetStateAction, useCallback, useMemo, useRef } from "react";
+import { useCallback, useMemo, useRef } from "react";
 
-import { useLayoutState } from "./useLayoutState";
+import { LayoutStateSetter, useLayoutState } from "./useLayoutState";
+
+export type RecyclingStateSetter<T> = LayoutStateSetter<T>;
+
+export type RecyclingStateInitialValue<T> = T | (() => T);
 
 /**
  * A custom hook that provides state management with automatic reset functionality.
@@ -16,10 +20,10 @@ import { useLayoutState } from "./useLayoutState";
  *   - A setState function that works like useState's setState
  */
 export function useRecyclingState<T>(
-  initialState: T | (() => T),
+  initialState: RecyclingStateInitialValue<T>,
   deps: React.DependencyList,
   onReset?: () => void
-): [T, Dispatch<SetStateAction<T>>] {
+): [T, RecyclingStateSetter<T>] {
   // Store the current state value in a ref to persist between renders
   const valueStore = useRef<T>();
   // Use layoutState to trigger re-renders when state changes
@@ -42,8 +46,8 @@ export function useRecyclingState<T>(
    * Proxy setState function that updates the stored value and triggers a re-render.
    * Only triggers a re-render if the new value is different from the current value.
    */
-  const setStateProxy = useCallback(
-    (newValue: T | ((prevValue: T) => T)) => {
+  const setStateProxy: RecyclingStateSetter<T> = useCallback(
+    (newValue, skipParentLayout) => {
       // Calculate next state value from function or direct value
       const nextState =
         typeof newValue === "function"
@@ -53,7 +57,7 @@ export function useRecyclingState<T>(
       // Only update and trigger re-render if value has changed
       if (nextState !== valueStore.current) {
         valueStore.current = nextState;
-        setCounter((prev) => prev + 1);
+        setCounter((prev) => prev + 1, skipParentLayout);
       }
     },
     [setCounter]

package/src/recyclerview/layout-managers/GridLayoutManager.ts

@@ -14,6 +14,9 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
   /** The width of the bounded area for the grid */
   private boundedSize: number;
 
+  /** If there's a span change for grid layout, we need to recompute all the widths */
+  private fullRelayoutRequired = false;
+
   constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
     super(params, previousLayoutManager);
     this.boundedSize = params.windowSize.width;
@@ -33,10 +36,7 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
       this.boundedSize = params.windowSize.width;
       if (this.layouts.length > 0) {
         // update all widths
-        for (let i = 0; i < this.layouts.length; i++) {
-          this.layouts[i].width = this.getWidth(i);
-        }
-        // console.log("-----> recomputeLayouts");
+        this.updateAllWidths();
 
         this.recomputeLayouts(0, this.layouts.length - 1);
         this.requiresRepaint = true;
@@ -57,6 +57,13 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
       layout.isHeightMeasured = true;
       layout.isWidthMeasured = true;
     }
+
+    // TODO: Can be optimized
+    if (this.fullRelayoutRequired) {
+      this.updateAllWidths();
+      this.fullRelayoutRequired = false;
+      return 0;
+    }
   }
 
   /**
@@ -72,13 +79,21 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     layout.enforcedWidth = true;
   }
 
+  /**
+   * Handles span change for an item.
+   * @param index Index of the item
+   */
+  handleSpanChange(index: number) {
+    this.fullRelayoutRequired = true;
+  }
+
   /**
    * Returns the total size of the layout area.
    * @returns RVDimension containing width and height of the layout
    */
   getLayoutSize(): RVDimension {
     if (this.layouts.length === 0) return { width: 0, height: 0 };
-    const totalHeight = this.computeTotalHeight(this.layouts.length - 1);
+    const totalHeight = this.computeTotalHeightTillRow(this.layouts.length - 1);
     return {
       width: this.boundedSize,
       height: totalHeight,
@@ -91,7 +106,7 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
    * @param endIndex Ending index of items to recompute
    */
   recomputeLayouts(startIndex: number, endIndex: number): void {
-    const newStartIndex = this.locateFirstNeighbourIndex(
+    const newStartIndex = this.locateFirstIndexInRow(
       Math.max(0, startIndex - 1)
     );
     const startVal = this.getLayout(newStartIndex);
@@ -122,25 +137,23 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
    * @returns Width of the item
    */
   private getWidth(index: number): number {
-    const span = this.getSpanSizeInfo(index).span ?? 1;
-    return (this.boundedSize / this.maxColumns) * span;
+    return (this.boundedSize / this.maxColumns) * this.getSpan(index);
   }
 
   /**
    * Processes items in a row and returns the tallest item.
    * Also handles height normalization for items in the same row.
    * Tallest item per row helps in forcing tallest items height on neighbouring items.
-   * @param index Index of the last item in the row
+   * @param endIndex Index of the last item in the row
    * @returns The tallest item in the row
    */
-  private processAndReturnTallestItemInRow(index: number): RVLayout {
-    const startIndex = this.locateFirstNeighbourIndex(index);
-    const y = this.layouts[startIndex].y;
+  private processAndReturnTallestItemInRow(endIndex: number): RVLayout {
+    const startIndex = this.locateFirstIndexInRow(endIndex);
     let tallestItem: RVLayout | undefined;
     let maxHeight = 0;
     let i = startIndex;
     let isMeasured = false;
-    while (Math.ceil(this.layouts[i].y) === Math.ceil(y)) {
+    while (i <= endIndex) {
       const layout = this.layouts[i];
       isMeasured = isMeasured || Boolean(layout.isHeightMeasured);
       maxHeight = Math.max(maxHeight, layout.height);
@@ -156,7 +169,9 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
         break;
       }
     }
-
+    if (!tallestItem && maxHeight > 0) {
+      maxHeight = Number.MAX_SAFE_INTEGER;
+    }
     tallestItem = tallestItem ?? this.layouts[startIndex];
 
     if (!isMeasured) {
@@ -170,7 +185,7 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
         this.requiresRepaint = true;
       }
       i = startIndex;
-      while (Math.ceil(this.layouts[i].y) === Math.ceil(y)) {
+      while (i <= endIndex) {
         this.layouts[i].minHeight = targetHeight;
         if (targetHeight > 0) {
           this.layouts[i].height = targetHeight;
@@ -187,15 +202,15 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
 
   /**
    * Computes the total height of the layout.
-   * @param index Index of the last item in the layout
+   * @param endIndex Index of the last item in the row
    * @returns Total height of the layout
    */
-  private computeTotalHeight(index: number): number {
-    const startIndex = this.locateFirstNeighbourIndex(index);
+  private computeTotalHeightTillRow(endIndex: number): number {
+    const startIndex = this.locateFirstIndexInRow(endIndex);
     const y = this.layouts[startIndex].y;
     let maxHeight = 0;
     let i = startIndex;
-    while (Math.ceil(this.layouts[i].y) === Math.ceil(y)) {
+    while (i <= endIndex) {
       maxHeight = Math.max(maxHeight, this.layouts[i].height);
       i++;
       if (i >= this.layouts.length) {
@@ -205,6 +220,12 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     return y + maxHeight;
   }
 
+  private updateAllWidths() {
+    for (let i = 0; i < this.layouts.length; i++) {
+      this.layouts[i].width = this.getWidth(i);
+    }
+  }
+
   /**
    * Checks if an item can fit within the bounded width.
    * @param itemX Starting X position of the item
@@ -217,14 +238,14 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
 
   /**
    * Locates the index of the first item in the current row.
-   * @param startIndex Index to start searching from
+   * @param itemIndex Index to start searching from
    * @returns Index of the first item in the row
    */
-  private locateFirstNeighbourIndex(startIndex: number): number {
-    if (startIndex === 0) {
+  private locateFirstIndexInRow(itemIndex: number): number {
+    if (itemIndex === 0) {
       return 0;
     }
-    let i = startIndex;
+    let i = itemIndex;
     for (; i >= 0; i--) {
       if (this.layouts[i].x === 0) {
         break;

package/src/recyclerview/layout-managers/LayoutManager.ts

@@ -20,8 +20,6 @@ export abstract class RVLayoutManager {
   protected layouts: RVLayout[];
   /** Dimensions of the visible window/viewport */
   protected windowSize: RVDimension;
-  /** Information about item spans and sizes */
-  protected spanSizeInfo: SpanSizeInfo = {};
   /** Maximum number of columns in the layout */
   protected maxColumns: number;
 
@@ -41,6 +39,13 @@ export abstract class RVLayoutManager {
   private widthAverageWindow: MultiTypeAverageWindow;
   /** Maximum number of items to process in a single layout pass */
   private maxItemsToProcess = 250; // TODO: make this dynamic
+  /** Information about item spans and sizes */
+  private spanSizeInfo: SpanSizeInfo = {};
+  /** Span tracker for each item */
+  private spanTracker: (number | undefined)[] = [];
+
+  /** Current max index with changed layout */
+  private currentMaxIndexWithChangedLayout = -1;
 
   constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
     this.heightAverageWindow = new MultiTypeAverageWindow(5, 200);
@@ -164,37 +169,46 @@ export abstract class RVLayoutManager {
 
     if (this.layouts.length > totalItemCount) {
       this.layouts.length = totalItemCount;
+      this.spanTracker.length = totalItemCount;
       minRecomputeIndex = totalItemCount - 1; // <0 gets skipped so it's safe to set to totalItemCount - 1
     }
     // update average windows
     minRecomputeIndex = Math.min(
       minRecomputeIndex,
-      this.computeEstimatesAndMinRecomputeIndex(layoutInfo)
+      this.computeEstimatesAndMinMaxChangedLayout(layoutInfo)
     );
 
     if (this.layouts.length < totalItemCount && totalItemCount > 0) {
       const startIndex = this.layouts.length;
       this.layouts.length = totalItemCount;
+      this.spanTracker.length = totalItemCount;
       for (let i = startIndex; i < totalItemCount; i++) {
         this.getLayout(i);
+        this.getSpan(i);
       }
       this.recomputeLayouts(startIndex, totalItemCount - 1);
     }
-    minRecomputeIndex = Math.min(
-      minRecomputeIndex,
-      this.processLayoutInfo(layoutInfo, totalItemCount) ?? minRecomputeIndex
-    );
+
     // compute minRecomputeIndex
+
     minRecomputeIndex = Math.min(
       minRecomputeIndex,
-      this.computeEstimatesAndMinRecomputeIndex(layoutInfo)
+      this.computeMinIndexWithChangedSpan(layoutInfo),
+      this.processLayoutInfo(layoutInfo, totalItemCount) ?? minRecomputeIndex,
+      this.computeEstimatesAndMinMaxChangedLayout(layoutInfo)
     );
+
     if (minRecomputeIndex >= 0 && minRecomputeIndex < totalItemCount) {
+      const maxRecomputeIndex = this.getMaxRecomputeIndex(minRecomputeIndex);
       this.recomputeLayouts(
         this.getMinRecomputeIndex(minRecomputeIndex),
-        this.getMaxRecomputeIndex(minRecomputeIndex)
+        maxRecomputeIndex
       );
+      if (maxRecomputeIndex + 1 < totalItemCount) {
+        this.layouts[maxRecomputeIndex + 1].repositionPending = true;
+      }
     }
+    this.currentMaxIndexWithChangedLayout = -1;
   }
 
   /**
@@ -260,16 +274,30 @@ export abstract class RVLayoutManager {
   protected abstract estimateLayout(index: number): void;
 
   /**
-   * Gets span size information for an item, applying any overrides.
+   * Gets span for an item, applying any overrides.
+   * This is intended to be called during a relayout call. The value is tracked and used to determine if a span change has occurred.
+   * If skipTracking is true, the operation is not tracked. Can be useful if span is required outside of a relayout call.
+   * The tracker is used to call handleSpanChange if a span change has occurred before relayout call.
+   * // TODO: improve this contract.
    * @param index Index of the item
-   * @returns SpanSizeInfo for the item
+   * @returns Span for the item
    */
-  protected getSpanSizeInfo(index: number): SpanSizeInfo {
+  protected getSpan(index: number, skipTracking = false): number {
     this.spanSizeInfo.span = undefined;
     this.overrideItemLayout(index, this.spanSizeInfo);
-    return this.spanSizeInfo;
+    const span = Math.min(this.spanSizeInfo.span ?? 1, this.maxColumns);
+    if (!skipTracking) {
+      this.spanTracker[index] = span;
+    }
+    return span;
   }
 
+  /**
+   * Method to handle span change for an item. Can be overridden by subclasses.
+   * @param index Index of the item
+   */
+  protected handleSpanChange(index: number) {}
+
   /**
    * Gets the maximum index to process in a single layout pass.
    * @param startIndex Starting index
@@ -277,7 +305,8 @@ export abstract class RVLayoutManager {
    */
   private getMaxRecomputeIndex(startIndex: number): number {
     return Math.min(
-      startIndex + this.maxItemsToProcess,
+      Math.max(startIndex, this.currentMaxIndexWithChangedLayout) +
+        this.maxItemsToProcess,
       this.layouts.length - 1
     );
   }
@@ -296,7 +325,7 @@ export abstract class RVLayoutManager {
    * @param layoutInfo Array of layout information for items
    * @returns Minimum index that needs recomputation
    */
-  private computeEstimatesAndMinRecomputeIndex(
+  private computeEstimatesAndMinMaxChangedLayout(
     layoutInfo: RVLayoutInfo[]
   ): number {
     let minRecomputeIndex = Number.MAX_VALUE;
@@ -307,10 +336,18 @@ export abstract class RVLayoutManager {
         !storedLayout ||
         !storedLayout.isHeightMeasured ||
         !storedLayout.isWidthMeasured ||
+        storedLayout.repositionPending ||
         areDimensionsNotEqual(storedLayout.height, dimensions.height) ||
         areDimensionsNotEqual(storedLayout.width, dimensions.width)
       ) {
         minRecomputeIndex = Math.min(minRecomputeIndex, index);
+        this.currentMaxIndexWithChangedLayout = Math.max(
+          this.currentMaxIndexWithChangedLayout,
+          index
+        );
+        if (storedLayout?.repositionPending) {
+          storedLayout.repositionPending = false;
+        }
       }
       this.heightAverageWindow.addValue(
         dimensions.height,
@@ -323,6 +360,21 @@ export abstract class RVLayoutManager {
     }
     return minRecomputeIndex;
   }
+
+  private computeMinIndexWithChangedSpan(layoutInfo: RVLayoutInfo[]): number {
+    let minIndexWithChangedSpan = Number.MAX_VALUE;
+    for (const info of layoutInfo) {
+      const { index } = info;
+      const span = this.getSpan(index, true);
+      const storedSpan = this.spanTracker[index];
+      if (span !== storedSpan) {
+        this.spanTracker[index] = span;
+        this.handleSpanChange(index);
+        minIndexWithChangedSpan = Math.min(minIndexWithChangedSpan, index);
+      }
+    }
+    return minIndexWithChangedSpan;
+  }
 }
 
 /**
@@ -467,6 +519,13 @@ export interface RVLayout extends RVDimension {
    * When false, the height is determined by content
    */
   enforcedHeight?: boolean;
+
+  /**
+   * When true, the layout is pending repositioning
+   * When false, the layout is up to date
+   * ViewHolder update is not required.
+   */
+  repositionPending?: boolean;
 }
 
 /**

package/src/recyclerview/layout-managers/MasonryLayoutManager.ts

@@ -19,10 +19,13 @@ export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
   /** Current column index for sequential placement */
   private currentColumn = 0;
 
+  /** If there's a span change for masonry layout, we need to recompute all the widths */
+  private fullRelayoutRequired = false;
+
   constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
     super(params, previousLayoutManager);
     this.boundedSize = params.windowSize.width;
-    this.optimizeItemArrangement = params.optimizeItemArrangement ?? false;
+    this.optimizeItemArrangement = params.optimizeItemArrangement;
     this.columnHeights = this.columnHeights ?? Array(this.maxColumns).fill(0);
   }
 
@@ -44,10 +47,7 @@ export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
         // console.log("-----> recomputeLayouts");
 
         // update all widths
-        for (let i = 0; i < this.layouts.length; i++) {
-          this.layouts[i].width = this.getWidth(i);
-          this.layouts[i].minHeight = undefined;
-        }
+        this.updateAllWidths();
         this.recomputeLayouts(0, this.layouts.length - 1);
         this.requiresRepaint = true;
       }
@@ -69,6 +69,13 @@ export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
       layout.isWidthMeasured = true;
       this.layouts[index] = layout;
     }
+
+    // TODO: Can be optimized
+    if (this.fullRelayoutRequired) {
+      this.updateAllWidths();
+      this.fullRelayoutRequired = false;
+      return 0;
+    }
   }
 
   /**
@@ -87,6 +94,14 @@ export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
     layout.enforcedWidth = true;
   }
 
+  /**
+   * Handles span change for an item.
+   * @param index Index of the item
+   */
+  handleSpanChange(index: number) {
+    this.fullRelayoutRequired = true;
+  }
+
   /**
    * Returns the total size of the layout area.
    * @returns RVDimension containing width and height of the layout
@@ -124,7 +139,8 @@ export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
 
     for (let i = startIndex; i < itemCount; i++) {
       const layout = this.getLayout(i);
-      const span = this.getSpanSizeInfo(i).span ?? 1;
+      // Skip tracking span because we're not changing widths
+      const span = this.getSpan(i, true);
 
       if (this.optimizeItemArrangement) {
         if (span === 1) {
@@ -147,8 +163,14 @@ export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
    * @returns Width of the item
    */
   private getWidth(index: number): number {
-    const span = this.getSpanSizeInfo(index).span ?? 1;
-    return (this.boundedSize / this.maxColumns) * span;
+    return (this.boundedSize / this.maxColumns) * this.getSpan(index);
+  }
+
+  private updateAllWidths() {
+    for (let i = 0; i < this.layouts.length; i++) {
+      this.layouts[i].width = this.getWidth(i);
+      this.layouts[i].minHeight = undefined;
+    }
   }
 
   /**

package/src/viewability/ViewabilityManager.ts

@@ -22,17 +22,21 @@ export default class ViewabilityManager<T> {
       this.viewabilityHelpers.push(
         this.createViewabilityHelper(
           flashListRef.props.viewabilityConfig,
-          flashListRef.props.onViewableItemsChanged
+          (info) => {
+            flashListRef.props.onViewableItemsChanged?.(info);
+          }
         )
       );
     }
     (flashListRef.props.viewabilityConfigCallbackPairs ?? []).forEach(
-      (pair) => {
+      (pair, index) => {
         this.viewabilityHelpers.push(
-          this.createViewabilityHelper(
-            pair.viewabilityConfig,
-            pair.onViewableItemsChanged
-          )
+          this.createViewabilityHelper(pair.viewabilityConfig, (info) => {
+            const callback =
+              flashListRef.props.viewabilityConfigCallbackPairs?.[index]
+                ?.onViewableItemsChanged;
+            callback?.(info);
+          })
         );
       }
     );