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

package/src/recyclerview/hooks/useRecyclingState.ts

@@ -0,0 +1,67 @@
+import { useCallback, useMemo, useRef } from "react";
+
+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.
+ * Similar to useState, but automatically resets the state when specified dependencies change.
+ * This is particularly useful for managing state that needs to be reset when certain props or values change when items are recycled.
+ * This also avoids another setState call on recycling and helps with performance.
+ *
+ * @param initialState - The initial state value or a function that returns the initial state
+ * @param deps - Array of dependencies that trigger a state reset when changed
+ * @param onReset - Optional callback function that is called when the state is reset
+ * @returns A tuple containing:
+ *   - The current state value
+ *   - A setState function that works like useState's setState
+ */
+export function useRecyclingState<T>(
+  initialState: RecyclingStateInitialValue<T>,
+  deps: React.DependencyList,
+  onReset?: () => void
+): [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
+  const [_, setCounter] = useLayoutState(0);
+
+  // Reset state when dependencies change
+  useMemo(() => {
+    // Calculate initial value from function or direct value
+    const initialValue =
+      typeof initialState === "function"
+        ? (initialState as () => T)()
+        : initialState;
+    valueStore.current = initialValue;
+    // Call onReset callback if provided
+    onReset?.();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  /**
+   * 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: RecyclingStateSetter<T> = useCallback(
+    (newValue, skipParentLayout) => {
+      // Calculate next state value from function or direct value
+      const nextState =
+        typeof newValue === "function"
+          ? (newValue as (prevValue: T) => T)(valueStore.current!)
+          : newValue;
+
+      // Only update and trigger re-render if value has changed
+      if (nextState !== valueStore.current) {
+        valueStore.current = nextState;
+        setCounter((prev) => prev + 1, skipParentLayout);
+      }
+    },
+    [setCounter]
+  );
+
+  return [valueStore.current!, setStateProxy];
+}

package/src/recyclerview/hooks/useSecondaryProps.tsx

@@ -0,0 +1,124 @@
+import { Animated, RefreshControl } from "react-native";
+import React, { useMemo } from "react";
+
+import { RecyclerViewProps } from "../RecyclerViewProps";
+import { getValidComponent } from "../utils/componentUtils";
+import { CompatView } from "../components/CompatView";
+import { CompatAnimatedScroller } from "../components/CompatScroller";
+
+/**
+ * Hook that manages secondary props and components for the RecyclerView.
+ * This hook handles the creation and management of:
+ * 1. Pull-to-refresh functionality
+ * 2. Header and footer components
+ * 3. Empty state component
+ * 4. Custom scroll component with animation support
+ *
+ * @param props - The RecyclerViewProps containing all configuration options
+ * @returns An object containing:
+ *   - refreshControl: The pull-to-refresh control component
+ *   - renderHeader: The header component renderer
+ *   - renderFooter: The footer component renderer
+ *   - renderEmpty: The empty state component renderer
+ *   - CompatScrollView: The animated scroll component
+ */
+export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
+  const {
+    ListHeaderComponent,
+    ListHeaderComponentStyle,
+    ListFooterComponent,
+    ListFooterComponentStyle,
+    ListEmptyComponent,
+    renderScrollComponent,
+    refreshing,
+    progressViewOffset,
+    onRefresh,
+    data,
+    refreshControl: customRefreshControl,
+  } = props;
+
+  /**
+   * Creates the refresh control component if onRefresh is provided.
+   */
+  const refreshControl = useMemo(() => {
+    if (customRefreshControl) {
+      return customRefreshControl;
+    } else if (onRefresh) {
+      return (
+        <RefreshControl
+          refreshing={Boolean(refreshing)}
+          progressViewOffset={progressViewOffset}
+          onRefresh={onRefresh}
+        />
+      );
+    }
+    return undefined;
+  }, [onRefresh, refreshing, progressViewOffset, customRefreshControl]);
+
+  /**
+   * Creates the header component with optional styling.
+   */
+  const renderHeader = useMemo(() => {
+    if (!ListHeaderComponent) {
+      return null;
+    }
+    return (
+      <CompatView style={ListHeaderComponentStyle}>
+        {getValidComponent(ListHeaderComponent)}
+      </CompatView>
+    );
+  }, [ListHeaderComponent, ListHeaderComponentStyle]);
+
+  /**
+   * Creates the footer component with optional styling.
+   */
+  const renderFooter = useMemo(() => {
+    if (!ListFooterComponent) {
+      return null;
+    }
+    return (
+      <CompatView style={ListFooterComponentStyle}>
+        {getValidComponent(ListFooterComponent)}
+      </CompatView>
+    );
+  }, [ListFooterComponent, ListFooterComponentStyle]);
+
+  /**
+   * Creates the empty state component when there's no data.
+   * Only rendered when ListEmptyComponent is provided and data is empty.
+   */
+  const renderEmpty = useMemo(() => {
+    if (!ListEmptyComponent || (data && data.length > 0)) {
+      return null;
+    }
+    return getValidComponent(ListEmptyComponent);
+  }, [ListEmptyComponent, data]);
+
+  /**
+   * Creates an animated scroll component based on the provided renderScrollComponent.
+   * If no custom component is provided, uses the default CompatAnimatedScroller.
+   */
+  const CompatScrollView = useMemo(() => {
+    let scrollComponent = CompatAnimatedScroller;
+    if (typeof renderScrollComponent === "function") {
+      // Create a forwarded ref wrapper for the custom scroll component
+      const ForwardedScrollComponent = React.forwardRef((_props, ref) =>
+        (renderScrollComponent as any)({ ..._props, ref } as any)
+      );
+      ForwardedScrollComponent.displayName = "CustomScrollView";
+      scrollComponent = ForwardedScrollComponent as any;
+    } else if (renderScrollComponent) {
+      scrollComponent = renderScrollComponent;
+    }
+    // Wrap the scroll component with Animated.createAnimatedComponent
+    return Animated.createAnimatedComponent(scrollComponent);
+  }, [renderScrollComponent]);
+
+  return {
+    refreshControl,
+    renderHeader,
+    renderFooter,
+    renderEmpty,
+    CompatScrollView,
+  };
+}

package/src/recyclerview/hooks/useUnmountAwareCallbacks.ts

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * 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 useUnmountAwareTimeout() {
+  // Store active timeout IDs in a Set for more efficient add/remove operations
+  const [timeoutIds] = useState<Set<NodeJS.Timeout>>(() => new Set());
+
+  // Clear all timeouts on unmount
+  useEffect(() => {
+    return () => {
+      timeoutIds.forEach((id) => global.clearTimeout(id));
+      timeoutIds.clear();
+    };
+  }, [timeoutIds]);
+
+  // Create a safe setTimeout that will be cleared on unmount
+  const setTimeout = useCallback(
+    (callback: () => void, delay: number): void => {
+      const id = global.setTimeout(() => {
+        // Remove this timeout ID from the tracking set
+        timeoutIds.delete(id);
+        callback();
+      }, delay);
+
+      // Track this timeout ID
+      timeoutIds.add(id);
+    },
+    [timeoutIds]
+  );
+
+  return {
+    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

@@ -0,0 +1,27 @@
+import { useRef, useLayoutEffect } from "react";
+
+/**
+ * Hook that provides a way to track component unmounting state.
+ * This hook is particularly useful for preventing state updates or side effects
+ * after a component has unmounted, helping to avoid memory leaks and race conditions.
+ *
+ * @returns A ref containing a boolean flag that indicates whether the component is unmounted
+ *         (true) or mounted (false)
+ */
+export const useUnmountFlag = () => {
+  // Create a ref to store the unmount state
+  // Using ref ensures the value persists between renders without causing re-renders
+  const isUnmounted = useRef(false);
+
+  // 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;
+    };
+  }, []);
+
+  return isUnmounted;
+};

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

@@ -0,0 +1,256 @@
+import {
+  LayoutParams,
+  RVDimension,
+  RVLayout,
+  RVLayoutInfo,
+  RVLayoutManager,
+} from "./LayoutManager";
+
+/**
+ * GridLayoutManager implementation that arranges items in a grid pattern.
+ * Items are placed in rows and columns, with support for items spanning multiple columns.
+ */
+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;
+  }
+
+  /**
+   * Updates layout parameters and triggers recomputation if necessary.
+   * @param params New layout parameters
+   */
+  updateLayoutParams(params: LayoutParams): void {
+    const prevNumColumns = this.maxColumns;
+    super.updateLayoutParams(params);
+    if (
+      this.boundedSize !== params.windowSize.width ||
+      prevNumColumns !== params.maxColumns
+    ) {
+      this.boundedSize = params.windowSize.width;
+      if (this.layouts.length > 0) {
+        // 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
+   * @param itemCount Total number of items in the list
+   */
+  processLayoutInfo(layoutInfo: RVLayoutInfo[], itemCount: number) {
+    for (const info of layoutInfo) {
+      const { index, dimensions } = info;
+      const layout = this.layouts[index];
+      layout.height = dimensions.height;
+      layout.isHeightMeasured = true;
+      layout.isWidthMeasured = true;
+    }
+
+    // TODO: Can be optimized
+    if (this.fullRelayoutRequired) {
+      this.updateAllWidths();
+      this.fullRelayoutRequired = false;
+      return 0;
+    }
+  }
+
+  /**
+   * 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.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 };
+    const totalHeight = this.computeTotalHeightTillRow(this.layouts.length - 1);
+    return {
+      width: this.boundedSize,
+      height: totalHeight,
+    };
+  }
+
+  /**
+   * Recomputes layouts for items in the given range.
+   * @param startIndex Starting index of items to recompute
+   * @param endIndex Ending index of items to recompute
+   */
+  recomputeLayouts(startIndex: number, endIndex: number): void {
+    const newStartIndex = this.locateFirstIndexInRow(
+      Math.max(0, startIndex - 1)
+    );
+    const startVal = this.getLayout(newStartIndex);
+
+    let startX = startVal.x;
+    let startY = startVal.y;
+
+    for (let i = newStartIndex; i <= endIndex; i++) {
+      const layout = this.getLayout(i);
+      if (!this.checkBounds(startX, layout.width)) {
+        const tallestItem = this.processAndReturnTallestItemInRow(i - 1);
+        startY = tallestItem.y + tallestItem.height;
+        startX = 0;
+      }
+
+      layout.x = startX;
+      layout.y = startY;
+      startX += layout.width;
+    }
+    if (endIndex === this.layouts.length - 1) {
+      this.processAndReturnTallestItemInRow(endIndex);
+    }
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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 endIndex Index of the last item in the row
+   * @returns The tallest item in the row
+   */
+  private processAndReturnTallestItemInRow(endIndex: number): RVLayout {
+    const startIndex = this.locateFirstIndexInRow(endIndex);
+    let tallestItem: RVLayout | undefined;
+    let maxHeight = 0;
+    let i = startIndex;
+    let isMeasured = false;
+    while (i <= endIndex) {
+      const layout = this.layouts[i];
+      isMeasured = isMeasured || Boolean(layout.isHeightMeasured);
+      maxHeight = Math.max(maxHeight, layout.height);
+      if (
+        layout.height > (layout.minHeight ?? 0) &&
+        layout.height > (tallestItem?.height ?? 0)
+      ) {
+        tallestItem = layout;
+      }
+
+      i++;
+      if (i >= this.layouts.length) {
+        break;
+      }
+    }
+    if (!tallestItem && maxHeight > 0) {
+      maxHeight = Number.MAX_SAFE_INTEGER;
+    }
+    tallestItem = tallestItem ?? this.layouts[startIndex];
+
+    if (!isMeasured) {
+      return tallestItem;
+    }
+
+    if (tallestItem) {
+      let targetHeight = tallestItem.height;
+      if (maxHeight - tallestItem.height > 1) {
+        targetHeight = 0;
+        this.requiresRepaint = true;
+      }
+      i = startIndex;
+      while (i <= endIndex) {
+        this.layouts[i].minHeight = targetHeight;
+        if (targetHeight > 0) {
+          this.layouts[i].height = targetHeight;
+        }
+        i++;
+        if (i >= this.layouts.length) {
+          break;
+        }
+      }
+      tallestItem.minHeight = 0;
+    }
+    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
+   * @param width Width of the item
+   * @returns True if the item fits within bounds
+   */
+  private checkBounds(itemX: number, width: number): boolean {
+    return itemX + width <= this.boundedSize + 0.9;
+  }
+
+  /**
+   * Locates the index of the first item in the current row.
+   * @param itemIndex Index to start searching from
+   * @returns Index of the first item in the row
+   */
+  private locateFirstIndexInRow(itemIndex: number): number {
+    if (itemIndex === 0) {
+      return 0;
+    }
+    let i = itemIndex;
+    for (; i >= 0; i--) {
+      if (this.layouts[i].x === 0) {
+        break;
+      }
+    }
+    return Math.max(i, 0);
+  }
+}