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

package/src/recyclerview/ViewHolderCollection.tsx

@@ -0,0 +1,164 @@
+/**
+ * ViewHolderCollection is a container component that manages multiple ViewHolder instances.
+ * It handles the rendering of a collection of list items, manages layout updates,
+ * and coordinates with the RecyclerView context for layout changes.
+ */
+
+import React, { useEffect, useImperativeHandle, useLayoutEffect } from "react";
+import { ViewHolder, ViewHolderProps } from "./ViewHolder";
+import { RVDimension, RVLayout } from "./layout-managers/LayoutManager";
+import { FlashListProps } from "../FlashListProps";
+import { CompatView } from "./components/CompatView";
+import { useRecyclerViewContext } from "./RecyclerViewContextProvider";
+
+/**
+ * Props interface for the ViewHolderCollection component
+ * @template TItem - The type of items in the data array
+ */
+export interface ViewHolderCollectionProps<TItem> {
+  /** The data array to be rendered */
+  data: FlashListProps<TItem>["data"];
+  /** Map of indices to React keys for each rendered item */
+  renderStack: Map<number, string>;
+  /** Function to get layout information for a specific index */
+  getLayout: (index: number) => RVLayout;
+  /** Ref to control layout updates from parent components */
+  viewHolderCollectionRef: React.Ref<ViewHolderCollectionRef>;
+  /** Map to store refs for each ViewHolder instance */
+  refHolder: ViewHolderProps<TItem>["refHolder"];
+  /** Callback when any item's size changes */
+  onSizeChanged: ViewHolderProps<TItem>["onSizeChanged"];
+  /** Function to render each item */
+  renderItem: FlashListProps<TItem>["renderItem"];
+  /** Additional data passed to renderItem that can trigger re-renders */
+  extraData: any;
+  /** Function to get the container's layout dimensions */
+  getChildContainerLayout: () => RVDimension | undefined;
+  /** Callback after layout effects are committed */
+  onCommitLayoutEffect?: () => void;
+  /** Callback after effects are committed */
+  onCommitEffect?: () => void;
+  /** Optional custom component to wrap each item */
+  CellRendererComponent?: FlashListProps<TItem>["CellRendererComponent"];
+  /** Optional component to render between items */
+  ItemSeparatorComponent?: FlashListProps<TItem>["ItemSeparatorComponent"];
+  /** Whether the list is horizontal or vertical */
+  horizontal: FlashListProps<TItem>["horizontal"];
+}
+
+/**
+ * Ref interface for ViewHolderCollection that exposes methods to control layout updates
+ */
+export interface ViewHolderCollectionRef {
+  /** Forces a layout update by triggering a re-render */
+  commitLayout: () => void;
+}
+
+/**
+ * ViewHolderCollection component that manages the rendering of multiple ViewHolder instances
+ * and handles layout updates for the entire collection
+ * @template TItem - The type of items in the data array
+ */
+export const ViewHolderCollection = <TItem,>(
+  props: ViewHolderCollectionProps<TItem>
+) => {
+  const {
+    data,
+    renderStack,
+    getLayout,
+    refHolder,
+    onSizeChanged,
+    renderItem,
+    extraData,
+    viewHolderCollectionRef,
+    getChildContainerLayout,
+    onCommitLayoutEffect,
+    CellRendererComponent,
+    ItemSeparatorComponent,
+    onCommitEffect,
+    horizontal,
+  } = props;
+
+  const [renderId, setRenderId] = React.useState(0);
+
+  const containerLayout = getChildContainerLayout();
+
+  // TODO: guard againt precision issues
+  const fixedContainerSize = horizontal
+    ? containerLayout?.height
+    : containerLayout?.width;
+
+  const recyclerViewContext = useRecyclerViewContext();
+
+  useLayoutEffect(() => {
+    if (renderId > 0) {
+      // console.log(
+      //   "parent layout trigger due to child container size change",
+      //   fixedContainerSize
+      // );
+      recyclerViewContext?.layout();
+    }
+  }, [fixedContainerSize]);
+
+  useLayoutEffect(() => {
+    if (renderId > 0) {
+      onCommitLayoutEffect?.();
+    }
+  }, [renderId]);
+
+  useEffect(() => {
+    if (renderId > 0) {
+      onCommitEffect?.();
+    }
+  }, [renderId]);
+
+  // Expose forceUpdate through ref
+  useImperativeHandle(viewHolderCollectionRef, () => ({
+    commitLayout: () => {
+      // This will trigger a re-render of the component
+      setRenderId((prev) => prev + 1);
+    },
+  }));
+
+  const hasData = data && data.length > 0;
+
+  const containerStyle = {
+    width: horizontal ? containerLayout?.width : undefined,
+    height: containerLayout?.height,
+  };
+
+  return (
+    <CompatView
+      // TODO: Take care of web scroll bar here
+      style={hasData && containerStyle}
+    >
+      {containerLayout &&
+        hasData &&
+        Array.from(renderStack, ([index, reactKey]) => {
+          const item = data[index];
+          const trailingItem = ItemSeparatorComponent
+            ? data[index + 1]
+            : undefined;
+          return (
+            <ViewHolder
+              key={reactKey}
+              index={index}
+              item={item}
+              trailingItem={trailingItem}
+              layout={{
+                ...getLayout(index),
+              }}
+              refHolder={refHolder}
+              onSizeChanged={onSizeChanged}
+              target="Cell"
+              renderItem={renderItem}
+              extraData={extraData}
+              CellRendererComponent={CellRendererComponent}
+              ItemSeparatorComponent={ItemSeparatorComponent}
+              horizontal={horizontal}
+            />
+          );
+        })}
+    </CompatView>
+  );
+};

package/src/recyclerview/components/CompatScroller.ts

@@ -0,0 +1,9 @@
+import { ScrollView, Animated } from "react-native";
+
+const AnimatedScrollView = Animated.ScrollView;
+
+/** Regular scroll view component */
+export { ScrollView as CompatScroller };
+
+/** Animated scroll view component for smooth scrolling animations */
+export { AnimatedScrollView as CompatAnimatedScroller };

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,53 @@
+/**
+ * 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 { useImperativeHandle, useMemo, useState } from "react";
+import { CompatView } from "./CompatView";
+import React from "react";
+
+/**
+ * Props for the ScrollAnchor component
+ */
+export interface ScrollAnchorProps {
+  /** Ref to access scroll anchor methods */
+  scrollAnchorRef: React.Ref<ScrollAnchorRef>;
+}
+
+/**
+ * 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 }: 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: scrollOffset }}
+      />
+    );
+  }, [scrollOffset]);
+
+  return anchor;
+}

package/src/recyclerview/components/StickyHeaders.tsx

@@ -0,0 +1,210 @@
+/**
+ * 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 { CompatAnimatedView } from "./CompatView";
+import { RecyclerViewManager } from "../RecyclerViewManager";
+import { ViewHolder } from "../ViewHolder";
+
+/**
+ * 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: readonly 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;
+}
+
+export const StickyHeaders = <TItem,>({
+  stickyHeaderIndices,
+  renderItem,
+  stickyHeaderRef,
+  recyclerViewManager,
+  scrollY,
+  data,
+  extraData,
+}: StickyHeaderProps<TItem>) => {
+  const [stickyIndices, setStickyIndices] = useState<{
+    currentStickyIndex: number;
+    nextStickyIndex: number;
+  }>({ currentStickyIndex: -1, nextStickyIndex: -1 });
+
+  const { currentStickyIndex, nextStickyIndex } = stickyIndices;
+  const hasLayout = recyclerViewManager.hasLayout();
+
+  // Memoize sorted indices based on their Y positions
+  const sortedIndices = useMemo(() => {
+    if (!hasLayout) {
+      return [];
+    }
+    return stickyHeaderIndices.sort((a, b) => a - b);
+  }, [stickyHeaderIndices, recyclerViewManager, hasLayout]);
+
+  const compute = useCallback(() => {
+    const adjustedValue = recyclerViewManager.getLastScrollOffset();
+
+    // Binary search for current sticky index
+    const currentIndexInArray = findCurrentStickyIndex(
+      sortedIndices,
+      adjustedValue,
+      (index) => recyclerViewManager.getLayout(index).y
+    );
+
+    const newStickyIndex = sortedIndices[currentIndexInArray] ?? -1;
+    let newNextStickyIndex = sortedIndices[currentIndexInArray + 1] ?? -1;
+
+    if (newNextStickyIndex > recyclerViewManager.getEngagedIndices().endIndex) {
+      newNextStickyIndex = -1;
+    }
+
+    if (
+      newStickyIndex !== currentStickyIndex ||
+      newNextStickyIndex !== nextStickyIndex
+    ) {
+      setStickyIndices({
+        currentStickyIndex: newStickyIndex,
+        nextStickyIndex: newNextStickyIndex,
+      });
+    }
+  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, sortedIndices]);
+
+  useEffect(() => {
+    compute();
+  }, [compute]);
+
+  // Optimized scroll handler using binary search pattern
+  useImperativeHandle(
+    stickyHeaderRef,
+    () => ({
+      reportScrollEvent: () => {
+        compute();
+      },
+    }),
+    [
+      stickyHeaderIndices,
+      recyclerViewManager,
+      currentStickyIndex,
+      nextStickyIndex,
+    ]
+  );
+
+  const refHolder = useRef(new Map()).current;
+
+  // Memoize translateY calculation
+  const translateY = useMemo(() => {
+    if (currentStickyIndex === -1 || nextStickyIndex === -1) {
+      return scrollY.interpolate({
+        inputRange: [0, Infinity],
+        outputRange: [0, 0],
+        extrapolate: "clamp",
+      });
+    }
+
+    const currentLayout = recyclerViewManager.getLayout(currentStickyIndex);
+    const nextLayout = recyclerViewManager.getLayout(nextStickyIndex);
+
+    const pushStartsAt = nextLayout.y - currentLayout.height;
+
+    return scrollY.interpolate({
+      inputRange: [
+        pushStartsAt + recyclerViewManager.firstItemOffset,
+        nextLayout.y + recyclerViewManager.firstItemOffset,
+      ],
+      outputRange: [0, -currentLayout.height],
+      extrapolate: "clamp",
+    });
+  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, scrollY]);
+
+  // Memoize header content
+  const headerContent = useMemo(() => {
+    if (currentStickyIndex === -1) return null;
+
+    return (
+      <CompatAnimatedView
+        style={{
+          position: "absolute",
+          top: 0,
+          left: 0,
+          right: 0,
+          transform: [{ translateY }],
+        }}
+      >
+        <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"
+        />
+      </CompatAnimatedView>
+    );
+  }, [currentStickyIndex, data, renderItem, extraData, refHolder, translateY]);
+
+  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 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(0, -1);
+
+  /**
+   * 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;
+    }
+  }
+}