duckfn-docs-kit 0.2.1 → 0.4.0

package/dist/sql/remark.d.ts

@@ -34,8 +34,13 @@ export interface RunnableSqlConfig {
      *
      * `html` and `iframe` are the same renderer: both sandbox the markup in an
      * iframe, so scripts run with an opaque origin.
+     *
+     * `mermaid` renders the column's mermaid source as a diagram through
+     * `<dfk-mermaid>` (the same element a ```mermaid fence produces), so the result
+     * gets the element's zoom, fullscreen, source editing and SVG download for
+     * free.
      */
-    show?: 'table' | 'html' | 'iframe' | 'svg' | 'text';
+    show?: 'table' | 'html' | 'iframe' | 'svg' | 'text' | 'mermaid';
     /**
      * What this block is expected to do when the docs' own SQL test suite runs it
      * (`duckfn-docs-kit/sql/verify`). Defaults to `'ok'`; `'error'` marks a block

package/dist/sql/renderers.d.ts

@@ -5,6 +5,8 @@ import type { RunnableSqlConfig } from './remark';
  *
  * The registry is the seam later phases plug into. It ships `table` (VisActor
  * VTable), a `text` fallback, the markup previews `iframe` / `html` / `svg`,
+ * `mermaid` (which hands the cell to the kit's own `<dfk-mermaid>` element, so a
+ * query can produce a diagram the reader can zoom, expand, edit and download),
  * plus the `error` view every renderer shares.
  *
  * Heavy dependencies (`@visactor/vtable`) load through dynamic `import()`

package/dist/sql/runtime.d.ts

@@ -49,6 +49,26 @@ export type RuntimeState = 'idle' | 'loading' | 'ready' | 'error';
 export interface RuntimeOptions {
     /** Let `LOAD` accept an extension whose signature does not verify. */
     allowUnsignedExtensions?: boolean;
+    /**
+     * Serve the DuckDB-Wasm engine from explicit same-origin URLs instead of the
+     * jsDelivr CDN. Used by the offline SQL verifier (`sql/browserRunner`): the
+     * harness passes the locally-served `duckdb-*.wasm` / worker script so a CI
+     * run never reaches the network. When set, `#create()` skips
+     * `getJsDelivrBundles()`/`selectBundle()` and the cross-origin blob-worker
+     * wrapper (the worker is same-origin here, so it is constructed directly).
+     */
+    bundle?: LocalBundle;
+}
+/**
+ * A locally-served DuckDB-Wasm bundle: absolute same-origin URLs for the
+ * engine wasm and its worker script. `pthreadWorker` is only needed for the
+ * cross-origin-isolated (COI) bundle; the default non-COI `eh`/`mvp` bundles run
+ * single-threaded and leave it unset.
+ */
+export interface LocalBundle {
+    mainModule: string;
+    mainWorker: string;
+    pthreadWorker?: string;
 }
 /** Options for {@link DuckDBRuntime.loadExtension}. */
 export interface LoadExtensionOptions {

package/dist/sql/verify.d.ts

@@ -1,4 +1,4 @@
-import { type WasmPlatform } from './nodeRunner';
+import { type WasmPlatform } from './browserRunner';
 export interface VerifyOptions {
     /** Docs site root; defaults to the working directory. */
     siteDir?: string;
@@ -16,11 +16,10 @@ export interface VerifyOptions {
     /** Per-block timeout in milliseconds; a hang is reported instead of blocking CI. */
     timeoutMs?: number;
     /**
-     * Directory the blocks run in. Defaults to a fresh temporary directory that
-     * is removed afterwards: a block may `COPY … TO 'a.csv'`, and on Node
-     * DuckDB's file system is the real one, relative to the working directory.
+     * The browser executable that runs the blocks. Defaults to a detected
+     * Chrome/Edge; the `DFK_BROWSER` environment variable is the same override.
      */
-    workingDir?: string;
+    browser?: string;
     /** Write the full result list here as JSON. */
     reportFile?: string;
 }

package/dist/sql/verify.js

@@ -1,52 +1,39 @@
 import { collectRunnableSql as e, expectsError as t } from "./collect.js";
-import { WasmSqlRunner as n } from "./nodeRunner.js";
+import { BrowserSqlRunner as n } from "./browserRunner.js";
 import { join as r, resolve as i } from "node:path";
-import { mkdirSync as a, mkdtempSync as o, readdirSync as s, rmSync as c, statSync as l, writeFileSync as u } from "node:fs";
-import { tmpdir as d } from "node:os";
+import { readdirSync as a, statSync as o, writeFileSync as s } from "node:fs";
 //#region src/sql/verify.ts
-var f = ["docs", "i18n"], p = 3e4;
-async function m(t = {}) {
-	let n = i(t.siteDir ?? process.cwd()), s = e({
+var c = ["docs", "i18n"], l = 3e4;
+async function u(t = {}) {
+	let n = i(t.siteDir ?? process.cwd()), r = e({
 		siteDir: n,
-		contentDirs: t.contentDirs ?? v(n)
-	}), l = t.extension, f = l ? /^https?:\/\//i.test(l) ? l : i(l) : y(n), m = t.timeoutMs ?? p, g = t.workingDir ? i(t.workingDir) : o(r(d(), "duckfn-sql-verify-"));
-	a(g, { recursive: !0 });
-	let _ = process.cwd();
-	process.chdir(g);
-	let b;
-	try {
-		b = await h(s, f, t, m);
-	} finally {
-		process.chdir(_), t.workingDir || c(g, {
-			recursive: !0,
-			force: !0
-		});
-	}
-	let x = {
-		blocks: b,
-		asDeclared: b.filter((e) => e.outcome === "ok" || e.outcome === "error-as-expected"),
-		unexpected: b.filter((e) => e.outcome === "unexpected-error" || e.outcome === "unexpected-success")
+		contentDirs: t.contentDirs ?? m(n)
+	}), a = t.extension, o = await d(r, a ? /^https?:\/\//i.test(a) ? a : i(a) : h(n), t, t.timeoutMs ?? l), c = {
+		blocks: o,
+		asDeclared: o.filter((e) => e.outcome === "ok" || e.outcome === "error-as-expected"),
+		unexpected: o.filter((e) => e.outcome === "unexpected-error" || e.outcome === "unexpected-success")
 	};
-	return t.reportFile && u(t.reportFile, `${JSON.stringify(x, null, 2)}\n`), x;
+	return t.reportFile && s(t.reportFile, `${JSON.stringify(c, null, 2)}\n`), c;
 }
-async function h(e, t, r, i) {
+async function d(e, t, r, i) {
 	let a = await n.create({
 		extension: t,
 		platform: r.platform,
-		engine: r.engine
+		engine: r.engine,
+		browser: r.browser
 	}), o = [];
 	try {
 		let t = null;
-		for (let n of e) n.file !== t && (t = n.file, await a.newPage()), o.push(await g(a, n, i));
+		for (let n of e) n.file !== t && (t = n.file, await a.newPage()), o.push(await f(a, n, i));
 	} finally {
 		await a.close();
 	}
 	return o;
 }
-async function g(e, n, r) {
+async function f(e, n, r) {
 	let i = t(n.config);
 	try {
-		let t = await _(e.run(n.sql), r);
+		let t = await p(e.run(n.sql), r);
 		return {
 			file: n.file,
 			line: n.line,
@@ -63,43 +50,43 @@ async function g(e, n, r) {
 		};
 	}
 }
-function _(e, t) {
+function p(e, t) {
 	let n, r = new Promise((e, r) => {
 		n = setTimeout(() => r(/* @__PURE__ */ Error(`timed out after ${t}ms`)), t);
 	});
 	return Promise.race([e, r]).finally(() => clearTimeout(n));
 }
-function v(e) {
+function m(e) {
 	let t = [];
-	b(r(e, f[0])) && t.push(f[0]);
-	let n = r(e, f[1]);
-	if (b(n)) for (let e of s(n)) b(r(n, e, "docusaurus-plugin-content-docs", "current")) && t.push(r("i18n", e, "docusaurus-plugin-content-docs", "current"));
+	g(r(e, c[0])) && t.push(c[0]);
+	let n = r(e, c[1]);
+	if (g(n)) for (let e of a(n)) g(r(n, e, "docusaurus-plugin-content-docs", "current")) && t.push(r("i18n", e, "docusaurus-plugin-content-docs", "current"));
 	return t.length > 0 ? t : ["."];
 }
-function y(e) {
-	let t = r(e, "static", "duckdb-extensions"), n = b(t) ? s(t).filter((e) => e.endsWith(".duckdb_extension.wasm")) : [];
+function h(e) {
+	let t = r(e, "static", "duckdb-extensions"), n = g(t) ? a(t).filter((e) => e.endsWith(".duckdb_extension.wasm")) : [];
 	if (n.length === 0) throw Error(`sql/verify: no extension found in ${t} — pass --extension <file|url>, or let the site's extension preload plugin fetch it first`);
 	if (n.length > 1) throw Error(`sql/verify: several extensions found in ${t} (${n.join(", ")}) — pass --extension to pick one`);
 	return r(t, n[0]);
 }
-function b(e) {
-	return l(e, { throwIfNoEntry: !1 })?.isDirectory() ?? !1;
+function g(e) {
+	return o(e, { throwIfNoEntry: !1 })?.isDirectory() ?? !1;
 }
-async function x(e) {
-	let t = C(e);
+async function _(e) {
+	let t = y(e);
 	if (t.help) {
-		process.stdout.write(S);
+		process.stdout.write(v);
 		return;
 	}
-	let n = Date.now(), r = await m(t), i = ((Date.now() - n) / 1e3).toFixed(1), a = r.blocks.filter((e) => e.outcome === "error-as-expected").length;
+	let n = Date.now(), r = await u(t), i = ((Date.now() - n) / 1e3).toFixed(1), a = r.blocks.filter((e) => e.outcome === "error-as-expected").length;
 	if (t.quiet || (process.stdout.write(`\n${r.blocks.length} block(s) in ${i}s\n`), process.stdout.write(`  ${r.asDeclared.length} as declared (${a} erroring on purpose), ${r.unexpected.length} unexpected\n`)), r.unexpected.length > 0) {
 		process.stdout.write("unexpected behaviour:\n");
 		for (let e of r.unexpected) process.stdout.write(`- ${e.file}:${e.line} [${e.outcome}] :: ${e.detail}\n`);
 		process.exitCode = 1;
 	}
 }
-var S = "Usage: duckfn-sql-verify [options]\n\nRuns every runnable SQL block of a duckfn docs site in DuckDB-Wasm, and checks\nthat each one behaves as its own metadata declares (\"expect\": \"error\" for a\nblock that demonstrates a failure).\n\n  --site <dir>          Docs site root (default: the working directory)\n  --content <dir>       Content directory, relative to the site root (repeatable;\n                        default: docs/ plus every i18n/<locale>/… translation)\n  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,\n                        or an absolute http(s) URL (default: the single file under\n                        static/duckdb-extensions/)\n  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build\n                        (default: eh)\n  --engine <path>       Engine wasm override\n  --timeout <ms>        Per-block timeout (default: 30000)\n  --working-dir <dir>   Directory the blocks run in (default: a temporary one)\n  --report <file>       Write the full result list as JSON\n  --quiet               Only report unexpected behaviour\n  --help                Show this help\n";
-function C(e) {
+var v = "Usage: duckfn-sql-verify [options]\n\nRuns every runnable SQL block of a duckfn docs site in a headless browser\n(DuckDB-Wasm), and checks that each one behaves as its own metadata declares\n(\"expect\": \"error\" for a block that demonstrates a failure).\n\n  --site <dir>          Docs site root (default: the working directory)\n  --content <dir>       Content directory, relative to the site root (repeatable;\n                        default: docs/ plus every i18n/<locale>/… translation)\n  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,\n                        or an absolute http(s) URL (default: the single file under\n                        static/duckdb-extensions/)\n  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build\n                        (default: eh)\n  --engine <path>       Engine wasm override\n  --browser <path>      Browser executable (default: a detected Chrome/Edge,\n                        or the DFK_BROWSER environment variable)\n  --timeout <ms>        Per-block timeout (default: 30000)\n  --report <file>       Write the full result list as JSON\n  --quiet               Only report unexpected behaviour\n  --help                Show this help\n";
+function y(e) {
 	let t = {}, n = [];
 	for (let r = 0; r < e.length; r++) {
 		let i = e[r], a = () => {
@@ -123,12 +110,12 @@ function C(e) {
 			case "--engine":
 				t.engine = a();
 				break;
+			case "--browser":
+				t.browser = a();
+				break;
 			case "--timeout":
 				t.timeoutMs = Number(a());
 				break;
-			case "--working-dir":
-				t.workingDir = a();
-				break;
 			case "--report":
 				t.reportFile = a();
 				break;
@@ -145,4 +132,4 @@ function C(e) {
 	return n.length > 0 && (t.contentDirs = n), t;
 }
 //#endregion
-export { x as cliMain, m as verifySqlDocs };
+export { _ as cliMain, u as verifySqlDocs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Shared Docusaurus building blocks (TOC toggle, home-page web components, brand tokens, remark version placeholder) for duckfn-family extension docs sites.",
   "license": "MIT",
   "keywords": [
@@ -45,7 +45,7 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json",
+    "build": "vite build && vite build --config vite.harness.config.ts && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "prepack": "npm run build"
@@ -59,9 +59,13 @@
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
     "@duckdb/duckdb-wasm": "1.33.1-dev64.0",
+    "@panzoom/panzoom": "^4.6.2",
     "@visactor/vtable": "^1.26.8",
     "codemirror": "^6.0.2",
+    "filenamify": "^7.0.3",
     "iconify-icon": "^3.0.3",
+    "mermaid": "^12.0.0",
+    "playwright-core": "^1.63.0",
     "sql-formatter": "^15.9.0"
   },
   "devDependencies": {

package/src/IconButton.ts

@@ -0,0 +1,50 @@
+import type {IconifyIconHTMLElement} from 'iconify-icon';
+import {el} from './dom';
+
+/**
+ * A compact icon-only button with a hover/focus tooltip, built once and then
+ * mutated. Shared by `<dfk-sql>`'s code-block cluster and `<dfk-mermaid>`'s
+ * diagram cluster: both want the same "floating icon row over content" idiom,
+ * and neither wants a second implementation of it.
+ *
+ * The tooltip is also the accessible name — an icon-only control has no text to
+ * fall back on. The two class names are written by this module and styled in
+ * *each* consumer's shadow-root CSS; that duplication is unavoidable (a shadow
+ * boundary stops one sheet from reaching the other tree), so the rules carry the
+ * same names and are kept in sync by hand.
+ */
+export class IconButton {
+  readonly root = el('button', {class: 'dfk-icon-button', type: 'button'});
+  readonly #icon: IconifyIconHTMLElement = el('iconify-icon', {
+    class: 'dfk-icon',
+    attrs: {'aria-hidden': 'true'},
+  });
+
+  constructor(icon: string, onClick: () => void) {
+    this.root.appendChild(this.#icon);
+    this.root.addEventListener('click', onClick);
+    this.setIcon(icon);
+  }
+
+  setIcon(icon: string): void {
+    this.#icon.setAttribute('icon', icon);
+  }
+
+  setLabel(text: string): void {
+    this.root.setAttribute('data-tip', text);
+    this.root.setAttribute('aria-label', text);
+  }
+
+  /** Marks a toggle as currently on (e.g. the SQL block's wrap toggle). */
+  setOn(on: boolean): void {
+    this.root.classList.toggle('dfk-icon-on', on);
+  }
+
+  setDisabled(disabled: boolean): void {
+    if (disabled) {
+      this.root.setAttribute('disabled', '');
+    } else {
+      this.root.removeAttribute('disabled');
+    }
+  }
+}

package/src/codemirror.ts

@@ -0,0 +1,88 @@
+/**
+ * The CodeMirror 6 editor behind the kit's editable content: the code view of a
+ * runnable SQL block (`<dfk-sql>`) and the diagram-source dialog of a
+ * `<dfk-mermaid>`. One implementation, two languages — the SQL block asks for
+ * highlighting, the diagram editor takes the plain-text default.
+ *
+ * Every CodeMirror module arrives through a dynamic `import()` inside
+ * {@link mountCodeEditor}: a page full of blocks pays nothing for the editor on
+ * its critical path, and Docusaurus' Node prerender never evaluates any of it.
+ *
+ * This is browser-only code: `document` is touched only through the container
+ * the caller hands over, and everything else is behind the `import()`s.
+ */
+
+export interface CodeEditor {
+  getValue(): string;
+  setValue(value: string): void;
+  /** Soft-wraps long lines, or stops wrapping them (the block's wrap toggle). */
+  setWrap(wrapped: boolean): void;
+  destroy(): void;
+}
+
+export interface CodeEditorOptions {
+  /**
+   * Highlight the document as SQL. Omitted, the editor is plain text — which is
+   * what a mermaid diagram gets: there is no first-party CodeMirror language for
+   * it, and a docs reader is editing prose-shaped source, not writing SQL.
+   */
+  language?: 'sql';
+}
+
+export async function mountCodeEditor(
+  container: HTMLElement,
+  value: string,
+  onChange: (value: string) => void,
+  options: CodeEditorOptions = {},
+): Promise<CodeEditor> {
+  const [{basicSetup}, {EditorView, keymap}, {defaultKeymap, historyKeymap}, {Compartment}] =
+    await Promise.all([
+      import('codemirror'),
+      import('@codemirror/view'),
+      import('@codemirror/commands'),
+      import('@codemirror/state'),
+    ]);
+  // Loaded only for the blocks that ask for it, so a diagram editor does not pull
+  // the SQL grammar (and its lezer parsers) into the page.
+  const language =
+    options.language === 'sql' ? [(await import('@codemirror/lang-sql')).sql()] : [];
+
+  // Wrapping is toggled from the outside, and reconfiguring it must not disturb
+  // the document or the undo history — that is exactly what a compartment is
+  // for, so the extension is swapped in place rather than rebuilt.
+  const wrap = new Compartment();
+
+  const view = new EditorView({
+    doc: value,
+    extensions: [
+      basicSetup,
+      ...language,
+      keymap.of([...defaultKeymap, ...historyKeymap]),
+      wrap.of([]),
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) {
+          onChange(update.state.doc.toString());
+        }
+      }),
+    ],
+    parent: container,
+    // `root` is left to CodeMirror's own `getRoot(container)`. The container sits
+    // in the component's shadow root, so style-mod mounts the base theme into
+    // that same shadow root — exactly where the `.cm-*` rules are needed.
+    // Pinning it to `document` would put them outside the editor's tree instead,
+    // where a shadow boundary stops them.
+  });
+
+  return {
+    getValue: () => view.state.doc.toString(),
+    setValue: (next: string) =>
+      view.dispatch({
+        changes: {from: 0, to: view.state.doc.length, insert: next},
+      }),
+    setWrap: (wrapped: boolean) =>
+      view.dispatch({
+        effects: wrap.reconfigure(wrapped ? EditorView.lineWrapping : []),
+      }),
+    destroy: () => view.destroy(),
+  };
+}

package/src/index.ts

@@ -1,7 +1,14 @@
 import type {HTMLAttributes} from 'react';
+// Imported as well as re-exported: the `HTMLElementTagNameMap` augmentation below
+// names the classes, and a module augmentation can only refer to local bindings.
+import {DfkFeatures} from './home/DfkFeatures';
+import {DfkHero} from './home/DfkHero';
+import {DfkMermaid} from './mermaid/DfkMermaid';
+import {DfkNextSteps} from './home/DfkNextSteps';
+import {DfkSql} from './sql/DfkSql';
 
 /**
- * Browser entry for duckfn-docs-kit: the home-page custom elements and the
+ * Browser entry for duckfn-docs-kit: the custom elements it registers and the
  * value types their `set*` methods accept.
  *
  * The components are retained-mode (build once, then mutate held nodes) and
@@ -13,17 +20,16 @@ import type {HTMLAttributes} from 'react';
  * web component, which `registerDfkElements()` registers as a side effect, so
  * this package ships no icon data.
  *
- * `TocToggle` and the remark plugin keep their own subpaths
- * (`duckfn-docs-kit/toc-toggle/TocToggle`, `duckfn-docs-kit/remark`) instead of
+ * `TocToggle` and the remark plugins keep their own subpaths
+ * (`duckfn-docs-kit/toc-toggle/TocToggle`, `duckfn-docs-kit/remark`,
+ * `duckfn-docs-kit/sql/remark`, `duckfn-docs-kit/mermaid/remark`) instead of
  * being merged here: a Docusaurus config file must never pull browser code into
  * Node, and a site that only wants the TOC collapse button should not pay for
  * the bundled `iconify-icon`.
  */
-export {DfkFeatures} from './home/DfkFeatures';
-export {DfkHero} from './home/DfkHero';
-export {DfkNextSteps} from './home/DfkNextSteps';
-export {DfkSql} from './sql/DfkSql';
+export {DfkFeatures, DfkHero, DfkMermaid, DfkNextSteps, DfkSql};
 export {registerDfkElements} from './register';
+export type {DfkMermaidConfig, DfkMermaidConfigInput} from './mermaid/config';
 export type {RunnableSqlConfig} from './sql/remark';
 export type {
   FeatureItem,
@@ -47,6 +53,23 @@ export type {
  */
 export type DfkElementProps = HTMLAttributes<HTMLElement>;
 
+/**
+ * The kit's tags in the DOM's own tag map, so `document.createElement('dfk-sql')`
+ * (and the kit's `el()` helper) is typed as the class it upgrades to. Without
+ * this, every place that builds a `dfk-*` element from scratch — `sql/renderers.ts`
+ * building a `<dfk-mermaid>` for a `mermaid` result, `docs/src/pages/index.tsx`
+ * mounting the home elements — would have to cast the result.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    'dfk-hero': DfkHero;
+    'dfk-features': DfkFeatures;
+    'dfk-next-steps': DfkNextSteps;
+    'dfk-sql': DfkSql;
+    'dfk-mermaid': DfkMermaid;
+  }
+}
+
 declare module 'react' {
   namespace JSX {
     interface IntrinsicElements {
@@ -54,6 +77,7 @@ declare module 'react' {
       'dfk-features': DfkElementProps;
       'dfk-next-steps': DfkElementProps;
       'dfk-sql': DfkElementProps;
+      'dfk-mermaid': DfkElementProps;
     }
   }
 }