Improve component props docs

Author: bvaughn

lib/components/grid/types.ts

@@ -40,7 +40,7 @@ export type GridProps<
    * Additional props to be passed to the cell-rendering component.
    * Grid will automatically re-render cells when values in this object change.
    *
-   * ⚠️ This object must not contain either an `index` or `style` prop.
+   * ⚠️ This object must not contain `ariaAttributes`, `index`, or `style` props.
    */
   cellProps: ExcludeForbiddenKeys<CellProps>;
 
@@ -96,7 +96,43 @@ export type GridProps<
    *
    * ⚠️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
-  gridRef?: Ref<GridImperativeAPI>;
+  gridRef?: Ref<{
+    get element(): HTMLDivElement | null;
+
+    scrollToCell({
+      behavior,
+      columnAlign,
+      columnIndex,
+      rowAlign,
+      rowIndex
+    }: {
+      behavior?: "auto" | "instant" | "smooth";
+      columnAlign?: "auto" | "center" | "end" | "smart" | "start";
+      columnIndex: number;
+      rowAlign?: "auto" | "center" | "end" | "smart" | "start";
+      rowIndex: number;
+    }): void;
+
+    scrollToColumn({
+      align,
+      behavior,
+      index
+    }: {
+      align?: "auto" | "center" | "end" | "smart" | "start";
+      behavior?: "auto" | "instant" | "smooth";
+      index: number;
+    }): void;
+
+    scrollToRow({
+      align,
+      behavior,
+      index
+    }: {
+      align?: "auto" | "center" | "end" | "smart" | "start";
+      behavior?: "auto" | "instant" | "smooth";
+      index: number;
+    }): void;
+  }>;
 
   /**
    * Callback notified when the range of rendered cells changes.
@@ -167,55 +203,21 @@ export type CellComponent<CellProps extends object> =
 export type CellComponentProps<CellProps extends object = object> =
   ComponentProps<CellComponent<CellProps>>;
 
+export type GridImperativeAPI<CellProps extends object> = NonNullable<
+  GridProps<CellProps>["gridRef"]
+>;
+
+export type OnCellsRendered = NonNullable<GridProps<object>["onCellsRendered"]>;
+
 export type ScrollState = {
   prevScrollTop: number;
   scrollTop: number;
 };
 
-export type OnCellsRendered = NonNullable<GridProps<object>["onCellsRendered"]>;
-
 export type CachedBounds = Map<
   number,
   {
     height: number;
     scrollTop: number;
   }
 >;
-
-export type GridImperativeAPI = {
-  get element(): HTMLDivElement | null;
-
-  scrollToCell({
-    behavior,
-    columnAlign,
-    columnIndex,
-    rowAlign,
-    rowIndex
-  }: {
-    behavior?: "auto" | "instant" | "smooth";
-    columnAlign?: "auto" | "center" | "end" | "smart" | "start";
-    columnIndex: number;
-    rowAlign?: "auto" | "center" | "end" | "smart" | "start";
-    rowIndex: number;
-  }): void;
-
-  scrollToColumn({
-    align,
-    behavior,
-    index
-  }: {
-    align?: "auto" | "center" | "end" | "smart" | "start";
-    behavior?: "auto" | "instant" | "smooth";
-    index: number;
-  }): void;
-
-  scrollToRow({
-    align,
-    behavior,
-    index
-  }: {
-    align?: "auto" | "center" | "end" | "smart" | "start";
-    behavior?: "auto" | "instant" | "smooth";
-    index: number;
-  }): void;
-};

lib/components/list/types.ts

@@ -47,7 +47,32 @@ export type ListProps<
    *
    * ⚠️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
-  listRef?: Ref<ListImperativeAPI>;
+  listRef?: Ref<{
+    /**
+     * Get root HTMLElement for List or null if it is not mounted.
+     *
+     * @return HTMLDivElement | null
+     */
+    get element(): HTMLDivElement | null;
+
+    /**
+     * Scroll to the specified row.
+     */
+    scrollToRow(config: {
+      /**
+       * How to align the row within the list.
+       */
+      align?: "auto" | "center" | "end" | "smart" | "start";
+      /**
+       * Scrolling behavior.
+       */
+      behavior?: "auto" | "instant" | "smooth";
+      /**
+       * Index of row to scroll to.
+       */
+      index: number;
+    }): void;
+  }>;
 
   /**
    * Callback notified when the List's outermost HTMLElement resizes.
@@ -117,7 +142,7 @@ export type ListProps<
    * Additional props to be passed to the row-rendering component.
    * List will automatically re-render rows when values in this object change.
    *
-   * ⚠️ This object must not contain either an `index` or `style` prop.
+   * ⚠️ This object must not contain `ariaAttributes`, `index`, or `style` props.
    */
   rowProps: ExcludeForbiddenKeys<RowProps>;
 
@@ -144,24 +169,14 @@ export type RowComponentProps<RowProps extends object = object> =
 
 export type OnRowsRendered = NonNullable<ListProps<object>["onRowsRendered"]>;
 
+export type ListImperativeAPI<RowProps extends object> = NonNullable<
+  ListProps<RowProps>["listRef"]
+>;
+
 export type CachedBounds = Map<
   number,
   {
     height: number;
     scrollTop: number;
   }
 >;
-
-export type ListImperativeAPI = {
-  get element(): HTMLDivElement | null;
-
-  scrollToRow({
-    align,
-    behavior,
-    index
-  }: {
-    align?: "auto" | "center" | "end" | "smart" | "start";
-    behavior?: "auto" | "instant" | "smooth";
-    index: number;
-  }): void;
-};

package.json

@@ -24,8 +24,8 @@
     "build:docs": "TARGET=docs vite build",
     "build:lib": "TARGET=lib vite build",
     "compile": "pnpm run compile:code-snippets && pnpm run compile:docs",
-    "compile:code-snippets": "node --loader ts-node/esm ./scripts/code-snippets/run.ts",
-    "compile:docs": "node --loader ts-node/esm ./scripts/docs/run.ts",
+    "compile:code-snippets": "node --loader ts-node/esm ./scripts/compile-code-snippets.ts",
+    "compile:docs": "node --loader ts-node/esm ./scripts/compile-docs.ts",
     "lint": "eslint .",
     "prerelease": "rm -rf dist && pnpm run build:lib",
     "prettier": "prettier --write \"**/*.{css,html,js,json,jsx,ts,tsx}\"",