react-lib-tools 0.0.1

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "react-lib-tools",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "Brian Vaughn <brian.david.vaughn@gmail.com> (https://github.com/bvaughn/)",
+  "contributors": [
+    "Brian Vaughn <brian.david.vaughn@gmail.com> (https://github.com/bvaughn/)"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bvaughn/react-lib-tools.git"
+  },
+  "main": "dist/react-lib-tools.cjs",
+  "module": "dist/react-lib-tools.js",
+  "types": "dist/react-lib-tools.d.ts",
+  "files": [
+    "dist",
+    "scripts",
+    "styles.css"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "pnpm run build:lib && pnpm run build:docs",
+    "build:docs": "TARGET=docs vite build",
+    "build:lib": "TARGET=lib vite build",
+    "lint": "eslint .",
+    "prerelease": "rm -rf dist && pnpm run build:lib",
+    "prettier": "prettier --write \"**/*.{css,html,js,json,jsx,ts,tsx}\"",
+    "prettier:ci": "prettier --check \"**/*.{css,html,js,json,jsx,ts,tsx}\"",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "test:debug": "vitest --inspect-brk=127.0.0.1:3000 --no-file-parallelism",
+    "tsc": "tsc -b"
+  },
+  "lint-staged": {
+    "**/*": "prettier --write --ignore-unknown"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@codemirror/lang-css": "latest",
+    "@codemirror/lang-html": "latest",
+    "@codemirror/lang-javascript": "latest",
+    "@codemirror/lang-markdown": "latest",
+    "@codemirror/language": "latest",
+    "@codemirror/state": "latest",
+    "@csstools/postcss-oklab-function": "^4.0.11",
+    "@eslint/js": "^9.30.1",
+    "@headlessui/react": "^2.2.4",
+    "@headlessui/tailwindcss": "^0.2.2",
+    "@heroicons/react": "^2.2.0",
+    "@lezer/highlight": "latest",
+    "@tailwindcss/vite": "^4.1.11",
+    "@tailwindplus/elements": "^1.0.5",
+    "@testing-library/jest-dom": "^6.6.4",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@ts-ast-parser/core": "^0.8.0",
+    "@types/compression": "^1.8.1",
+    "@types/express": "^5.0.5",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^24.2.0",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react-swc": "^3.10.2",
+    "clsx": "^2.1.1",
+    "compression": "^1.8.1",
+    "csstype": "^3.1.3",
+    "eslint": "^9.30.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "express": "^5.1.0",
+    "globals": "^16.3.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "lint-staged": "^16.1.4",
+    "markdown-it": "^14.1.0",
+    "marked": "^16.4.1",
+    "postcss": "^8.5.6",
+    "prettier": "3.6.2",
+    "prettier-plugin-tailwindcss": "^0.7.1",
+    "react": "^19.2.3",
+    "react-docgen-typescript": "^2.4.0",
+    "react-dom": "^19.2.3",
+    "react-error-boundary": "^6.0.0",
+    "react-router-dom": "^7.6.3",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-visualizer": "^6.0.3",
+    "rollup-preserve-directives": "^1.1.3",
+    "sirv": "^3.0.2",
+    "tailwind-merge": "^3.3.1",
+    "tailwindcss": "^4.1.11",
+    "terser": "^5.43.1",
+    "ts-blank-space": "^0.6.2",
+    "ts-node": "^10.9.2",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.35.1",
+    "typescript-json-schema": "^0.65.1",
+    "vite": "^7.0.4",
+    "vitest-fail-on-console": "^0.10.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-svgr": "^4.3.0",
+    "vitest": "^3.2.4",
+    "zustand": "^5.0.7"
+  }
+}

package/scripts/compile-docs.ts

@@ -0,0 +1,22 @@
+import { compileComponents } from "./utils/docs/compileComponents.ts";
+import { compileImperativeHandles } from "./utils/docs/compileImperativeHandles.ts";
+
+export async function compileDocs({
+  componentNames,
+  imperativeHandleNames,
+  outputDirName = "docs"
+}: {
+  componentNames: string[];
+  imperativeHandleNames: string[];
+  outputDirName?: string | undefined;
+}) {
+  await compileComponents({
+    componentNames,
+    outputDirName
+  });
+
+  await compileImperativeHandles({
+    names: imperativeHandleNames,
+    outputDirName
+  });
+}

package/scripts/compile-examples.ts

@@ -0,0 +1,71 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { initialize } from "./utils/initialize.ts";
+import { syntaxHighlight } from "./utils/syntax-highlight.ts";
+import { trimExcludedText } from "./utils/examples/trimExcludedText.ts";
+
+export async function compileExamples({
+  fileExtensions = [".html", ".ts", ".tsx"],
+  inputPath = ["src", "routes"],
+  outputDirName = "examples"
+}: {
+  fileExtensions?: string[] | undefined;
+  inputPath?: string[] | undefined;
+  outputDirName?: string | undefined;
+} = {}) {
+  const { files, outputDir } = await initialize({
+    fileExtensions,
+    inputPath,
+    outputDirName
+  });
+
+  for (const file of files) {
+    const buffer = await readFile(file);
+
+    let rawText = buffer.toString();
+
+    {
+      // Remove special comments and directives before syntax highlighting
+      rawText = trimExcludedText(rawText);
+
+      rawText = rawText
+        .split("\n")
+        .filter(
+          (line) =>
+            !line.includes("prettier-ignore") &&
+            !line.includes("eslint-disable-next-line") &&
+            !line.includes("@ts-expect-error") &&
+            !line.includes("// hidden")
+        )
+        .join("\n");
+    }
+
+    let html;
+    if (file.endsWith(".html")) {
+      html = await syntaxHighlight(rawText, "HTML");
+    } else if (file.endsWith(".js") || file.endsWith(".jsx")) {
+      html = await syntaxHighlight(
+        rawText,
+        file.endsWith("jsx") ? "JSX" : "JS"
+      );
+    } else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
+      html = await syntaxHighlight(
+        rawText,
+        file.endsWith("tsx") ? "TSX" : "TS"
+      );
+    } else {
+      throw Error(`Unsupported file type: ${file}`);
+    }
+
+    const fileName = basename(file);
+
+    const outputFile = join(
+      outputDir,
+      fileName.replace(/\.example\..+$/, ".json")
+    );
+
+    console.debug("Writing to", outputFile);
+
+    await writeFile(outputFile, JSON.stringify({ html }, null, 2));
+  }
+}

package/scripts/utils/docs/compileComponent.ts

@@ -0,0 +1,116 @@
+import { writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { cwd } from "node:process";
+import { type FileParser, type PropItem } from "react-docgen-typescript";
+import type { ComponentMetadata } from "../../../lib/types.ts";
+import { assert } from "../../../lib/utils/assert.ts";
+import { syntaxHighlight } from "../syntax-highlight.ts";
+import { getPropTypeText } from "./getPropTypeText.ts";
+import { parseDescription } from "./parseDescription.ts";
+import { propsToTable } from "./propsToTable.ts";
+
+const TOKEN_TO_REPLACE = "TOKEN_TO_REPLACE";
+
+export async function compileComponent({
+  filePath,
+  outputDir,
+  parser
+}: {
+  filePath: string;
+  outputDir: string;
+  parser: FileParser;
+}) {
+  const parsed = parser.parse(filePath);
+  assert(
+    parsed.length === 1,
+    `Expected 1 parsed component but found ${parsed.length}`
+  );
+
+  const component = parsed[0];
+
+  // Convert to local paths
+  component.filePath = relative(cwd(), filePath);
+
+  // 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];
+    }
+  }
+
+  // Generate syntax highlighted HTML for prop types
+  {
+    const componentMetadata: ComponentMetadata = {
+      description: await parseDescription(component.description),
+      filePath: component.filePath,
+      name: component.displayName,
+      props: {}
+    };
+
+    for (const name in component.props) {
+      const prop = component.props[name];
+
+      let textToFormat = getPropTypeText(prop);
+
+      if (prop.defaultValue?.value) {
+        const formattedValue =
+          typeof prop.defaultValue.value === "string"
+            ? `"${prop.defaultValue.value}"`
+            : prop.defaultValue.value;
+
+        textToFormat = `${textToFormat} = ${formattedValue}`;
+      }
+
+      // 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>`
+        );
+
+        componentMetadata.props[name] = {
+          description: await parseDescription(prop.description),
+          html,
+          name,
+          required: prop.required
+        };
+      } 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));
+  }
+
+  // Generate markdown for prop types
+  const requiredProps: PropItem[] = [];
+  const optionalProps: PropItem[] = [];
+
+  for (const propName in component.props) {
+    const prop = component.props[propName];
+    if (prop.required) {
+      requiredProps.push(prop);
+    } else {
+      optionalProps.push(prop);
+    }
+  }
+
+  return {
+    componentName: component.displayName,
+    description: component.description,
+    optionalPropsTable: await propsToTable(optionalProps),
+    requiredPropsTable: await propsToTable(requiredProps)
+  };
+}

package/scripts/utils/docs/compileComponents.ts

@@ -0,0 +1,74 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cwd } from "node:process";
+import { withCustomConfig } from "react-docgen-typescript";
+import { initialize } from "../initialize.ts";
+import { compileComponent } from "./compileComponent.ts";
+import { insertPropsMarkdown } from "./insertPropsMarkdown.ts";
+
+export async function compileComponents({
+  componentNames,
+  outputDirName
+}: {
+  componentNames: string[];
+  outputDirName: string;
+}) {
+  const parser = withCustomConfig("./tsconfig.json", {
+    savePropValueAsString: true,
+    shouldExtractLiteralValuesFromEnum: true,
+    shouldExtractValuesFromUnion: true,
+    shouldRemoveUndefinedFromOptional: true
+  });
+
+  const { files, outputDir } = await initialize({
+    fileExtensions: [".ts", ".tsx"],
+    fileFilter: (file) =>
+      componentNames.some((componentName) => file.endsWith(componentName)),
+    inputPath: ["lib", "components"],
+    outputDirName
+  });
+
+  const markdownPath = join(cwd(), "README.md");
+
+  let markdown = await readFile(markdownPath, { encoding: "utf-8" });
+
+  await Promise.all(
+    files.map((filePath) =>
+      compileComponent({
+        filePath,
+        outputDir,
+        parser
+      }).then(
+        ({
+          componentName,
+          description,
+          optionalPropsTable,
+          requiredPropsTable
+        }) => {
+          markdown = insertPropsMarkdown({
+            componentMarkdown: description,
+            componentName,
+            markdown,
+            section: "description"
+          });
+
+          markdown = insertPropsMarkdown({
+            componentMarkdown: requiredPropsTable,
+            componentName,
+            markdown,
+            section: "required-props"
+          });
+
+          markdown = insertPropsMarkdown({
+            componentMarkdown: optionalPropsTable,
+            componentName,
+            markdown,
+            section: "optional-props"
+          });
+        }
+      )
+    )
+  );
+
+  await writeFile(markdownPath, markdown);
+}

package/scripts/utils/docs/compileImperativeHandle.ts

@@ -0,0 +1,48 @@
+import type { InterfaceNode } from "@ts-ast-parser/core";
+import assert from "node:assert";
+import { writeFile } from "node:fs/promises";
+import { join } from "path";
+import type { ImperativeHandleMetadata } from "../../../lib/types.ts";
+import { syntaxHighlight } from "../syntax-highlight.ts";
+import { parseDescription } from "./parseDescription.ts";
+
+export async function compileImperativeHandle({
+  filePath,
+  interfaceNode,
+  outputDir
+}: {
+  filePath: string;
+  interfaceNode: InterfaceNode;
+  outputDir: string;
+}) {
+  const name = interfaceNode.getName();
+
+  const json: ImperativeHandleMetadata = {
+    description: await parseDescription(
+      "" + interfaceNode.getJSDoc().getTag("description")?.text
+    ),
+    filePath,
+    methods: [],
+    name
+  };
+
+  const methods = interfaceNode.getMethods();
+  for (const method of methods) {
+    const jsDoc = method.getJSDoc();
+    assert(jsDoc);
+
+    json.methods.push({
+      description: await parseDescription(
+        "" + jsDoc.getTag("description")?.text
+      ),
+      html: await syntaxHighlight(method.getTSNode().getText(), "TS"),
+      name: method.getName()
+    });
+  }
+
+  const outputFile = join(outputDir, `${name}.json`);
+
+  console.debug("Writing to", outputFile);
+
+  await writeFile(outputFile, JSON.stringify(json, null, 2));
+}

package/scripts/utils/docs/compileImperativeHandles.ts

@@ -0,0 +1,45 @@
+import { parseFromProject, type InterfaceNode } from "@ts-ast-parser/core";
+import tsConfig from "../../../tsconfig.json" with { type: "json" };
+import { compileImperativeHandle } from "./compileImperativeHandle.ts";
+import { join } from "node:path";
+import { cwd } from "node:process";
+
+export async function compileImperativeHandles({
+  names,
+  outputDirName
+}: {
+  names: string[];
+  outputDirName: string;
+}) {
+  const outputDir = join(cwd(), "public", "generated", outputDirName);
+
+  const result = await parseFromProject(tsConfig);
+  const reflectedModules = result.project?.getModules() ?? [];
+
+  const nodes: {
+    filePath: string;
+    node: InterfaceNode;
+  }[] = [];
+
+  names.forEach((name) => {
+    reflectedModules.forEach((reflectedModule) => {
+      const node = reflectedModule.getDeclarationByName(name);
+      if (node) {
+        nodes.push({
+          filePath: reflectedModule.getSourcePath(),
+          node: node as unknown as InterfaceNode
+        });
+      }
+    });
+  });
+
+  await Promise.all(
+    nodes.map(({ filePath, node }) =>
+      compileImperativeHandle({
+        filePath,
+        interfaceNode: node,
+        outputDir
+      })
+    )
+  );
+}

package/scripts/utils/docs/formatDescriptionText.ts

@@ -0,0 +1,11 @@
+import Markdown from "markdown-it";
+
+let processor: Markdown | undefined = undefined;
+
+export function formatDescriptionText(text: string) {
+  if (processor === undefined) {
+    processor = new Markdown();
+  }
+
+  return processor.render(text);
+}

package/scripts/utils/docs/getPropTypeText.ts

@@ -0,0 +1,28 @@
+import type { PropItem } from "react-docgen-typescript";
+
+export function getPropTypeText(prop: PropItem) {
+  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;
+
+    // List/Grid and rowComponent/cellComponent are annotated with a return type of ReactElement instead of ReactNode
+    // As a result of this change the generated docs are significantly less readable, so tidy them up here
+    // See github.com/bvaughn/react-window/issues/875
+    textToFormat = textToFormat.replace(
+      "ReactElement<unknown, string | JSXElementConstructor<...>>",
+      "ReactNode"
+    );
+  }
+
+  if (!textToFormat) {
+    textToFormat = `${prop.type.name}`;
+
+    const match = textToFormat.match(/ExcludeForbiddenKeys<([^>]+)>/);
+    if (match) {
+      textToFormat = match[1];
+    }
+  }
+
+  return textToFormat;
+}

package/scripts/utils/docs/insertPropsMarkdown.ts

@@ -0,0 +1,29 @@
+export function insertPropsMarkdown({
+  componentMarkdown,
+  componentName,
+  markdown,
+  section
+}: {
+  componentMarkdown: string;
+  componentName: string;
+  markdown: string;
+  section: string;
+}) {
+  const flag = `${componentName}:${section}`;
+  const startToken = `<!-- ${flag}:begin -->`;
+  const stopToken = `<!-- ${flag}:end -->`;
+
+  const startIndex = markdown.indexOf(startToken) + startToken.length;
+  const stopIndex = markdown.indexOf(stopToken);
+  if (startIndex < 0 || stopIndex < 0) {
+    throw Error("Parsing README failed");
+  }
+
+  return (
+    markdown.substring(0, startIndex) +
+    "\n" +
+    (componentMarkdown || "None") +
+    "\n" +
+    markdown.substring(stopIndex)
+  );
+}

package/scripts/utils/docs/parseDescription.ts

@@ -0,0 +1,59 @@
+import type { Intent, Section } from "../../../lib/types.ts";
+import { formatDescriptionText } from "./formatDescriptionText.ts";
+import { syntaxHighlight, type Language } from "../syntax-highlight.ts";
+
+export async function parseDescription(rawText: string) {
+  const sections: Section[] = [];
+
+  // Paper over differences between "@ts-ast-parser/core" and "react-docgen-typescript"
+  let text = rawText;
+  Object.keys(INTENT_FLAGS).forEach((flag) => {
+    text = text
+      .split(`\n${flag}`)
+      .join(`\n\n${flag}`)
+      .replaceAll("\n\n\n", "\n\n");
+  });
+
+  for (const chunk of text.split("\n\n")) {
+    let content = "";
+    let intent: Intent | undefined = undefined;
+
+    if (chunk.startsWith("```")) {
+      const match = chunk.match(/^```([a-z]+)/)!;
+      const language = match[1].toUpperCase() as Language;
+
+      content = await syntaxHighlight(
+        chunk.substring(language.length + 3, chunk.length - 3).trim(),
+        language
+      );
+    } else {
+      content = formatDescriptionText(chunk.trim());
+
+      for (const char in INTENT_FLAGS) {
+        if (content.startsWith(`<p>${char} `)) {
+          intent = INTENT_FLAGS[char as keyof typeof INTENT_FLAGS] as Intent;
+          content = content.replace(`<p>${char} `, "<p>");
+        }
+      }
+    }
+
+    // Strip TSDoc comments
+    content = content.replace(/\n@param.+/, "");
+    content = content.replace(/\n@return.+/, "");
+
+    sections.push({
+      content,
+      intent
+    });
+  }
+
+  return sections;
+}
+
+const INTENT_FLAGS = {
+  "❌": "danger",
+  "NOTE:": "none",
+  ℹ️: "primary",
+  "✅": "success",
+  "⚠️": "warning"
+};

package/scripts/utils/docs/propsToTable.ts

@@ -0,0 +1,48 @@
+import { marked } from "marked";
+import type { PropItem } from "react-docgen-typescript";
+import { getPropTypeText } from "./getPropTypeText.ts";
+
+const TABLE_TAG_START = `
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>`;
+
+const PROP_ROW = `
+    <tr>
+      <td>[[name]]</td>
+      <td>[[description]]</td>
+    </tr>`;
+
+const TABLE_TAG_STOP = `
+  </tbody>
+</table>
+`;
+
+export async function propsToTable(props: PropItem[]) {
+  const htmlStrings = [];
+
+  if (props.length > 0) {
+    htmlStrings.push(TABLE_TAG_START);
+
+    for (const prop of props) {
+      const type = getPropTypeText(prop);
+
+      const description = await marked(prop.description);
+
+      htmlStrings.push(
+        PROP_ROW.replace("[[name]]", prop.name)
+          .replace("[[type]]", type)
+          .replace("[[description]]", description)
+      );
+    }
+
+    htmlStrings.push(TABLE_TAG_STOP);
+  }
+
+  return htmlStrings.join("");
+}

package/scripts/utils/examples/trimExcludedText.ts

@@ -0,0 +1,13 @@
+export function trimExcludedText(rawText: string) {
+  {
+    const pieces = rawText.split("// <begin>");
+    rawText = pieces[pieces.length - 1].trim();
+  }
+
+  {
+    const pieces = rawText.split("// <end>");
+    rawText = pieces[0].trim();
+  }
+
+  return rawText;
+}