Relax List rowHeight constraint (alt) (#857)

Author: bvaughn

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.2.0
+
+- Support for dynamic row heights via new `useDynamicRowHeight` hook.
+
+```tsx
+const rowHeight = useDynamicRowHeight({
+  defaultRowHeight: 50
+});
+
+return <List rowHeight={rowHeight} {...rest} />;
+```
+
+- Smaller NPM bundle; (docs are no longer included as part of the bundle due to the added size)
+
 ## 2.1.2
 
 Prevent `ResizeObserver` API from being called at all if an explicit `List` height (or `Grid` width and height) is provided.

README.md

@@ -28,16 +28,6 @@ npm install react-window
 
 Documentation for this project is available at [react-window.vercel.app](https://react-window.vercel.app/).
 
-Each release also ships with its own copy of the documentation (in the `docs` folder) which can be viewed by running:
-
-```sh
-# From the package directory
-npx serve -s docs
-
-# Or as an NPM-installed dependency
-npx serve -s ./node_modules/react-window/docs
-```
-
 > **Note**: Older version 1.x documentation can be found at [react-window-v1.vercel.app](https://react-window-v1.vercel.app/) or on the NPM page for a specific version, e.g. [1.8.11](https://www.npmjs.com/package/react-window/v/1.8.11).)
 
 ## TypeScript types

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,126 @@ describe("List", () => {
 
       expect(container.querySelectorAll('[role="listitem"]')).toHaveLength(4);
     });
+
+    describe("type: DynamicRowHeight", () => {
+      let onRowsRendered: ReturnType<typeof 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}
+          />
+        );
+      }
+
+      function setMockRowHeights(
+        indexToHeight: Map<number, number>,
+        defaultHeight: number = 25
+      ) {
+        setElementSizeFunction((element) => {
+          const attribute = element.getAttribute(DATA_ATTRIBUTE_LIST_INDEX);
+          if (attribute !== null) {
+            const index = parseInt(attribute);
+            const height = indexToHeight.get(index) ?? defaultHeight;
+            return new DOMRect(0, 0, 100, height);
+          }
+        });
+      }
+
+      beforeEach(() => {
+        onRowsRendered = vi.fn();
+      });
+
+      test("initial measuring", () => {
+        setMockRowHeights(
+          new Map([
+            [0, 20],
+            [1, 40],
+            [2, 60],
+            [3, 80]
+          ])
+        );
+
+        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");
+      });
+
+      test("caching and invalidation", () => {
+        setMockRowHeights(
+          new Map([
+            [0, 20],
+            [1, 40],
+            [2, 60],
+            [3, 80]
+          ])
+        );
+
+        render(<Example />);
+
+        expect(RowComponent).toHaveBeenCalledTimes(4 + 3);
+
+        RowComponent.mockReset();
+
+        act(() => {
+          setMockRowHeights(
+            new Map([
+              [0, 20],
+              [1, 50], // Changed
+              [2, 60],
+              [3, 80]
+            ])
+          );
+        });
+
+        // Only the row that has been nudged down should be re-rendered;
+        // the other two should be memoized
+        expect(RowComponent).toHaveBeenCalledTimes(1);
+        expect(RowComponent).toHaveBeenLastCalledWith(
+          expect.objectContaining({
+            index: 2
+          }),
+          undefined
+        );
+      });
+    });
   });
 
   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.