Relax List rowHeight constraint

Author: bvaughn

lib/components/grid/Grid.tsx

@@ -221,7 +221,7 @@ export function Grid<
         rowIndex++
       ) {
         const rowBounds = cachedRowBounds.getItemBounds(rowIndex);
-        const rowOffset = rowBounds?.scrollOffset;
+        const rowOffset = rowBounds?.scrollOffset ?? 0;
 
         const columns: ReactNode[] = [];
 
@@ -231,7 +231,7 @@ export function Grid<
           columnIndex++
         ) {
           const columnBounds = cachedColumnBounds.getItemBounds(columnIndex);
-          const columnOffset = columnBounds?.scrollOffset;
+          const columnOffset = columnBounds?.scrollOffset ?? 0;
 
           columns.push(
             <CellComponent

lib/components/list/List.test.tsx

@@ -7,6 +7,7 @@ import {
   disableResizeObserverForCurrentTest,
   setDefaultElementSize,
   setElementSize,
+  setElementSizeFunction,
   simulateUnsupportedEnvironmentForTest
 } from "../../utils/test/mockResizeObserver";
 import { List } from "./List";
@@ -555,6 +556,30 @@ describe("List", () => {
 
       expect(container.querySelectorAll('[role="listitem"]')).toHaveLength(4);
     });
+
+    // Most dynamic size tests are in useVirtualizer
+    test("type: dynamic (lazily measured)", () => {
+      setElementSizeFunction((element) => {
+        const attribute = element.getAttribute("data-react-window-index");
+        if (attribute !== null) {
+          const index = parseInt(attribute);
+          if (!Number.isNaN(index)) {
+            return new DOMRect(0, 0, 100, (index + 1) * 5);
+          }
+        }
+      });
+
+      const { container } = render(
+        <List
+          overscanCount={0}
+          rowCount={50}
+          rowComponent={RowComponent}
+          rowProps={EMPTY_OBJECT}
+        />
+      );
+
+      expect(container.querySelectorAll('[role="listitem"]')).toHaveLength(6);
+    });
   });
 
   describe("edge cases", () => {

lib/components/list/List.tsx

@@ -119,7 +119,7 @@ export function List<
 
   const offset =
     startIndexOverscan >= 0
-      ? cachedBounds.getItemBounds(startIndexOverscan).scrollOffset
+      ? (cachedBounds.getItemBounds(startIndexOverscan)?.scrollOffset ?? 0)
       : 0;
 
   const rows = useMemo(() => {
@@ -131,10 +131,18 @@ export function List<
         index++
       ) {
         const bounds = cachedBounds.getItemBounds(index);
-        const style: CSSProperties = {
-          height: hasRowHeight ? bounds.size : undefined,
-          width: "100%"
-        };
+
+        let style: CSSProperties = {};
+        if (bounds) {
+          style = {
+            height: hasRowHeight ? bounds.size : undefined,
+            width: "100%"
+          };
+        } else {
+          style = {
+            width: "100%"
+          };
+        }
 
         if (index === startIndexOverscan) {
           style.marginTop = `${offset}px`;

lib/components/list/types.ts

@@ -95,8 +95,15 @@ export type ListProps<
    * - number of pixels (number)
    * - percentage of the grid's current height (string)
    * - function that returns the row height (in pixels) given an index and `cellProps`
+   *
+   * If this property is not provided, a ResizeObserver will be used to measure the height of a row's content.
+   *
+   * ⚠️ Row height should be provided if it is known ahead of time as that is the most efficient way to render the list.
    */
-  rowHeight: number | string | ((index: number, cellProps: RowProps) => number);
+  rowHeight?:
+    | number
+    | string
+    | ((index: number, cellProps: RowProps) => number);
 
   /**
    * Additional props to be passed to the row-rendering component.

lib/core/createCachedBounds.test.ts

@@ -68,4 +68,62 @@ describe("createCachedBounds", () => {
       cachedBounds.getItemBounds(1);
     }).toThrow("Invalid index 1");
   });
+
+  test("should gracefully handle undefined item sizes", () => {
+    const cachedBounds = createCachedBounds({
+      itemCount: 10,
+      itemProps: {},
+      itemSize: undefined
+    });
+
+    cachedBounds.setItemSize(0, 10);
+
+    expect(cachedBounds.size).toBe(1);
+    expect(cachedBounds.getItemBounds(0)).toEqual({
+      scrollOffset: 0,
+      size: 10
+    });
+
+    cachedBounds.setItemSize(1, 20);
+
+    expect(cachedBounds.size).toBe(2);
+    expect(cachedBounds.getItemBounds(1)).toEqual({
+      scrollOffset: 10,
+      size: 20
+    });
+  });
+
+  test("should gracefully handle sparsely populated cache", () => {
+    const cachedBounds = createCachedBounds({
+      itemCount: 5,
+      itemProps: {},
+      itemSize: undefined
+    });
+
+    expect(cachedBounds.getEstimatedSize()).toBeUndefined();
+
+    // Estimated average should be based on measured cells
+    cachedBounds.setItemSize(0, 10);
+    expect(cachedBounds.getEstimatedSize()).toBe(10);
+    cachedBounds.setItemSize(2, 20);
+    expect(cachedBounds.getEstimatedSize()).toBe(15);
+    cachedBounds.setItemSize(4, 30);
+    expect(cachedBounds.getEstimatedSize()).toBe(20);
+
+    // Bounds offsets based on measured cells; gaps should be filled in by averages
+    expect(cachedBounds.getItemBounds(0)).toEqual({
+      scrollOffset: 0,
+      size: 10
+    });
+    expect(cachedBounds.getItemBounds(1)).toBeUndefined();
+    expect(cachedBounds.getItemBounds(2)).toEqual({
+      scrollOffset: 30,
+      size: 20
+    });
+    expect(cachedBounds.getItemBounds(3)).toBeUndefined();
+    expect(cachedBounds.getItemBounds(4)).toEqual({
+      scrollOffset: 70,
+      size: 30
+    });
+  });
 });

lib/core/createCachedBounds.ts

@@ -1,5 +1,5 @@
 import { assert } from "../utils/assert";
-import type { Bounds, CachedBounds, SizeFunction } from "./types";
+import type { CachedBounds, SizeFunction } from "./types";
 
 export function createCachedBounds<Props extends object>({
   itemCount,
@@ -8,66 +8,89 @@ export function createCachedBounds<Props extends object>({
 }: {
   itemCount: number;
   itemProps: Props;
-  itemSize: number | SizeFunction<Props>;
+  itemSize: number | SizeFunction<Props> | undefined;
 }): CachedBounds {
-  const cache = new Map<number, Bounds>();
+  const cache = new Map<number, number>();
+
+  let lastContiguousMeasuredIndex = -1;
+  let totalSize = 0;
 
   const api = {
     getEstimatedSize() {
       if (itemCount === 0) {
         return 0;
       } else {
-        const bounds = api.getItemBounds(cache.size === 0 ? 0 : cache.size - 1);
-        assert(bounds, "Unexpected bounds cache miss");
+        if (cache.size === 0 && itemSize !== undefined) {
+          // If possible, lazily measure the first row so we can estimate a size
+          api.getItemBounds(0);
+        }
 
-        return (bounds.scrollOffset + bounds.size) / cache.size;
+        return cache.size === 0 ? undefined : totalSize / cache.size;
       }
     },
     getItemBounds(index: number) {
       assert(index < itemCount, `Invalid index ${index}`);
 
-      while (cache.size - 1 < index) {
-        const currentIndex = cache.size;
+      let size: number | undefined = undefined;
 
-        let size: number = 0;
-        switch (typeof itemSize) {
-          case "function": {
-            size = itemSize(currentIndex, itemProps);
-            break;
-          }
-          case "number": {
-            size = itemSize;
-            break;
+      if (itemSize) {
+        while (cache.size <= index) {
+          const currentIndex = cache.size;
+
+          switch (typeof itemSize) {
+            case "function": {
+              size = itemSize(currentIndex, itemProps);
+              break;
+            }
+            case "number": {
+              size = itemSize;
+              break;
+            }
           }
+
+          lastContiguousMeasuredIndex = currentIndex;
+          totalSize += size;
+
+          cache.set(currentIndex, size);
         }
 
-        if (currentIndex === 0) {
-          cache.set(currentIndex, {
-            scrollOffset: 0,
-            size
-          });
-        } else {
-          const previousRowBounds = cache.get(currentIndex - 1);
-          assert(
-            previousRowBounds !== undefined,
-            `Unexpected bounds cache miss for index ${index}`
-          );
-
-          cache.set(currentIndex, {
-            scrollOffset:
-              previousRowBounds.scrollOffset + previousRowBounds.size,
-            size
-          });
+        size = cache.get(index);
+      } else {
+        size = cache.get(index);
+      }
+
+      if (size !== undefined) {
+        const averageSize = api.getEstimatedSize() ?? 0;
+
+        let scrollOffset = 0;
+
+        while (index > 0) {
+          index--;
+          scrollOffset += cache.get(index) ?? averageSize;
         }
+
+        return {
+          scrollOffset,
+          size
+        };
+      }
+    },
+    hasItemBounds(index: number) {
+      return cache.has(index);
+    },
+    setItemSize(index: number, size: number) {
+      const prevSize = cache.get(index);
+      if (prevSize !== undefined) {
+        totalSize -= prevSize;
       }
 
-      const bounds = cache.get(index);
-      assert(
-        bounds !== undefined,
-        `Unexpected bounds cache miss for index ${index}`
-      );
+      totalSize += size;
+
+      if (index === lastContiguousMeasuredIndex + 1) {
+        lastContiguousMeasuredIndex = index;
+      }
 
-      return bounds;
+      cache.set(index, size);
     },
     get size() {
       return cache.size;

lib/core/getEstimatedSize.test.ts

@@ -100,4 +100,48 @@ describe("getEstimatedSize", () => {
       ).toBe(250);
     });
   });
+
+  describe("itemSize: undefined (lazily measured)", () => {
+    test("should return undefined if no measurements have been taken", () => {
+      expect(
+        getEstimatedSize({
+          cachedBounds: createCachedBounds({
+            itemCount: 10,
+            itemProps: EMPTY_OBJECT,
+            itemSize: undefined
+          }),
+          itemCount: 10,
+          itemSize: undefined
+        })
+      ).toBeUndefined();
+    });
+
+    test("should return an estimated size based on measurements that have been taken", () => {
+      const cachedBounds = createCachedBounds({
+        itemCount: 10,
+        itemProps: EMPTY_OBJECT,
+        itemSize: undefined
+      });
+      cachedBounds.setItemSize(0, 10);
+      cachedBounds.setItemSize(1, 20);
+
+      expect(
+        getEstimatedSize({
+          cachedBounds,
+          itemCount: 10,
+          itemSize: undefined
+        })
+      ).toBe(150);
+
+      cachedBounds.setItemSize(2, 30);
+
+      expect(
+        getEstimatedSize({
+          cachedBounds,
+          itemCount: 10,
+          itemSize: undefined
+        })
+      ).toBe(200);
+    });
+  });
 });

lib/core/getEstimatedSize.ts

@@ -1,4 +1,5 @@
 import type { CachedBounds, SizeFunction } from "./types";
+import { assert } from "../utils/assert";
 
 export function getEstimatedSize<Props extends object>({
   cachedBounds,
@@ -7,7 +8,7 @@ export function getEstimatedSize<Props extends object>({
 }: {
   cachedBounds: CachedBounds;
   itemCount: number;
-  itemSize: number | SizeFunction<Props>;
+  itemSize: number | SizeFunction<Props> | undefined;
 }) {
   if (itemCount === 0) {
     return 0;
@@ -17,6 +18,7 @@ export function getEstimatedSize<Props extends object>({
         const bounds = cachedBounds.getItemBounds(
           cachedBounds.size === 0 ? 0 : cachedBounds.size - 1
         );
+        assert(bounds !== undefined, "Unexpected bounds cache miss");
 
         const averageItemSize =
           (bounds.scrollOffset + bounds.size) / cachedBounds.size;
@@ -26,6 +28,12 @@ export function getEstimatedSize<Props extends object>({
       case "number": {
         return itemCount * itemSize;
       }
+      default: {
+        const estimatedSize = cachedBounds.getEstimatedSize();
+        if (estimatedSize !== undefined) {
+          return estimatedSize * itemCount;
+        }
+      }
     }
   }
 }