react-lib-tools 0.0.19 → 0.0.21

package/dist/react-lib-tools.d.ts

@@ -11,6 +11,9 @@ import { MouseEvent as MouseEvent_2 } from 'react';
 import { PropsWithChildren } from 'react';
 import { ReactNode } from 'react';
 
+/**
+ * Displays an application shell with desktop and mobile layouts.
+ */
 export declare function AppRoot({ navLinks, overview, packageDescription, packageName, routes, showOpenCollectLink, versions }: {
     navLinks: ReactNode;
     overview?: ReactNode | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lib-tools",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "type": "module",
   "author": "Brian Vaughn <brian.david.vaughn@gmail.com> (https://github.com/bvaughn/)",
   "contributors": [

package/scripts/compile-docs.ts

@@ -10,16 +10,35 @@ import {
   ScriptTarget
 } from "typescript";
 
+/**
+ * Compile TSDoc comments into a formatted structure that can be rendered by the `ComponentProps` component.
+ */
 export async function compileDocs({
   analyserOptions: analyserOptionsParam,
   componentNames = [],
   imperativeHandleNames = [],
-  outputDirName = "docs"
+  outputPath = ["public", "generated", "docs"]
 }: {
+  /**
+   * AST Parser config; see `@ts-ast-parser/core` documentation for more information.
+   */
   analyserOptions?: Partial<AnalyserOptions>;
+
+  /**
+   * Which components should be compiled?
+   */
   componentNames?: string[] | undefined;
+
+  /**
+   * Which imperative handles should be compiled?
+   */
   imperativeHandleNames?: string[] | undefined;
-  outputDirName?: string | undefined;
+
+  /**
+   * Where should the output be stored?
+   * By default examples are stored within the `public/generated/docs` directory.
+   */
+  outputPath?: string[] | undefined;
 }) {
   const compilerOptions: Partial<CompilerOptions> = {
     ...defaultCompilerOptions,
@@ -35,13 +54,13 @@ export async function compileDocs({
   await compileComponents({
     compilerOptions,
     componentNames,
-    outputDirName
+    outputPath
   });
 
   await compileImperativeHandles({
     analyserOptions,
     names: imperativeHandleNames,
-    outputDirName
+    outputPath
   });
 }
 

package/scripts/compile-examples.ts

@@ -1,22 +1,39 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { trimExcludedText } from "./utils/examples/trimExcludedText.ts";
 import { initialize } from "./utils/initialize.ts";
 import { syntaxHighlight } from "./utils/syntax-highlight.ts";
-import { trimExcludedText } from "./utils/examples/trimExcludedText.ts";
 
+/**
+ * Compile example snippets into syntax-highlighted HTML that can be rendered by the `Code` component.
+ */
 export async function compileExamples({
-  fileExtensions = [".css", ".html", ".ts", ".tsx"],
+  fileExtensions = [".css", ".html", ".js", ".jsx", ".ts", ".tsx"],
   inputPath = ["src", "routes"],
-  outputDirName = "examples"
+  outputPath = ["public", "generated", "examples"]
 }: {
+  /**
+   * Which file extension are supported?
+   * By default CSS, HTML, TS/TSX, and JS/JSX file extensions are supported.
+   */
   fileExtensions?: string[] | undefined;
+
+  /**
+   * Where are example files located?
+   * By default this script looks for examples within the `src/routes` root directory.
+   */
   inputPath?: string[] | undefined;
-  outputDirName?: string | undefined;
+
+  /**
+   * Where should the output be stored?
+   * By default examples are stored within the `public/generated/examples` directory.
+   */
+  outputPath?: string[] | undefined;
 } = {}) {
   const { files, outputDir } = await initialize({
     fileExtensions,
     inputPath,
-    outputDirName
+    outputPath
   });
 
   for (const file of files) {

package/scripts/utils/docs/compileComponents.ts

@@ -10,11 +10,11 @@ import { insertPropsMarkdown } from "./insertPropsMarkdown.ts";
 export async function compileComponents({
   compilerOptions,
   componentNames,
-  outputDirName
+  outputPath
 }: {
   compilerOptions: Partial<CompilerOptions>;
   componentNames: string[];
-  outputDirName: string;
+  outputPath: string[];
 }) {
   const parser = withCompilerOptions(compilerOptions, {
     savePropValueAsString: true,
@@ -30,7 +30,7 @@ export async function compileComponents({
         file.includes(`${componentName}.ts`)
       ),
     inputPath: ["lib", "components"],
-    outputDirName
+    outputPath
   });
 
   const markdownPath = join(cwd(), "README.md");

package/scripts/utils/docs/compileImperativeHandles.ts

@@ -10,13 +10,13 @@ import { compileImperativeHandle } from "./compileImperativeHandle.ts";
 export async function compileImperativeHandles({
   analyserOptions,
   names,
-  outputDirName
+  outputPath
 }: {
   analyserOptions: Partial<AnalyserOptions>;
   names: string[];
-  outputDirName: string;
+  outputPath: string[];
 }) {
-  const outputDir = join(cwd(), "public", "generated", outputDirName);
+  const outputDir = join(cwd(), ...outputPath);
 
   const result = await parseFromProject(analyserOptions);
   const reflectedModules = result.project?.getModules() ?? [];

package/scripts/utils/docs/parseDescription.ts

@@ -8,7 +8,9 @@ export async function parseDescription(rawText: string) {
   // Paper over differences between "@ts-ast-parser/core" and "react-docgen-typescript"
   let text = rawText;
 
-  text = text.replace("@deprecated", "❌ This prop has been deprecated.");
+  text = text.replaceAll("@deprecated", "❌ This prop has been deprecated.");
+  text = text.replace(/@param ([\w]+)/g, "- `$1`");
+  text = text.replaceAll("@return", "\n");
 
   Object.keys(INTENT_FLAGS).forEach((flag) => {
     text = text

package/scripts/utils/initialize.ts

@@ -8,15 +8,15 @@ export async function initialize({
   fileExtensions,
   fileFilter,
   inputPath,
-  outputDirName
+  outputPath
 }: {
   fileExtensions: string[];
   fileFilter?: ((path: string) => boolean) | undefined;
   inputPath: string[];
-  outputDirName: string;
+  outputPath: string[];
 }) {
   const inputDir = join(cwd(), ...inputPath);
-  const outputDir = join(cwd(), "public", "generated", outputDirName);
+  const outputDir = join(cwd(), ...outputPath);
   await mkdir(outputDir, { recursive: true });
   await rmFilesWithExtensions(outputDir, [".json"]);