duckfn-docs-kit 0.3.0 → 0.4.1

package/dist/IconButton.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare class IconButton {
+    #private;
+    readonly root: HTMLButtonElement;
+    constructor(icon: string, onClick: () => void);
+    setIcon(icon: string): void;
+    setLabel(text: string): void;
+    /** Marks a toggle as currently on (e.g. the SQL block's wrap toggle). */
+    setOn(on: boolean): void;
+    setDisabled(disabled: boolean): void;
+}

package/dist/codemirror.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare function mountCodeEditor(container: HTMLElement, value: string, onChange: (value: string) => void, options?: CodeEditorOptions): Promise<CodeEditor>;

package/dist/download.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Saving something the kit rendered to a file: the payload shape, the click that
+ * performs the save, and how the file is named.
+ *
+ * Shared by `<dfk-mermaid>` (a downloaded diagram) and the SQL result chrome (a
+ * downloaded result of any kind), so a docs page has one definition of "what a
+ * download is" rather than one per component.
+ *
+ * This is browser-only code.
+ */
+/** One file's worth of text, ready to save. */
+export interface DownloadPayload {
+    /** The file name, extension included. */
+    name: string;
+    /** The blob's MIME type. */
+    mime: string;
+    /** The file's contents — text for every format the kit produces. */
+    text: string;
+}
+/**
+ * Saves a payload through a temporary object URL.
+ *
+ * The anchor is in the document for the click — some browsers ignore a detached
+ * one — and the URL is revoked on the next tick, once the download has been
+ * handed to the browser.
+ */
+export declare function saveDownload(payload: DownloadPayload): void;
+/**
+ * What a downloaded figure is called.
+ *
+ * The name is derived from the page, not from the figure: a diagram or an SVG
+ * result has no name of its own, and the reader downloading one is after "the
+ * figure from that section", not `diagram.svg`.
+ *
+ * Three sources, most specific first, each falling back to the next:
+ *
+ * 1. **The figure's own title** — mermaid's frontmatter (`---\ntitle: …\n---`,
+ *    which mermaid itself draws above the diagram); only read when `options.source`
+ *    is given.
+ * 2. **The nearest heading above it** — the section the figure 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 figure that sits
+ *    above every heading on its page.
+ *
+ * Nothing found → `options.fallback` (or {@link DEFAULT_BASE}), with `extension`
+ * appended either way.
+ */
+export declare function sectionFileName(element: Element, extension: string, options?: {
+    source?: string;
+    fallback?: string;
+}): string;

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 import type { HTMLAttributes } from 'react';
+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
@@ -12,17 +17,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, HeroAction, HeroBadge, HeroLink, NextStepItem, } from './types';
 /**
@@ -38,6 +42,22 @@ export type { FeatureItem, HeroAction, HeroBadge, HeroLink, NextStepItem, } from
  * from the declaration file.
  */
 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 {
@@ -45,6 +65,7 @@ declare module 'react' {
             'dfk-features': DfkElementProps;
             'dfk-next-steps': DfkElementProps;
             'dfk-sql': DfkElementProps;
+            'dfk-mermaid': DfkElementProps;
         }
     }
 }

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, r, t as i } from "./register-CALCwFBv.js";
-export { e as DfkFeatures, t as DfkHero, r as DfkNextSteps, n as DfkSql, i as registerDfkElements };
+import { a as e, i as t, n, o as r, r as i, t as a } from "./register-wdwf0LC4.js";
+export { r as DfkFeatures, e as DfkHero, t as DfkMermaid, i as DfkNextSteps, n as DfkSql, a as registerDfkElements };

package/dist/mermaid/DfkMermaid.d.ts

@@ -0,0 +1,25 @@
+import { HTMLElementBase } from '../dom';
+import { type DownloadPayload } from '../download';
+export declare class DfkMermaid extends HTMLElementBase {
+    #private;
+    constructor();
+    /**
+     * The zoom/source controls an embedded diagram offers, for the host to place in
+     * its own chrome. Empty (and unused) when standalone — the element keeps them.
+     */
+    get actions(): HTMLElement;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Turns zoom/pan on or off for an embedded diagram. The host calls this with its
+     * own fullscreen state: an embedded diagram zooms exactly where its result area
+     * is expanded, and fills that area while it is.
+     */
+    setFullscreen(value: boolean): void;
+    /**
+     * The file this diagram would be saved as, or `null` while nothing is rendered.
+     * An embedded diagram hands this to the result chrome's download button, which
+     * is why the element does not save it itself.
+     */
+    downloadPayload(): DownloadPayload | null;
+}

package/dist/mermaid/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The mermaid look and palette, shared by the Node-side remark plugin (which
+ * stamps it onto every `<dfk-mermaid>` it emits) and the browser element (whose
+ * fallback when no config travels with the element).
+ *
+ * Pure data with no imports, like `sql/runtimeConfig.ts`: both sides have to
+ * agree on the shape, and neither may drag the other into its bundle — the
+ * remark plugin runs in Docusaurus' Node build, the element in the browser.
+ *
+ * Why the config travels per element instead of living in the component: the
+ * palette is the one part of a diagram that is *site-specific*. Passing it
+ * through the site's `docusaurus.config.ts` (as an option of `remarkMermaid`)
+ * keeps that choice where the rest of the site's theme is decided, and keeps a
+ * downstream docs site from having to fork the kit to change two colour names.
+ */
+/** The two colour modes a diagram is rendered for. */
+export type MermaidColorMode = 'light' | 'dark';
+/** A partial config, as a site writes it. */
+export interface DfkMermaidConfigInput {
+    /** Mermaid theme name per colour mode; missing sides fall back to the default. */
+    theme?: Partial<Record<MermaidColorMode, string>>;
+    /** Extra mermaid options, spread into `initialize()` after `theme`. */
+    options?: Record<string, unknown>;
+}
+/** A resolved config: both themes present, options ready to spread. */
+export interface DfkMermaidConfig {
+    theme: Record<MermaidColorMode, string>;
+    options: Record<string, unknown>;
+}
+/**
+ * The kit's default: the `neo` look (mermaid's flatter, rounder chrome) with the
+ * redux palette — `redux-color` in light mode, `redux-dark-color` in dark.
+ *
+ * `look` has no per-mode counterpart in mermaid, so it belongs in `options`;
+ * `theme` is the per-mode one. Both are easy to get wrong *silently*: mermaid
+ * ignores an unrecognised value and falls back, so a change is verified in a
+ * browser, not by a build.
+ */
+export declare const DEFAULT_MERMAID_CONFIG: DfkMermaidConfig;
+/** Merges a site's overrides over {@link DEFAULT_MERMAID_CONFIG}. */
+export declare function resolveMermaidConfig(input?: DfkMermaidConfigInput | null): DfkMermaidConfig;
+/**
+ * Parses the `config` attribute the remark plugin writes. Anything unreadable
+ * falls back to the default rather than failing a diagram, and only the two
+ * known keys are read — the attribute is content, not a channel for arbitrary
+ * configuration.
+ */
+export declare function parseMermaidConfig(raw: string | null | undefined): DfkMermaidConfig;

package/dist/mermaid/remark.d.ts

@@ -0,0 +1,40 @@
+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 declare 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;
+}
+export declare const remarkMermaid: Plugin<[RemarkMermaidOptions?]>;

package/dist/mermaid/remark.js

@@ -0,0 +1,32 @@
+//#region src/mermaid/remark.ts
+var e = "dfk-mermaid", t = (e = {}) => (t) => {
+	let r = e.config === void 0 ? null : JSON.stringify(e.config), i = (e) => {
+		if (typeof e != "object" || !e) return;
+		let t = e;
+		Array.isArray(t.children) && (t.children = t.children.map((e) => {
+			if (typeof e != "object" || !e) return e;
+			let t = e;
+			return t.type === "code" && t.lang === "mermaid" ? n(t, r) : (i(t), t);
+		}));
+	};
+	i(t);
+};
+function n(t, n) {
+	let r = [{
+		type: "mdxJsxAttribute",
+		name: "source",
+		value: String(t.value ?? "")
+	}];
+	return n !== null && r.push({
+		type: "mdxJsxAttribute",
+		name: "config",
+		value: n
+	}), {
+		type: "mdxJsxFlowElement",
+		name: e,
+		attributes: r,
+		children: []
+	};
+}
+//#endregion
+export { e as DFK_MERMAID_TAG, t as remarkMermaid };

package/dist/mermaid/render.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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';
+/** 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 declare function renderMermaid({ source, config, colorMode, }: MermaidRenderRequest): Promise<MermaidRenderOutput>;
+/** The colour mode the page is actually in, read from the pre-paint attribute. */
+export declare function documentColorMode(): MermaidColorMode;
+/**
+ * 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 declare function watchColorMode(listener: () => void): () => void;
+/**
+ * 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 declare function parseMermaidSvg(owner: Document, svg: string): SVGElement | null;
+/**
+ * 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 declare function serializeMermaidSvg(svg: SVGElement): string;

package/dist/mermaid/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function mermaidStyles(): CSSStyleSheet;

package/dist/panzoom-view.d.ts

@@ -0,0 +1,17 @@
+export declare class PanZoomView {
+    #private;
+    constructor(viewport: HTMLElement, content: HTMLElement);
+    /** Whether the figure is enlarged past its fit-to-box size. */
+    get zoomed(): boolean;
+    /** Replaces the figure on screen and returns the view to fit. */
+    setContent(node: Node | null): void;
+    /**
+     * Turns wheel zoom and dragging on or off. Activating loads panzoom on first
+     * use (a figure nobody zooms never pays for the chunk); deactivating leaves the
+     * view at fit, so the figure a reader returns to is the whole one.
+     */
+    setActive(active: boolean): void;
+    reset(): void;
+    /** Releases the panzoom instance and returns the viewport to its idle state. */
+    destroy(): void;
+}