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

package/src/recyclerview/hooks/useRecyclerViewManager.ts

@@ -2,15 +2,20 @@ import { useEffect, useMemo, useState } from "react";
 
 import { RecyclerViewProps } from "../RecyclerViewProps";
 import { RecyclerViewManager } from "../RecyclerViewManager";
+import { VelocityTracker } from "../helpers/VelocityTracker";
 
 export const useRecyclerViewManager = <T>(props: RecyclerViewProps<T>) => {
   const [recyclerViewManager] = useState<RecyclerViewManager<T>>(
     () => new RecyclerViewManager(props)
   );
+  const [velocityTracker] = useState(() => new VelocityTracker());
+
   const { data } = props;
 
   useMemo(() => {
     recyclerViewManager.updateProps(props);
+    // used to update props so rule can be disabled
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [props]);
 
   /**
@@ -18,13 +23,20 @@ export const useRecyclerViewManager = <T>(props: RecyclerViewProps<T>) => {
    */
   useMemo(() => {
     recyclerViewManager.processDataUpdate();
+    // used to process data update so rule can be disabled
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [data]);
 
   useEffect(() => {
+    recyclerViewManager.restoreIfNeeded();
+
     return () => {
       recyclerViewManager.dispose();
+      velocityTracker.cleanUp();
     };
+    // Used to perform cleanup on unmount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  return { recyclerViewManager };
+  return { recyclerViewManager, velocityTracker };
 };

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/hooks/useSecondaryProps.tsx

@@ -105,7 +105,7 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
       const ForwardedScrollComponent = React.forwardRef((_props, ref) =>
         (renderScrollComponent as any)({ ..._props, ref } as any)
       );
-      ForwardedScrollComponent.displayName = "CompatScrollView";
+      ForwardedScrollComponent.displayName = "CustomScrollView";
       scrollComponent = ForwardedScrollComponent as any;
     } else if (renderScrollComponent) {
       scrollComponent = renderScrollComponent;

package/src/recyclerview/hooks/useUnmountAwareCallbacks.ts

@@ -1,10 +1,10 @@
 import { useCallback, useEffect, useState } from "react";
 
 /**
- * Hook that provides callbacks which are aware of component unmount state.
- * Any timeouts created with these callbacks will be automatically cleared when the component unmounts.
+ * Hook that provides a setTimeout which is aware of component unmount state.
+ * Any timeouts created with this hook will be automatically cleared when the component unmounts.
  */
-export function useUnmountAwareCallbacks() {
+export function useUnmountAwareTimeout() {
   // Store active timeout IDs in a Set for more efficient add/remove operations
   const [timeoutIds] = useState<Set<NodeJS.Timeout>>(() => new Set());
 
@@ -35,3 +35,39 @@ export function useUnmountAwareCallbacks() {
     setTimeout,
   };
 }
+
+/**
+ * Hook that provides a requestAnimationFrame which is aware of component unmount state.
+ * Any animation frames requested with this hook will be automatically canceled when the component unmounts.
+ */
+export function useUnmountAwareAnimationFrame() {
+  // Store active animation frame request IDs in a Set for more efficient add/remove operations
+  const [requestIds] = useState<Set<number>>(() => new Set());
+
+  // Cancel all animation frame requests on unmount
+  useEffect(() => {
+    return () => {
+      requestIds.forEach((id) => cancelAnimationFrame(id));
+      requestIds.clear();
+    };
+  }, [requestIds]);
+
+  // Create a safe requestAnimationFrame that will be canceled on unmount
+  const requestAnimationFrame = useCallback(
+    (callback: FrameRequestCallback): void => {
+      const id = global.requestAnimationFrame((timestamp) => {
+        // Remove this request ID from the tracking set
+        requestIds.delete(id);
+        callback(timestamp);
+      });
+
+      // Track this request ID
+      requestIds.add(id);
+    },
+    [requestIds]
+  );
+
+  return {
+    requestAnimationFrame,
+  };
+}

package/src/recyclerview/hooks/useUnmountFlag.ts

@@ -16,6 +16,7 @@ export const useUnmountFlag = () => {
   // Use layoutEffect to set up cleanup on unmount
   // This ensures the flag is set before any other cleanup effects run
   useLayoutEffect(() => {
+    isUnmounted.current = false;
     // Cleanup function that runs when the component unmounts
     return () => {
       isUnmounted.current = true;

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,18 +79,24 @@ 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 lastRowTallestItem = this.processAndReturnTallestItemInRow(
-      this.layouts.length - 1
-    );
+    const totalHeight = this.computeTotalHeightTillRow(this.layouts.length - 1);
     return {
       width: this.boundedSize,
-      height: lastRowTallestItem.y + lastRowTallestItem.height,
+      height: totalHeight,
     };
   }
 
@@ -93,7 +106,9 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
    * @param endIndex Ending index of items to recompute
    */
   recomputeLayouts(startIndex: number, endIndex: number): void {
-    const newStartIndex = this.locateFirstNeighbourIndex(startIndex);
+    const newStartIndex = this.locateFirstIndexInRow(
+      Math.max(0, startIndex - 1)
+    );
     const startVal = this.getLayout(newStartIndex);
 
     let startX = startVal.x;
@@ -102,7 +117,7 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     for (let i = newStartIndex; i <= endIndex; i++) {
       const layout = this.getLayout(i);
       if (!this.checkBounds(startX, layout.width)) {
-        const tallestItem = this.processAndReturnTallestItemInRow(i);
+        const tallestItem = this.processAndReturnTallestItemInRow(i - 1);
         startY = tallestItem.y + tallestItem.height;
         startX = 0;
       }
@@ -111,6 +126,9 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
       layout.y = startY;
       startX += layout.width;
     }
+    if (endIndex === this.layouts.length - 1) {
+      this.processAndReturnTallestItemInRow(endIndex);
+    }
   }
 
   /**
@@ -119,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);
@@ -153,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) {
@@ -167,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;
@@ -182,6 +200,32 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     return tallestItem;
   }
 
+  /**
+   * Computes the total height of the layout.
+   * @param endIndex Index of the last item in the row
+   * @returns Total height of the layout
+   */
+  private computeTotalHeightTillRow(endIndex: number): number {
+    const startIndex = this.locateFirstIndexInRow(endIndex);
+    const y = this.layouts[startIndex].y;
+    let maxHeight = 0;
+    let i = startIndex;
+    while (i <= endIndex) {
+      maxHeight = Math.max(maxHeight, this.layouts[i].height);
+      i++;
+      if (i >= this.layouts.length) {
+        break;
+      }
+    }
+    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
@@ -194,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 - 1;
+    let i = itemIndex;
     for (; i >= 0; i--) {
       if (this.layouts[i].x === 0) {
         break;

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

@@ -20,12 +20,8 @@ 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;
-  /** Optional callback to override default item layout */
-  protected overrideItemLayout?: (index: number, layout: SpanSizeInfo) => void;
 
   /** Whether to optimize item placement for better space utilization */
   protected optimizeItemArrangement: boolean;
@@ -33,19 +29,34 @@ export abstract class RVLayoutManager {
   /** Flag indicating if the layout requires repainting */
   public requiresRepaint = false;
 
+  /** Optional callback to override default item layout */
+  private overrideItemLayout: (index: number, layout: SpanSizeInfo) => void;
   /** Optional function to determine item type */
-  private _getItemType?: (index: number) => string | number;
+  private getItemType: (index: number) => string;
   /** Window for tracking average heights by item type */
   private heightAverageWindow: MultiTypeAverageWindow;
   /** Window for tracking average widths by item type */
   private widthAverageWindow: MultiTypeAverageWindow;
   /** Maximum number of items to process in a single layout pass */
-  private maxItemsToProcess = 250; // TODO: make this dynamic
+  private maxItemsToProcess = 250;
+  /** 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;
+
+  /**
+   * Last index that was skipped during layout computation.
+   * Used to determine if a layout needs to be recomputed.
+   */
+  private lastSkippedLayoutIndex = Number.MAX_VALUE;
 
   constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
     this.heightAverageWindow = new MultiTypeAverageWindow(5, 200);
     this.widthAverageWindow = new MultiTypeAverageWindow(5, 200);
-    this._getItemType = params.getItemType;
+    this.getItemType = params.getItemType;
     this.overrideItemLayout = params.overrideItemLayout;
     this.layouts = previousLayoutManager?.layouts ?? [];
     if (previousLayoutManager) {
@@ -57,15 +68,6 @@ export abstract class RVLayoutManager {
     }
   }
 
-  /**
-   * Gets the type of an item at the given index.
-   * @param index Index of the item
-   * @returns Item type or "default" if not specified
-   */
-  private getItemType(index: number): string | number {
-    return this._getItemType?.(index) ?? "default";
-  }
-
   /**
    * Gets the estimated width for an item based on its type.
    * @param index Index of the item
@@ -114,8 +116,8 @@ export abstract class RVLayoutManager {
   /**
    * Gets indices of items currently visible in the viewport.
    * Uses binary search for efficient lookup.
-   * @param unboundDimensionStart Start position of viewport
-   * @param unboundDimensionEnd End position of viewport
+   * @param unboundDimensionStart Start position of viewport (start X or start Y)
+   * @param unboundDimensionEnd End position of viewport (end X or end Y)
    * @returns ConsecutiveNumbers containing visible indices
    */
   getVisibleLayouts(
@@ -157,7 +159,7 @@ export abstract class RVLayoutManager {
     }
     const startIndex = Math.min(...indices);
     // Recompute layouts starting from the smallest index in the original indices array
-    this.recomputeLayouts(
+    this._recomputeLayouts(
       this.getMinRecomputeIndex(startIndex),
       this.getMaxRecomputeIndex(startIndex)
     );
@@ -169,41 +171,49 @@ export abstract class RVLayoutManager {
    * @param totalItemCount Total number of items in the list
    */
   modifyLayout(layoutInfo: RVLayoutInfo[], totalItemCount: number): void {
+    this.maxItemsToProcess = Math.max(
+      this.maxItemsToProcess,
+      layoutInfo.length * 10
+    );
     let minRecomputeIndex = Number.MAX_VALUE;
 
     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.lastSkippedLayoutIndex,
+      this.computeMinIndexWithChangedSpan(layoutInfo),
+      this.processLayoutInfo(layoutInfo, totalItemCount) ?? minRecomputeIndex,
+      this.computeEstimatesAndMinMaxChangedLayout(layoutInfo)
     );
+
     if (minRecomputeIndex >= 0 && minRecomputeIndex < totalItemCount) {
-      this.recomputeLayouts(
-        this.getMinRecomputeIndex(minRecomputeIndex),
-        this.getMaxRecomputeIndex(minRecomputeIndex)
-      );
+      const maxRecomputeIndex = this.getMaxRecomputeIndex(minRecomputeIndex);
+      this._recomputeLayouts(minRecomputeIndex, maxRecomputeIndex);
     }
+    this.currentMaxIndexWithChangedLayout = -1;
   }
 
   /**
@@ -269,16 +279,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;
+    this.overrideItemLayout(index, 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
@@ -286,7 +310,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
     );
   }
@@ -300,12 +325,36 @@ export abstract class RVLayoutManager {
     return startIndex;
   }
 
+  private _recomputeLayouts(startIndex: number, endIndex: number): void {
+    this.recomputeLayouts(startIndex, endIndex);
+    if (
+      this.lastSkippedLayoutIndex >= startIndex &&
+      this.lastSkippedLayoutIndex <= endIndex
+    ) {
+      this.lastSkippedLayoutIndex = Number.MAX_VALUE;
+    }
+
+    if (endIndex + 1 < this.layouts.length) {
+      this.lastSkippedLayoutIndex = Math.min(
+        endIndex + 1,
+        this.lastSkippedLayoutIndex
+      );
+      const lastIndex = this.layouts.length - 1;
+      // Since layout managers derive height from last indices we need to make
+      // sure they're not too much out of sync.
+      if (this.layouts[lastIndex].y < this.layouts[endIndex].y) {
+        this.recomputeLayouts(this.lastSkippedLayoutIndex, lastIndex);
+        this.lastSkippedLayoutIndex = Number.MAX_VALUE;
+      }
+    }
+  }
+
   /**
    * Computes size estimates and finds the minimum recompute index.
    * @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;
@@ -313,6 +362,7 @@ export abstract class RVLayoutManager {
       const { index, dimensions } = info;
       const storedLayout = this.layouts[index];
       if (
+        index >= this.lastSkippedLayoutIndex ||
         !storedLayout ||
         !storedLayout.isHeightMeasured ||
         !storedLayout.isWidthMeasured ||
@@ -320,6 +370,10 @@ export abstract class RVLayoutManager {
         areDimensionsNotEqual(storedLayout.width, dimensions.width)
       ) {
         minRecomputeIndex = Math.min(minRecomputeIndex, index);
+        this.currentMaxIndexWithChangedLayout = Math.max(
+          this.currentMaxIndexWithChangedLayout,
+          index
+        );
       }
       this.heightAverageWindow.addValue(
         dimensions.height,
@@ -332,6 +386,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;
+  }
 }
 
 /**
@@ -348,31 +417,31 @@ export interface LayoutParams {
    * Determines if the list scrolls horizontally (true) or vertically (false)
    * Affects how items are positioned and which dimension is used for scrolling
    */
-  horizontal?: boolean;
+  horizontal: boolean;
 
   /**
    * Maximum number of columns in a grid layout
    * Controls how many items can be placed side by side
    */
-  maxColumns?: number;
+  maxColumns: number;
 
   /**
    * When true, attempts to optimize item placement for better space utilization
    * May affect the ordering of items to minimize empty space
    */
-  optimizeItemArrangement?: boolean;
+  optimizeItemArrangement: boolean;
 
   /**
    * Callback to manually override layout properties for specific items
    * Allows custom control over span and size for individual items
    */
-  overrideItemLayout?: (index: number, layout: SpanSizeInfo) => void;
+  overrideItemLayout: (index: number, layout: SpanSizeInfo) => void;
 
   /**
    * Function to determine the type of an item at a specific index
    * Used for size estimation and optimization based on item types
    */
-  getItemType?: (index: number) => string | number;
+  getItemType: (index: number) => string;
 }
 
 /**