Improve component props docs

Author: bvaughn

lib/components/grid/types.ts

@@ -96,7 +96,29 @@ 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(config: {
+      behavior?: "auto" | "instant" | "smooth";
+      columnAlign?: "auto" | "center" | "end" | "smart" | "start";
+      columnIndex: number;
+      rowAlign?: "auto" | "center" | "end" | "smart" | "start";
+      rowIndex: number;
+    }): void;
+
+    scrollToColumn(config: {
+      align?: "auto" | "center" | "end" | "smart" | "start";
+      behavior?: "auto" | "instant" | "smooth";
+      index: number;
+    }): void;
+
+    scrollToRow(config: {
+      align?: "auto" | "center" | "end" | "smart" | "start";
+      behavior?: "auto" | "instant" | "smooth";
+      index: number;
+    }): void;
+  }>;
 
   /**
    * Callback notified when the range of rendered cells changes.

lib/components/list/types.ts

@@ -47,7 +47,15 @@ export type ListProps<
    *
    * ⚠️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
-  listRef?: Ref<ListImperativeAPI>;
+  listRef?: Ref<{
+    get element(): HTMLDivElement | null;
+
+    scrollToRow(config: {
+      align?: "auto" | "center" | "end" | "smart" | "start";
+      behavior?: "auto" | "instant" | "smooth";
+      index: number;
+    }): void;
+  }>;
 
   /**
    * Callback notified when the List's outermost HTMLElement resizes.

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}\"",

public/generated/js-docs/Grid.json

@@ -1,23 +1,17 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
-import { cwd } from "node:process";
-import { getFilesWithExtensions, rmFilesWithExtensions } from "../utils.ts";
-import { syntaxHighlight } from "./syntax-highlight.ts";
+import { initialize } from "./utils/initialize.ts";
+import { syntaxHighlight } from "./utils/syntax-highlight.ts";
+import { trimExcludedText } from "./utils/trimExcludedText.ts";
 
 async function run() {
-  const inputDir = join(cwd(), "src", "routes");
-  const outputDir = join(cwd(), "public", "generated", "code-snippets");
+  const { files, outputDir } = await initialize({
+    fileExtensions: [".html", ".ts", ".tsx"],
+    inputPath: ["src", "routes"],
+    outputDirName: "code-snippets"
+  });
 
-  await mkdir(outputDir, { recursive: true });
-
-  await rmFilesWithExtensions(outputDir, [".json"]);
-
-  const tsFiles = await getFilesWithExtensions(inputDir, [
-    ".html",
-    ".ts",
-    ".tsx"
-  ]);
-  const exampleFiles = tsFiles.filter((file) => file.includes(".example."));
+  const exampleFiles = files.filter((file) => file.includes(".example."));
 
   for (const file of exampleFiles) {
     console.debug("Extracting", file);
@@ -28,14 +22,7 @@ async function run() {
 
     {
       // Remove special comments and directives before syntax highlighting
-      {
-        const pieces = rawText.split("// <begin>");
-        rawText = pieces[pieces.length - 1].trim();
-      }
-      {
-        const pieces = rawText.split("// <end>");
-        rawText = pieces[0].trim();
-      }
+      rawText = trimExcludedText(rawText);
 
       rawText = rawText
         .split("\n")

public/generated/js-docs/List.json

@@ -0,0 +1,105 @@
+import { writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { cwd } from "node:process";
+import { withCustomConfig } from "react-docgen-typescript";
+import type { ComponentMetadata } from "../src/types.ts";
+import { formatDescriptionText } from "./utils/formatDescriptionText.ts";
+import { initialize } from "./utils/initialize.ts";
+import { syntaxHighlight } from "./utils/syntax-highlight.ts";
+
+const parser = withCustomConfig("./tsconfig.json", {
+  savePropValueAsString: true,
+  shouldExtractLiteralValuesFromEnum: true,
+  shouldExtractValuesFromUnion: true
+});
+
+const TOKEN_TO_REPLACE = "TOKEN_TO_REPLACE";
+
+async function run() {
+  const { files, outputDir } = await initialize({
+    fileExtensions: [".ts", ".tsx"],
+    fileFilter: (file) =>
+      file.endsWith("/List.tsx") || file.endsWith("/Grid.tsx"),
+    inputPath: ["lib", "components"],
+    outputDirName: "js-docs"
+  });
+
+  for (const file of files) {
+    console.debug("Parsing", file);
+
+    const parsed = parser.parse(file);
+
+    for (const component of parsed) {
+      // Convert to local paths
+      component.filePath = relative(cwd(), file);
+
+      const componentMetadata: ComponentMetadata = {
+        filePath: component.filePath,
+        name: component.displayName,
+        props: {}
+      };
+
+      // Filter inherited HTML attributes
+      for (const key in component.props) {
+        const prop = component.props[key];
+        if (
+          prop.declarations?.filter(
+            (declaration) => !declaration.fileName.includes("node_modules")
+          ).length === 0
+        ) {
+          delete component.props[key];
+        }
+      }
+
+      // Syntax highlight prop types
+      for (const name in component.props) {
+        const prop = component.props[name];
+
+        let textToFormat = prop.type.raw;
+        if (!textToFormat && prop.type.name.includes(":")) {
+          // Edge case where some prop types aren't registered as containing raw TS
+          textToFormat = prop.type.name;
+        }
+
+        if (!textToFormat) {
+          textToFormat = `${prop.type.name}`;
+        }
+
+        if (prop.defaultValue?.value) {
+          textToFormat = `${textToFormat} = ${prop.defaultValue.value}`;
+        }
+
+        // Format with a placeholder token so we can replace it with a formatted string
+        textToFormat = `${TOKEN_TO_REPLACE}${prop.required ? "" : "?"}: ${textToFormat}`;
+
+        try {
+          let html = await syntaxHighlight(textToFormat, "TS");
+          html = html.replace(
+            TOKEN_TO_REPLACE,
+            `<span class="tok-propertyName">${name}</span>`
+          );
+
+          const [description, warning = ""] = prop.description.split("⚠️");
+
+          componentMetadata.props[name] = {
+            description: formatDescriptionText(description.trim()),
+            html,
+            name,
+            required: prop.required,
+            warning: warning ? formatDescriptionText(warning.trim()) : undefined
+          };
+        } catch (error) {
+          console.error(error);
+        }
+      }
+
+      const outputFile = join(outputDir, `${component.displayName}.json`);
+
+      console.debug("Writing to", outputFile);
+
+      await writeFile(outputFile, JSON.stringify(componentMetadata, null, 2));
+    }
+  }
+}
+
+run();

scripts/code-snippets/ts-to-js.ts

@@ -0,0 +1,6 @@
+export function formatDescriptionText(text: string) {
+  return text
+    .replaceAll("\n- ", "<br/>• ")
+    .replaceAll("\n\n", "<br/><br/>")
+    .replaceAll(/`([^`]+)`/g, "<code>$1</code>");
+}