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

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

@@ -0,0 +1,301 @@
+import {
+  LayoutParams,
+  RVDimension,
+  RVLayout,
+  RVLayoutInfo,
+  RVLayoutManager,
+} from "./LayoutManager";
+
+/**
+ * MasonryLayoutManager implementation that arranges items in a masonry/pinterest-style layout.
+ * Items are placed in columns, with support for items spanning multiple columns.
+ * Can optimize item placement to minimize column height differences.
+ */
+export class RVMasonryLayoutManagerImpl extends RVLayoutManager {
+  /** The width of the bounded area for the masonry layout */
+  private boundedSize: number;
+  /** Array tracking the current height of each column */
+  private columnHeights: number[];
+  /** Current column index for sequential placement */
+  private currentColumn = 0;
+
+  constructor(params: LayoutParams, previousLayoutManager?: RVLayoutManager) {
+    super(params, previousLayoutManager);
+    this.boundedSize = params.windowSize.width;
+    this.optimizeItemArrangement = params.optimizeItemArrangement ?? false;
+    this.columnHeights = this.columnHeights ?? Array(this.maxColumns).fill(0);
+  }
+
+  /**
+   * Updates layout parameters and triggers recomputation if necessary.
+   * @param params New layout parameters
+   */
+  updateLayoutParams(params: LayoutParams) {
+    const prevMaxColumns = this.maxColumns;
+    const prevOptimizeItemArrangement = this.optimizeItemArrangement;
+    super.updateLayoutParams(params);
+    if (
+      this.boundedSize !== params.windowSize.width ||
+      prevMaxColumns !== params.maxColumns ||
+      prevOptimizeItemArrangement !== params.optimizeItemArrangement
+    ) {
+      this.boundedSize = params.windowSize.width;
+      if (this.layouts.length > 0) {
+        // 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.recomputeLayouts(0, this.layouts.length - 1);
+        this.requiresRepaint = true;
+      }
+    }
+  }
+
+  /**
+   * Processes layout information for items, updating their dimensions.
+   * @param layoutInfo Array of layout information for items (real measurements)
+   * @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.height = dimensions.height;
+      layout.isHeightMeasured = true;
+      layout.isWidthMeasured = true;
+      this.layouts[index] = layout;
+    }
+  }
+
+  /**
+   * Estimates layout dimensions for an item at the given index.
+   * Can be called by base class if estimate is required.
+   * @param index Index of the item to estimate layout for
+   */
+  estimateLayout(index: number) {
+    const layout = this.layouts[index];
+
+    // Set width based on columns and span
+    layout.width = this.getWidth(index);
+    layout.height = this.getEstimatedHeight(index);
+
+    layout.isWidthMeasured = true;
+    layout.enforcedWidth = 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 };
+
+    // Find the tallest column
+    const maxHeight = Math.max(...this.columnHeights);
+
+    return {
+      width: this.boundedSize,
+      height: maxHeight,
+    };
+  }
+
+  /**
+   * Recomputes layouts for items in the given range.
+   * Uses different placement strategies based on optimization settings.
+   * @param startIndex Starting index of items to recompute
+   * @param endIndex Ending index of items to recompute
+   */
+  recomputeLayouts(startIndex: number, endIndex: number): void {
+    // Reset column heights if starting from the beginning
+    if (startIndex === 0) {
+      this.columnHeights = Array(this.maxColumns).fill(0);
+      this.currentColumn = 0;
+    } else {
+      // Find the y-position of the first item to recompute
+      // and adjust column heights accordingly
+      this.updateColumnHeightsToIndex(startIndex);
+    }
+
+    const itemCount = this.layouts.length;
+
+    for (let i = startIndex; i < itemCount; i++) {
+      const layout = this.getLayout(i);
+      const span = this.getSpanSizeInfo(i).span ?? 1;
+
+      if (this.optimizeItemArrangement) {
+        if (span === 1) {
+          // For single column items, place in the shortest column
+          this.placeSingleColumnItem(layout);
+        } else {
+          // For multi-column items, find the best position
+          this.placeOptimizedMultiColumnItem(layout, span);
+        }
+      } else {
+        // No optimization - place items sequentially
+        this.placeItemSequentially(layout, span);
+      }
+    }
+  }
+
+  /**
+   * Calculates the width of an item based on its span.
+   * @param index Index of the item
+   * @returns Width of the item
+   */
+  private getWidth(index: number): number {
+    const span = this.getSpanSizeInfo(index).span ?? 1;
+    return (this.boundedSize / this.maxColumns) * span;
+  }
+
+  /**
+   * Places an item sequentially in the next available position.
+   * @param layout Layout information for the item
+   * @param span Number of columns the item spans
+   */
+  private placeItemSequentially(layout: RVLayout, span: number): void {
+    // Check if the item can fit in the current row
+    if (this.currentColumn + span > this.maxColumns) {
+      // Move to the next row
+      this.currentColumn = 0;
+    }
+
+    // Find the maximum height of the columns this item will span
+    let maxHeight = this.columnHeights[this.currentColumn];
+    for (
+      let col = this.currentColumn + 1;
+      col < this.currentColumn + span;
+      col++
+    ) {
+      if (col < this.maxColumns) {
+        maxHeight = Math.max(maxHeight, this.columnHeights[col]);
+      }
+    }
+
+    // Place the item
+    layout.x = (this.boundedSize / this.maxColumns) * this.currentColumn;
+    layout.y = maxHeight;
+
+    // Update column heights
+    for (let col = this.currentColumn; col < this.currentColumn + span; col++) {
+      if (col < this.maxColumns) {
+        this.columnHeights[col] = maxHeight + layout.height;
+      }
+    }
+
+    // Move to the next column
+    this.currentColumn += span;
+    if (this.currentColumn >= this.maxColumns) {
+      this.currentColumn = 0;
+    }
+  }
+
+  /**
+   * Places a single-column item in the shortest available column.
+   * @param layout Layout information for the item
+   */
+  private placeSingleColumnItem(layout: RVLayout): void {
+    // Find the shortest column
+    let shortestColumnIndex = 0;
+    let minHeight = this.columnHeights[0];
+
+    for (let i = 1; i < this.maxColumns; i++) {
+      if (this.columnHeights[i] < minHeight) {
+        minHeight = this.columnHeights[i];
+        shortestColumnIndex = i;
+      }
+    }
+
+    // Place the item in the shortest column
+    layout.x = (this.boundedSize / this.maxColumns) * shortestColumnIndex;
+    layout.y = this.columnHeights[shortestColumnIndex];
+
+    // Update the column height
+    this.columnHeights[shortestColumnIndex] += layout.height;
+  }
+
+  /**
+   * Places a multi-column item in the position that minimizes total column heights.
+   * @param layout Layout information for the item
+   * @param span Number of columns the item spans
+   */
+  private placeOptimizedMultiColumnItem(layout: RVLayout, span: number): void {
+    let bestStartColumn = 0;
+    let minTotalHeight = Number.MAX_VALUE;
+
+    // Try all possible positions
+    for (let startCol = 0; startCol <= this.maxColumns - span; startCol++) {
+      // Find the maximum height among the columns this item would span
+      let maxHeight = this.columnHeights[startCol];
+      for (let col = startCol + 1; col < startCol + span; col++) {
+        maxHeight = Math.max(maxHeight, this.columnHeights[col]);
+      }
+
+      // Calculate the total height after placing the item
+      let totalHeight = 0;
+      for (let col = 0; col < this.maxColumns; col++) {
+        if (col >= startCol && col < startCol + span) {
+          totalHeight += maxHeight + layout.height;
+        } else {
+          totalHeight += this.columnHeights[col];
+        }
+      }
+
+      // Update best position if this is better
+      if (totalHeight < minTotalHeight) {
+        minTotalHeight = totalHeight;
+        bestStartColumn = startCol;
+      }
+    }
+
+    // Place the item at the best position
+    const maxHeight = Math.max(
+      ...this.columnHeights.slice(bestStartColumn, bestStartColumn + span)
+    );
+    layout.x = (this.boundedSize / this.maxColumns) * bestStartColumn;
+    layout.y = maxHeight;
+
+    // Update column heights
+    for (let col = bestStartColumn; col < bestStartColumn + span; col++) {
+      this.columnHeights[col] = maxHeight + layout.height;
+    }
+  }
+
+  /**
+   * Updates column heights up to a given index by recalculating item positions.
+   * @param index Index to update column heights up to
+   */
+  private updateColumnHeightsToIndex(index: number): void {
+    // Reset column heights
+    this.columnHeights = Array(this.maxColumns).fill(0);
+    this.currentColumn = 0;
+
+    // Recalculate column heights up to the given index
+    for (let i = 0; i < index; i++) {
+      const layout = this.layouts[i];
+      const itemWidth = layout.width;
+      const columnWidth = this.boundedSize / this.maxColumns;
+      const span = Math.round(itemWidth / columnWidth);
+
+      // Find which columns this item spans
+      const startColumn = Math.round(layout.x / columnWidth);
+      const endColumn = Math.min(startColumn + span, this.maxColumns);
+
+      // Update column heights
+      for (let col = startColumn; col < endColumn; col++) {
+        this.columnHeights[col] = Math.max(
+          this.columnHeights[col],
+          layout.y + layout.height
+        );
+      }
+
+      // Update current column for non-optimized layout
+      if (!this.optimizeItemArrangement) {
+        this.currentColumn = (startColumn + span) % this.maxColumns;
+      }
+    }
+  }
+}

package/src/recyclerview/utils/adjustOffsetForRTL.ts

@@ -0,0 +1,17 @@
+/**
+ * Adjusts the scroll offset for Right-to-Left (RTL) layouts.
+ * offset it flipped when RTL is enabled.
+ * This function converts a left-to-right offset to its RTL equivalent.
+ *
+ * @param offset - The original scroll offset in LTR layout
+ * @param contentSize - The total size of the scrollable content
+ * @param windowSize - The size of the visible window/viewport
+ * @returns The adjusted offset for RTL layout
+ */
+export function adjustOffsetForRTL(
+  offset: number,
+  contentSize: number,
+  windowSize: number
+) {
+  return contentSize - offset - windowSize;
+}

package/src/recyclerview/utils/componentUtils.ts

@@ -0,0 +1,28 @@
+import React from "react";
+
+/**
+ * Helper function to handle both React components and React elements.
+ * This utility ensures proper rendering of components whether they are passed as
+ * component types or pre-rendered elements.
+ *
+ * @param component - Can be a React component type, React element, null, or undefined
+ * @returns A valid React element if the input is valid, null otherwise
+ *
+ * @example
+ * // With a component type
+ * getValidComponent(MyComponent)
+ *
+ * @example
+ * // With a pre-rendered element
+ * getValidComponent(<MyComponent />)
+ */
+export const getValidComponent = (
+  component: React.ComponentType | React.ReactElement | null | undefined
+): React.ReactElement | null => {
+  if (React.isValidElement(component)) {
+    return component;
+  } else if (typeof component === "function") {
+    return React.createElement(component);
+  }
+  return null;
+};

package/src/recyclerview/utils/findVisibleIndex.ts

@@ -0,0 +1,93 @@
+import { RVLayout } from "../layout-managers/LayoutManager";
+
+/**
+ * A helper function to perform binary search for the first or last visible index.
+ * This function efficiently finds items that are visible within a viewport by using
+ * a binary search algorithm on sorted layouts.
+ *
+ * @param layouts - The sorted array of RVLayout objects, sorted by either x or y position
+ * @param threshold - The threshold value to determine visibility (viewport boundary)
+ * @param isSortedByX - A boolean indicating if the array is sorted by x (true) or y (false)
+ * @param findFirst - A boolean indicating whether to find the first (true) or last (false) visible index
+ * @returns The index of the visible layout or -1 if none are visible
+ *
+ * @remarks
+ * The binary search implementation ensures O(log n) time complexity for finding visible items.
+ * The function assumes the layouts array is pre-sorted by the relevant dimension (x or y).
+ */
+function binarySearchVisibleIndex(
+  layouts: RVLayout[],
+  threshold: number,
+  isSortedByX: boolean,
+  findFirst: boolean
+): number {
+  let left = 0;
+  let right = layouts.length - 1;
+  let visibleIndex = -1;
+
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const layout = layouts[mid];
+
+    // Check visibility based on the sorting criteria
+    const position = isSortedByX ? layout.x : layout.y;
+    const size = isSortedByX ? layout.width : layout.height;
+
+    if (findFirst) {
+      // Logic for finding the first visible index
+      if (position >= threshold || position + size > threshold) {
+        // Potential visible index found, continue searching left for earlier visible items
+        visibleIndex = mid;
+        right = mid - 1;
+      } else {
+        // Search in the right half for visible items
+        left = mid + 1;
+      }
+    } else if (position <= threshold) {
+      // Potential visible index found, continue searching right for later visible items
+      visibleIndex = mid;
+      left = mid + 1;
+    } else {
+      // Search in the left half for visible items
+      right = mid - 1;
+    }
+  }
+
+  return visibleIndex;
+}
+
+/**
+ * Finds the first visible index in a sorted array of RVLayout objects.
+ * This is a wrapper around binarySearchVisibleIndex that specifically finds
+ * the first item that becomes visible in the viewport.
+ *
+ * @param layouts - The sorted array of RVLayout objects
+ * @param threshold - The threshold value to determine visibility
+ * @param isSortedByX - A boolean indicating if the array is sorted by x (true) or y (false)
+ * @returns The index of the first visible layout or -1 if none are visible
+ */
+export function findFirstVisibleIndex(
+  layouts: RVLayout[],
+  threshold: number,
+  isSortedByX: boolean
+): number {
+  return binarySearchVisibleIndex(layouts, threshold, isSortedByX, true);
+}
+
+/**
+ * Finds the last visible index in a sorted array of RVLayout objects.
+ * This is a wrapper around binarySearchVisibleIndex that specifically finds
+ * the last item that remains visible in the viewport.
+ *
+ * @param layouts - The sorted array of RVLayout objects
+ * @param threshold - The threshold value to determine visibility
+ * @param isSortedByX - A boolean indicating if the array is sorted by x (true) or y (false)
+ * @returns The index of the last visible layout or -1 if none are visible
+ */
+export function findLastVisibleIndex(
+  layouts: RVLayout[],
+  threshold: number,
+  isSortedByX: boolean
+): number {
+  return binarySearchVisibleIndex(layouts, threshold, isSortedByX, false);
+}

package/src/recyclerview/utils/measureLayout.ts

@@ -0,0 +1,128 @@
+import { PixelRatio, View } from "react-native";
+
+interface Layout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Measures the layout of a view relative to itselft.
+ * Using measure wasn't returing accurate values but this workaround does.
+ * Returns the x, y coordinates and dimensions of the view.
+ *
+ * @param view - The React Native View component to measure
+ * @returns An object containing x, y, width, and height measurements
+ */
+function measureLayout(view: View, oldLayout: Layout | undefined) {
+  // const layout = view.unstable_getBoundingClientRect();
+  // layout.width = roundOffPixel(layout.width);
+  // layout.height = roundOffPixel(layout.height);
+  // return layout;
+  return measureLayoutRelative(view, view, oldLayout);
+}
+
+/**
+ * Measures the layout of a view relative to another view.
+ * Useful for measuring positions relative to a specific reference view.
+ *
+ * @param view - The React Native View component to measure
+ * @param relativeTo - The reference view to measure against
+ * @returns An object containing x, y, width, and height measurements
+ */
+function measureLayoutRelative(
+  view: View,
+  relativeTo: View,
+  oldLayout: Layout | undefined
+) {
+  const layout = { x: 0, y: 0, width: 0, height: 0 };
+  view.measureLayout(relativeTo, (x, y, width, height) => {
+    layout.x = x;
+    layout.y = y;
+    layout.width = roundOffPixel(width);
+    layout.height = roundOffPixel(height);
+  });
+
+  if (oldLayout) {
+    if (areDimensionsEqual(layout.width, oldLayout.width)) {
+      layout.width = oldLayout.width;
+    }
+    if (areDimensionsEqual(layout.height, oldLayout.height)) {
+      layout.height = oldLayout.height;
+    }
+  }
+  return layout;
+}
+
+/**
+ * Checks if two dimension values are not equal, with a small tolerance.
+ * Used to handle floating-point precision issues in layout measurements.
+ *
+ * @param value1 - First dimension value to compare
+ * @param value2 - Second dimension value to compare
+ * @returns true if the values are significantly different, false otherwise
+ */
+export function areDimensionsNotEqual(value1: number, value2: number): boolean {
+  return !areDimensionsEqual(value1, value2);
+}
+
+/**
+ * Checks if two dimension values are equal, with a small tolerance.
+ * Used to handle floating-point precision issues in layout measurements.
+ *
+ * @param value1 - First dimension value to compare
+ * @param value2 - Second dimension value to compare
+ * @returns true if the values are approximately equal, false otherwise
+ */
+export function areDimensionsEqual(value1: number, value2: number): boolean {
+  return (
+    Math.abs(
+      PixelRatio.getPixelSizeForLayoutSize(value1) -
+        PixelRatio.getPixelSizeForLayoutSize(value2)
+    ) <= 1
+  );
+}
+
+export function roundOffPixel(value: number): number {
+  return PixelRatio.roundToNearestPixel(value);
+}
+
+/**
+ * Specific method for easier mocking
+ * Measures the layout of parent of RecyclerView
+ * Returns the x, y coordinates and dimensions of the view.
+ * @param view - The React Native View component to measure
+ * @returns An object containing x, y, width, and height measurements
+ */
+export function measureParentSize(view: View): Layout {
+  return measureLayout(view, undefined);
+}
+
+/**
+ * Specific method for easier mocking
+ * Measures the layout of child container of RecyclerView
+ * @param childContainerView
+ * @param parentView
+ * @returns
+ */
+export function measureFirstChildLayout(
+  childContainerView: View,
+  parentView: View
+): Layout {
+  return measureLayoutRelative(childContainerView, parentView, undefined);
+}
+
+/**
+ * Specific method for easier mocking
+ * Measures the layout of items of RecyclerView
+ * @param item
+ * @param oldLayout
+ * @returns
+ */
+export function measureItemLayout(
+  item: View,
+  oldLayout: Layout | undefined
+): Layout {
+  return measureLayout(item, oldLayout);
+}

package/src/recyclerview/utils/measureLayout.web.ts

@@ -0,0 +1,104 @@
+interface Layout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Gets scroll offsets from up to 3 parent elements
+ */
+function getScrollOffsets(element: Element, stopAt: Element) {
+  let scrollX = 0;
+  let scrollY = 0;
+  let currentElement: Element | null = element;
+  let depth = 0;
+
+  // Only check up to 3 parent elements
+  while (currentElement && currentElement !== stopAt && depth < 3) {
+    const htmlElement = currentElement as HTMLElement;
+    scrollX += htmlElement.scrollLeft ?? 0;
+    scrollY += htmlElement.scrollTop ?? 0;
+    currentElement = currentElement.parentElement;
+    depth++;
+  }
+
+  return { scrollX, scrollY };
+}
+
+/**
+ * Checks if two dimension values are not equal, with a small tolerance.
+ */
+export function areDimensionsNotEqual(value1: number, value2: number): boolean {
+  return !areDimensionsEqual(value1, value2);
+}
+
+/**
+ * Checks if two dimension values are equal, with a small tolerance.
+ */
+export function areDimensionsEqual(value1: number, value2: number): boolean {
+  return Math.abs(value1 - value2) <= 1;
+}
+
+export function roundOffPixel(value: number): number {
+  return value;
+}
+
+/**
+ * Measures the layout of parent of RecyclerView
+ */
+export function measureParentSize(view: Element): Layout {
+  return {
+    x: 0,
+    y: 0,
+    width: view.clientWidth,
+    height: view.clientHeight,
+  };
+}
+
+/**
+ * Measures the layout of child container of RecyclerView
+ */
+export function measureFirstChildLayout(
+  childContainerView: Element,
+  parentView: Element
+): Layout {
+  const childRect = childContainerView.getBoundingClientRect();
+  const parentRect = parentView.getBoundingClientRect();
+
+  // Get scroll offsets for child container (max 3 parents)
+  const scrollOffsets = getScrollOffsets(childContainerView, parentView);
+
+  return {
+    x: childRect.left - parentRect.left + scrollOffsets.scrollX,
+    y: childRect.top - parentRect.top + scrollOffsets.scrollY,
+    width: roundOffPixel(childRect.width),
+    height: roundOffPixel(childRect.height),
+  };
+}
+
+/**
+ * Measures the layout of items of RecyclerView
+ */
+export function measureItemLayout(
+  item: Element,
+  oldLayout: Layout | undefined
+): Layout {
+  const layout = {
+    x: 0,
+    y: 0,
+    width: item.clientWidth,
+    height: item.clientHeight,
+  };
+
+  if (oldLayout) {
+    if (areDimensionsEqual(layout.width, oldLayout.width)) {
+      layout.width = oldLayout.width;
+    }
+    if (areDimensionsEqual(layout.height, oldLayout.height)) {
+      layout.height = oldLayout.height;
+    }
+  }
+
+  return layout;
+}