Add Grid imperative API

Author: bvaughn

generated/docs/Grid.json

@@ -149,6 +149,45 @@
         ]
       }
     },
+    "gridRef": {
+      "defaultValue": null,
+      "description": "Ref used to interact with this component's imperative API.\n\nThis API has imperative methods for scrolling and a getter for the outermost DOM element.\n\n⚠️ The `useGridRef` hook is exported for convenience use in TypeScript projects.",
+      "name": "gridRef",
+      "declarations": [
+        {
+          "fileName": "react-window/lib/components/grid/types.ts",
+          "name": "TypeLiteral"
+        }
+      ],
+      "required": false,
+      "type": {
+        "name": "enum",
+        "raw": "Ref<GridImperativeAPI> | undefined",
+        "value": [
+          {
+            "value": "undefined"
+          },
+          {
+            "value": "null"
+          },
+          {
+            "value": "(instance: GridImperativeAPI | null) => void | (() => VoidOrUndefinedOnly)",
+            "description": "",
+            "fullComment": "",
+            "tags": {}
+          },
+          {
+            "value": "RefObject<GridImperativeAPI | null>",
+            "description": "Created by {@link createRef}, or {@link useRef} when passed `null`.",
+            "fullComment": "Created by {@link createRef}, or {@link useRef} when passed `null`.\n@template T The type of the ref's value.\n@example ```tsx\nconst ref = createRef<HTMLDivElement>();\n\nref.current = document.createElement('div'); // Error\n```",
+            "tags": {
+              "template": "T The type of the ref's value.",
+              "example": "```tsx\nconst ref = createRef<HTMLDivElement>();\n\nref.current = document.createElement('div'); // Error\n```"
+            }
+          }
+        ]
+      }
+    },
     "onCellsRendered": {
       "defaultValue": null,
       "description": "Callback notified when the range of rendered cells changes.",

generated/examples/CellComponent.example.jsx

@@ -0,0 +1,27 @@
+function CellComponent({ contacts, columnIndex, rowIndex, style }) {
+  // Column and header rows shown for example purposes; (they aren't required)
+  if (columnIndex === 0 && rowIndex === 0) {
+    return null;
+  } else if (rowIndex === 0) {
+    return (
+      <div className="text-sm font-bold" style={style}>
+        Column {columnIndex}
+      </div>
+    );
+  } else if (columnIndex === 0) {
+    return (
+      <div className="text-sm font-bold" style={style}>
+        Row {rowIndex}
+      </div>
+    );
+  }
+
+  const address = contacts[rowIndex - 1];
+  const content = address[indexToColumn(columnIndex - 1)];
+
+  return (
+    <div className="truncate" style={style}>
+      {content}
+    </div>
+  );
+}

generated/examples/CellComponent.example.tsx

@@ -0,0 +1,32 @@
+function CellComponent({
+  contacts,
+  columnIndex,
+  rowIndex,
+  style,
+}: GridComponentProps<CellProps>) {
+  // Column and header rows shown for example purposes; (they aren't required)
+  if (columnIndex === 0 && rowIndex === 0) {
+    return null;
+  } else if (rowIndex === 0) {
+    return (
+      <div className="text-sm font-bold" style={style}>
+        Column {columnIndex}
+      </div>
+    );
+  } else if (columnIndex === 0) {
+    return (
+      <div className="text-sm font-bold" style={style}>
+        Row {rowIndex}
+      </div>
+    );
+  }
+
+  const address = contacts[rowIndex - 1];
+  const content = address[indexToColumn(columnIndex - 1)];
+
+  return (
+    <div className="truncate" style={style}>
+      {content}
+    </div>
+  );
+}

generated/examples/Grid.example.jsx

@@ -5,44 +5,12 @@ function Example({ contacts }) {
     <Grid
       cellComponent={CellComponent}
       cellProps={{ contacts }}
-      columnCount={10}
+      columnCount={11}
       columnWidth={columnWidth}
-      rowCount={contacts.length}
+      rowCount={
+        contacts.length + 1 // Extra header row
+      }
       rowHeight={25}
     />
   );
 }
-
-function columnWidth(index) {
-  switch (indexToColumn(index)) {
-    case "address": {
-      return 250;
-    }
-    case "email": {
-      return 300;
-    }
-    case "job_title": {
-      return 150;
-    }
-    case "timezone": {
-      return 200;
-    }
-    case "zipcode": {
-      return 75;
-    }
-    default: {
-      return 100;
-    }
-  }
-}
-
-function CellComponent({ contacts, columnIndex, rowIndex, style }) {
-  const address = contacts[rowIndex];
-  const content = address[indexToColumn(columnIndex)];
-
-  return (
-    <div className="truncate" style={style}>
-      {content}
-    </div>
-  );
-}

generated/examples/Grid.example.tsx

@@ -1,4 +1,4 @@
-import { Grid, type GridComponentProps } from "react-window";
+import { Grid } from "react-window";
 
 type CellProps = {
   contacts: Contact[];
@@ -9,49 +9,12 @@ function Example({ contacts }: { contacts: Contact[] }) {
     <Grid
       cellComponent={CellComponent}
       cellProps={{ contacts }}
-      columnCount={10}
+      columnCount={11}
       columnWidth={columnWidth}
-      rowCount={contacts.length}
+      rowCount={
+        contacts.length + 1 // Extra header row
+      }
       rowHeight={25}
     />
   );
-}
-
-function columnWidth(index: number) {
-  switch (indexToColumn(index)) {
-    case "address": {
-      return 250;
-    }
-    case "email": {
-      return 300;
-    }
-    case "job_title": {
-      return 150;
-    }
-    case "timezone": {
-      return 200;
-    }
-    case "zipcode": {
-      return 75;
-    }
-    default: {
-      return 100;
-    }
-  }
-}
-
-function CellComponent({
-  contacts,
-  columnIndex,
-  rowIndex,
-  style,
-}: GridComponentProps<CellProps>) {
-  const address = contacts[rowIndex];
-  const content = address[indexToColumn(columnIndex)];
-
-  return (
-    <div className="truncate" style={style}>
-      {content}
-    </div>
-  );
 }

generated/examples/GridImperativeApi.example.jsx

@@ -0,0 +1,17 @@
+import { Grid } from "react-window";
+import { CellComponent } from "./Grid.example";
+import { columnWidth } from "./columnWidth.example";
+
+export function Example({ contacts, gridRef }) {
+  return (
+    <Grid
+      cellComponent={CellComponent}
+      cellProps={{ contacts }}
+      columnCount={10}
+      columnWidth={columnWidth}
+      gridRef={gridRef}
+      rowCount={contacts.length}
+      rowHeight={25}
+    />
+  );
+}

generated/examples/GridImperativeApi.example.tsx

@@ -0,0 +1,24 @@
+import type { Ref } from "react";
+import { Grid, type GridImperativeAPI } from "react-window";
+import { CellComponent, type Contact } from "./Grid.example";
+import { columnWidth } from "./columnWidth.example";
+
+export function Example({
+  contacts,
+  gridRef,
+}: {
+  contacts: Contact[];
+  gridRef: Ref<GridImperativeAPI>;
+}) {
+  return (
+    <Grid
+      cellComponent={CellComponent}
+      cellProps={{ contacts }}
+      columnCount={10}
+      columnWidth={columnWidth}
+      gridRef={gridRef}
+      rowCount={contacts.length}
+      rowHeight={25}
+    />
+  );
+}

generated/examples/columnWidth.example.js

@@ -0,0 +1,22 @@
+function columnWidth(index) {
+  switch (indexToColumn(index)) {
+    case "address": {
+      return 250;
+    }
+    case "email": {
+      return 300;
+    }
+    case "job_title": {
+      return 150;
+    }
+    case "timezone": {
+      return 200;
+    }
+    case "zipcode": {
+      return 75;
+    }
+    default: {
+      return 100;
+    }
+  }
+}

generated/examples/columnWidth.example.ts

@@ -0,0 +1,22 @@
+function columnWidth(index: number) {
+  switch (indexToColumn(index)) {
+    case "address": {
+      return 250;
+    }
+    case "email": {
+      return 300;
+    }
+    case "job_title": {
+      return 150;
+    }
+    case "timezone": {
+      return 200;
+    }
+    case "zipcode": {
+      return 75;
+    }
+    default: {
+      return 100;
+    }
+  }
+}

generated/examples/gridRefClickEventHandler.example.js

@@ -0,0 +1,10 @@
+const onClick = () => {
+  const grid = gridRef.current;
+  grid?.scrollToCell({
+    behavior: "auto", // optional
+    columnAlign: "auto", // optional
+    columnIndex: 10,
+    rowAlign: "auto", // optional
+    rowIndex: 250,
+  });
+};