@pantoken/typedoc-plugin-live-example 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @pantoken/typedoc-plugin-live-example
+
+Embed a live HTML preview beneath each `@example` on a CSS reference page.
+
+`@cssdoc/markdown` renders an `@example` as a plain ` ```html ` code fence and keeps it that way — a
+generic renderer can't assume the host page loads the component CSS. When your docs _do_ load the
+component stylesheet globally (pantoken's do), this plugin makes each example render live under its
+source: after every ` ```html ` fence it appends a `<div class="css-example">` holding the same markup.
+Overlay examples (`<dialog>`, `[popover]`) are skipped — they're hidden until opened, so a `## Demo`
+iframe drives their preview instead.
+
+By default the preview is wrapped in `<div class="css-example">`, but the **wrapper structure is
+yours** — pass a `wrap` function (or a `liveExampleWrapper` template in config) to render each example in
+any element you like, e.g. a card:
+
+```html
+<div class="instui-card">
+  <!-- your example markup -->
+</div>
+```
+
+## Usage
+
+Register it as a TypeDoc plugin (rewrites pages under `liveExampleDir`, default `css`, on render end).
+`liveExampleWrapper` is a template whose `%s` is replaced by the example markup:
+
+```json
+{
+  "plugin": ["typedoc-plugin-markdown", "@cssdoc/typedoc", "@pantoken/typedoc-plugin-live-example"],
+  "liveExampleDir": "css",
+  "liveExampleWrapper": "<div class=\"instui-card\">%s</div>"
+}
+```
+
+Or call it directly when your CSS pages are written by a post-render step — `wrap` gives full control of
+the wrapper structure:
+
+```ts
+import { injectLiveExamples, withLiveExamples } from "@pantoken/typedoc-plugin-live-example";
+
+// Default `<div class="css-example">` wrapper:
+injectLiveExamples("docs/api/css");
+// Custom structure — a card:
+injectLiveExamples("docs/api/css", {
+  wrap: (html) => `<div class="instui-card">\n${html}\n</div>`,
+});
+const page = withLiveExamples(markdown, { wrap }); // or transform one page's markdown
+```
+
+## API
+
+- **`withLiveExamples(markdown, options?): string`** — append a live-preview block after each ` ```html ` fence in a markdown string.
+- **`injectLiveExamples(dir, options?): number`** — rewrite every `.md` under `dir` (recursively) in place; returns the count changed.
+- **`LiveExampleOptions.wrap(html): string`** — build the block inserted after each fence; controls the wrapper structure (default `<div class="css-example">…</div>`).
+- **`defaultWrap(html): string`** — the default `css-example` wrapper, exported for composition.
+- **`load(app): void`** — the TypeDoc plugin entry point (options: `liveExampleDir`, `liveExampleWrapper`).

package/dist/index.d.mts

@@ -0,0 +1,55 @@
+import { Application } from "typedoc";
+
+//#region src/index.d.ts
+/** Options controlling how a live-example preview is built. */
+interface LiveExampleOptions {
+  /**
+   * Build the block inserted after each ` ```html ` fence from the example's markup — override this to
+   * control the wrapper STRUCTURE (a card element, extra nesting, data attributes, …). It's called only
+   * for non-overlay examples. Defaults to {@link defaultWrap} (`<div class="css-example">…</div>`).
+   *
+   * @param html - The example's raw HTML (verbatim from the fence).
+   * @returns The markdown/HTML block to place beneath the source fence.
+   */
+  wrap?: (html: string) => string;
+}
+/** The default wrapper: the example markup in a `<div class="css-example">`. */
+declare function defaultWrap(html: string): string;
+/**
+ * Append a live preview after each ` ```html ` fence in `markdown`, echoing the fence's markup through
+ * {@link LiveExampleOptions.wrap} so it renders beneath the source. Overlay examples are left source-only.
+ *
+ * @param markdown - The rendered page markdown.
+ * @param options - Wrapper structure ({@link LiveExampleOptions}).
+ * @returns The markdown with live-preview blocks inserted.
+ *
+ * @example
+ * ```ts
+ * import { withLiveExamples } from "@pantoken/typedoc-plugin-live-example";
+ *
+ * // Default wrapper:
+ * withLiveExamples(page);
+ * // Custom structure — a card:
+ * withLiveExamples(page, { wrap: (html) => `<div class="instui-card">\n${html}\n</div>` });
+ * ```
+ */
+declare function withLiveExamples(markdown: string, options?: LiveExampleOptions): string;
+/**
+ * Rewrite every `.md` under `dir` (recursively) through {@link withLiveExamples}.
+ *
+ * @param dir - The directory of CSS reference pages.
+ * @param options - Wrapper structure ({@link LiveExampleOptions}).
+ * @returns How many files were changed.
+ */
+declare function injectLiveExamples(dir: string, options?: LiveExampleOptions): number;
+/**
+ * TypeDoc entry point. On `RendererEvent.END`, rewrites the CSS reference pages (default `<output>/css`,
+ * override with `liveExampleDir`) to embed a live preview beneath each `@example`. Set `liveExampleWrapper`
+ * to a template whose `%s` is replaced by the example markup — e.g. `<div class="instui-card">%s</div>` —
+ * to control the wrapper structure from config; omit it for the default `<div class="css-example">`.
+ *
+ * @param app - The TypeDoc application.
+ */
+declare function load(app: Application): void;
+//#endregion
+export { LiveExampleOptions, defaultWrap, injectLiveExamples, load, withLiveExamples };

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ParameterType, RendererEvent } from "typedoc";
+//#region src/index.ts
+/**
+* `@pantoken/typedoc-plugin-live-example` — embed a live HTML preview beneath each `@example` on a CSS
+* reference page.
+*
+* `@cssdoc/markdown` renders an `@example` as a plain ` ```html ` code fence, and stays that way on
+* purpose — a generic renderer can't assume the host page loads the component CSS globally. pantoken's
+* docs DO load `@pantoken/components` globally, so each example can render live under its source. This
+* plugin post-processes the emitted markdown: after every ` ```html ` fence it appends a
+* `<div class="css-example">` holding the same markup, which the docs theme styles as one joined
+* "source + preview" card. Overlay examples (`<dialog>`, `[popover]`) are skipped — they're hidden until
+* opened, so their `## Demo` iframe drives the preview instead.
+*
+* Usable two ways: call {@link withLiveExamples} / {@link injectLiveExamples} directly when your CSS
+* pages are written by a post-render step, or register it as a TypeDoc plugin — {@link load} rewrites the
+* pages under `liveExampleDir` on `RendererEvent.END`.
+*
+* @module
+* @beta
+*/
+/** A fenced ` ```html ` block and its inner markup. */
+const HTML_FENCE = /```html\n([\s\S]*?)\n```/gu;
+/** An example that's hidden until opened (a `<dialog>` or a `[popover]`), so its live preview is skipped. */
+function isOverlay(html) {
+	return /^<dialog\b/u.test(html.trim()) || /\spopover(?:=|\s|>)/u.test(html);
+}
+/** The default wrapper: the example markup in a `<div class="css-example">`. */
+function defaultWrap(html) {
+	return `<div class="css-example">\n${html}\n</div>`;
+}
+/**
+* Append a live preview after each ` ```html ` fence in `markdown`, echoing the fence's markup through
+* {@link LiveExampleOptions.wrap} so it renders beneath the source. Overlay examples are left source-only.
+*
+* @param markdown - The rendered page markdown.
+* @param options - Wrapper structure ({@link LiveExampleOptions}).
+* @returns The markdown with live-preview blocks inserted.
+*
+* @example
+* ```ts
+* import { withLiveExamples } from "@pantoken/typedoc-plugin-live-example";
+*
+* // Default wrapper:
+* withLiveExamples(page);
+* // Custom structure — a card:
+* withLiveExamples(page, { wrap: (html) => `<div class="instui-card">\n${html}\n</div>` });
+* ```
+*/
+function withLiveExamples(markdown, options = {}) {
+	const wrap = options.wrap ?? defaultWrap;
+	return markdown.replace(HTML_FENCE, (fence, html) => isOverlay(html) ? fence : `${fence}\n\n${wrap(html)}`);
+}
+/**
+* Rewrite every `.md` under `dir` (recursively) through {@link withLiveExamples}.
+*
+* @param dir - The directory of CSS reference pages.
+* @param options - Wrapper structure ({@link LiveExampleOptions}).
+* @returns How many files were changed.
+*/
+function injectLiveExamples(dir, options = {}) {
+	let changed = 0;
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) changed += injectLiveExamples(path, options);
+		else if (name.endsWith(".md")) {
+			const before = readFileSync(path, "utf8");
+			const after = withLiveExamples(before, options);
+			if (after !== before) {
+				writeFileSync(path, after, "utf8");
+				changed++;
+			}
+		}
+	}
+	return changed;
+}
+/**
+* TypeDoc entry point. On `RendererEvent.END`, rewrites the CSS reference pages (default `<output>/css`,
+* override with `liveExampleDir`) to embed a live preview beneath each `@example`. Set `liveExampleWrapper`
+* to a template whose `%s` is replaced by the example markup — e.g. `<div class="instui-card">%s</div>` —
+* to control the wrapper structure from config; omit it for the default `<div class="css-example">`.
+*
+* @param app - The TypeDoc application.
+*/
+function load(app) {
+	app.options.addDeclaration({
+		name: "liveExampleDir",
+		help: "Subdirectory under the docs output whose pages get live-example previews.",
+		type: ParameterType.String,
+		defaultValue: "css"
+	});
+	app.options.addDeclaration({
+		name: "liveExampleWrapper",
+		help: "Wrapper template; `%s` is replaced by the example markup. Empty → `<div class=\"css-example\">`.",
+		type: ParameterType.String,
+		defaultValue: ""
+	});
+	app.renderer.on(RendererEvent.END, (event) => {
+		const dir = join(event.outputDirectory, app.options.getValue("liveExampleDir"));
+		const template = app.options.getValue("liveExampleWrapper");
+		const wrap = template ? (html) => template.replace("%s", html) : void 0;
+		try {
+			injectLiveExamples(dir, { wrap });
+		} catch {}
+	});
+}
+//#endregion
+export { defaultWrap, injectLiveExamples, load, withLiveExamples };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pantoken/typedoc-plugin-live-example",
+  "version": "0.1.0",
+  "description": "TypeDoc plugin: embed a live HTML preview beneath each @example on a CSS reference page.",
+  "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"
+  }
+}