@hanzo/docs-docgen 3.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Fuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Fumadocs Doc Gen
+
+Remark plugins & Docs Generator utilities.

package/dist/chunk-4AFQP74Z.js

@@ -0,0 +1,24 @@
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+export {
+  __async
+};

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { Code, Root } from 'mdast';
+import { Transformer } from 'unified';
+import { VFile } from 'vfile';
+import { Expression } from 'estree';
+import { MdxJsxAttribute } from 'mdast-util-mdx-jsx';
+import { z } from 'zod';
+
+type Awaitable<T> = T | Promise<T>;
+interface DocGenerator {
+    name: string;
+    /**
+     * Transform codeblocks to another mdast element
+     */
+    run: (input: unknown, context: Context) => Awaitable<object | object[] | undefined>;
+    onFile?: (tree: Root, file: VFile) => void;
+}
+interface Context {
+    node: Code;
+    path: string;
+    cwd: string;
+}
+interface RemarkDocGenOptions {
+    generators?: DocGenerator[];
+}
+declare function remarkDocGen({ generators, }: RemarkDocGenOptions): Transformer<Root, Root>;
+
+declare function createElement(name: string, attributes: object[], children?: unknown): object;
+declare function expressionToAttribute(key: string, value: Expression): MdxJsxAttribute;
+
+interface FileGeneratorOptions {
+    /** @defaultValue true */
+    trim?: boolean;
+    /**
+     * Resolve reference files relative to `vfile.path`
+     *
+     * @defaultValue false
+     */
+    relative?: boolean;
+}
+type FileGeneratorInput = z.output<typeof fileGeneratorSchema>;
+declare const fileGeneratorSchema: z.ZodObject<{
+    file: z.ZodString;
+    codeblock: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        lang: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodBoolean]>>;
+}, z.core.$strip>;
+declare function fileGenerator({ relative, trim, }?: FileGeneratorOptions): DocGenerator;
+
+interface PackageManager {
+    name: string;
+    /**
+     * Convert from npm to another package manager
+     */
+    command: (command: string) => string;
+}
+type RemarkInstallOptions = {
+    Tabs?: string;
+    Tab?: string;
+    /**
+     * Persist Tab value (Fumadocs UI only)
+     *
+     * @defaultValue false
+     */
+    persist?: {
+        id: string;
+    } | false;
+    packageManagers?: PackageManager[];
+};
+/**
+ * It generates the following structure from a code block with `package-install` as language
+ *
+ * @example
+ * ```tsx
+ * <Tabs items={["npm", "pnpm", "yarn", "bun"]}>
+ *  <Tab value="pnpm">...</Tab>
+ *  ...
+ * </Tabs>
+ * ```
+ *
+ * @deprecated Use `remarkNpm` from `@hanzo/docs-core/mdx-plugins` instead, it's a drop-in replacement.
+ */
+declare function remarkInstall({ Tab, Tabs, persist, packageManagers, }?: RemarkInstallOptions): Transformer<Root, Root>;
+
+declare function remarkShow(options?: {
+    variables?: Record<string, unknown>;
+}): Transformer<Root, Root>;
+
+export { type DocGenerator, type FileGeneratorInput, type FileGeneratorOptions, type RemarkDocGenOptions, type RemarkInstallOptions, createElement, expressionToAttribute, fileGenerator, fileGeneratorSchema, remarkDocGen, remarkInstall, remarkShow };

package/dist/index.js

@@ -0,0 +1,228 @@
+import {
+  __async
+} from "./chunk-4AFQP74Z.js";
+
+// src/remark-docgen.ts
+import { visit } from "unist-util-visit";
+var metaRegex = new RegExp("doc-gen:(?<name>.+)");
+function remarkDocGen({
+  generators = []
+}) {
+  return (tree, file) => __async(null, null, function* () {
+    generators.forEach((gen) => {
+      var _a;
+      return (_a = gen.onFile) == null ? void 0 : _a.call(gen, tree, file);
+    });
+    const queue = [];
+    visit(tree, "code", (code, _, parent) => {
+      if (code.lang !== "json" || !code.meta || !parent) return;
+      const matches = metaRegex.exec(code.meta);
+      if (!matches) return;
+      const name = matches[1];
+      const gen = generators.find((g) => g.name === name);
+      const run = () => __async(null, null, function* () {
+        const result = yield gen == null ? void 0 : gen.run(JSON.parse(code.value), {
+          cwd: file.cwd,
+          path: file.path,
+          node: code
+        });
+        const index = parent.children.findIndex((c) => c === code);
+        if (result && index !== -1) {
+          const items = Array.isArray(result) ? result : [result];
+          parent.children.splice(index, 1, ...items);
+        }
+      });
+      queue.push(run());
+    });
+    yield Promise.all(queue);
+  });
+}
+
+// src/utils.ts
+function createElement(name, attributes, children) {
+  const element = {
+    type: "mdxJsxFlowElement",
+    name,
+    attributes
+  };
+  if (children) element.children = children;
+  return element;
+}
+function expressionToAttribute(key, value) {
+  return {
+    type: "mdxJsxAttribute",
+    name: key,
+    value: {
+      type: "mdxJsxAttributeValueExpression",
+      value: "",
+      data: {
+        estree: {
+          type: "Program",
+          body: [
+            {
+              type: "ExpressionStatement",
+              expression: value
+            }
+          ]
+        }
+      }
+    }
+  };
+}
+
+// src/file-generator.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { z } from "zod";
+var fileGeneratorSchema = z.object({
+  file: z.string(),
+  /**
+   * Turn file content into a code block
+   *
+   * @defaultValue false
+   */
+  codeblock: z.union([
+    z.object({
+      lang: z.string().optional(),
+      meta: z.string().optional()
+    }),
+    z.boolean()
+  ]).default(false)
+});
+function fileGenerator({
+  relative = false,
+  trim = true
+} = {}) {
+  return {
+    name: "file",
+    run(input, ctx) {
+      return __async(this, null, function* () {
+        var _a2;
+        const { file, codeblock = false } = fileGeneratorSchema.parse(input);
+        const dest = relative ? path.resolve(ctx.cwd, path.dirname(ctx.path), file) : path.resolve(ctx.cwd, file);
+        let value = yield fs.readFile(dest).then((res) => res.toString());
+        if (trim) value = value.trim();
+        if (codeblock === false) {
+          return {
+            type: "paragraph",
+            children: [{ type: "text", value }]
+          };
+        }
+        const codeOptions = codeblock === true ? {} : codeblock;
+        return {
+          type: "code",
+          lang: (_a2 = codeOptions.lang) != null ? _a2 : path.extname(dest).slice(1),
+          meta: codeOptions.meta,
+          value
+        };
+      });
+    }
+  };
+}
+
+// src/remark-install.ts
+import { visit as visit2 } from "unist-util-visit";
+import convert from "npm-to-yarn";
+function remarkInstall({
+  Tab = "Tab",
+  Tabs = "Tabs",
+  persist = false,
+  packageManagers = [
+    { command: (cmd) => convert(cmd, "npm"), name: "npm" },
+    { command: (cmd) => convert(cmd, "pnpm"), name: "pnpm" },
+    { command: (cmd) => convert(cmd, "yarn"), name: "yarn" },
+    { command: (cmd) => convert(cmd, "bun"), name: "bun" }
+  ]
+} = {}) {
+  return (tree) => {
+    visit2(tree, "code", (node) => {
+      if (node.lang !== "package-install") return "skip";
+      const value = node.value.startsWith("npm") || node.value.startsWith("npx") ? node.value : `npm install ${node.value}`;
+      const insert = createElement(
+        Tabs,
+        [
+          ...typeof persist === "object" ? [
+            {
+              type: "mdxJsxAttribute",
+              name: "groupId",
+              value: persist.id
+            },
+            {
+              type: "mdxJsxAttribute",
+              name: "persist",
+              value: null
+            }
+          ] : [],
+          expressionToAttribute("items", {
+            type: "ArrayExpression",
+            elements: packageManagers.map(({ name }) => ({
+              type: "Literal",
+              value: name
+            }))
+          })
+        ],
+        packageManagers.map(({ command, name }) => ({
+          type: "mdxJsxFlowElement",
+          name: Tab,
+          attributes: [{ type: "mdxJsxAttribute", name: "value", value: name }],
+          children: [
+            {
+              type: "code",
+              lang: "bash",
+              meta: node.meta,
+              value: command(value)
+            }
+          ]
+        }))
+      );
+      Object.assign(node, insert);
+    });
+  };
+}
+
+// src/remark-show.ts
+import { visit as visit3 } from "unist-util-visit";
+function remarkShow(options) {
+  var _a;
+  const variables = (_a = options == null ? void 0 : options.variables) != null ? _a : {};
+  return (tree, file) => __async(null, null, function* () {
+    const { toJs } = yield import("estree-util-to-js");
+    const tasks = [];
+    visit3(tree, "mdxJsxFlowElement", (node) => {
+      var _a2;
+      if (node.name !== "show") return;
+      for (const attr of node.attributes) {
+        if (attr.type !== "mdxJsxAttribute" || attr.name !== "on") continue;
+        if (!attr.value || typeof attr.value !== "object" || !((_a2 = attr.value.data) == null ? void 0 : _a2.estree))
+          return "skip";
+        const js = toJs(attr.value.data.estree);
+        const callback = new Function(
+          ...Object.keys(variables),
+          `return ${js.value}`
+        )(...Object.values(variables));
+        tasks.push(
+          (() => __async(null, null, function* () {
+            const value = typeof callback === "function" ? yield callback(file) : callback;
+            Object.assign(node, {
+              type: "mdxJsxFlowElement",
+              name: null,
+              attributes: [],
+              children: value === true ? node.children : []
+            });
+          }))()
+        );
+        return "skip";
+      }
+    });
+    yield Promise.all(tasks);
+  });
+}
+export {
+  createElement,
+  expressionToAttribute,
+  fileGenerator,
+  fileGeneratorSchema,
+  remarkDocGen,
+  remarkInstall,
+  remarkShow
+};

package/dist/remark-ts2js.d.ts

@@ -0,0 +1,35 @@
+import { Transformer } from 'unified';
+import { Root } from 'mdast';
+
+interface TypeScriptToJavaScriptOptions {
+    /**
+     * Persist Tab value (Fumadocs UI only)
+     *
+     * @defaultValue false
+     */
+    persist?: {
+        id: string;
+    } | false;
+    defaultValue?: 'js' | 'ts';
+    /**
+     * Transform all TypeScript codeblocks by default, without a trigger
+     */
+    disableTrigger?: boolean;
+}
+/**
+ * A remark plugin to transform TypeScript codeblocks into two tabs of codeblocks with its JS variant.
+ *
+ * Add `ts2js` to enable transformation:
+ * ````md
+ * ```tsx ts2js
+ * import { ReactNode } from "react";
+ *
+ * export default function Layout({ children }: { children: ReactNode }) {
+ *     return <div>{children}</div>
+ * }
+ * ```
+ * ````
+ */
+declare function remarkTypeScriptToJavaScript({ persist, defaultValue, disableTrigger, }?: TypeScriptToJavaScriptOptions): Transformer<Root>;
+
+export { type TypeScriptToJavaScriptOptions, remarkTypeScriptToJavaScript };

package/dist/remark-ts2js.js

@@ -0,0 +1,84 @@
+import {
+  __async
+} from "./chunk-4AFQP74Z.js";
+
+// src/remark-ts2js.ts
+import { visit } from "unist-util-visit";
+import {
+  generateCodeBlockTabs,
+  parseCodeBlockAttributes
+} from "@hanzo/docs-core/mdx-plugins/codeblock-utils";
+function remarkTypeScriptToJavaScript({
+  persist = false,
+  defaultValue = "ts",
+  disableTrigger = false
+} = {}) {
+  return (tree, file) => __async(null, null, function* () {
+    const oxc = yield import("oxc-transform");
+    const tasks = [];
+    visit(tree, "code", (node) => {
+      var _a;
+      const lang = node.lang;
+      if (lang !== "ts" && lang !== "tsx") return;
+      const meta = parseCodeBlockAttributes((_a = node.meta) != null ? _a : "", ["ts2js"]);
+      if (!disableTrigger && !("ts2js" in meta.attributes)) return;
+      tasks.push(
+        (() => __async(null, null, function* () {
+          var _a2, _b;
+          const result = yield oxc.transform(
+            `${(_a2 = file.path) != null ? _a2 : "test"}.${lang}`,
+            node.value,
+            {
+              sourcemap: false,
+              jsx: "preserve"
+            }
+          );
+          const replacement = generateCodeBlockTabs({
+            persist,
+            defaultValue,
+            triggers: [
+              {
+                value: "ts",
+                children: [{ type: "text", value: "TypeScript" }]
+              },
+              {
+                value: "js",
+                children: [{ type: "text", value: "JavaScript" }]
+              }
+            ],
+            tabs: [
+              {
+                value: "ts",
+                children: [
+                  {
+                    type: "code",
+                    lang: node.lang,
+                    meta: meta.rest,
+                    value: node.value
+                  }
+                ]
+              },
+              {
+                value: "js",
+                children: [
+                  {
+                    type: "code",
+                    lang: lang === "tsx" ? "jsx" : "js",
+                    meta: (_b = meta.attributes.ts2js) != null ? _b : meta.rest,
+                    value: result.code
+                  }
+                ]
+              }
+            ]
+          });
+          Object.assign(node, replacement);
+        }))()
+      );
+      return "skip";
+    });
+    yield Promise.all(tasks);
+  });
+}
+export {
+  remarkTypeScriptToJavaScript
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@hanzo/docs-docgen",
+  "version": "3.0.4",
+  "description": "Useful remark utilities and plugins for Hanzo Docs",
+  "keywords": [
+    "Hanzo",
+    "Docs",
+    "remark",
+    "mdx",
+    "Docgen"
+  ],
+  "homepage": "https://hanzo.ai/docs",
+  "repository": "github:hanzoai/docs",
+  "license": "MIT",
+  "author": "Fuma Nama",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./remark-ts2js": {
+      "import": "./dist/remark-ts2js.js",
+      "types": "./dist/remark-ts2js.d.ts"
+    }
+  },
+  "dependencies": {
+    "estree-util-to-js": "^2.0.0",
+    "estree-util-value-to-estree": "^3.5.0",
+    "npm-to-yarn": "^3.0.1",
+    "oxc-transform": "^0.102.0",
+    "unist-util-visit": "^5.0.0",
+    "zod": "^4.1.13"
+  },
+  "peerDependencies": {
+    "@hanzo/docs-core": "^15.7.2 || ^16.0.0"
+  },
+  "devDependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "@types/estree": "^1.0.8",
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "24.10.2",
+    "mdast-util-mdx-jsx": "^3.2.0",
+    "remark": "^15.0.1",
+    "typescript": "^5.9.3",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3",
+    "eslint-config-custom": "0.0.0",
+    "@hanzo/docs-core": "16.2.6",
+    "tsconfig": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "types:check": "tsc --noEmit"
+  }
+}