@react-native-ohos/flash-list 1.8.3 → 2.1.1-rc.1

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

@@ -0,0 +1,171 @@
+import {
+  LayoutParams,
+  RVDimension,
+  RVLayoutInfo,
+  RVLayout,
+  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 = false;
+
+  /** Reference to the tallest item in the layout */
+  private tallestItem?: RVLayout;
+  /** Height of the tallest item */
+  private tallestItemHeight = 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 ?? this.boundedSize
+        : 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;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,323 @@
+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;
+
+  /** 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;
+    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
+        this.updateAllWidths();
+        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;
+    }
+
+    // TODO: Can be optimized
+    if (this.fullRelayoutRequired) {
+      this.updateAllWidths();
+      this.fullRelayoutRequired = false;
+      return 0;
+    }
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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 };
+
+    // 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);
+      // Skip tracking span because we're not changing widths
+      const span = this.getSpan(i, true);
+
+      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 {
+    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;
+    }
+  }
+
+  /**
+   * 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);
+}