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

package/src/__tests__/useUnmountAwareCallbacks.test.tsx

@@ -0,0 +1,285 @@
+import React from "react";
+import { render } from "@quilted/react-testing";
+
+import { useUnmountAwareTimeout } from "../recyclerview/hooks/useUnmountAwareCallbacks";
+
+const TestComponent = ({
+  onRender,
+}: {
+  onRender: (api: ReturnType<typeof useUnmountAwareTimeout>) => void;
+}) => {
+  const api = useUnmountAwareTimeout();
+  onRender(api);
+  return null;
+};
+
+describe("useUnmountAwareCallbacks", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.clearAllMocks();
+  });
+
+  it("returns a setTimeout function", () => {
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+    render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    expect(api).toBeDefined();
+    expect(api?.setTimeout).toBeDefined();
+    expect(typeof api?.setTimeout).toBe("function");
+  });
+
+  it("executes the callback after the specified delay", () => {
+    const callback = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    api?.setTimeout(callback, 1000);
+
+    expect(callback).not.toHaveBeenCalled();
+
+    // Fast-forward time
+    jest.advanceTimersByTime(1000);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("executes multiple callbacks after their respective delays", () => {
+    const callback1 = jest.fn();
+    const callback2 = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    api?.setTimeout(callback1, 1000);
+    api?.setTimeout(callback2, 2000);
+
+    expect(callback1).not.toHaveBeenCalled();
+    expect(callback2).not.toHaveBeenCalled();
+
+    // Fast-forward time by 1000ms
+    jest.advanceTimersByTime(1000);
+
+    expect(callback1).toHaveBeenCalledTimes(1);
+    expect(callback2).not.toHaveBeenCalled();
+
+    // Fast-forward time by another 1000ms
+    jest.advanceTimersByTime(1000);
+
+    expect(callback1).toHaveBeenCalledTimes(1);
+    expect(callback2).toHaveBeenCalledTimes(1);
+  });
+
+  it("clears all timeouts when the component unmounts", () => {
+    const callback = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    const component = render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    api?.setTimeout(callback, 1000);
+    api?.setTimeout(callback, 2000);
+
+    // Spy on clearTimeout to verify it's called during unmount
+    const clearTimeoutSpy = jest.spyOn(global, "clearTimeout");
+
+    // Unmount the component
+    component.unmount();
+
+    // Fast-forward time
+    jest.advanceTimersByTime(2000);
+
+    // Expect callbacks not to be called because timeouts were cleared
+    expect(callback).not.toHaveBeenCalled();
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+  });
+
+  it("removes timeout from tracking set once it executes", () => {
+    const callback = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    const component = render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    api?.setTimeout(callback, 1000);
+
+    // Fast-forward time
+    jest.advanceTimersByTime(1000);
+
+    // Verify callback was called
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    // We can't directly check the timeoutIds Set, so we'll verify indirectly
+    // by making sure no clearTimeout calls happen on unmount (since the timeout was already cleared)
+    const clearTimeoutSpy = jest.spyOn(global, "clearTimeout");
+    clearTimeoutSpy.mockClear(); // Reset the mock calls before unmount
+
+    // Unmount the component
+    component.unmount();
+
+    // If the timeout was properly removed from the set, clearTimeout won't be called on unmount
+    expect(clearTimeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it("handles multiple timeouts correctly", () => {
+    const callback1 = jest.fn();
+    const callback2 = jest.fn();
+    const callback3 = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    const component = render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    // Set up three timeouts with different delays
+    api?.setTimeout(callback1, 1000);
+    api?.setTimeout(callback2, 2000);
+    api?.setTimeout(callback3, 3000);
+
+    // Fast-forward time by 1500ms (should trigger only the first callback)
+    jest.advanceTimersByTime(1500);
+
+    expect(callback1).toHaveBeenCalledTimes(1);
+    expect(callback2).not.toHaveBeenCalled();
+    expect(callback3).not.toHaveBeenCalled();
+
+    // Unmount the component (should clear remaining timeouts)
+    component.unmount();
+
+    // Fast-forward time to when all callbacks would have been called
+    jest.advanceTimersByTime(2000);
+
+    // Only the first callback should have been called
+    expect(callback1).toHaveBeenCalledTimes(1);
+    expect(callback2).not.toHaveBeenCalled();
+    expect(callback3).not.toHaveBeenCalled();
+  });
+
+  it("handles callbacks that trigger new timeouts", () => {
+    const finalCallback = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    const firstCallback = () => {
+      api?.setTimeout(finalCallback, 1000);
+    };
+
+    api?.setTimeout(firstCallback, 1000);
+
+    // Fast-forward time to trigger first callback
+    jest.advanceTimersByTime(1000);
+
+    expect(finalCallback).not.toHaveBeenCalled();
+
+    // Fast-forward time to trigger second callback
+    jest.advanceTimersByTime(1000);
+
+    expect(finalCallback).toHaveBeenCalledTimes(1);
+  });
+
+  it("handles zero delay timeouts", () => {
+    const callback = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    api?.setTimeout(callback, 0);
+
+    expect(callback).not.toHaveBeenCalled();
+
+    // Even with zero delay, we need to advance the timer to execute
+    jest.advanceTimersByTime(0);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("handles errors in callbacks without affecting other timeouts", () => {
+    const errorCallback = jest.fn(() => {
+      throw new Error("Test error");
+    });
+    const successCallback = jest.fn();
+    let api: ReturnType<typeof useUnmountAwareTimeout> | undefined;
+
+    // Suppress error log during test
+    const originalConsoleError = console.error;
+    console.error = jest.fn();
+
+    render(
+      <TestComponent
+        onRender={(hookApi) => {
+          api = hookApi;
+        }}
+      />
+    );
+
+    api?.setTimeout(errorCallback, 1000);
+    api?.setTimeout(successCallback, 2000);
+
+    // Fast-forward time to trigger error callback
+    try {
+      jest.advanceTimersByTime(1000);
+    } catch (error) {
+      // Expected error
+    }
+
+    expect(errorCallback).toHaveBeenCalledTimes(1);
+    expect(successCallback).not.toHaveBeenCalled();
+
+    // Fast-forward time to trigger success callback
+    jest.advanceTimersByTime(1000);
+
+    expect(successCallback).toHaveBeenCalledTimes(1);
+
+    // Restore console.error
+    console.error = originalConsoleError;
+  });
+});

package/src/benchmark/useBenchmark.ts

@@ -199,42 +199,5 @@ function computeSuggestions(
         `Data count is low. Try to increase it to a large number (e.g 200) using the 'useDataMultiplier' hook.`
       );
     }
-    const distanceFromWindow = roundToDecimalPlaces(
-      flashListRef.current.firstItemOffset,
-      0
-    );
-    if (
-      (flashListRef.current.props.estimatedFirstItemOffset || 0) !==
-      distanceFromWindow
-    ) {
-      suggestions.push(
-        `estimatedFirstItemOffset can be set to ${distanceFromWindow}`
-      );
-    }
-    const rlv = flashListRef.current.recyclerlistview_unsafe;
-    const horizontal = flashListRef.current.props.horizontal;
-    if (rlv) {
-      const sizeArray = rlv.props.dataProvider
-        .getAllData()
-        .map((_, index) =>
-          horizontal
-            ? rlv.getLayout?.(index)?.width || 0
-            : rlv.getLayout?.(index)?.height || 0
-        );
-      const averageSize = Math.round(
-        sizeArray.reduce((prev, current) => prev + current, 0) /
-          sizeArray.length
-      );
-      if (
-        Math.abs(
-          averageSize -
-            (flashListRef.current.props.estimatedItemSize ??
-              flashListRef.current.state.layoutProvider
-                .defaultEstimatedItemSize)
-        ) > 5
-      ) {
-        suggestions.push(`estimatedItemSize can be set to ${averageSize}`);
-      }
-    }
   }
 }

package/src/benchmark/useFlatListBenchmark.ts

@@ -25,7 +25,7 @@ export function useFlatListBenchmark(
 ) {
   useEffect(() => {
     const cancellable = new Cancellable();
-    if (flatListRef.current) {
+    if (flatListRef.current && flatListRef.current.props) {
       if (!(Number(flatListRef.current.props.data?.length) > 0)) {
         throw new Error("Data is empty, cannot run benchmark");
       }
@@ -71,7 +71,7 @@ async function runScrollBenchmark(
   scrollSpeedMultiplier: number
 ): Promise<void> {
   if (flatListRef.current) {
-    const horizontal = flatListRef.current.props.horizontal;
+    const horizontal = Boolean(flatListRef.current.props?.horizontal);
 
     const fromX = 0;
     const fromY = 0;

package/src/enableNewCore.ts

@@ -1,3 +1,5 @@
+import { Platform } from "react-native";
+
 let useNewCore: boolean | undefined;
 export function enableNewCore(enable: boolean) {
   useNewCore = enable;
@@ -15,7 +17,7 @@ function isReactNativeNewArchitecture(): boolean {
     // Check for TurboModule system
     const hasTurboModule = Boolean((global as any)?.__turboModuleProxy);
 
-    return hasFabricUIManager || hasTurboModule;
+    return hasFabricUIManager || hasTurboModule || Platform.OS === "web";
   } catch {
     return false;
   }

package/src/index.ts

@@ -1,9 +1,11 @@
+// eslint-disable-next-line import/no-named-default
 import { default as OriginalFlashList } from "./FlashList";
 import { isNewCoreEnabled } from "./enableNewCore";
 import { RecyclerView } from "./recyclerview/RecyclerView";
 
 // Keep this unmodified for TS type checking
 export { default as FlashList } from "./FlashList";
+export { FlashListRef } from "./FlashListRef";
 export {
   FlashListProps,
   ContentStyle,
@@ -44,19 +46,28 @@ export {
 } from "./MasonryFlashList";
 export { useLayoutState } from "./recyclerview/hooks/useLayoutState";
 export { useRecyclingState } from "./recyclerview/hooks/useRecyclingState";
+export { useMappingHelper } from "./recyclerview/hooks/useMappingHelper";
 export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
 export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";
 export { default as ViewToken } from "./viewability/ViewToken";
 export { default as CellContainer } from "./native/cell-container/CellContainer";
 export { RecyclerView } from "./recyclerview/RecyclerView";
 export { RecyclerViewProps } from "./recyclerview/RecyclerViewProps";
-export { useRecyclerViewContext } from "./recyclerview/RecyclerViewContextProvider";
+export { useFlashListContext } from "./recyclerview/RecyclerViewContextProvider";
+export {
+  LayoutCommitObserver,
+  LayoutCommitObserverProps,
+} from "./recyclerview/LayoutCommitObserver";
 
 // @ts-ignore - This is ignored by TypeScript but will be present in the compiled JS
 // In the compiled JS, this will override the previous FlashList export with a conditional one
-if (typeof module !== "undefined" && module.exports) {
+if (
+  typeof module !== "undefined" &&
+  module.exports &&
+  process?.env?.NODE_ENV !== "test"
+) {
   Object.defineProperty(module.exports, "FlashList", {
-    get: function () {
+    get() {
       return isNewCoreEnabled() ? RecyclerView : OriginalFlashList;
     },
     configurable: true,

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

@@ -2,6 +2,8 @@ import { BaseItemAnimator } from "recyclerlistview";
 
 const PlatformConfig = {
   defaultDrawDistance: 250,
+  supportsOffsetCorrection: true,
+  trackAverageRenderTimeForOffsetProjection: true,
   // Using rotate instead of scaleY on Android to avoid performance issues. Issue: https://github.com/Shopify/flash-list/issues/751
   invertedTransformStyle: { transform: [{ rotate: "180deg" }] },
   invertedTransformStyleHorizontal: { transform: [{ rotate: "180deg" }] },

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

@@ -2,6 +2,8 @@ import { BaseItemAnimator } from "recyclerlistview";
 
 const PlatformConfig = {
   defaultDrawDistance: 250,
+  supportsOffsetCorrection: true,
+  trackAverageRenderTimeForOffsetProjection: false,
   invertedTransformStyle: { transform: [{ scaleY: -1 }] },
   invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
 };

package/src/native/config/PlatformHelper.ts

@@ -3,6 +3,8 @@ import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platfor
 
 const PlatformConfig = {
   defaultDrawDistance: 250,
+  supportsOffsetCorrection: false,
+  trackAverageRenderTimeForOffsetProjection: false,
   invertedTransformStyle: { transform: [{ scaleY: -1 }] },
   invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
 };

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

@@ -4,7 +4,9 @@ import { BaseItemAnimator } from "recyclerlistview";
 import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platform/reactnative/itemanimators/defaultjsanimator/DefaultJSItemAnimator";
 
 const PlatformConfig = {
-  defaultDrawDistance: 2000,
+  defaultDrawDistance: 500,
+  supportsOffsetCorrection: false,
+  trackAverageRenderTimeForOffsetProjection: false,
   invertedTransformStyle: { transform: [{ scaleY: -1 }] },
   invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
 };

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";