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

package/src/recyclerview/RecyclerView.tsx

@@ -19,11 +19,14 @@ import {
   NativeSyntheticEvent,
 } from "react-native";
 
+import { FlashListRef } from "../FlashListRef";
+
 import { RVDimension } from "./layout-managers/LayoutManager";
 import {
   areDimensionsNotEqual,
-  measureLayout,
-  measureLayoutRelative,
+  measureFirstChildLayout,
+  measureItemLayout,
+  measureParentSize,
 } from "./utils/measureLayout";
 import {
   RecyclerViewContext,
@@ -46,6 +49,7 @@ import { useSecondaryProps } from "./hooks/useSecondaryProps";
 import { StickyHeaders, StickyHeaderRef } from "./components/StickyHeaders";
 import { ScrollAnchor, ScrollAnchorRef } from "./components/ScrollAnchor";
 import { useRecyclerViewController } from "./hooks/useRecyclerViewController";
+import { RenderTimeTracker } from "./helpers/RenderTimeTracker";
 
 /**
  * Main RecyclerView component that handles list rendering, scrolling, and item recycling.
@@ -53,7 +57,7 @@ import { useRecyclerViewController } from "./hooks/useRecyclerViewController";
  */
 const RecyclerViewComponent = <T,>(
   props: RecyclerViewProps<T>,
-  ref: React.Ref<any>
+  ref: React.Ref<FlashListRef<T>>
 ) => {
   // Destructure props and initialize refs
   const {
@@ -74,8 +78,6 @@ const RecyclerViewComponent = <T,>(
     ListFooterComponentStyle,
     ItemSeparatorComponent,
     renderScrollComponent,
-    onScroll,
-    disableRecycling,
     style,
     stickyHeaderIndices,
     maintainVisibleContentPosition,
@@ -83,10 +85,14 @@ const RecyclerViewComponent = <T,>(
     ...rest
   } = props;
 
+  const [renderTimeTracker] = useState(() => new RenderTimeTracker());
+
+  renderTimeTracker.startTracking();
+
   // Core refs for managing scroll view, internal view, and child container
   const scrollViewRef = useRef<CompatScroller>(null);
   const internalViewRef = useRef<CompatView>(null);
-  const childContainerViewRef = useRef<CompatView>(null);
+  const firstChildViewRef = useRef<CompatView>(null);
   const containerViewSizeRef = useRef<RVDimension | undefined>(undefined);
   const pendingChildIds = useRef<Set<string>>(new Set()).current;
 
@@ -108,15 +114,19 @@ const RecyclerViewComponent = <T,>(
   );
 
   // Initialize core RecyclerView manager and content offset management
-  const { recyclerViewManager } = useRecyclerViewManager(props);
-  const { applyContentOffset, applyInitialScrollIndex } =
-    useRecyclerViewController(
-      recyclerViewManager,
-      ref,
-      scrollViewRef,
-      scrollAnchorRef,
-      props
-    );
+  const { recyclerViewManager, velocityTracker } =
+    useRecyclerViewManager(props);
+  const {
+    applyOffsetCorrection,
+    computeFirstVisibleIndexForOffsetCorrection,
+    applyInitialScrollIndex,
+    handlerMethods,
+  } = useRecyclerViewController(
+    recyclerViewManager,
+    ref,
+    scrollViewRef,
+    scrollAnchorRef
+  );
 
   // Initialize view holder collection ref
   const viewHolderCollectionRef = useRef<ViewHolderCollectionRef>(null);
@@ -125,40 +135,44 @@ const RecyclerViewComponent = <T,>(
   useOnListLoad(recyclerViewManager, onLoad);
 
   // Hook to detect when scrolling reaches list bounds
-  const { checkBounds } = useBoundDetection(
-    recyclerViewManager,
-    props,
-    scrollViewRef
-  );
+  const { checkBounds } = useBoundDetection(recyclerViewManager, scrollViewRef);
+
+  const isHorizontalRTL = I18nManager.isRTL && horizontal;
 
   /**
    * Initialize the RecyclerView by measuring and setting up the window size
    * This effect runs when the component mounts or when layout changes
    */
   useLayoutEffect(() => {
-    if (internalViewRef.current && childContainerViewRef.current) {
+    if (internalViewRef.current && firstChildViewRef.current) {
       // Measure the outer and inner container layouts
-      const outerViewLayout = measureLayout(internalViewRef.current, undefined);
-      const childViewLayout = measureLayoutRelative(
-        childContainerViewRef.current,
-        internalViewRef.current,
-        undefined
+      const outerViewLayout = measureParentSize(internalViewRef.current);
+      const firstChildViewLayout = measureFirstChildLayout(
+        firstChildViewRef.current,
+        internalViewRef.current
       );
 
       containerViewSizeRef.current = outerViewLayout;
 
       // Calculate offset of first item
       const firstItemOffset = horizontal
-        ? childViewLayout.x - outerViewLayout.x
-        : childViewLayout.y - outerViewLayout.y;
+        ? firstChildViewLayout.x - outerViewLayout.x
+        : firstChildViewLayout.y - outerViewLayout.y;
 
       // Update the RecyclerView manager with window dimensions
       recyclerViewManager.updateLayoutParams(
         {
-          width: horizontal ? outerViewLayout.width : childViewLayout.width,
-          height: horizontal ? childViewLayout.height : outerViewLayout.height,
+          width: horizontal
+            ? outerViewLayout.width
+            : firstChildViewLayout.width,
+          height: horizontal
+            ? firstChildViewLayout.height
+            : outerViewLayout.height,
         },
-        firstItemOffset
+        isHorizontalRTL && recyclerViewManager.hasLayout()
+          ? firstItemOffset -
+              recyclerViewManager.getChildContainerDimensions().width
+          : firstItemOffset
       );
     }
   });
@@ -167,18 +181,19 @@ const RecyclerViewComponent = <T,>(
    * Effect to handle layout updates for list items
    * This ensures proper positioning and recycling of items
    */
+  // eslint-disable-next-line react-hooks/exhaustive-deps
   useLayoutEffect(() => {
     if (pendingChildIds.size > 0) {
       return;
     }
     const layoutInfo = Array.from(refHolder, ([index, viewHolderRef]) => {
-      const layout = measureLayout(
+      const layout = measureItemLayout(
         viewHolderRef.current!,
-        recyclerViewManager.getLayout(index)
+        recyclerViewManager.tryGetLayout(index)
       );
 
-      //comapre height with stored layout
-      //const storedLayout = recyclerViewManager.getLayout(index);
+      // comapre height with stored layout
+      // const storedLayout = recyclerViewManager.getLayout(index);
       // if (
       //   storedLayout.height !== layout.height &&
       //   storedLayout.isHeightMeasured
@@ -199,10 +214,8 @@ const RecyclerViewComponent = <T,>(
       // Trigger re-render if layout modifications were made
       setRenderId((prev) => prev + 1);
     } else {
-      //console.log("commitLayout");
-      // TODO: reduce perf impact of commitLayout
       viewHolderCollectionRef.current?.commitLayout();
-      applyContentOffset();
+      applyOffsetCorrection();
     }
   });
 
@@ -211,30 +224,45 @@ const RecyclerViewComponent = <T,>(
    */
   const onScrollHandler = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-      let velocity = event.nativeEvent.velocity;
+      if (recyclerViewManager.ignoreScrollEvents) {
+        return;
+      }
+
       let scrollOffset = horizontal
         ? event.nativeEvent.contentOffset.x
         : event.nativeEvent.contentOffset.y;
 
       // Handle RTL (Right-to-Left) layout adjustments
-      if (I18nManager.isRTL && horizontal) {
+      if (isHorizontalRTL) {
         scrollOffset = adjustOffsetForRTL(
           scrollOffset,
           event.nativeEvent.contentSize.width,
           event.nativeEvent.layoutMeasurement.width
         );
-        if (velocity) {
-          velocity = {
-            x: -velocity.x,
-            y: velocity.y,
-          };
-        }
       }
 
-      // Update scroll position and trigger re-render if needed
-      if (recyclerViewManager.updateScrollOffset(scrollOffset, velocity)) {
-        setRenderId((prev) => prev + 1);
-      }
+      velocityTracker.computeVelocity(
+        scrollOffset,
+        recyclerViewManager.getAbsoluteLastScrollOffset(),
+        Boolean(horizontal),
+        (velocity, isMomentumEnd) => {
+          if (recyclerViewManager.ignoreScrollEvents) {
+            return;
+          }
+
+          if (isMomentumEnd) {
+            computeFirstVisibleIndexForOffsetCorrection();
+            if (!recyclerViewManager.isOffsetProjectionEnabled) {
+              return;
+            }
+            recyclerViewManager.resetVelocityCompute();
+          }
+          // Update scroll position and trigger re-render if needed
+          if (recyclerViewManager.updateScrollOffset(scrollOffset, velocity)) {
+            setRenderId((prev) => prev + 1);
+          }
+        }
+      );
 
       // Update sticky headers and check bounds
       stickyHeaderRef.current?.reportScrollEvent(event.nativeEvent);
@@ -245,22 +273,41 @@ const RecyclerViewComponent = <T,>(
       recyclerViewManager.computeItemViewability();
 
       // Call user-provided onScroll handler
-      onScroll?.(event);
+      recyclerViewManager.props.onScroll?.(event);
     },
-    [horizontal, recyclerViewManager]
+    [
+      checkBounds,
+      computeFirstVisibleIndexForOffsetCorrection,
+      horizontal,
+      isHorizontalRTL,
+      recyclerViewManager,
+      velocityTracker,
+    ]
   );
 
+  const parentRecyclerViewContext = useRecyclerViewContext();
+  const recyclerViewId = useId();
+
   // Create context for child components
-  const recyclerViewContext: RecyclerViewContext = useMemo(() => {
+  const recyclerViewContext: RecyclerViewContext<T> = useMemo(() => {
     return {
       layout: () => {
         setLayoutTreeId((prev) => prev + 1);
       },
       getRef: () => {
-        return ref;
+        if (recyclerViewManager.isDisposed) {
+          return null;
+        }
+        return handlerMethods;
+      },
+      getParentRef: () => {
+        return parentRecyclerViewContext?.getRef() ?? null;
+      },
+      getParentScrollViewRef: () => {
+        return parentRecyclerViewContext?.getScrollViewRef() ?? null;
       },
       getScrollViewRef: () => {
-        return scrollViewRef;
+        return scrollViewRef.current;
       },
       markChildLayoutAsPending: (id: string) => {
         pendingChildIds.add(id);
@@ -272,10 +319,13 @@ const RecyclerViewComponent = <T,>(
         }
       },
     };
-  }, [setLayoutTreeId]);
-
-  const parentRecyclerViewContext = useRecyclerViewContext();
-  const recyclerViewId = useId();
+  }, [
+    handlerMethods,
+    parentRecyclerViewContext,
+    pendingChildIds,
+    recyclerViewManager.isDisposed,
+    setLayoutTreeId,
+  ]);
 
   /**
    * Validates that item dimensions match the expected layout
@@ -307,7 +357,7 @@ const RecyclerViewComponent = <T,>(
         recyclerViewContext.layout();
       }
     },
-    [recyclerViewManager]
+    [recyclerViewContext, recyclerViewManager]
   );
 
   // Get secondary props and components
@@ -347,7 +397,14 @@ const RecyclerViewComponent = <T,>(
       );
     }
     return null;
-  }, [data, stickyHeaderIndices, renderItem, extraData]);
+  }, [
+    data,
+    stickyHeaderIndices,
+    renderItem,
+    scrollY,
+    recyclerViewManager,
+    extraData,
+  ]);
 
   // Set up scroll event handling with animation support for sticky headers
   const animatedEvent = useMemo(() => {
@@ -358,31 +415,24 @@ const RecyclerViewComponent = <T,>(
       );
     }
     return onScrollHandler;
-  }, [onScrollHandler, stickyHeaders]);
+  }, [onScrollHandler, scrollY, stickyHeaders]);
+
+  const shouldMaintainVisibleContentPosition =
+    recyclerViewManager.shouldMaintainVisibleContentPosition();
 
   const maintainVisibleContentPositionInternal = useMemo(() => {
-    if (maintainVisibleContentPosition?.disabled || horizontal) {
-      return undefined;
-    } else {
+    if (shouldMaintainVisibleContentPosition) {
       return {
         ...maintainVisibleContentPosition,
         minIndexForVisible: 0,
       };
     }
-  }, [maintainVisibleContentPosition]);
+    return undefined;
+  }, [maintainVisibleContentPosition, shouldMaintainVisibleContentPosition]);
 
   const shouldRenderFromBottom =
-    maintainVisibleContentPositionInternal?.startRenderingFromBottom ?? false;
-
-  // Calculate minimum height adjustment for bottom rendering
-  const adjustmentMinHeight = recyclerViewManager.hasLayout()
-    ? Math.max(
-        0,
-        recyclerViewManager.getWindowSize().height -
-          recyclerViewManager.getChildContainerDimensions().height -
-          recyclerViewManager.firstItemOffset
-      )
-    : 0;
+    recyclerViewManager.getDataLength() > 0 &&
+    (maintainVisibleContentPosition?.startRenderingFromBottom ?? false);
 
   // Create view for measuring bounded size
   const viewToMeasureBoundedSize = useMemo(() => {
@@ -391,20 +441,35 @@ const RecyclerViewComponent = <T,>(
         style={{
           height: horizontal ? undefined : 0,
           width: horizontal ? 0 : undefined,
-          minHeight: shouldRenderFromBottom ? adjustmentMinHeight : undefined,
         }}
-        ref={childContainerViewRef}
+        ref={firstChildViewRef}
       />
     );
-  }, [horizontal, shouldRenderFromBottom, adjustmentMinHeight]);
+  }, [horizontal]);
 
-  //console.log("render");
+  const scrollAnchor = useMemo(() => {
+    if (shouldMaintainVisibleContentPosition) {
+      return (
+        <ScrollAnchor
+          horizontal={Boolean(horizontal)}
+          scrollAnchorRef={scrollAnchorRef}
+        />
+      );
+    }
+    return null;
+  }, [horizontal, shouldMaintainVisibleContentPosition]);
+
+  // console.log("render", recyclerViewManager.getRenderStack());
 
   // Render the main RecyclerView structure
   return (
     <RecyclerViewContextProvider value={recyclerViewContext}>
       <CompatView
-        style={{ flex: horizontal ? undefined : 1, ...style }}
+        style={{
+          flex: horizontal ? undefined : 1,
+          overflow: "hidden",
+          ...style,
+        }}
         ref={internalViewRef}
         collapsable={false}
         onLayout={(event) => {
@@ -433,7 +498,6 @@ const RecyclerViewComponent = <T,>(
           horizontal={horizontal}
           ref={scrollViewRef}
           onScroll={animatedEvent}
-          // TODO: evaluate perf
           maintainVisibleContentPosition={
             maintainVisibleContentPositionInternal
           }
@@ -441,11 +505,10 @@ const RecyclerViewComponent = <T,>(
           {...overrideProps}
         >
           {/* Scroll anchor for maintaining content position */}
-          {maintainVisibleContentPositionInternal && (
-            <ScrollAnchor scrollAnchorRef={scrollAnchorRef} />
-          )}
+          {scrollAnchor}
+          {isHorizontalRTL && viewToMeasureBoundedSize}
           {renderHeader}
-          {viewToMeasureBoundedSize}
+          {!isHorizontalRTL && viewToMeasureBoundedSize}
           {/* Main list content */}
           <ViewHolderCollection
             viewHolderCollectionRef={viewHolderCollectionRef}
@@ -453,6 +516,25 @@ const RecyclerViewComponent = <T,>(
             horizontal={horizontal}
             renderStack={recyclerViewManager.getRenderStack()}
             getLayout={(index) => recyclerViewManager.getLayout(index)}
+            getAdjustmentMargin={() => {
+              if (!shouldRenderFromBottom || !recyclerViewManager.hasLayout()) {
+                return 0;
+              }
+
+              const windowSize = horizontal
+                ? recyclerViewManager.getWindowSize().width
+                : recyclerViewManager.getWindowSize().height;
+              const childContainerSize = horizontal
+                ? recyclerViewManager.getChildContainerDimensions().width
+                : recyclerViewManager.getChildContainerDimensions().height;
+
+              return Math.max(
+                0,
+                windowSize -
+                  childContainerSize -
+                  recyclerViewManager.firstItemOffset
+              );
+            }}
             refHolder={refHolder}
             onSizeChanged={validateItemSize}
             renderItem={renderItem}
@@ -465,10 +547,14 @@ const RecyclerViewComponent = <T,>(
               onCommitLayoutEffect?.();
             }}
             onCommitEffect={() => {
+              renderTimeTracker.markRenderComplete();
+              recyclerViewManager.updateAverageRenderTime(
+                renderTimeTracker.getAverageRenderTime()
+              );
               applyInitialScrollIndex();
               checkBounds();
               recyclerViewManager.computeItemViewability();
-              recyclerViewManager.disableRecycling = Boolean(disableRecycling);
+              recyclerViewManager.animationOptimizationsEnabled = false;
             }}
             CellRendererComponent={CellRendererComponent}
             ItemSeparatorComponent={ItemSeparatorComponent}
@@ -487,9 +573,12 @@ const RecyclerViewComponent = <T,>(
   );
 };
 
+// Set displayName for the inner component
+RecyclerViewComponent.displayName = "FlashList";
+
 // Type definition for the RecyclerView component
 type RecyclerViewType = <T>(
-  props: RecyclerViewProps<T> & { ref?: React.Ref<any> }
+  props: RecyclerViewProps<T> & { ref?: React.Ref<FlashListRef<T>> }
 ) => React.JSX.Element;
 
 // Create and export the memoized, forwarded ref component

package/src/recyclerview/RecyclerViewContextProvider.ts

@@ -1,19 +1,65 @@
 import { createContext, useContext } from "react";
+
+import { FlashListRef } from "../FlashListRef";
+
 import { CompatScroller } from "./components/CompatScroller";
 
-export interface RecyclerViewContext {
-  layout: () => void;
-  getRef: () => React.Ref<any>;
-  getScrollViewRef: () => React.RefObject<CompatScroller | null>;
+export interface RecyclerViewContext<T> extends FlashListContext<T> {
+  /**
+   * Mark the children FlashLists as pending for layout
+   * This will force parent FlashList to wait for children to be laid out before
+   * rendering the next batch of items.
+   * @param id - The id of the child FlashList
+   * @returns void
+   */
   markChildLayoutAsPending: (id: string) => void;
+  /**
+   * Unmark the child FlashList as pending for layout
+   * This will allow parent FlashList to render the next batch of items.
+   * @param id - The id of the child FlashList
+   * @returns void
+   */
   unmarkChildLayoutAsPending: (id: string) => void;
 }
 
+export interface FlashListContext<T> {
+  /**
+   * Layout the current FlashList
+   * @returns void
+   */
+  layout: () => void;
+  /**
+   * Get the ref for the current FlashList
+   */
+  getRef: () => FlashListRef<T> | null;
+  /**
+   * Get the ref for the parent FlashList if present
+   */
+  getParentRef: () => FlashListRef<unknown> | null;
+  /**
+   * Get the scrollView ref for the current FlashList if present
+   */
+  getScrollViewRef: () => CompatScroller | null;
+  /**
+   * Get the scrollView ref for the parent FlashList if present
+   */
+  getParentScrollViewRef: () => CompatScroller | null;
+}
+
 const RecyclerViewContextInstance = createContext<
-  RecyclerViewContext | undefined
+  RecyclerViewContext<unknown> | undefined
 >(undefined);
 
 export const RecyclerViewContextProvider = RecyclerViewContextInstance.Provider;
-export function useRecyclerViewContext() {
-  return useContext(RecyclerViewContextInstance);
+export function useRecyclerViewContext<T>():
+  | RecyclerViewContext<T>
+  | undefined {
+  return useContext(RecyclerViewContextInstance) as
+    | RecyclerViewContext<T>
+    | undefined;
+}
+export function useFlashListContext<T>(): FlashListContext<T> | undefined {
+  return useContext(RecyclerViewContextInstance) as
+    | FlashListContext<T>
+    | undefined;
 }