duckfn-docs-kit 0.2.1 → 0.4.0

package/src/mermaid/remark.ts

@@ -0,0 +1,98 @@
+import type {Plugin} from 'unified';
+import type {DfkMermaidConfigInput} from './config';
+
+/**
+ * Turns a ```mermaid fence into a `<dfk-mermaid>` custom element, so the docs
+ * site renders diagrams through this kit instead of through
+ * `@docusaurus/theme-mermaid`.
+ *
+ * That theme's React component cannot avoid the two upstream defects
+ * `./render.ts` documents — it colours by `useColorMode()`, which lags behind on
+ * the first client render, so a dark-mode first load paints a light diagram and
+ * then a dark one (the flash, and occasionally an empty SVG), and mermaid's
+ * mutable singleton renders two diagrams at once. Doing the render in a custom
+ * element instead puts both fixes in one place that every duckfn-family docs site
+ * shares, and lets the runnable-SQL `mermaid` output reuse the same renderer.
+ *
+ * The source travels as the `source` attribute and the palette as the `config`
+ * one (see `./config`): React 19 reconciles string props onto a custom element as
+ * attributes, so both survive prerendering and hydration. The element has no
+ * children — the diagram is built in its shadow root, so there is no prerendered
+ * markup to hide (contrast `sql/remark.ts`, whose code node is the fallback the
+ * editor replaces).
+ *
+ * This is Node-side build code: it must not touch `window` / `document`, and it
+ * must not import any browser module (type-only imports are fine).
+ */
+
+/** The custom element the plugin emits; must match `register.ts`. */
+export const DFK_MERMAID_TAG = 'dfk-mermaid';
+
+export interface RemarkMermaidOptions {
+  /**
+   * Overrides for the kit's default look and palette, merged by the element (see
+   * `resolveMermaidConfig`). This is where a site picks its mermaid colours — the
+   * one part of a diagram that is site-specific — so no docs site has to fork the
+   * kit to change two theme names.
+   *
+   * Omitted, no `config` attribute is written at all and every element falls back
+   * to the kit's default (`DEFAULT_MERMAID_CONFIG` in `./config`).
+   */
+  config?: DfkMermaidConfigInput;
+}
+
+interface CodeNode {
+  type: string;
+  lang?: string | null;
+  value?: unknown;
+}
+
+interface ParentNode {
+  children?: unknown[];
+}
+
+export const remarkMermaid: Plugin<[RemarkMermaidOptions?]> =
+  (options = {}) =>
+  (tree) => {
+    // One JSON string for the whole page rather than one per fence: the attribute
+    // is identical everywhere, and building it once keeps the walk cheap.
+    const config = options.config === undefined ? null : JSON.stringify(options.config);
+
+    const walk = (node: unknown): void => {
+      if (typeof node !== 'object' || node === null) {
+        return;
+      }
+      const parent = node as ParentNode;
+      if (!Array.isArray(parent.children)) {
+        return;
+      }
+      parent.children = parent.children.map((child) => {
+        if (typeof child !== 'object' || child === null) {
+          return child;
+        }
+        const candidate = child as CodeNode;
+        if (candidate.type === 'code' && candidate.lang === 'mermaid') {
+          return wrapMermaid(candidate, config);
+        }
+        walk(candidate);
+        return candidate;
+      });
+    };
+
+    walk(tree);
+  };
+
+function wrapMermaid(code: CodeNode, config: string | null): Record<string, unknown> {
+  const attributes = [
+    {type: 'mdxJsxAttribute', name: 'source', value: String(code.value ?? '')},
+  ];
+  if (config !== null) {
+    attributes.push({type: 'mdxJsxAttribute', name: 'config', value: config});
+  }
+  return {
+    type: 'mdxJsxFlowElement',
+    name: DFK_MERMAID_TAG,
+    attributes,
+    children: [],
+  };
+}

package/src/mermaid/render.ts

@@ -0,0 +1,178 @@
+/**
+ * The one place the kit talks to mermaid: the load, the render queue, the config
+ * the renderer is initialised with, and the two document-level facts a diagram
+ * needs (which colour mode the page is in, and how a rendered SVG gets into a
+ * shadow tree).
+ *
+ * Two upstream problems are solved here, and neither can be fixed from a site's
+ * `docusaurus.config.ts` or from the diagram source:
+ *
+ * 1. **The flash on a dark-mode first load, and the blank diagram.** Docusaurus'
+ *    `useColorMode()` deliberately lags behind on the first client render (its
+ *    state is initialised in an effect, to avoid hydration mismatches), so a
+ *    theme-aware renderer paints once with the light palette and then again with
+ *    the dark one: the light one lands on screen briefly (the flash), and the two
+ *    overlap inside mermaid's mutable singleton, which can resolve with an empty
+ *    SVG (an empty container, no error — facebook/docusaurus#8357). This module
+ *    reads `<html data-theme>` instead: the attribute the inline script in
+ *    `<head>` writes *before* the first paint, and the one the page CSS keys off.
+ *    Nothing is rendered until it is known, so each diagram is rendered exactly
+ *    once per mode, in the mode the page is really in.
+ * 2. **Concurrent renders.** Mermaid is a mutable singleton that cannot render
+ *    two diagrams at once (`mermaid.initialize()` sets one global config, and the
+ *    renderer mutates it as it goes): docusaurus#8357 asks to "render them
+ *    sequentially one after the other", pointing at mermaid-js/mermaid#3577.
+ *    Every render therefore goes through a single queue.
+ *
+ * This is browser-only code: `mermaid` and every DOM API are reached lazily, so
+ * Docusaurus' Node prerender can import the module graph without evaluating any
+ * of it.
+ */
+
+import type {DfkMermaidConfig, MermaidColorMode} from './config';
+
+/** The mermaid singleton, exactly as the package's default export types it. */
+type Mermaid = (typeof import('mermaid'))['default'];
+type RenderResult = Awaited<ReturnType<Mermaid['render']>>;
+type MermaidConfig = Parameters<Mermaid['initialize']>[0];
+
+/**
+ * One queue for the whole page: mermaid's `render()` calls are serialised,
+ * never concurrent. A rejected task must not poison the queue, hence the
+ * `catch` on the tail that the next task chains from.
+ */
+let queue: Promise<unknown> = Promise.resolve();
+
+function enqueue<T>(task: () => Promise<T>): Promise<T> {
+  const result = queue.then(task, task);
+  queue = result.catch(() => undefined);
+  return result;
+}
+
+let mermaidModule: Promise<Mermaid> | null = null;
+
+/**
+ * Loads (once) and returns the mermaid singleton. A dynamic `import()` so a page
+ * with no diagram never downloads it, and the Node prerender never evaluates it.
+ */
+function loadMermaid(): Promise<Mermaid> {
+  mermaidModule ??= import('mermaid').then((module) => module.default);
+  return mermaidModule;
+}
+
+/** Keeps the ids mermaid is handed unique across every diagram on a page. */
+let sequence = 0;
+
+/** How a diagram is rendered: its source, its config, and its colour mode. */
+export interface MermaidRenderRequest {
+  source: string;
+  config: DfkMermaidConfig;
+  colorMode: MermaidColorMode;
+}
+
+/** A rendered diagram: the SVG markup, plus mermaid's bind hook for click handlers. */
+export interface MermaidRenderOutput {
+  svg: string;
+  bind?(container: Element): void;
+}
+
+/**
+ * Renders one diagram, through the page-wide queue. Each render re-initialises
+ * mermaid with this diagram's config first: mermaid has two config levels and the
+ * site-wide one can only be set through `initialize()`.
+ */
+export function renderMermaid({
+  source,
+  config,
+  colorMode,
+}: MermaidRenderRequest): Promise<MermaidRenderOutput> {
+  const id = `dfk-mermaid-svg-${(sequence += 1)}`;
+  return enqueue(async () => {
+    const mermaid = await loadMermaid();
+    const options: MermaidConfig = {
+      startOnLoad: false,
+      ...config.options,
+      // `DfkMermaidConfig.theme` is a plain string on purpose — the kit does not
+      // pin mermaid's theme list (the shared config must stay dependency-free,
+      // and a site may name a theme a newer mermaid adds). This is the one place
+      // the value meets mermaid's own union, so the narrowing happens here.
+      theme: config.theme[colorMode] as MermaidConfig['theme'],
+    };
+    mermaid.initialize(options);
+    try {
+      const result: RenderResult = await mermaid.render(id, source);
+      return {svg: result.svg, bind: result.bindFunctions};
+    } catch (error) {
+      // Mermaid leaves a stray SVG/message in the DOM on error
+      // (https://github.com/mermaid-js/mermaid/issues/3205).
+      document.querySelector(`#d${id}`)?.remove();
+      throw error;
+    }
+  });
+}
+
+/** The colour mode the page is actually in, read from the pre-paint attribute. */
+export function documentColorMode(): MermaidColorMode {
+  return document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light';
+}
+
+/**
+ * Calls `listener` whenever the page's colour mode changes, and returns the
+ * unsubscribe. The `<head>` script only *writes* the attribute on load, so a
+ * mode switch made later has to be observed — that is how a diagram follows the
+ * theme toggle.
+ */
+export function watchColorMode(listener: () => void): () => void {
+  const observer = new MutationObserver(listener);
+  observer.observe(document.documentElement, {attributeFilter: ['data-theme']});
+  return () => observer.disconnect();
+}
+
+/**
+ * Turns mermaid's SVG markup into a node a shadow tree can host.
+ *
+ * Mermaid serialises through `innerHTML`, so its output is *HTML*, not strict
+ * XML: an HTML label can carry a bare `<br>`, which `image/svg+xml` would reject.
+ * Parsing as `text/html` and taking the `<svg>` element gives the right
+ * namespace for free (the HTML parser enters foreign content for `<svg>`) and
+ * keeps markup out of `innerHTML`, which the kit's conventions rule out.
+ *
+ * Returns `null` when there is no `<svg>` to be found, so the caller can show an
+ * error instead of an empty box.
+ */
+export function parseMermaidSvg(owner: Document, svg: string): SVGElement | null {
+  const parsed = new DOMParser().parseFromString(svg, 'text/html');
+  const root = parsed.body.querySelector('svg');
+  return root ? (owner.importNode(root, true) as unknown as SVGElement) : null;
+}
+
+/** The pan/zoom library, loaded once on first use (see `DfkMermaid`). */
+export async function loadPanzoom(): Promise<typeof import('@panzoom/panzoom')['default']> {
+  const module = await import('@panzoom/panzoom');
+  return module.default;
+}
+
+/**
+ * Serialises a rendered diagram into standalone SVG markup.
+ *
+ * Mermaid hands its SVG back as an **HTML** string (it stringifies a detached
+ * element through `innerHTML`), and HTML serialisation writes a void element
+ * without a closing slash: a `<br/>` the author put inside a label comes back as
+ * `<br>`. That is fine where it lands — the page's HTML parser reads it, and
+ * `parseMermaidSvg()` parses it the same way — but it is fatal for a *file*: a
+ * browser opening an `.svg` parses XML, and `<br>` inside a `<p>` there is
+ * `Opening and ending tag mismatch: br … and p`, with the drawing cut off at the
+ * first error.
+ *
+ * Re-serialising the live node with `XMLSerializer` fixes both halves at once:
+ * XML serialisation closes every element, and it emits the namespace declarations
+ * a standalone document needs (`xmlns` on the `<svg>`, and one on any
+ * `foreignObject` subtree, whose XHTML content inherits its namespace from the
+ * page rather than carrying it as an attribute).
+ *
+ * This is why the element keeps the rendered `<svg>` node for the download
+ * instead of mermaid's own string: only the node can be re-serialised.
+ */
+export function serializeMermaidSvg(svg: SVGElement): string {
+  return new XMLSerializer().serializeToString(svg);
+}

package/src/mermaid/styles.ts

@@ -0,0 +1,24 @@
+// The `<dfk-mermaid>` shadow-root CSS as an inline string (Vite `?inline`
+// import), mirroring `home/styles.ts` and `sql/styles.ts`. Everything the
+// component draws lives in the shadow tree — the diagram included, which is what
+// keeps mermaid's inline `<style>` (it ships one inside every SVG) scoped to this
+// one component instead of leaking into the page or into a sibling diagram.
+//
+// The type declaration lives in `vite-env.d.ts`; `tsc` never resolves the
+// `?inline` suffix, so the module graph stays buildable without Vite running.
+import mermaidCss from './DfkMermaid.css?inline';
+
+let sheet: CSSStyleSheet | null = null;
+
+/**
+ * The one parsed stylesheet shared by every `<dfk-mermaid>` shadow root.
+ * Created lazily: `CSSStyleSheet` does not exist during Docusaurus' Node
+ * prerender, and only the browser ever calls this.
+ */
+export function mermaidStyles(): CSSStyleSheet {
+  if (!sheet) {
+    sheet = new CSSStyleSheet();
+    sheet.replaceSync(mermaidCss);
+  }
+  return sheet;
+}

package/src/mermaid/title.ts

@@ -0,0 +1,127 @@
+import filenamify from 'filenamify';
+
+/**
+ * What a downloaded diagram is called.
+ *
+ * The name is derived from the page, not from the diagram: a diagram has no name
+ * of its own, and the reader downloading one is after "the diagram from that
+ * section", not `mermaid-diagram.svg`.
+ *
+ * Three sources, most specific first, each falling back to the next:
+ *
+ * 1. **The diagram's own title** — mermaid's frontmatter
+ *    (`---\ntitle: …\n---`, which mermaid itself draws above the diagram).
+ * 2. **The nearest heading above it** — the section the diagram belongs to, which
+ *    on a docs page is what a reader would call it.
+ * 3. **The document title** — the browser tab's title, for a diagram that sits
+ *    above every heading on its page.
+ *
+ * Nothing found → {@link DEFAULT_DIAGRAM_FILE}.
+ *
+ * This is browser-only code.
+ */
+
+/** Used when nothing on the page says anything about this diagram. */
+export const DEFAULT_DIAGRAM_FILE = 'mermaid-diagram.svg';
+
+/**
+ * The length cap. `filenamify` truncates by grapheme, so a CJK heading is cut at
+ * 80 *characters*, not bytes, and an emoji survives whole.
+ */
+const MAX_LENGTH = 80;
+
+/** How a reserved character is spelled in the file name (`2. Registration: …`). */
+const REPLACEMENT = '-';
+
+/**
+ * The *format* characters (zero-width space, word joiner, byte-order mark…) and
+ * whitespace that a title can wear at its edges.
+ */
+const EDGE_NOISE = /^[\s\p{Cf}]+|[\s\p{Cf}]+$/gu;
+
+/**
+ * Trims a candidate down to its text, dropping format characters at the edges.
+ *
+ * Plain whitespace trimming is not enough: Docusaurus gives every heading an
+ * anchor link whose label is a zero-width space, so `textContent` of a heading is
+ * `"2. Registration\u200B"`. `filenamify` turns a format character into the
+ * replacement rather than dropping it, which would produce
+ * `2. Registration-.svg`. Only the *edges*: an interior zero-width joiner is what
+ * holds an emoji together.
+ */
+function cleanTitle(value: string | undefined): string {
+  return value === undefined ? '' : value.replace(EDGE_NOISE, '');
+}
+
+export function diagramFileName(source: string, element: Element): string {
+  const candidates = [
+    frontmatterTitle(source),
+    precedingHeading(element),
+    element.ownerDocument.title,
+  ].map(cleanTitle);
+  const title = candidates.find((candidate) => candidate !== '');
+  if (title === undefined) {
+    return DEFAULT_DIAGRAM_FILE;
+  }
+  // Filenames are a filesystem concern, so they go through a library rather than a
+  // hand-rolled character class. Three things it does that matter here and that a
+  // browser does *not*: it strips what Windows and macOS reject (`:`, `?`, `*`,
+  // `"`, `<`, `>`, `|`, the path separators and control characters), it trims the
+  // trailing dots and spaces Windows silently drops, and it avoids the reserved
+  // device names (`con`, `nul`, …). The `download` attribute's own sanitisation
+  // covers only `/` and `\`.
+  //
+  // It also normalises Unicode whitespace and drops format characters, which
+  // quietly cleans up Docusaurus' heading anchors: the `<a>` it appends to every
+  // heading contributes a zero-width space to `textContent`.
+  return `${filenamify(title, {replacement: REPLACEMENT, maxLength: MAX_LENGTH})}.svg`;
+}
+
+/**
+ * mermaid's frontmatter block, if the source opens with one.
+ *
+ * Only the top-level `title:` key is read. Mermaid's frontmatter is YAML, and the
+ * rest of it (a nested `config:`, `displayMode:`, …) is none of this module's
+ * business: a key that is always a plain scalar on one line does not justify a
+ * YAML parser, and anything indented — a nested key — is skipped by anchoring the
+ * match at the line start.
+ */
+function frontmatterTitle(source: string): string | undefined {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source.trimStart())?.[1];
+  if (block === undefined) {
+    return undefined;
+  }
+  const value = /^title\s*:\s*(.+)$/m.exec(block)?.[1];
+  return value === undefined ? undefined : unquote(value.trim());
+}
+
+/** Strips one pair of matching quotes, so `title: "A: B"` keeps its colon. */
+function unquote(value: string): string {
+  const first = value[0];
+  return (first === '"' || first === "'") && value.endsWith(first) ? value.slice(1, -1) : value;
+}
+
+/**
+ * The text of the last heading that precedes the diagram, or `undefined`.
+ *
+ * The search is scoped to the enclosing `<article>` where there is one: a docs
+ * page's navbar, sidebar and footer are full of headings that have nothing to do
+ * with this diagram, and the article is the one container that holds the page's
+ * own content.
+ */
+function precedingHeading(element: Element): string | undefined {
+  const scope: ParentNode = element.closest('article') ?? element.ownerDocument;
+  let found: string | undefined;
+  for (const heading of scope.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+    // `FOLLOWING` means the heading comes before the element in document order.
+    if (!(heading.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING)) {
+      // Headings are in document order, so nothing later can precede it either.
+      break;
+    }
+    const text = heading.textContent?.trim();
+    if (text) {
+      found = text;
+    }
+  }
+  return found;
+}

package/src/register.ts

@@ -4,6 +4,7 @@
 import 'iconify-icon';
 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';
 
@@ -12,6 +13,7 @@ const TAGS = {
   features: 'dfk-features',
   nextSteps: 'dfk-next-steps',
   sql: 'dfk-sql',
+  mermaid: 'dfk-mermaid',
 } as const;
 
 /**
@@ -31,6 +33,7 @@ export function registerDfkElements(): void {
     [TAGS.features]: DfkFeatures,
     [TAGS.nextSteps]: DfkNextSteps,
     [TAGS.sql]: DfkSql,
+    [TAGS.mermaid]: DfkMermaid,
   })) {
     if (!customElements.get(name)) {
       customElements.define(name, ctor);

package/src/remark.ts

@@ -15,7 +15,7 @@ import type {Plugin} from 'unified';
 export const DEFAULT_VERSION_PLACEHOLDER = '{{DUCKFN_VERSION}}';
 
 export interface VersionPlaceholderOptions {
-  /** The real version string to substitute in, e.g. `0.0.14`. */
+  /** The real version string to substitute in, e.g. `0.0.17`. */
   version: string;
   /** Override the token if a site uses a different one. */
   placeholder?: string;

package/src/sql/DfkSql.css

@@ -159,10 +159,13 @@
 
 /* --- Icon buttons and their tooltips ------------------------------------- */
 
-/* Duplicated in `sql.css`: these buttons live in this shadow tree, while the
-   fullscreen toggle a renderer parks in the result's tab strip lives in the
-   light DOM, where a shadow rule could not reach it. Keep both copies in sync. */
-.dfk-sql-icon-button {
+/* The class names are written by the shared `IconButton` widget (`src/IconButton.ts`).
+   The rules are duplicated in `sql.css` and `DfkMermaid.css`: these buttons live
+   in this shadow tree, the fullscreen toggle a renderer parks in the result's tab
+   strip lives in the light DOM, and a diagram's cluster lives in another shadow
+   tree entirely — a shadow rule can only ever reach one of the three. Keep the
+   copies in sync. */
+.dfk-icon-button {
   position: relative;
   display: inline-flex;
   align-items: center;
@@ -178,27 +181,27 @@
   transition: background 0.12s ease, color 0.12s ease;
 }
 
-.dfk-sql-icon-button:hover:not(:disabled),
-.dfk-sql-icon-button:focus-visible {
+.dfk-icon-button:hover:not(:disabled),
+.dfk-icon-button:focus-visible {
   background: var(--ifm-color-emphasis-200, #e6e6e6);
   color: var(--ifm-color-primary, #14459b);
 }
 
-.dfk-sql-icon-button:disabled {
+.dfk-icon-button:disabled {
   opacity: 0.45;
   cursor: progress;
 }
 
-.dfk-sql-icon-button[hidden] {
+.dfk-icon-button[hidden] {
   display: none;
 }
 
 /* A sticky state, e.g. the wrap toggle while wrapping is on. */
-.dfk-sql-icon-on {
+.dfk-icon-on {
   color: var(--ifm-color-primary, #14459b);
 }
 
-.dfk-sql-icon {
+.dfk-icon {
   font-size: 1rem;
 }
 

package/src/sql/DfkSql.ts

@@ -1,8 +1,8 @@
-import type {IconifyIconHTMLElement} from 'iconify-icon';
 import type {RunnableSqlConfig} from './remark';
 import {DuckDBRuntime, type QueryResult} from './runtime';
 import {rendererFor, type RenderContext} from './renderers';
-import {mountSqlEditor, type SqlEditor} from './editor';
+import {mountCodeEditor, type CodeEditor} from '../codemirror';
+import {IconButton} from '../IconButton';
 import {sqlStyles} from './styles';
 import {el, HTMLElementBase} from '../dom';
 
@@ -204,7 +204,7 @@ export class DfkSql extends HTMLElementBase {
   };
 
   #resultHost: HTMLElement | null = null;
-  #editor: SqlEditor | null = null;
+  #editor: CodeEditor | null = null;
   #disposeResult: (() => void) | null = null;
 
   constructor() {
@@ -337,9 +337,14 @@ export class DfkSql extends HTMLElementBase {
     this.#mounting = true;
     this.#setEditorPending(true);
     try {
-      const editor = await mountSqlEditor(this.#editorHost, this.#currentSql, (value) => {
-        this.#currentSql = value;
-      });
+      const editor = await mountCodeEditor(
+        this.#editorHost,
+        this.#currentSql,
+        (value) => {
+          this.#currentSql = value;
+        },
+        {language: 'sql'},
+      );
       if (!this.isConnected) {
         // Disconnected while the CodeMirror modules were loading: nothing will
         // ever dispose this editor, so dispose it here.
@@ -571,46 +576,6 @@ export class DfkSql extends HTMLElementBase {
   }
 }
 
-/**
- * A compact icon-only button with a hover tooltip, built once. The tooltip is
- * also the accessible name — an icon-only control has no text to fall back on.
- */
-class IconButton {
-  readonly root = el('button', {class: 'dfk-sql-icon-button', type: 'button'});
-  readonly #icon: IconifyIconHTMLElement = el('iconify-icon', {
-    class: 'dfk-sql-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 (the wrap button). */
-  setOn(on: boolean): void {
-    this.root.classList.toggle('dfk-sql-icon-on', on);
-  }
-
-  setDisabled(disabled: boolean): void {
-    if (disabled) {
-      this.root.setAttribute('disabled', '');
-    } else {
-      this.root.removeAttribute('disabled');
-    }
-  }
-}
-
 function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }