@shopify/flash-list 2.0.0-rc.9 → 2.0.0

package/src/native/config/PlatformHelper.ios.ts

@@ -1,30 +1,7 @@
-import { BaseItemAnimator } from "recyclerlistview";
-
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
   trackAverageRenderTimeForOffsetProjection: false,
-  invertedTransformStyle: { transform: [{ scaleY: -1 }] },
-  invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
-};
-const getCellContainerPlatformStyles = (
-  inverted: boolean,
-  parentProps: { x: number; y: number; isHorizontal?: boolean }
-): { transform: string; WebkitTransform: string } | undefined => {
-  return undefined;
-};
-
-const getItemAnimator = (): BaseItemAnimator | undefined => {
-  return undefined;
 };
 
-const getFooterContainer = (): React.ComponentClass | undefined => {
-  return undefined;
-};
-
-export {
-  PlatformConfig,
-  getCellContainerPlatformStyles,
-  getItemAnimator,
-  getFooterContainer,
-};
+export { PlatformConfig };

package/src/native/config/PlatformHelper.ts

@@ -1,31 +1,7 @@
-import { BaseItemAnimator } from "recyclerlistview";
-import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platform/reactnative/itemanimators/defaultjsanimator/DefaultJSItemAnimator";
-
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: false,
   trackAverageRenderTimeForOffsetProjection: false,
-  invertedTransformStyle: { transform: [{ scaleY: -1 }] },
-  invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
-};
-const getCellContainerPlatformStyles = (
-  inverted: boolean,
-  parentProps: { x: number; y: number; isHorizontal?: boolean }
-): { transform: string; WebkitTransform: string } | undefined => {
-  return undefined;
-};
-
-const getItemAnimator = (): BaseItemAnimator | undefined => {
-  return new DefaultJSItemAnimator();
 };
 
-const getFooterContainer = (): React.ComponentClass | undefined => {
-  return undefined;
-};
-
-export {
-  PlatformConfig,
-  getCellContainerPlatformStyles,
-  getItemAnimator,
-  getFooterContainer,
-};
+export { PlatformConfig };

package/src/native/config/PlatformHelper.web.ts

@@ -1,36 +1,7 @@
-import React from "react";
-import { View } from "react-native";
-import { BaseItemAnimator } from "recyclerlistview";
-import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platform/reactnative/itemanimators/defaultjsanimator/DefaultJSItemAnimator";
-
 const PlatformConfig = {
   defaultDrawDistance: 500,
   supportsOffsetCorrection: false,
   trackAverageRenderTimeForOffsetProjection: false,
-  invertedTransformStyle: { transform: [{ scaleY: -1 }] },
-  invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
-};
-const getCellContainerPlatformStyles = (
-  inverted: boolean,
-  parentProps: { x: number; y: number; isHorizontal?: boolean }
-): { transform: string; WebkitTransform: string } | undefined => {
-  const transformValue = `translate(${parentProps.x}px,${parentProps.y}px)${
-    inverted ? ` ${parentProps.isHorizontal ? `scaleX` : `scaleY`}(-1)` : ``
-  }`;
-  return { transform: transformValue, WebkitTransform: transformValue };
-};
-
-const getItemAnimator = (): BaseItemAnimator | undefined => {
-  return new DefaultJSItemAnimator();
 };
 
-const getFooterContainer = (): React.ComponentClass | undefined => {
-  return View;
-};
-
-export {
-  PlatformConfig,
-  getCellContainerPlatformStyles,
-  getItemAnimator,
-  getFooterContainer,
-};
+export { PlatformConfig };

package/src/recyclerview/LayoutCommitObserver.tsx

@@ -0,0 +1,74 @@
+import React, { useLayoutEffect, useMemo, useRef } from "react";
+
+import {
+  RecyclerViewContext,
+  RecyclerViewContextProvider,
+  useRecyclerViewContext,
+} from "./RecyclerViewContextProvider";
+import { useLayoutState } from "./hooks/useLayoutState";
+
+export interface LayoutCommitObserverProps {
+  children: React.ReactNode;
+  onCommitLayoutEffect?: () => void;
+}
+
+/**
+ * LayoutCommitObserver can be used to observe when FlashList commits a layout.
+ * It is useful when your component has one or more FlashLists somewhere down the tree.
+ * LayoutCommitObserver will trigger `onCommitLayoutEffect` when all of the FlashLists in the tree have finished their first commit.
+ */
+export const LayoutCommitObserver = React.memo(
+  (props: LayoutCommitObserverProps) => {
+    const { children, onCommitLayoutEffect } = props;
+    const parentRecyclerViewContext = useRecyclerViewContext();
+    const [_, setRenderId] = useLayoutState(0);
+    const pendingChildIds = useRef<Set<string>>(new Set()).current;
+
+    useLayoutEffect(() => {
+      if (pendingChildIds.size > 0) {
+        return;
+      }
+      onCommitLayoutEffect?.();
+    });
+
+    // Create context for child components
+    const recyclerViewContext: RecyclerViewContext<unknown> = useMemo(() => {
+      return {
+        layout: () => {
+          setRenderId((prev) => prev + 1);
+        },
+        getRef: () => {
+          return parentRecyclerViewContext?.getRef() ?? null;
+        },
+        getParentRef: () => {
+          return parentRecyclerViewContext?.getParentRef() ?? null;
+        },
+        getParentScrollViewRef: () => {
+          return parentRecyclerViewContext?.getParentScrollViewRef() ?? null;
+        },
+        getScrollViewRef: () => {
+          return parentRecyclerViewContext?.getScrollViewRef() ?? null;
+        },
+        markChildLayoutAsPending: (id: string) => {
+          parentRecyclerViewContext?.markChildLayoutAsPending(id);
+          pendingChildIds.add(id);
+        },
+        unmarkChildLayoutAsPending: (id: string) => {
+          parentRecyclerViewContext?.unmarkChildLayoutAsPending(id);
+          if (pendingChildIds.has(id)) {
+            pendingChildIds.delete(id);
+            recyclerViewContext.layout();
+          }
+        },
+      };
+    }, [parentRecyclerViewContext, pendingChildIds, setRenderId]);
+
+    return (
+      <RecyclerViewContextProvider value={recyclerViewContext}>
+        {children}
+      </RecyclerViewContextProvider>
+    );
+  }
+);
+
+LayoutCommitObserver.displayName = "LayoutCommitObserver";

package/src/recyclerview/RecyclerView.tsx

@@ -20,6 +20,7 @@ import {
 } from "react-native";
 
 import { FlashListRef } from "../FlashListRef";
+import { ErrorMessages } from "../errors/ErrorMessages";
 
 import { RVDimension } from "./layout-managers/LayoutManager";
 import {
@@ -384,6 +385,9 @@ const RecyclerViewComponent = <T,>(
       stickyHeaderIndices &&
       stickyHeaderIndices.length > 0
     ) {
+      if (horizontal) {
+        throw new Error(ErrorMessages.stickyHeadersNotSupportedForHorizontal);
+      }
       return (
         <StickyHeaders
           stickyHeaderIndices={stickyHeaderIndices}
@@ -402,6 +406,7 @@ const RecyclerViewComponent = <T,>(
     stickyHeaderIndices,
     renderItem,
     scrollY,
+    horizontal,
     recyclerViewManager,
     extraData,
   ]);
@@ -434,16 +439,6 @@ const RecyclerViewComponent = <T,>(
     recyclerViewManager.getDataLength() > 0 &&
     (maintainVisibleContentPosition?.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;
-
   // Create view for measuring bounded size
   const viewToMeasureBoundedSize = useMemo(() => {
     return (
@@ -451,12 +446,11 @@ const RecyclerViewComponent = <T,>(
         style={{
           height: horizontal ? undefined : 0,
           width: horizontal ? 0 : undefined,
-          minHeight: shouldRenderFromBottom ? adjustmentMinHeight : undefined,
         }}
         ref={firstChildViewRef}
       />
     );
-  }, [horizontal, shouldRenderFromBottom, adjustmentMinHeight]);
+  }, [horizontal]);
 
   const scrollAnchor = useMemo(() => {
     if (shouldMaintainVisibleContentPosition) {
@@ -527,6 +521,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}

package/src/recyclerview/RecyclerViewManager.ts

@@ -1,5 +1,6 @@
-import ViewabilityManager from "../viewability/ViewabilityManager";
+import { ErrorMessages } from "../errors/ErrorMessages";
 
+import ViewabilityManager from "./viewability/ViewabilityManager";
 import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
 import { RVGridLayoutManagerImpl } from "./layout-managers/GridLayoutManager";
 import {
@@ -20,13 +21,14 @@ import {
 import { RenderStackManager } from "./RenderStackManager";
 // Abstracts layout manager, render stack manager and viewability manager and generates render stack (progressively on load)
 export class RecyclerViewManager<T> {
-  private initialDrawBatchSize = 1;
+  private initialDrawBatchSize = 2;
   private engagedIndicesTracker: RVEngagedIndicesTracker;
   private renderStackManager: RenderStackManager;
   private layoutManager?: RVLayoutManager;
   // Map of index to key
   private isFirstLayoutComplete = false;
   private hasRenderedProgressively = false;
+  private progressiveRenderCount = 0;
   private propsRef: RecyclerViewProps<T>;
   private itemViewabilityManager: ViewabilityManager<T>;
   private _isDisposed = false;
@@ -53,8 +55,12 @@ export class RecyclerViewManager<T> {
     return this._isDisposed;
   }
 
+  public get numColumns() {
+    return this.propsRef.numColumns ?? 1;
+  }
+
   constructor(props: RecyclerViewProps<T>) {
-    this.getStableId = this.getStableId.bind(this);
+    this.getDataKey = this.getDataKey.bind(this);
     this.getItemType = this.getItemType.bind(this);
     this.overrideItemLayout = this.overrideItemLayout.bind(this);
     this.propsRef = props;
@@ -68,7 +74,7 @@ export class RecyclerViewManager<T> {
   // updates render stack based on the engaged indices which are sorted. Recycles unused keys.
   private updateRenderStack = (engagedIndices: ConsecutiveNumbers): void => {
     this.renderStackManager.sync(
-      this.getStableId,
+      this.getDataKey,
       this.getItemType,
       engagedIndices,
       this.getDataLength()
@@ -87,11 +93,6 @@ export class RecyclerViewManager<T> {
     this.propsRef = props;
     this.engagedIndicesTracker.drawDistance =
       props.drawDistance ?? this.engagedIndicesTracker.drawDistance;
-    if (this.propsRef.drawDistance === 0) {
-      this.initialDrawBatchSize = 1;
-    } else {
-      this.initialDrawBatchSize = (props.numColumns ?? 1) * 2;
-    }
     this.initialDrawBatchSize =
       this.propsRef.overrideProps?.initialDrawBatchSize ??
       this.initialDrawBatchSize;
@@ -131,9 +132,7 @@ export class RecyclerViewManager<T> {
 
   getLayout(index: number) {
     if (!this.layoutManager) {
-      throw new Error(
-        "LayoutManager is not initialized, layout info is unavailable"
-      );
+      throw new Error(ErrorMessages.layoutManagerNotInitializedLayoutInfo);
     }
     return this.layoutManager.getLayout(index);
   }
@@ -152,9 +151,7 @@ export class RecyclerViewManager<T> {
   // Doesn't include header / foot etc
   getChildContainerDimensions() {
     if (!this.layoutManager) {
-      throw new Error(
-        "LayoutManager is not initialized, child container layout is unavailable"
-      );
+      throw new Error(ErrorMessages.layoutManagerNotInitializedChildContainer);
     }
     return this.layoutManager.getLayoutSize();
   }
@@ -165,9 +162,7 @@ export class RecyclerViewManager<T> {
 
   getWindowSize() {
     if (!this.layoutManager) {
-      throw new Error(
-        "LayoutManager is not initialized, window size is unavailable"
-      );
+      throw new Error(ErrorMessages.layoutManagerNotInitializedWindowSize);
     }
     return this.layoutManager.getWindowsSize();
   }
@@ -211,9 +206,7 @@ export class RecyclerViewManager<T> {
       Boolean(this.layoutManager?.isHorizontal()) !==
         Boolean(this.propsRef.horizontal)
     ) {
-      throw new Error(
-        "Horizontal prop cannot be toggled, you can use a key on FlashList to recreate it."
-      );
+      throw new Error(ErrorMessages.horizontalPropCannotBeToggled);
     }
     if (this._isLayoutManagerDirty) {
       this.layoutManager = undefined;
@@ -221,7 +214,7 @@ export class RecyclerViewManager<T> {
     }
     const layoutManagerParams: LayoutParams = {
       windowSize,
-      maxColumns: this.propsRef.numColumns ?? 1,
+      maxColumns: this.numColumns,
       horizontal: Boolean(this.propsRef.horizontal),
       optimizeItemArrangement: this.propsRef.optimizeItemArrangement ?? true,
       overrideItemLayout: this.overrideItemLayout,
@@ -245,9 +238,7 @@ export class RecyclerViewManager<T> {
 
   computeVisibleIndices() {
     if (!this.layoutManager) {
-      throw new Error(
-        "LayoutManager is not initialized, visible indices are not unavailable"
-      );
+      throw new Error(ErrorMessages.layoutManagerNotInitializedVisibleIndices);
     }
     return this.engagedIndicesTracker.computeVisibleIndices(this.layoutManager);
   }
@@ -298,7 +289,7 @@ export class RecyclerViewManager<T> {
   processDataUpdate() {
     if (this.hasLayout()) {
       this.modifyChildrenLayout([], this.propsRef.data?.length ?? 0);
-      if (!this.recomputeEngagedIndices()) {
+      if (this.hasRenderedProgressively && !this.recomputeEngagedIndices()) {
         // recomputeEngagedIndices will update the render stack if there are any changes in the engaged indices.
         // It's important to update render stack so that elements are assgined right keys incase items were deleted.
         this.updateRenderStack(this.engagedIndicesTracker.getEngagedIndices());
@@ -346,17 +337,28 @@ export class RecyclerViewManager<T> {
     return this.propsRef.data?.length ?? 0;
   }
 
+  hasStableDataKeys() {
+    return Boolean(this.propsRef.keyExtractor);
+  }
+
+  getDataKey(index: number): string {
+    return (
+      this.propsRef.keyExtractor?.(this.propsRef.data![index], index) ??
+      index.toString()
+    );
+  }
+
   private getLayoutManagerClass() {
     // throw errors for incompatible props
     if (this.propsRef.masonry && this.propsRef.horizontal) {
-      throw new Error("Masonry and horizontal props are incompatible");
+      throw new Error(ErrorMessages.masonryAndHorizontalIncompatible);
     }
-    if ((this.propsRef.numColumns ?? 1) > 1 && this.propsRef.horizontal) {
-      throw new Error("numColumns and horizontal props are incompatible");
+    if (this.numColumns > 1 && this.propsRef.horizontal) {
+      throw new Error(ErrorMessages.numColumnsAndHorizontalIncompatible);
     }
     return this.propsRef.masonry
       ? RVMasonryLayoutManagerImpl
-      : (this.propsRef.numColumns ?? 1) > 1 && !this.propsRef.horizontal
+      : this.numColumns > 1 && !this.propsRef.horizontal
       ? RVGridLayoutManagerImpl
       : RVLinearLayoutManagerImpl;
   }
@@ -392,6 +394,7 @@ export class RecyclerViewManager<T> {
   }
 
   private renderProgressively() {
+    this.progressiveRenderCount++;
     const layoutManager = this.layoutManager;
     if (layoutManager) {
       this.applyInitialScrollAdjustment();
@@ -407,16 +410,20 @@ export class RecyclerViewManager<T> {
         this.isFirstLayoutComplete = true;
       }
 
+      const batchSize =
+        this.numColumns *
+        this.initialDrawBatchSize ** Math.ceil(this.progressiveRenderCount / 5);
+
       // If everything is measured then render stack will be in sync. The buffer items will get rendered in the next update
       // triggered by the useOnLoad hook.
       !this.hasRenderedProgressively &&
         this.updateRenderStack(
-          // pick first n indices from visible ones and n is size of renderStack
+          // pick first n indices from visible ones based on batch size
           visibleIndices.slice(
             0,
             Math.min(
               visibleIndices.length,
-              this.getRenderStack().size + this.initialDrawBatchSize
+              this.getRenderStack().size + batchSize
             )
           )
         );
@@ -430,19 +437,12 @@ export class RecyclerViewManager<T> {
     ).toString();
   }
 
-  private getStableId(index: number): string {
-    return (
-      this.propsRef.keyExtractor?.(this.propsRef.data![index], index) ??
-      index.toString()
-    );
-  }
-
   private overrideItemLayout(index: number, layout: SpanSizeInfo) {
     this.propsRef?.overrideItemLayout?.(
       layout,
       this.propsRef.data![index],
       index,
-      this.propsRef.numColumns ?? 1,
+      this.numColumns,
       this.propsRef.extraData
     );
   }

package/src/recyclerview/RecyclerViewProps.ts

@@ -1,11 +1 @@
-import { ScrollViewProps } from "react-native";
-
-import { FlashListProps } from "../FlashListProps";
-
-export interface RecyclerViewProps<TItem>
-  extends Omit<FlashListProps<TItem>, "contentContainerStyle"> {
-  /**
-   * Style for the RecyclerView's parent container.
-   */
-  contentContainerStyle?: ScrollViewProps["contentContainerStyle"];
-}
+export { FlashListProps as RecyclerViewProps } from "../FlashListProps";

package/src/recyclerview/ViewHolderCollection.tsx

@@ -37,15 +37,19 @@ export interface ViewHolderCollectionProps<TItem> {
   /** Function to get the container's layout dimensions */
   getChildContainerLayout: () => RVDimension | undefined;
   /** Callback after layout effects are committed */
-  onCommitLayoutEffect?: () => void;
+  onCommitLayoutEffect: () => void;
   /** Callback after effects are committed */
-  onCommitEffect?: () => void;
+  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"];
+  /** Function to get the adjustment margin for the container.
+   * For startRenderingFromBottom, we need to adjust the height of the container
+   */
+  getAdjustmentMargin: () => number;
 }
 
 /**
@@ -79,6 +83,7 @@ export const ViewHolderCollection = <TItem,>(
     ItemSeparatorComponent,
     onCommitEffect,
     horizontal,
+    getAdjustmentMargin,
   } = props;
 
   const [renderId, setRenderId] = React.useState(0);
@@ -136,6 +141,8 @@ export const ViewHolderCollection = <TItem,>(
   const containerStyle = {
     width: horizontal ? containerLayout?.width : undefined,
     height: containerLayout?.height,
+    marginTop: horizontal ? undefined : getAdjustmentMargin(),
+    marginLeft: horizontal ? getAdjustmentMargin() : undefined,
     // TODO: Temp workaround, useLayoutEffect doesn't block paint in some cases
     // We need to investigate why this is happening
     opacity: renderId > 0 ? 1 : 0,

package/src/recyclerview/hooks/useBoundDetection.ts

@@ -26,14 +26,35 @@ export function useBoundDetection<T>(
   const pendingStartReached = useRef(false);
   // Track whether we should auto-scroll to bottom when new content is added
   const pendingAutoscrollToBottom = useRef(false);
+
+  const lastCheckBoundsTime = useRef(Date.now());
+
   const { data } = recyclerViewManager.props;
   const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
 
+  const windowHeight = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getWindowSize().height
+    : 0;
+
+  const contentHeight = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getChildContainerDimensions().height
+    : 0;
+
+  const windowWidth = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getWindowSize().width
+    : 0;
+
+  const contentWidth = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getChildContainerDimensions().width
+    : 0;
+
   /**
    * Checks if the scroll position is near the start or end of the list
    * and triggers appropriate callbacks if configured.
    */
   const checkBounds = useCallback(() => {
+    lastCheckBoundsTime.current = Date.now();
+
     const {
       onEndReached,
       onStartReached,
@@ -111,6 +132,20 @@ export function useBoundDetection<T>(
     }
   }, [recyclerViewManager]);
 
+  const runAutoScrollToBottomCheck = useCallback(() => {
+    if (pendingAutoscrollToBottom.current) {
+      pendingAutoscrollToBottom.current = false;
+      requestAnimationFrame(() => {
+        const shouldAnimate =
+          recyclerViewManager.props.maintainVisibleContentPosition
+            ?.animateAutoScrollToBottom ?? true;
+        scrollViewRef.current?.scrollToEnd({
+          animated: shouldAnimate,
+        });
+      });
+    }
+  }, [requestAnimationFrame, scrollViewRef, recyclerViewManager]);
+
   // Reset end reached state when data changes
   useMemo(() => {
     pendingEndReached.current = false;
@@ -120,13 +155,20 @@ export function useBoundDetection<T>(
 
   // Auto-scroll to bottom when new content is added and we're near the bottom
   useEffect(() => {
-    if (pendingAutoscrollToBottom.current) {
-      requestAnimationFrame(() => {
-        scrollViewRef.current?.scrollToEnd();
-        pendingAutoscrollToBottom.current = false;
-      });
+    runAutoScrollToBottomCheck();
+  }, [data, runAutoScrollToBottomCheck, windowHeight, windowWidth]);
+
+  // Since content changes frequently, we try and avoid doing the auto scroll during active scrolls
+  useEffect(() => {
+    if (Date.now() - lastCheckBoundsTime.current >= 100) {
+      runAutoScrollToBottomCheck();
     }
-  }, [data, requestAnimationFrame, scrollViewRef]);
+  }, [
+    contentHeight,
+    contentWidth,
+    recyclerViewManager.firstItemOffset,
+    runAutoScrollToBottomCheck,
+  ]);
 
   return {
     checkBounds,