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

package/src/__tests__/findVisibleIndex.test.ts

@@ -0,0 +1,369 @@
+import {
+  findFirstVisibleIndex,
+  findLastVisibleIndex,
+} from "../recyclerview/utils/findVisibleIndex";
+import { RVLayout } from "../recyclerview/layout-managers/LayoutManager";
+
+import {
+  createPopulatedLayoutManager,
+  LayoutManagerType,
+  getAllLayouts,
+} from "./helpers/createLayoutManager";
+
+describe("findVisibleIndex", () => {
+  // Helper function to create mock layouts directly for precise control
+  function createMockLayouts(
+    count: number,
+    startPosition: number,
+    itemSize: number,
+    isHorizontal: boolean
+  ): RVLayout[] {
+    const layouts: RVLayout[] = [];
+    for (let i = 0; i < count; i++) {
+      const x = isHorizontal ? startPosition + i * itemSize : 0;
+      const y = isHorizontal ? 0 : startPosition + i * itemSize;
+      layouts.push({
+        x,
+        y,
+        width: isHorizontal ? itemSize : 100,
+        height: isHorizontal ? 100 : itemSize,
+      });
+    }
+    return layouts;
+  }
+
+  describe("findFirstVisibleIndex", () => {
+    // Test 1: Basic functionality - vertical layout
+    it("finds the first visible index in a vertical layout", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.LINEAR,
+        20,
+        { horizontal: false }
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      // Viewport starts at y=150, so the second item (index 1) should be first visible
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 150, false);
+      expect(firstVisibleIndex).toBe(1);
+    });
+
+    // Test 2: Basic functionality - horizontal layout
+    it("finds the first visible index in a horizontal layout", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.LINEAR,
+        20,
+        { horizontal: true }
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      // Viewport starts at x=150, so the second item (index 1) should be first visible
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 150, true);
+      expect(firstVisibleIndex).toBe(1);
+    });
+
+    // Test 3: Empty layouts array
+    it("returns -1 for empty layouts array", () => {
+      const firstVisibleIndex = findFirstVisibleIndex([], 100, false);
+      expect(firstVisibleIndex).toBe(-1);
+    });
+
+    // Test 4: All items are visible (threshold at 0)
+    it("returns 0 when all items are visible (threshold at 0)", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.LINEAR,
+        10
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 0, false);
+      expect(firstVisibleIndex).toBe(0);
+    });
+
+    // Test 5: No items are visible (threshold beyond all items)
+    it("returns -1 when no items are visible", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold is beyond all items (10 items * 100 height = 1000)
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 1100, false);
+      expect(firstVisibleIndex).toBe(-1);
+    });
+
+    // Test 6: Edge case - threshold exactly at item boundary
+    it("returns correct index when threshold is exactly at item boundary", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold exactly at the start of the 5th item
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 400, false);
+      expect(firstVisibleIndex).toBe(4);
+    });
+
+    // Test 7: Edge case - threshold in the middle of an item
+    it("returns correct index when threshold is in the middle of an item", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold in the middle of the 3rd item
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 250, false);
+      expect(firstVisibleIndex).toBe(2);
+    });
+
+    // Test 8: With grid layout - threshold crosses multiple columns
+    it("finds first visible index with grid layout", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.GRID,
+        20,
+        { maxColumns: 2 }
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      // With 2 columns, items are positioned differently
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 150, false);
+
+      // Expected result depends on how grid layout positions items
+      // This test might need adjustment based on actual grid layout behavior
+      expect(firstVisibleIndex).not.toBe(-1);
+    });
+
+    // Test 9: With masonry layout - variable height items
+    it("finds first visible index with masonry layout and variable item sizes", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.MASONRY,
+        20,
+        { maxColumns: 2 },
+        100,
+        100,
+        true // Variable size
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 200, false);
+      expect(firstVisibleIndex).not.toBe(-1);
+    });
+
+    // Test 10: Partial visibility - item just starting to appear
+    it("finds item that is just starting to become visible", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold just 1px before item 4 ends
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 399, false);
+      expect(firstVisibleIndex).toBe(3);
+    });
+  });
+
+  describe("findLastVisibleIndex", () => {
+    // Test 11: Basic functionality - vertical layout
+    it("finds the last visible index in a vertical layout", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.LINEAR,
+        20,
+        { horizontal: false }
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      // Viewport ends at y=250, so the third item (index 2) should be last visible
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 250, false);
+      expect(lastVisibleIndex).toBe(2);
+    });
+
+    // Test 12: Basic functionality - horizontal layout
+    it("finds the last visible index in a horizontal layout", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.LINEAR,
+        20,
+        { horizontal: true }
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      // Viewport ends at x=250, so the third item (index 2) should be last visible
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 250, true);
+      expect(lastVisibleIndex).toBe(2);
+    });
+
+    // Test 13: Empty layouts array
+    it("returns -1 for empty layouts array", () => {
+      const lastVisibleIndex = findLastVisibleIndex([], 100, false);
+      expect(lastVisibleIndex).toBe(-1);
+    });
+
+    // Test 14: All items are within viewport
+    it("returns the last item index when all items are within viewport", () => {
+      const layouts = createMockLayouts(5, 0, 100, false);
+
+      // Viewport ends at y=1000, which includes all 5 items
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 1000, false);
+      expect(lastVisibleIndex).toBe(4); // Last item index is 4
+    });
+
+    // Test 15: No items are visible (threshold before all items)
+    it("returns -1 when no items are visible", () => {
+      const layouts = createMockLayouts(10, 100, 100, false);
+
+      // Threshold is before all items start
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 50, false);
+      expect(lastVisibleIndex).toBe(-1);
+    });
+
+    // Test 16: Edge case - threshold exactly at item boundary
+    it("returns correct index when threshold is exactly at item boundary", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold exactly at the end of the 3rd item
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 300, false);
+      expect(lastVisibleIndex).toBe(3);
+    });
+
+    // Test 17: Edge case - threshold in the middle of an item
+    it("returns correct index when threshold is in the middle of an item", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold in the middle of the 3rd item
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 250, false);
+      expect(lastVisibleIndex).toBe(2);
+    });
+
+    // Test 18: With grid layout
+    it("finds last visible index with grid layout", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.GRID,
+        20,
+        { maxColumns: 2 }
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 350, false);
+      expect(lastVisibleIndex).not.toBe(-1);
+    });
+
+    // Test 19: With masonry layout - variable height items
+    it("finds last visible index with masonry layout and variable item sizes", () => {
+      const layoutManager = createPopulatedLayoutManager(
+        LayoutManagerType.MASONRY,
+        20,
+        { maxColumns: 2 },
+        100,
+        100,
+        true // Variable size
+      );
+      const layouts = getAllLayouts(layoutManager);
+
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 400, false);
+      expect(lastVisibleIndex).not.toBe(-1);
+    });
+
+    // Test 20: Last item partially visible
+    it("includes last item when it's partially visible", () => {
+      const layouts = createMockLayouts(10, 0, 100, false);
+
+      // Threshold just 1px into the 5th item
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 401, false);
+      expect(lastVisibleIndex).toBe(4);
+    });
+  });
+
+  describe("Edge cases and complex scenarios", () => {
+    // Test 21: Single item layout
+    it("correctly handles single item layout for first visible", () => {
+      const layouts = createMockLayouts(1, 0, 100, false);
+
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 50, false);
+      expect(firstVisibleIndex).toBe(0);
+    });
+
+    // Test 22: Single item layout
+    it("correctly handles single item layout for last visible", () => {
+      const layouts = createMockLayouts(1, 0, 100, false);
+
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 50, false);
+      expect(lastVisibleIndex).toBe(0);
+    });
+
+    // Test 23: Variable size items for first visible index
+    it("correctly finds first visible with variable size items", () => {
+      const layouts: RVLayout[] = [
+        { x: 0, y: 0, width: 100, height: 50 },
+        { x: 0, y: 50, width: 100, height: 150 },
+        { x: 0, y: 200, width: 100, height: 75 },
+        { x: 0, y: 275, width: 100, height: 100 },
+      ];
+
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 175, false);
+      expect(firstVisibleIndex).toBe(1); // Second item is still visible at threshold 175
+    });
+
+    // Test 24: Variable size items for last visible index
+    it("correctly finds last visible with variable size items", () => {
+      const layouts: RVLayout[] = [
+        { x: 0, y: 0, width: 100, height: 50 },
+        { x: 0, y: 50, width: 100, height: 150 },
+        { x: 0, y: 200, width: 100, height: 75 },
+        { x: 0, y: 275, width: 100, height: 100 },
+      ];
+
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 225, false);
+      expect(lastVisibleIndex).toBe(2); // Third item is visible at threshold 225
+    });
+
+    // Test 25: Items with zero size
+    it("correctly handles items with zero size for first visible", () => {
+      const layouts: RVLayout[] = [
+        { x: 0, y: 0, width: 100, height: 0 },
+        { x: 0, y: 0, width: 100, height: 100 },
+      ];
+
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 0, false);
+      expect(firstVisibleIndex).toBe(0); // First item is at position but has zero height
+    });
+
+    // Test 26: Items with zero size
+    it("correctly handles items with zero size for last visible", () => {
+      const layouts: RVLayout[] = [
+        { x: 0, y: 0, width: 100, height: 100 },
+        { x: 0, y: 100, width: 100, height: 0 },
+      ];
+
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 100, false);
+      expect(lastVisibleIndex).toBe(1); // Second item is at threshold position but has zero height
+    });
+
+    // Test 27: Large number of items - performance test
+    it("efficiently finds first visible index in large dataset", () => {
+      const layouts = createMockLayouts(1000, 0, 100, false);
+
+      // Threshold in the middle of the list
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 50000, false);
+      expect(firstVisibleIndex).toBe(500);
+    });
+
+    // Test 28: Large number of items - performance test
+    it("efficiently finds last visible index in large dataset", () => {
+      const layouts = createMockLayouts(1000, 0, 100, false);
+
+      // Threshold in the middle of the list
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 50000, false);
+      expect(lastVisibleIndex).toBe(500);
+    });
+
+    // Test 29: Non-sequential indices
+    it("works with non-sequential indices for first visible", () => {
+      const layouts: RVLayout[] = [
+        { x: 0, y: 0, width: 100, height: 100 },
+        { x: 0, y: 100, width: 100, height: 100 },
+        { x: 0, y: 200, width: 100, height: 100 },
+      ];
+
+      const firstVisibleIndex = findFirstVisibleIndex(layouts, 150, false);
+      expect(firstVisibleIndex).toBe(1); // Second layout in the array, not index 1
+    });
+
+    // Test 30: Non-sequential indices
+    it("works with non-sequential indices for last visible", () => {
+      const layouts: RVLayout[] = [
+        { x: 0, y: 0, width: 100, height: 100 },
+        { x: 0, y: 100, width: 100, height: 100 },
+        { x: 0, y: 200, width: 100, height: 100 },
+      ];
+
+      const lastVisibleIndex = findLastVisibleIndex(layouts, 150, false);
+      expect(lastVisibleIndex).toBe(1); // Second layout in the array, not index 1
+    });
+  });
+});

package/src/__tests__/helpers/createLayoutManager.ts

@@ -0,0 +1,141 @@
+/* eslint-disable @shopify/typescript/prefer-pascal-case-enums */
+import {
+  LayoutParams,
+  RVDimension,
+  RVLayout,
+  RVLayoutInfo,
+  RVLayoutManager,
+} from "../../recyclerview/layout-managers/LayoutManager";
+import { RVLinearLayoutManagerImpl } from "../../recyclerview/layout-managers/LinearLayoutManager";
+import { RVGridLayoutManagerImpl } from "../../recyclerview/layout-managers/GridLayoutManager";
+import { RVMasonryLayoutManagerImpl } from "../../recyclerview/layout-managers/MasonryLayoutManager";
+
+/**
+ * Layout manager types available in the app
+ */
+export enum LayoutManagerType {
+  LINEAR = "linear",
+  GRID = "grid",
+  MASONRY = "masonry",
+}
+
+/**
+ * Default window size for layout managers
+ */
+const DEFAULT_WINDOW_SIZE: RVDimension = {
+  width: 400,
+  height: 900,
+};
+
+/**
+ * Create layout parameters with sensible defaults
+ */
+export function createLayoutParams(
+  params: Partial<LayoutParams> = {}
+): LayoutParams {
+  return {
+    windowSize: params.windowSize || DEFAULT_WINDOW_SIZE,
+    horizontal: params.horizontal ?? false,
+    maxColumns: params.maxColumns ?? 1,
+    optimizeItemArrangement: params.optimizeItemArrangement ?? true,
+    overrideItemLayout: params.overrideItemLayout ?? (() => {}),
+    getItemType: params.getItemType ?? (() => "default"),
+  };
+}
+
+/**
+ * Create a layout manager of the specified type
+ */
+export function createLayoutManager(
+  type: LayoutManagerType,
+  params: Partial<LayoutParams> = {},
+  previousLayoutManager?: RVLayoutManager
+): RVLayoutManager {
+  const layoutParams = createLayoutParams(params);
+
+  switch (type) {
+    case LayoutManagerType.LINEAR:
+      return new RVLinearLayoutManagerImpl(layoutParams, previousLayoutManager);
+    case LayoutManagerType.GRID:
+      return new RVGridLayoutManagerImpl(layoutParams, previousLayoutManager);
+    case LayoutManagerType.MASONRY:
+      return new RVMasonryLayoutManagerImpl(
+        layoutParams,
+        previousLayoutManager
+      );
+    default:
+      throw new Error(`Unknown layout manager type: ${type}`);
+  }
+}
+
+/**
+ * Generate mock layout info for testing
+ */
+export function createMockLayoutInfo(
+  index: number,
+  width: number,
+  height: number
+): RVLayoutInfo {
+  return {
+    index,
+    dimensions: {
+      width,
+      height,
+    },
+  };
+}
+
+/**
+ * Populate layout data in a layout manager
+ */
+export function populateLayouts(
+  layoutManager: RVLayoutManager,
+  itemCount: number,
+  itemWidth = 100,
+  itemHeight = 100,
+  variableSize = false
+): void {
+  const layoutInfos: RVLayoutInfo[] = [];
+
+  for (let i = 0; i < itemCount; i++) {
+    // If variableSize is true, add some randomness to the item dimensions
+    const width = variableSize ? itemWidth + (i % 3) * 20 : itemWidth;
+    const height = variableSize ? itemHeight + (i % 5) * 25 : itemHeight;
+
+    layoutInfos.push(createMockLayoutInfo(i, width, height));
+  }
+
+  layoutManager.modifyLayout(layoutInfos, itemCount);
+}
+
+/**
+ * Create and populate a layout manager in one step
+ */
+export function createPopulatedLayoutManager(
+  type: LayoutManagerType,
+  itemCount: number,
+  params: Partial<LayoutParams> = {},
+  itemWidth = 100,
+  itemHeight = 100,
+  variableSize = false
+): RVLayoutManager {
+  const layoutManager = createLayoutManager(type, params);
+  populateLayouts(
+    layoutManager,
+    itemCount,
+    itemWidth,
+    itemHeight,
+    variableSize
+  );
+  return layoutManager;
+}
+
+/**
+ * Get all layouts from a layout manager
+ */
+export function getAllLayouts(layoutManager: RVLayoutManager): RVLayout[] {
+  // Access the internal layouts array
+  return Array.from({ length: layoutManager.getLayoutCount() }, (_, index) =>
+    layoutManager.getLayout(index)
+  );
+}