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

package/src/recyclerview/components/CompatView.ts

@@ -0,0 +1,9 @@
+import { View, Animated } from "react-native";
+
+/** Regular view component */
+export { View as CompatView };
+
+const AnimatedView = Animated.View;
+
+/** Animated view component for smooth animations */
+export { AnimatedView as CompatAnimatedView };

package/src/recyclerview/components/ScrollAnchor.tsx

@@ -0,0 +1,66 @@
+/**
+ * ScrollAnchor component provides a mechanism to programmatically scroll
+ * the list by manipulating an invisible anchor element's position.
+ * This helps us use ScrollView's maintainVisibleContentPosition property
+ * to adjust the scroll position of the list as the size of content changes without any glitches.
+ */
+
+import React, { useImperativeHandle, useMemo, useState } from "react";
+
+import { CompatView } from "./CompatView";
+
+/**
+ * Props for the ScrollAnchor component
+ */
+export interface ScrollAnchorProps {
+  /** Ref to access scroll anchor methods */
+  scrollAnchorRef: React.Ref<ScrollAnchorRef>;
+  horizontal: boolean;
+}
+
+/**
+ * Ref interface for ScrollAnchor component
+ */
+export interface ScrollAnchorRef {
+  /** Scrolls the list by the specified offset */
+  scrollBy: (offset: number) => void;
+}
+
+/**
+ * ScrollAnchor component that provides programmatic scrolling capabilities using maintainVisibleContentPosition property
+ * @param props - Component props
+ * @returns An invisible anchor element used for scrolling
+ */
+export function ScrollAnchor({
+  scrollAnchorRef,
+  horizontal,
+}: ScrollAnchorProps) {
+  const [scrollOffset, setScrollOffset] = useState(1000000); // TODO: Fix this value
+
+  // Expose scrollBy method through ref
+  useImperativeHandle(
+    scrollAnchorRef,
+    () => ({
+      scrollBy: (offset: number) => {
+        setScrollOffset((prev) => prev + offset);
+      },
+    }),
+    []
+  );
+
+  // Create an invisible anchor element that can be positioned
+  const anchor = useMemo(() => {
+    return (
+      <CompatView
+        style={{
+          position: "absolute",
+          height: 0,
+          top: horizontal ? 0 : scrollOffset,
+          left: horizontal ? scrollOffset : 0,
+        }}
+      />
+    );
+  }, [scrollOffset, horizontal]);
+
+  return anchor;
+}

package/src/recyclerview/components/StickyHeaders.tsx

@@ -0,0 +1,222 @@
+/**
+ * StickyHeaders component manages the sticky header behavior in a FlashList.
+ * It handles the animation and positioning of headers that should remain fixed
+ * at the top of the list while scrolling.
+ */
+
+import React, {
+  useRef,
+  useState,
+  useMemo,
+  useImperativeHandle,
+  useCallback,
+  useEffect,
+} from "react";
+import { Animated, NativeScrollEvent } from "react-native";
+
+import { FlashListProps } from "../..";
+import { RecyclerViewManager } from "../RecyclerViewManager";
+import { ViewHolder } from "../ViewHolder";
+
+import { CompatAnimatedView } from "./CompatView";
+
+/**
+ * Props for the StickyHeaders component
+ * @template TItem - The type of items in the list
+ */
+export interface StickyHeaderProps<TItem> {
+  /** Array of indices that should have sticky headers */
+  stickyHeaderIndices: number[];
+  /** The data array being rendered */
+  data: ReadonlyArray<TItem>;
+  /** Animated value tracking scroll position */
+  scrollY: Animated.Value;
+  /** Function to render each item */
+  renderItem: FlashListProps<TItem>["renderItem"];
+  /** Ref to access sticky header methods */
+  stickyHeaderRef: React.RefObject<StickyHeaderRef>;
+  /** Manager for recycler view operations */
+  recyclerViewManager: RecyclerViewManager<TItem>;
+  /** Additional data to trigger re-renders */
+  extraData: FlashListProps<TItem>["extraData"];
+}
+
+/**
+ * Ref interface for StickyHeaders component
+ */
+export interface StickyHeaderRef {
+  /** Reports scroll events to update sticky header positions */
+  reportScrollEvent: (event: NativeScrollEvent) => void;
+}
+
+interface StickyHeaderState {
+  currentStickyIndex: number;
+  pushStartsAt: number;
+}
+
+export const StickyHeaders = <TItem,>({
+  stickyHeaderIndices,
+  renderItem,
+  stickyHeaderRef,
+  recyclerViewManager,
+  scrollY,
+  data,
+  extraData,
+}: StickyHeaderProps<TItem>) => {
+  const [stickyHeaderState, setStickyHeaderState] = useState<StickyHeaderState>(
+    {
+      currentStickyIndex: -1,
+      pushStartsAt: Number.MAX_SAFE_INTEGER,
+    }
+  );
+
+  const { currentStickyIndex, pushStartsAt } = stickyHeaderState;
+
+  // sort indices and memoize compute
+  const sortedIndices = useMemo(() => {
+    return [...stickyHeaderIndices].sort((first, second) => first - second);
+  }, [stickyHeaderIndices]);
+
+  const legthInvalid =
+    sortedIndices.length === 0 ||
+    recyclerViewManager.getDataLength() <=
+      sortedIndices[sortedIndices.length - 1];
+
+  const compute = useCallback(() => {
+    if (legthInvalid) {
+      return;
+    }
+    const adjustedScrollOffset = recyclerViewManager.getLastScrollOffset();
+
+    // Binary search for current sticky index
+    const currentIndexInArray = findCurrentStickyIndex(
+      sortedIndices,
+      adjustedScrollOffset,
+      (index) => recyclerViewManager.getLayout(index).y
+    );
+
+    const newStickyIndex = sortedIndices[currentIndexInArray] ?? -1;
+    let newNextStickyIndex = sortedIndices[currentIndexInArray + 1] ?? -1;
+
+    if (newNextStickyIndex > recyclerViewManager.getEngagedIndices().endIndex) {
+      newNextStickyIndex = -1;
+    }
+
+    // To make sure header offset is 0 in the interpolate compute
+    const newNextStickyY =
+      newNextStickyIndex === -1
+        ? Number.MAX_SAFE_INTEGER
+        : (recyclerViewManager.tryGetLayout(newNextStickyIndex)?.y ?? 0) +
+          recyclerViewManager.firstItemOffset;
+    const newCurrentStickyHeight =
+      recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
+
+    const newPushStartsAt = newNextStickyY - newCurrentStickyHeight;
+
+    if (
+      newStickyIndex !== currentStickyIndex ||
+      newPushStartsAt !== pushStartsAt
+    ) {
+      setStickyHeaderState({
+        currentStickyIndex: newStickyIndex,
+        pushStartsAt: newPushStartsAt,
+      });
+    }
+  }, [
+    legthInvalid,
+    recyclerViewManager,
+    sortedIndices,
+    currentStickyIndex,
+    pushStartsAt,
+  ]);
+
+  useEffect(() => {
+    compute();
+  }, [compute]);
+
+  // Optimized scroll handler using binary search pattern
+  useImperativeHandle(
+    stickyHeaderRef,
+    () => ({
+      reportScrollEvent: () => {
+        compute();
+      },
+    }),
+    [compute]
+  );
+
+  const refHolder = useRef(new Map()).current;
+
+  const translateY = useMemo(() => {
+    const currentStickyHeight =
+      recyclerViewManager.tryGetLayout(currentStickyIndex)?.height ?? 0;
+
+    return scrollY.interpolate({
+      inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+      outputRange: [0, -currentStickyHeight],
+      extrapolate: "clamp",
+    });
+  }, [recyclerViewManager, currentStickyIndex, scrollY, pushStartsAt]);
+
+  // Memoize header content
+  const headerContent = useMemo(() => {
+    return (
+      <CompatAnimatedView
+        style={{
+          position: "absolute",
+          top: 0,
+          left: 0,
+          right: 0,
+          zIndex: 1,
+          transform: [{ translateY }],
+        }}
+      >
+        {currentStickyIndex !== -1 && currentStickyIndex < data.length ? (
+          <ViewHolder
+            index={currentStickyIndex}
+            item={data[currentStickyIndex]}
+            renderItem={renderItem}
+            layout={{ x: 0, y: 0, width: 0, height: 0 }}
+            refHolder={refHolder}
+            extraData={extraData}
+            trailingItem={null}
+            target="StickyHeader"
+          />
+        ) : null}
+      </CompatAnimatedView>
+    );
+  }, [translateY, currentStickyIndex, data, renderItem, refHolder, extraData]);
+
+  return headerContent;
+};
+
+/**
+ * Binary search utility to find the current sticky header index based on scroll position
+ * @param sortedIndices - Array of indices sorted by Y position
+ * @param adjustedValue - Current scroll position
+ * @param getY - Function to get Y position for an index
+ * @returns Index of the current sticky header
+ */
+function findCurrentStickyIndex(
+  sortedIndices: number[],
+  adjustedValue: number,
+  getY: (index: number) => number
+): number {
+  let left = 0;
+  let right = sortedIndices.length - 1;
+  let result = -1;
+
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const currentY = getY(sortedIndices[mid]);
+
+    if (currentY <= adjustedValue) {
+      result = mid;
+      left = mid + 1;
+    } else {
+      right = mid - 1;
+    }
+  }
+
+  return result;
+}

package/src/recyclerview/helpers/ConsecutiveNumbers.ts

@@ -0,0 +1,120 @@
+/**
+ * A simple wrapper for consecutive postive integer arrays
+ * Only stores start and end indices for faster computation as numbers are consecutive.
+ */
+export class ConsecutiveNumbers {
+  constructor(
+    public readonly startIndex: number,
+    public readonly endIndex: number
+  ) {}
+
+  static readonly EMPTY = new ConsecutiveNumbers(-1, -2);
+
+  /**
+   * Get the length of the array
+   */
+  get length(): number {
+    return Math.max(0, this.endIndex - this.startIndex + 1);
+  }
+
+  /**
+   * Get element at specified index
+   */
+  at(index: number): number {
+    return this.startIndex + index;
+  }
+
+  /**
+   * Check if two consecutive numbers are equal
+   */
+  equals(other: ConsecutiveNumbers): boolean {
+    return (
+      this.startIndex === other.startIndex && this.endIndex === other.endIndex
+    );
+  }
+
+  /**
+   * Converts the consecutive range to an actual array
+   * @returns An array containing all consecutive numbers
+   */
+  toArray(): number[] {
+    if (this.length === 0) {
+      return [];
+    }
+    const array = new Array(this.length);
+    for (let i = 0; i < this.length; i++) {
+      array[i] = this.startIndex + i;
+    }
+    return array;
+  }
+
+  /**
+   * Check if array includes a value
+   */
+  includes(value: number): boolean {
+    return value >= this.startIndex && value <= this.endIndex;
+  }
+
+  /**
+   * Get index of a value in the consecutive range
+   */
+  indexOf(value: number): number {
+    return this.includes(value) ? value - this.startIndex : -1;
+  }
+
+  findValue(
+    predicate: (
+      value: number,
+      index: number,
+      array: ConsecutiveNumbers
+    ) => boolean | undefined
+  ): number | undefined {
+    for (let i = 0; i < this.length; i++) {
+      const value = this.startIndex + i;
+      if (predicate(value, i, this)) {
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Tests whether all elements in the consecutive range pass the provided test function
+   * @param predicate A function that tests each element
+   * @returns true if all elements pass the test; otherwise, false
+   */
+  every(
+    predicate: (
+      value: number,
+      index: number,
+      array: ConsecutiveNumbers
+    ) => boolean | undefined
+  ): boolean {
+    for (let i = 0; i < this.length; i++) {
+      const value = this.startIndex + i;
+      if (!predicate(value, i, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Get a slice of the consecutive array
+   */
+  slice(start = 0, end = this.length): ConsecutiveNumbers {
+    const newStart = this.startIndex + start;
+    const newEnd = this.startIndex + Math.min(end, this.length) - 1;
+
+    return new ConsecutiveNumbers(newStart, Math.max(newStart - 1, newEnd));
+  }
+
+  /**
+   * Implement iterator to enable for...of
+   */
+  *[Symbol.iterator]() {
+    for (let i = this.startIndex; i <= this.endIndex; i++) {
+      yield i;
+    }
+  }
+}