@pantoken/typedoc-plugin-demo 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @pantoken/typedoc-plugin-demo
+
+A TypeDoc plugin for a `@demo` block tag. Authors attach a live, embeddable demo to any symbol, and
+this plugin turns it into a fenced `demo` block your docs renderer picks up as an iframe — an
+MDN-style "live sample" panel.
+
+It's deliberately provider-agnostic: it doesn't know or care what `stackblitz` or `wp-playground`
+means. It just moves the spec into a fence; your renderer resolves it.
+
+## Install
+
+```sh
+npm i -D @pantoken/typedoc-plugin-demo typedoc
+```
+
+## Setup
+
+Add the plugin, and register `@demo` in `blockTags` (the comment parser reads that list before
+plugins load, so the tag must be declared in config to avoid an "unknown block tag" warning):
+
+```jsonc
+// typedoc.json
+{
+  "plugin": ["typedoc-plugin-markdown", "@pantoken/typedoc-plugin-demo"],
+  "blockTags": ["@param", "@returns", "@example", "@demo"],
+}
+```
+
+## Authoring
+
+```ts
+/**
+ * A button stylesheet.
+ *
+ * @demo self:button
+ * @demo stackblitz:abc123
+ */
+export function buttonCss() {}
+```
+
+Each `@demo` becomes a `demo` fence in the symbol's description, in order. A spec is either a bare
+URL (`@demo https://…` or `@demo /path`) or a `<provider>:<ref>` pair. Common providers a renderer
+might support: `self`, `url`, `stackblitz`, `codesandbox`, `codepen`, `dartpad`, `wp-playground`.
+
+## Rendering
+
+The plugin only emits the fence. To display it, teach your docs to turn a `demo` fence into an
+iframe — for example a markdown-it fence rule that reads the spec and renders the right embed. In
+pantoken's VitePress site, `@pantoken/demo` resolves the provider spec into iframe attributes.
+
+## API
+
+- **`load(app)`** — the TypeDoc entry point.
+- **`rewriteComment(comment)`** — move a comment's `@demo` tags into summary fences (exported for
+  testing and reuse).
+- **`toDemoFence(spec)`** — wrap one spec in a `demo` fence.
+- **`DEMO_TAG`** (`"@demo"`), **`DEMO_FENCE`** (`"demo"`) — the tag and fence-language constants.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+import { Application, Comment } from "typedoc";
+
+//#region src/index.d.ts
+/** The block tag this plugin consumes. Register it in TypeDoc's `blockTags` so it won't warn. */
+declare const DEMO_TAG = "@demo";
+/** The fenced-code language the demo spec is emitted under — target it in your renderer. */
+declare const DEMO_FENCE = "demo";
+/**
+ * Wrap one demo spec in a fenced ```demo``` block.
+ *
+ * @param spec - A demo spec: a bare URL or a `<provider>:<ref>` pair.
+ * @returns The fenced code block as a string.
+ *
+ * @example
+ * ```ts
+ * import { toDemoFence } from "@pantoken/typedoc-plugin-demo";
+ *
+ * toDemoFence("stackblitz:abc123"); // "```demo\nstackblitz:abc123\n```"
+ * ```
+ */
+declare function toDemoFence(spec: string): string;
+/**
+ * Move every `@demo` block tag on a comment into ```demo``` fences appended to its summary, in order.
+ * Block-tag content gets re-fenced by the markdown theme, so the fence must live in the summary
+ * prose, which is emitted verbatim.
+ *
+ * @param comment - The comment to rewrite in place.
+ *
+ * @example
+ * ```ts
+ * import { rewriteComment } from "@pantoken/typedoc-plugin-demo";
+ *
+ * // Given a comment with `@demo self:button`, appends a ```demo``` fence and drops the tag.
+ * rewriteComment(comment);
+ * ```
+ */
+declare function rewriteComment(comment: Comment): void;
+/**
+ * TypeDoc entry point. Registers a resolve-time pass that rewrites `@demo` tags into demo fences.
+ *
+ * @param app - The TypeDoc application.
+ */
+declare function load(app: Application): void;
+//#endregion
+export { DEMO_FENCE, DEMO_TAG, load, rewriteComment, toDemoFence };

package/dist/index.mjs

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Converter, RendererEvent } from "typedoc";
+//#region src/index.ts
+/**
+* `@pantoken/typedoc-plugin-demo` — a TypeDoc plugin for the `@demo` block tag.
+*
+* Authors attach a live, embeddable demo to any symbol with `@demo <spec>`, where `<spec>` is either
+* a bare URL or a `<provider>:<ref>` pair (for example `stackblitz:abc123`, `codesandbox:xy12z`,
+* `wp-playground:https://…/blueprint.json`, or `self:button`). This plugin registers nothing about
+* providers itself — it stays deliberately dumb and reusable: it moves each `@demo` tag's spec into
+* a fenced ```demo``` block appended to the symbol's summary, and your docs renderer decides how to
+* turn a spec into an iframe. (See `@pantoken/demo` for a renderer that resolves the providers.)
+*
+* The fence rides through markdown untouched — including any translation pipeline that preserves
+* code blocks — so the demo survives localization.
+*
+* **Setup:** add `"@demo"` to TypeDoc's `blockTags` option. The comment parser reads that list before
+* plugins load, so a plugin can't register the tag late enough to suppress the "unknown block tag"
+* warning; it must be in your `typedoc.json`.
+*
+* @example
+* ```jsonc
+* // typedoc.json
+* {
+*   "plugin": ["typedoc-plugin-markdown", "@pantoken/typedoc-plugin-demo"],
+*   "blockTags": ["@param", "@returns", "@example", "@demo"]
+* }
+* ```
+*
+* @module
+* @beta
+*/
+/** The block tag this plugin consumes. Register it in TypeDoc's `blockTags` so it won't warn. */
+const DEMO_TAG = "@demo";
+/** The fenced-code language the demo spec is emitted under — target it in your renderer. */
+const DEMO_FENCE = "demo";
+/**
+* Wrap one demo spec in a fenced ```demo``` block.
+*
+* @param spec - A demo spec: a bare URL or a `<provider>:<ref>` pair.
+* @returns The fenced code block as a string.
+*
+* @example
+* ```ts
+* import { toDemoFence } from "@pantoken/typedoc-plugin-demo";
+*
+* toDemoFence("stackblitz:abc123"); // "```demo\nstackblitz:abc123\n```"
+* ```
+*/
+function toDemoFence(spec) {
+	return `\`\`\`${DEMO_FENCE}\n${spec}\n\`\`\``;
+}
+/** Yield every comment attached to a reflection (its own, plus signature/accessor comments). */
+function* commentsOf(reflection) {
+	if (reflection.comment) yield reflection.comment;
+	const declaration = reflection;
+	for (const signature of declaration.signatures ?? []) if (signature.comment) yield signature.comment;
+	if (declaration.getSignature?.comment) yield declaration.getSignature.comment;
+	if (declaration.setSignature?.comment) yield declaration.setSignature.comment;
+}
+/**
+* Move every `@demo` block tag on a comment into ```demo``` fences appended to its summary, in order.
+* Block-tag content gets re-fenced by the markdown theme, so the fence must live in the summary
+* prose, which is emitted verbatim.
+*
+* @param comment - The comment to rewrite in place.
+*
+* @example
+* ```ts
+* import { rewriteComment } from "@pantoken/typedoc-plugin-demo";
+*
+* // Given a comment with `@demo self:button`, appends a ```demo``` fence and drops the tag.
+* rewriteComment(comment);
+* ```
+*/
+function rewriteComment(comment) {
+	const demos = comment.blockTags.filter((tag) => tag.tag === DEMO_TAG);
+	if (demos.length === 0) return;
+	comment.blockTags = comment.blockTags.filter((tag) => tag.tag !== DEMO_TAG);
+	for (const demo of demos) {
+		const spec = demo.content.map((part) => part.text).join("").trim();
+		if (!spec) continue;
+		const fence = {
+			kind: "text",
+			text: `\n\n${toDemoFence(spec)}\n`
+		};
+		comment.summary.push(fence);
+	}
+}
+function normalizeModuleLink(link) {
+	return link.replace(/^\/api\//, "").replace(/^\//, "").replace(/\/+$/, "");
+}
+function flattenSrcNodes(items, targets) {
+	return items.map((item) => {
+		if (item.items) {
+			item.items = flattenSrcNodes(item.items, targets);
+			const srcIndex = item.items.findIndex((child) => child.text === "src" && child.link);
+			if (srcIndex >= 0) {
+				const srcNode = item.items[srcIndex];
+				const relativeLink = normalizeModuleLink(srcNode.link);
+				if (relativeLink.endsWith("/src")) targets.push({
+					link: relativeLink,
+					title: item.text
+				});
+				item.link = srcNode.link;
+				const remaining = item.items.filter((_, index) => index !== srcIndex);
+				item.items = [...srcNode.items ?? [], ...remaining];
+			}
+		}
+		return item;
+	});
+}
+function replaceFirstLine(content, oldText, newText) {
+	const lines = content.split("\n");
+	if (lines.length > 0 && lines[0].includes(oldText)) lines[0] = lines[0].replace(oldText, newText);
+	return lines.join("\n");
+}
+function rewriteModuleHeading(indexPath, title, modulePath) {
+	if (!existsSync(indexPath)) return;
+	const original = readFileSync(indexPath, "utf8");
+	const final = replaceFirstLine(original.replace(/^#\s+.+$/m, `# ${title}`), ` / ${modulePath}`, ` / ${title}`);
+	if (final !== original) writeFileSync(indexPath, final, "utf8");
+}
+function normalizeDocsOutput(outputDirectory) {
+	const sidebarPath = join(outputDirectory, "typedoc-sidebar.json");
+	if (!existsSync(sidebarPath)) return;
+	const sidebar = JSON.parse(readFileSync(sidebarPath, "utf8"));
+	const moduleTargets = [];
+	const normalized = flattenSrcNodes(sidebar, moduleTargets);
+	writeFileSync(sidebarPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+	for (const target of moduleTargets) rewriteModuleHeading(join(outputDirectory, target.link, "index.md"), target.title, target.link);
+}
+/**
+* TypeDoc entry point. Registers a resolve-time pass that rewrites `@demo` tags into demo fences.
+*
+* @param app - The TypeDoc application.
+*/
+function load(app) {
+	app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context) => {
+		for (const reflection of Object.values(context.project.reflections)) for (const comment of commentsOf(reflection)) rewriteComment(comment);
+	});
+	app.renderer.on(RendererEvent.END, (event) => {
+		normalizeDocsOutput(event.outputDirectory);
+	});
+}
+//#endregion
+export { DEMO_FENCE, DEMO_TAG, load, rewriteComment, toDemoFence };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pantoken/typedoc-plugin-demo",
+  "version": "0.1.0",
+  "description": "TypeDoc plugin: turn a @demo <provider>:<ref> block tag into an embeddable demo fence your docs render as an iframe.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typedoc": "^0.28.20",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "peerDependencies": {
+    "typedoc": ">=0.28"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}