Relax List rowHeight constraint (alt)

Author: bvaughn

lib/components/list/List.test.tsx

@@ -7,10 +7,12 @@ import {
   disableResizeObserverForCurrentTest,
   setDefaultElementSize,
   setElementSize,
+  setElementSizeFunction,
   simulateUnsupportedEnvironmentForTest
 } from "../../utils/test/mockResizeObserver";
-import { List } from "./List";
+import { DATA_ATTRIBUTE_LIST_INDEX, List } from "./List";
 import { type ListImperativeAPI, type RowComponentProps } from "./types";
+import { useDynamicRowHeight } from "./useDynamicRowHeight";
 import { useListCallbackRef } from "./useListCallbackRef";
 
 describe("List", () => {
@@ -555,6 +557,70 @@ describe("List", () => {
 
       expect(container.querySelectorAll('[role="listitem"]')).toHaveLength(4);
     });
+
+    test("type: DynamicRowHeight", () => {
+      const onRowsRendered = vi.fn();
+
+      function Example() {
+        const rowHeight = useDynamicRowHeight({
+          defaultRowHeight: 25
+        });
+
+        return (
+          <List
+            defaultHeight={100}
+            overscanCount={0}
+            onRowsRendered={onRowsRendered}
+            rowCount={10}
+            rowComponent={RowComponent}
+            rowHeight={rowHeight}
+            rowProps={EMPTY_OBJECT}
+          />
+        );
+      }
+
+      setElementSizeFunction((element) => {
+        const attribute = element.getAttribute(DATA_ATTRIBUTE_LIST_INDEX);
+        if (attribute !== null) {
+          const index = parseInt(attribute);
+          if (!Number.isNaN(index)) {
+            return new DOMRect(0, 0, 100, (index + 1) * 20);
+          }
+        }
+      });
+
+      const { container } = render(<Example />);
+
+      // 4 rows based on initial estimate
+      // 3 rows after actual sizes have been measured
+      expect(onRowsRendered).toHaveBeenCalledTimes(2);
+      expect(onRowsRendered).nthCalledWith(
+        1,
+        {
+          startIndex: 0,
+          stopIndex: 3
+        },
+        {
+          startIndex: 0,
+          stopIndex: 3
+        }
+      );
+      expect(onRowsRendered).nthCalledWith(
+        2,
+        {
+          startIndex: 0,
+          stopIndex: 2
+        },
+        {
+          startIndex: 0,
+          stopIndex: 2
+        }
+      );
+
+      expect(
+        container.querySelector<HTMLDivElement>("[aria-hidden]")?.style.height
+      ).toBe("500px");
+    });
   });
 
   describe("edge cases", () => {

lib/components/list/List.tsx

@@ -8,11 +8,15 @@ import {
   type ReactNode
 } from "react";
 import { useVirtualizer } from "../../core/useVirtualizer";
+import { useIsomorphicLayoutEffect } from "../../hooks/useIsomorphicLayoutEffect";
 import { useMemoizedObject } from "../../hooks/useMemoizedObject";
 import type { Align, TagNames } from "../../types";
 import { arePropsEqual } from "../../utils/arePropsEqual";
+import { isDynamicRowHeight as isDynamicRowHeightUtil } from "./isDynamicRowHeight";
 import type { ListProps } from "./types";
 
+export const DATA_ATTRIBUTE_LIST_INDEX = "data-react-window-index";
+
 export function List<
   RowProps extends object,
   TagName extends TagNames = "div"
@@ -26,7 +30,7 @@ export function List<
   overscanCount = 3,
   rowComponent: RowComponentProp,
   rowCount,
-  rowHeight,
+  rowHeight: rowHeightProp,
   rowProps: rowPropsUnstable,
   tagName = "div" as TagName,
   style,
@@ -40,6 +44,21 @@ export function List<
 
   const [element, setElement] = useState<HTMLDivElement | null>(null);
 
+  const isDynamicRowHeight = isDynamicRowHeightUtil(rowHeightProp);
+
+  const rowHeight = useMemo(() => {
+    if (isDynamicRowHeight) {
+      return (index: number) => {
+        return (
+          rowHeightProp.getRowHeight(index) ??
+          rowHeightProp.getAverageRowHeight()
+        );
+      };
+    }
+
+    return rowHeightProp;
+  }, [isDynamicRowHeight, rowHeightProp]);
+
   const {
     getCellBounds,
     getEstimatedSize,
@@ -93,6 +112,34 @@ export function List<
     [element, scrollToIndex]
   );
 
+  useIsomorphicLayoutEffect(() => {
+    if (!element) {
+      return;
+    }
+
+    const rows = Array.from(element.children).filter((item, index) => {
+      if (item.hasAttribute("aria-hidden")) {
+        // Ignore sizing element
+        return false;
+      }
+
+      const attribute = `${startIndexOverscan + index}`;
+      item.setAttribute(DATA_ATTRIBUTE_LIST_INDEX, attribute);
+
+      return true;
+    });
+
+    if (isDynamicRowHeight) {
+      return rowHeightProp.observeRowElements(rows);
+    }
+  }, [
+    element,
+    isDynamicRowHeight,
+    rowHeightProp,
+    startIndexOverscan,
+    stopIndexOverscan
+  ]);
+
   useEffect(() => {
     if (startIndexOverscan >= 0 && stopIndexOverscan >= 0 && onRowsRendered) {
       onRowsRendered(
@@ -138,7 +185,9 @@ export function List<
               position: "absolute",
               left: 0,
               transform: `translateY(${bounds.scrollOffset}px)`,
-              height: bounds.size,
+              // In case of dynamic row heights, don't specify a height style
+              // otherwise a default/estimated height would mask the actual height
+              height: isDynamicRowHeight ? undefined : bounds.size,
               width: "100%"
             }}
           />
@@ -149,6 +198,7 @@ export function List<
   }, [
     RowComponent,
     getCellBounds,
+    isDynamicRowHeight,
     rowCount,
     rowProps,
     startIndexOverscan,

lib/components/list/isDynamicRowHeight.ts

@@ -0,0 +1,10 @@
+import type { DynamicRowHeight } from "./types";
+
+export function isDynamicRowHeight(value: unknown): value is DynamicRowHeight {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "getAverageRowHeight" in value &&
+    typeof value.getAverageRowHeight === "function"
+  );
+}

lib/components/list/types.ts

@@ -7,6 +7,13 @@ import type {
 } from "react";
 import type { TagNames } from "../../types";
 
+export type DynamicRowHeight = {
+  getAverageRowHeight(): number;
+  getRowHeight(index: number): number | undefined;
+  setRowHeight(index: number, size: number): void;
+  observeRowElements: (elements: Element[] | NodeListOf<Element>) => () => void;
+};
+
 type ForbiddenKeys = "ariaAttributes" | "index" | "style";
 type ExcludeForbiddenKeys<Type> = {
   [Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
@@ -95,8 +102,16 @@ 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`
+   * - dynamic row height cache returned by the `useDynamicRowHeight` hook
+   *
+   * ⚠️ Dynamic row heights are not as efficient as predetermined sizes.
+   * It's recommended to provide your own height values if they can be determined ahead of time.
    */
-  rowHeight: number | string | ((index: number, cellProps: RowProps) => number);
+  rowHeight:
+    | number
+    | string
+    | ((index: number, cellProps: RowProps) => number)
+    | DynamicRowHeight;
 
   /**
    * Additional props to be passed to the row-rendering component.