react-window 2.3.3 → 2.4.0

package/dist/react-window.d.ts

@@ -33,7 +33,7 @@ declare type ForbiddenKeys = "ariaAttributes" | "columnIndex" | "rowIndex" | "st
 
 declare type ForbiddenKeys_2 = "ariaAttributes" | "index" | "style";
 
-export declare function getScrollbarSize(recalculate?: boolean): number;
+export declare function getScrollbarSize(recalculate?: boolean, ownerDocument?: Document | undefined): number;
 
 /**
  * Renders data with many rows and columns.
@@ -41,27 +41,27 @@ export declare function getScrollbarSize(recalculate?: boolean): number;
  * ℹ️ Unlike `List` rows, `Grid` cell sizes must be known ahead of time.
  * Either static sizes or something that can be derived (from the data in `CellProps`) without rendering.
  */
-export declare function Grid<CellProps extends object, TagName extends TagNames = "div">({ cellComponent: CellComponentProp, cellProps: cellPropsUnstable, children, className, columnCount, columnKey, columnWidth, defaultHeight, defaultWidth, dir, gridRef, onCellsRendered, onResize, overscanCount, rowCount, rowHeight, rowKey, style, tagName, ...rest }: GridProps<CellProps, TagName>): ReactElement;
+export declare function Grid<CellProps extends object, TagName extends TagNames = "div">({ cellComponent: CellComponentProp, cellProps: cellPropsUnstable, children, className, columnCount, columnKey, columnWidth, defaultHeight, defaultScrollLeft, defaultScrollTop, defaultWidth, dir, gridRef, onCellsRendered, onResize, overscanCount, rowCount, rowHeight, rowKey, style, tagName, ...rest }: GridProps<CellProps, TagName>): ReactElement;
 
 /**
  * Ref used to interact with this component's imperative API.
  *
  * This API has imperative methods for scrolling and a getter for the outermost DOM element.
  *
- * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+ * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience in TypeScript projects.
  */
 export declare interface GridImperativeAPI {
     /**
-     * Outermost HTML element for the grid if mounted and null (if not mounted.
+     * Outermost HTML element for the grid if mounted and null if not mounted.
      */
     get element(): HTMLDivElement | null;
     /**
      * Scrolls the grid so that the specified row and column are visible.
      *
      * @param behavior Determines whether scrolling is instant or animates smoothly
-     * @param columnAlign Determines the horizontal alignment of the element within the list
+     * @param columnAlign Determines the horizontal alignment of the element within the grid
      * @param columnIndex Index of the column to scroll to (0-based)
-     * @param rowAlign Determines the vertical alignment of the element within the list
+     * @param rowAlign Determines the vertical alignment of the element within the grid
      * @param rowIndex Index of the row to scroll to (0-based)
      *
      * @throws RangeError if an invalid row or column index is provided
@@ -76,7 +76,7 @@ export declare interface GridImperativeAPI {
     /**
      * Scrolls the grid so that the specified column is visible.
      *
-     * @param align Determines the horizontal alignment of the element within the list
+     * @param align Determines the horizontal alignment of the element within the grid
      * @param behavior Determines whether scrolling is instant or animates smoothly
      * @param index Index of the column to scroll to (0-based)
      *
@@ -90,7 +90,7 @@ export declare interface GridImperativeAPI {
     /**
      * Scrolls the grid so that the specified row is visible.
      *
-     * @param align Determines the vertical alignment of the element within the list
+     * @param align Determines the vertical alignment of the element within the grid
      * @param behavior Determines whether scrolling is instant or animates smoothly
      * @param index Index of the row to scroll to (0-based)
      *
@@ -107,7 +107,7 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
     /**
      * React component responsible for rendering a cell.
      *
-     * This component will receive an `index` and `style` prop by default.
+     * This component will receive `columnIndex`, `rowIndex`, and `style` props by default.
      * Additionally it will receive prop values passed to `cellProps`.
      *
      * ℹ️ The prop types for this component are exported as `CellComponentProps`
@@ -162,41 +162,74 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
      * - number of pixels (number)
      * - percentage of the grid's current width (string)
      * - function that returns the column width (in pixels) given an index and `cellProps`
+     *
+     * ℹ️ Percentage widths can't be resolved during server rendering unless a `defaultWidth` (or a pixel width via the `style` prop) is specified.
      */
     columnWidth: number | string | ((index: number, cellProps: CellProps) => number);
     /**
-     * Default height of grid for initial render.
-     * This value is important for server rendering.
+     * Default height of grid (in pixels) for initial render, before its actual height has been measured.
+     *
+     * ℹ️ Grids can't be measured during server rendering, so this value determines how many rows are server rendered.
+     * It's recommended to set this to the expected height of the grid (or to specify a pixel height via the `style` prop).
      */
     defaultHeight?: number;
     /**
-     * Default width of grid for initial render.
-     * This value is important for server rendering.
+     * Initial horizontal scroll offset (in pixels) of the grid.
+     * This value is only applied once, when the grid first mounts with at least one column.
+     *
+     * ℹ️ Server-rendered HTML can't be pre-scrolled, so server rendering always starts at the first column;
+     * the default scroll offset is applied once the grid hydrates.
+     *
+     * ⚠️ If the grid can't be scrolled that far when the offset is applied (e.g. it is hidden with `display: none`,
+     * or uses percentage column widths before its width has been measured), the offset is clamped or ignored and not retried.
+     * Specify a `defaultWidth` (or a pixel width via the `style` prop) when using percentage column widths.
+     */
+    defaultScrollLeft?: number;
+    /**
+     * Initial vertical scroll offset (in pixels) of the grid.
+     * This value is only applied once, when the grid first mounts with at least one row.
+     *
+     * ℹ️ Server-rendered HTML can't be pre-scrolled, so server rendering always starts at the first row;
+     * the default scroll offset is applied once the grid hydrates.
+     *
+     * ⚠️ If the grid can't be scrolled that far when the offset is applied (e.g. it is hidden with `display: none`,
+     * or uses percentage row heights before its height has been measured), the offset is clamped or ignored and not retried.
+     * Specify a `defaultHeight` (or a pixel height via the `style` prop) when using percentage row heights.
+     */
+    defaultScrollTop?: number;
+    /**
+     * Default width of grid (in pixels) for initial render, before its actual width has been measured.
+     *
+     * ℹ️ Grids can't be measured during server rendering, so this value determines how many columns are server rendered.
+     * It's recommended to set this to the expected width of the grid (or to specify a pixel width via the `style` prop).
      */
     defaultWidth?: number;
     /**
      * Indicates the directionality of grid cells.
      *
+     * ℹ️ The directionality of an ancestor element can't be detected during server rendering;
+     * specify this prop explicitly for server-rendered right-to-left grids.
+     *
      * ℹ️ See HTML `dir` [global attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/dir) for more information.
      */
     dir?: "ltr" | "rtl";
     /**
      * Imperative Grid API.
      *
-     * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+     * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience in TypeScript projects.
      */
     gridRef?: Ref<{
         /**
-         * Outermost HTML element for the grid if mounted and null (if not mounted.
+         * Outermost HTML element for the grid if mounted and null if not mounted.
          */
         get element(): HTMLDivElement | null;
         /**
          * Scrolls the grid so that the specified row and column are visible.
          *
          * @param behavior Determines whether scrolling is instant or animates smoothly
-         * @param columnAlign Determines the horizontal alignment of the element within the list
+         * @param columnAlign Determines the horizontal alignment of the element within the grid
          * @param columnIndex Index of the column to scroll to (0-based)
-         * @param rowAlign Determines the vertical alignment of the element within the list
+         * @param rowAlign Determines the vertical alignment of the element within the grid
          * @param rowIndex Index of the row to scroll to (0-based)
          *
          * @throws RangeError if an invalid row or column index is provided
@@ -211,7 +244,7 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
         /**
          * Scrolls the grid so that the specified column is visible.
          *
-         * @param align Determines the horizontal alignment of the element within the list
+         * @param align Determines the horizontal alignment of the element within the grid
          * @param behavior Determines whether scrolling is instant or animates smoothly
          * @param index Index of the column to scroll to (0-based)
          *
@@ -225,7 +258,7 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
         /**
          * Scrolls the grid so that the specified row is visible.
          *
-         * @param align Determines the vertical alignment of the element within the list
+         * @param align Determines the vertical alignment of the element within the grid
          * @param behavior Determines whether scrolling is instant or animates smoothly
          * @param index Index of the row to scroll to (0-based)
          *
@@ -276,6 +309,8 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
      * - 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`
+     *
+     * ℹ️ Percentage heights can't be resolved during server rendering unless a `defaultHeight` (or a pixel height via the `style` prop) is specified.
      */
     rowHeight: number | string | ((index: number, cellProps: CellProps) => number);
     /**
@@ -299,8 +334,8 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
      */
     style?: CSSProperties;
     /**
-     * Can be used to override the root HTML element rendered by the List component.
-     * The default value is "div", meaning that List renders an HTMLDivElement as its root.
+     * Can be used to override the root HTML element rendered by the Grid component.
+     * The default value is "div", meaning that Grid renders an HTMLDivElement as its root.
      *
      * ⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
      */
@@ -310,16 +345,16 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
 /**
  * Renders data with many rows.
  */
-export declare function List<RowProps extends object, TagName extends TagNames = "div">({ children, className, defaultHeight, listRef, onResize, onRowsRendered, overscanCount, rowComponent: RowComponentProp, rowCount, rowHeight: rowHeightProp, rowKey, rowProps: rowPropsUnstable, tagName, style, ...rest }: ListProps<RowProps, TagName>): ReactElement;
+export declare function List<RowProps extends object, TagName extends TagNames = "div">({ children, className, defaultHeight, defaultScrollOffset, listRef, onResize, onRowsRendered, overscanCount, rowComponent: RowComponentProp, rowCount, rowHeight: rowHeightProp, rowKey, rowProps: rowPropsUnstable, tagName, style, ...rest }: ListProps<RowProps, TagName>): ReactElement;
 
 /**
  * Imperative List API.
  *
- * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
+ * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience in TypeScript projects.
  */
 export declare interface ListImperativeAPI {
     /**
-     * Outermost HTML element for the list if mounted and null (if not mounted.
+     * Outermost HTML element for the list if mounted and null if not mounted.
      */
     get element(): HTMLDivElement | null;
     /**
@@ -346,7 +381,7 @@ export declare interface ListImperativeAPI {
 
 export declare type ListProps<RowProps extends object, TagName extends TagNames = "div"> = Omit<HTMLAttributes<HTMLDivElement>, "onResize"> & {
     /**
-     * Additional content to be rendered within the list (above cells).
+     * Additional content to be rendered within the list (above rows).
      * This property can be used to render things like overlays or tooltips.
      */
     children?: ReactNode;
@@ -355,20 +390,34 @@ export declare type ListProps<RowProps extends object, TagName extends TagNames
      */
     className?: string;
     /**
-     * Default height of list for initial render.
-     * This value is important for server rendering.
+     * Default height of list (in pixels) for initial render, before its actual height has been measured.
+     *
+     * ℹ️ Lists can't be measured during server rendering, so this value determines how many rows are server rendered.
+     * It's recommended to set this to the expected height of the list (or to specify a pixel height via the `style` prop).
      */
     defaultHeight?: number;
+    /**
+     * Initial scroll offset (in pixels) of the list.
+     * This value is only applied once, when the list first mounts with at least one row.
+     *
+     * ℹ️ Server-rendered HTML can't be pre-scrolled, so server rendering always starts at the first row;
+     * the default scroll offset is applied once the list hydrates.
+     *
+     * ⚠️ If the list can't be scrolled that far when the offset is applied (e.g. it is hidden with `display: none`,
+     * or uses percentage row heights before its height has been measured), the offset is clamped or ignored and not retried.
+     * Specify a `defaultHeight` (or a pixel height via the `style` prop) when using percentage row heights.
+     */
+    defaultScrollOffset?: number;
     /**
      * Ref used to interact with this component's imperative API.
      *
      * This API has imperative methods for scrolling and a getter for the outermost DOM element.
      *
-     * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
+     * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience in TypeScript projects.
      */
     listRef?: Ref<{
         /**
-         * Outermost HTML element for the list if mounted and null (if not mounted.
+         * Outermost HTML element for the list if mounted and null if not mounted.
          */
         get element(): HTMLDivElement | null;
         /**
@@ -442,10 +491,12 @@ export declare type ListProps<RowProps extends object, TagName extends TagNames
     /**
      * Row height; the following formats are supported:
      * - 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`
+     * - percentage of the list's current height (string)
+     * - function that returns the row height (in pixels) given an index and `rowProps`
      * - dynamic row height cache returned by the `useDynamicRowHeight` hook
      *
+     * ℹ️ Percentage heights can't be resolved during server rendering unless a `defaultHeight` (or a pixel height via the `style` prop) is specified.
+     *
      * ⚠️ 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.
      */
@@ -489,8 +540,25 @@ export declare type RowComponentProps<RowProps extends object = object> = Compon
 
 declare type TagNames = keyof JSX.IntrinsicElements;
 
-export declare function useDynamicRowHeight({ defaultRowHeight, key }: {
+export declare function useDynamicRowHeight({ defaultRowHeight, initialRowHeights, key }: {
+    /**
+     * Estimated height (in pixels) of rows that have not yet been measured.
+     */
     defaultRowHeight: number;
+    /**
+     * Row heights (in pixels) that are known or can be estimated ahead of time, e.g. estimated from each row's content.
+     * This can be either an array (where each item is the height of the row at that index) or a Map of row index to height.
+     *
+     * These values are used in place of `defaultRowHeight` until rows are rendered and measured,
+     * so providing them can make server-rendered lists and initial scroll positions more accurate.
+     *
+     * ℹ️ This value is only read when the hook first mounts and when the `key` changes.
+     */
+    initialRowHeights?: ReadonlyMap<number, number> | readonly number[];
+    /**
+     * Changing this value clears all measured row heights,
+     * e.g. when the list renders a different set of data.
+     */
     key?: string | number;
 }): DynamicRowHeight;