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

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

@@ -0,0 +1,493 @@
+// Interface of layout manager for app's listviews
+
+import { MultiTypeAverageWindow } from "../../utils/AverageWindow";
+import { ConsecutiveNumbers } from "../helpers/ConsecutiveNumbers";
+import {
+  findFirstVisibleIndex,
+  findLastVisibleIndex,
+} from "../utils/findVisibleIndex";
+import { areDimensionsNotEqual } from "../utils/measureLayout";
+
+/**
+ * Base abstract class for layout managers in the recycler view system.
+ * Provides common functionality for managing item layouts and dimensions.
+ * Supports both horizontal and vertical layouts with dynamic item sizing.
+ */
+export abstract class RVLayoutManager {
+  /** Whether the layout is horizontal (true) or vertical (false) */
+  protected horizontal: boolean;
+  /** Array of layout information for all items */
+  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;
+
+  /** Flag indicating if the layout requires repainting */
+  public requiresRepaint: boolean = false;
+
+  /** Optional function to determine item type */
+  private _getItemType?: (index: number) => string | number;
+  /** 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: number = 250; // TODO: make this dynamic
+
+  constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
+    this.heightAverageWindow = new MultiTypeAverageWindow(5, 200);
+    this.widthAverageWindow = new MultiTypeAverageWindow(5, 200);
+    this._getItemType = params.getItemType;
+    this.overrideItemLayout = params.overrideItemLayout;
+    this.layouts = previousLayoutManager?.layouts ?? [];
+    if (previousLayoutManager) {
+      this.updateLayoutParams(params);
+    } else {
+      this.horizontal = Boolean(params.horizontal);
+      this.windowSize = params.windowSize;
+      this.maxColumns = params.maxColumns ?? 1;
+    }
+  }
+
+  /**
+   * 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
+   * @returns Estimated width
+   */
+  protected getEstimatedWidth(index: number): number {
+    return this.widthAverageWindow.getCurrentValue(this.getItemType(index));
+  }
+
+  /**
+   * Gets the estimated height for an item based on its type.
+   * @param index Index of the item
+   * @returns Estimated height
+   */
+  protected getEstimatedHeight(index: number): number {
+    return this.heightAverageWindow.getCurrentValue(this.getItemType(index));
+  }
+
+  /**
+   * Abstract method to process layout information for items.
+   * @param layoutInfo Array of layout information for items
+   * @param itemCount Total number of items in the list
+   * @returns Index of first modified layout or void
+   */
+  protected abstract processLayoutInfo(
+    layoutInfo: RVLayoutInfo[],
+    itemCount: number
+  ): number | void;
+
+  /**
+   * Checks if the layout is horizontal.
+   * @returns True if horizontal, false if vertical
+   */
+  isHorizontal(): boolean {
+    return this.horizontal;
+  }
+
+  /**
+   * Gets the dimensions of the visible window.
+   * @returns Window dimensions
+   */
+  getWindowsSize(): RVDimension {
+    return this.windowSize;
+  }
+
+  /**
+   * 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
+   * @returns ConsecutiveNumbers containing visible indices
+   */
+  getVisibleLayouts(
+    unboundDimensionStart: number,
+    unboundDimensionEnd: number
+  ): ConsecutiveNumbers {
+    // Find the first visible index
+    const firstVisibleIndex = findFirstVisibleIndex(
+      this.layouts,
+      unboundDimensionStart,
+      this.horizontal
+    );
+
+    // Find the last visible index
+    const lastVisibleIndex = findLastVisibleIndex(
+      this.layouts,
+      unboundDimensionEnd,
+      this.horizontal
+    );
+
+    // Collect the indices in the range
+    if (firstVisibleIndex !== -1 && lastVisibleIndex !== -1) {
+      return new ConsecutiveNumbers(firstVisibleIndex, lastVisibleIndex);
+    }
+    return ConsecutiveNumbers.EMPTY;
+  }
+
+  /**
+   * Removes layout information for specified indices and recomputes layout.
+   * @param indices Array of indices to remove
+   */
+  deleteLayout(indices: number[]): void {
+    // Sort indices in descending order
+    indices.sort((num1, num2) => num2 - num1);
+
+    // Remove elements from the array
+    for (const index of indices) {
+      this.layouts.splice(index, 1);
+    }
+    const startIndex = Math.min(...indices);
+    // Recompute layouts starting from the smallest index in the original indices array
+    this.recomputeLayouts(
+      this.getMinRecomputeIndex(startIndex),
+      this.getMaxRecomputeIndex(startIndex)
+    );
+  }
+
+  /**
+   * Updates layout information for items and recomputes layout if necessary.
+   * @param layoutInfo Array of layout information for items (real measurements)
+   * @param totalItemCount Total number of items in the list
+   */
+  modifyLayout(layoutInfo: RVLayoutInfo[], totalItemCount: number): void {
+    let minRecomputeIndex = Number.MAX_VALUE;
+
+    if (this.layouts.length > totalItemCount) {
+      this.layouts.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)
+    );
+
+    if (this.layouts.length < totalItemCount && totalItemCount > 0) {
+      const startIndex = this.layouts.length;
+      this.layouts.length = totalItemCount;
+      for (let i = startIndex; i < totalItemCount; i++) {
+        this.getLayout(i);
+      }
+      this.recomputeLayouts(startIndex, totalItemCount - 1);
+    }
+    minRecomputeIndex = Math.min(
+      minRecomputeIndex,
+      this.processLayoutInfo(layoutInfo, totalItemCount) ?? minRecomputeIndex
+    );
+    // compute minRecomputeIndex
+    minRecomputeIndex = Math.min(
+      minRecomputeIndex,
+      this.computeEstimatesAndMinRecomputeIndex(layoutInfo)
+    );
+    if (minRecomputeIndex >= 0 && minRecomputeIndex < totalItemCount) {
+      this.recomputeLayouts(
+        this.getMinRecomputeIndex(minRecomputeIndex),
+        this.getMaxRecomputeIndex(minRecomputeIndex)
+      );
+    }
+  }
+
+  /**
+   * Gets layout information for an item at the given index.
+   * Creates and initializes a new layout if one doesn't exist.
+   * @param index Index of the item
+   * @returns Layout information for the item
+   */
+  getLayout(index: number): RVLayout {
+    if (index >= this.layouts.length) {
+      throw new Error("index out of bounds, not enough layouts");
+    }
+    let layout = this.layouts[index];
+    if (!layout) {
+      // Create new layout with estimated dimensions
+      layout = {
+        x: 0,
+        y: 0,
+        width: 0,
+        height: 0,
+      };
+      this.layouts[index] = layout;
+    }
+    if (!layout.isWidthMeasured || !layout.isHeightMeasured) {
+      this.estimateLayout(index);
+    }
+    return layout;
+  }
+
+  /**
+   * Updates layout parameters and triggers recomputation if necessary.
+   * @param params New layout parameters
+   */
+  updateLayoutParams(params: LayoutParams) {
+    this.windowSize = params.windowSize;
+    this.horizontal = params.horizontal ?? this.horizontal;
+    this.maxColumns = params.maxColumns ?? this.maxColumns;
+    this.optimizeItemArrangement =
+      params.optimizeItemArrangement ?? this.optimizeItemArrangement;
+  }
+
+  /**
+   * Abstract method to recompute layouts for items in the given range.
+   * @param startIndex Starting index of items to recompute
+   * @param endIndex Ending index of items to recompute
+   */
+  abstract recomputeLayouts(startIndex: number, endIndex: number): void;
+
+  /**
+   * Abstract method to get the total size of the layout area.
+   * @returns RVDimension containing width and height of the layout
+   */
+  abstract getLayoutSize(): RVDimension;
+
+  /**
+   * Abstract method to estimate layout dimensions for an item.
+   * @param index Index of the item to estimate layout for
+   */
+  protected abstract estimateLayout(index: number): void;
+
+  /**
+   * Gets span size information for an item, applying any overrides.
+   * @param index Index of the item
+   * @returns SpanSizeInfo for the item
+   */
+  protected getSpanSizeInfo(index: number): SpanSizeInfo {
+    this.spanSizeInfo.span = undefined;
+    this.overrideItemLayout?.(index, this.spanSizeInfo);
+    return this.spanSizeInfo;
+  }
+
+  /**
+   * Gets the maximum index to process in a single layout pass.
+   * @param startIndex Starting index
+   * @returns Maximum index to process
+   */
+  private getMaxRecomputeIndex(startIndex: number): number {
+    return Math.min(
+      startIndex + this.maxItemsToProcess,
+      this.layouts.length - 1
+    );
+  }
+
+  /**
+   * Gets the minimum index to process in a single layout pass.
+   * @param startIndex Starting index
+   * @returns Minimum index to process
+   */
+  private getMinRecomputeIndex(startIndex: number): number {
+    return startIndex;
+  }
+
+  /**
+   * 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(
+    layoutInfo: RVLayoutInfo[]
+  ): number {
+    let minRecomputeIndex = Number.MAX_VALUE;
+    for (const info of layoutInfo) {
+      const { index, dimensions } = info;
+      const storedLayout = this.layouts[index];
+      if (
+        !storedLayout.isHeightMeasured ||
+        !storedLayout.isWidthMeasured ||
+        areDimensionsNotEqual(storedLayout.height, dimensions.height) ||
+        areDimensionsNotEqual(storedLayout.width, dimensions.width)
+      ) {
+        minRecomputeIndex = Math.min(minRecomputeIndex, index);
+      }
+      this.heightAverageWindow.addValue(
+        dimensions.height,
+        this.getItemType(index)
+      );
+      this.widthAverageWindow.addValue(
+        dimensions.width,
+        this.getItemType(index)
+      );
+    }
+    return minRecomputeIndex;
+  }
+}
+
+/**
+ * Configuration parameters for the layout manager
+ */
+export interface LayoutParams {
+  /**
+   * The dimensions of the visible window/viewport that displays list items
+   * Used to determine which items are visible and need to be rendered
+   */
+  windowSize: RVDimension;
+
+  /**
+   * Determines if the list scrolls horizontally (true) or vertically (false)
+   * Affects how items are positioned and which dimension is used for scrolling
+   */
+  horizontal?: boolean;
+
+  /**
+   * Maximum number of columns in a grid layout
+   * Controls how many items can be placed side by side
+   */
+  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;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+}
+
+/**
+ * Information about an item's layout including its index and dimensions
+ * Used when updating layout information for specific items
+ */
+export interface RVLayoutInfo {
+  /**
+   * The index of the item in the data array
+   * Used to identify which item this layout information belongs to
+   */
+  index: number;
+
+  /**
+   * The width and height dimensions of the item
+   * Used to update the layout manager's knowledge of item sizes
+   */
+  dimensions: RVDimension;
+}
+
+/**
+ * Information about an item's span and size in a grid layout
+ * Used when overriding default layout behavior for specific items
+ */
+export interface SpanSizeInfo {
+  /**
+   * Number of columns/cells this item should span horizontally
+   * Used in grid layouts to allow items to take up multiple columns
+   */
+  span?: number;
+
+  /**
+   * Custom size value for the item
+   * Can be used to override the default size calculation
+   */
+  size?: number;
+}
+
+/**
+ * Complete layout information for a list item
+ * Extends RVDimension with positioning and constraint properties
+ * Used to position and size ViewHolder components in the list
+ */
+export interface RVLayout extends RVDimension {
+  /**
+   * X-coordinate (horizontal position) in pixels
+   * Used to position the item horizontally with absolute positioning
+   */
+  x: number;
+
+  /**
+   * Y-coordinate (vertical position) in pixels
+   * Used to position the item vertically with absolute positioning
+   */
+  y: number;
+
+  /**
+   * Indicates if the width has been measured from the actual rendered item
+   * When false, width may be an estimated value
+   */
+  isWidthMeasured?: boolean;
+
+  /**
+   * Indicates if the height has been measured from the actual rendered item
+   * When false, height may be an estimated value
+   */
+  isHeightMeasured?: boolean;
+
+  /**
+   * Minimum height constraint in pixels
+   * Applied to the ViewHolder's style to ensure item doesn't shrink below this value
+   */
+  minHeight?: number;
+
+  /**
+   * Minimum width constraint in pixels
+   * Applied to the ViewHolder's style to ensure item doesn't shrink below this value
+   */
+  minWidth?: number;
+
+  /**
+   * Maximum height constraint in pixels
+   * Applied to the ViewHolder's style to limit item's vertical growth
+   */
+  maxHeight?: number;
+
+  /**
+   * Maximum width constraint in pixels
+   * Applied to the ViewHolder's style to limit item's horizontal growth
+   */
+  maxWidth?: number;
+
+  /**
+   * When true, the width value is strictly enforced on the ViewHolder
+   * When false, the width is determined by content
+   */
+  enforcedWidth?: boolean;
+
+  /**
+   * When true, the height value is strictly enforced on the ViewHolder
+   * When false, the height is determined by content
+   */
+  enforcedHeight?: boolean;
+}
+
+/**
+ * Basic dimension interface representing width and height
+ * Used throughout the recycler view system to track item sizes
+ * and viewport dimensions
+ */
+export interface RVDimension {
+  /**
+   * Width in pixels
+   * Used for horizontal measurement and positioning
+   */
+  width: number;
+
+  /**
+   * Height in pixels
+   * Used for vertical measurement and positioning
+   */
+  height: number;
+}

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

@@ -0,0 +1,167 @@
+import { LayoutParams, RVDimension, RVLayoutInfo } from "./LayoutManager";
+import { RVLayout } from "./LayoutManager";
+import { RVLayoutManager } from "./LayoutManager";
+
+/**
+ * LinearLayoutManager implementation that arranges items in a single row or column.
+ * Supports both horizontal and vertical layouts with dynamic item sizing.
+ */
+export class RVLinearLayoutManagerImpl extends RVLayoutManager {
+  /** The bounded size (width for vertical, height for horizontal) */
+  private boundedSize: number;
+  /** Whether the bounded size has been set */
+  private hasSize: boolean = false;
+
+  /** Reference to the tallest item in the layout */
+  private tallestItem?: RVLayout;
+  /** Height of the tallest item */
+  private tallestItemHeight: number = 0;
+
+  constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
+    super(params, previousLayoutManager);
+    this.boundedSize = this.horizontal
+      ? params.windowSize.height
+      : params.windowSize.width;
+    this.hasSize = this.boundedSize > 0;
+  }
+
+  /**
+   * Updates layout parameters and triggers recomputation if necessary.
+   * @param params New layout parameters
+   */
+  updateLayoutParams(params: LayoutParams): void {
+    const prevHorizontal = this.horizontal;
+    super.updateLayoutParams(params);
+    const oldBoundedSize = this.boundedSize;
+    this.boundedSize = this.horizontal
+      ? params.windowSize.height
+      : params.windowSize.width;
+    if (
+      oldBoundedSize !== this.boundedSize ||
+      prevHorizontal !== this.horizontal
+    ) {
+      if (this.layouts.length > 0) {
+        //console.log("-----> recomputeLayouts", this.horizontal);
+        this.recomputeLayouts(0, this.layouts.length - 1);
+        this.requiresRepaint = true;
+      }
+    }
+  }
+
+  /**
+   * Processes layout information for items, updating their dimensions.
+   * For horizontal layouts, also normalizes heights of items.
+   * @param layoutInfo Array of layout information for items
+   * @param itemCount Total number of items in the list
+   */
+  processLayoutInfo(layoutInfo: RVLayoutInfo[], itemCount: number) {
+    // Update layout information
+    for (const info of layoutInfo) {
+      const { index, dimensions } = info;
+      const layout = this.layouts[index];
+      layout.width = this.horizontal ? dimensions.width : this.boundedSize;
+      layout.isHeightMeasured = true;
+      layout.isWidthMeasured = true;
+      layout.height = dimensions.height;
+    }
+
+    if (this.horizontal && !this.hasSize) {
+      this.normalizeLayoutHeights(layoutInfo);
+    }
+  }
+
+  /**
+   * Estimates layout dimensions for an item at the given index.
+   * @param index Index of the item to estimate layout for
+   */
+  estimateLayout(index: number) {
+    const layout = this.layouts[index];
+    layout.width = this.horizontal
+      ? this.getEstimatedWidth(index)
+      : this.boundedSize;
+    layout.height = this.getEstimatedHeight(index);
+    layout.isWidthMeasured = !this.horizontal;
+    layout.enforcedWidth = !this.horizontal;
+  }
+
+  /**
+   * 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 lastLayout = this.layouts[this.layouts.length - 1];
+    return {
+      width: this.horizontal
+        ? lastLayout.x + lastLayout.width
+        : this.boundedSize,
+      height: this.horizontal
+        ? this.tallestItem?.height ?? 0
+        : lastLayout.y + lastLayout.height,
+    };
+  }
+
+  /**
+   * Normalizes heights of items in horizontal layout to match the tallest item.
+   * @param layoutInfo Array of layout information for items
+   */
+  private normalizeLayoutHeights(layoutInfo: RVLayoutInfo[]) {
+    let newTallestItem: RVLayout | undefined;
+    for (const info of layoutInfo) {
+      const { index } = info;
+      const layout = this.layouts[index];
+      if (
+        layout.height > (layout.minHeight ?? 0) &&
+        layout.height > (newTallestItem?.height ?? 0)
+      ) {
+        newTallestItem = layout;
+      }
+    }
+    if (newTallestItem && newTallestItem.height !== this.tallestItemHeight) {
+      let targetMinHeight = newTallestItem.height;
+      if (newTallestItem.height < this.tallestItemHeight) {
+        this.requiresRepaint = true;
+        targetMinHeight = 0;
+      }
+      //set minHeight for all layouts
+      for (const layout of this.layouts) {
+        if (targetMinHeight > 0) {
+          layout.height = newTallestItem.height;
+        }
+        layout.minHeight = targetMinHeight;
+      }
+      newTallestItem.minHeight = 0;
+      this.tallestItem = newTallestItem;
+      this.tallestItemHeight = newTallestItem.height;
+    }
+  }
+
+  /**
+   * Recomputes layouts for items in the given range.
+   * Positions items sequentially based on layout direction.
+   * @param startIndex Starting index of items to recompute
+   * @param endIndex Ending index of items to recompute
+   */
+  recomputeLayouts(startIndex: number, endIndex: number): void {
+    for (let i = startIndex; i <= endIndex; i++) {
+      const layout = this.getLayout(i);
+
+      // Set positions based on whether this is the first item or not
+      if (i === 0) {
+        layout.x = 0;
+        layout.y = 0;
+      } else {
+        const prevLayout = this.getLayout(i - 1);
+        layout.x = this.horizontal ? prevLayout.x + prevLayout.width : 0;
+        layout.y = this.horizontal ? 0 : prevLayout.y + prevLayout.height;
+      }
+
+      // Set width for vertical layouts
+      if (!this.horizontal) {
+        layout.width = this.boundedSize;
+      } else if (this.hasSize) {
+        layout.minHeight = this.boundedSize;
+      }
+    }
+  }
+}