@rse/specbook 1.3.1 → 1.4.0

package/dst/specbook-export-diagram.js

@@ -0,0 +1,211 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { marked } from "marked";
+import { documentThemeTone } from "./specbook-export-common.js";
+import { themeColors, themeToneDefault } from "./specbook-theme.js";
+import { plainText } from "./specbook-link.js";
+import { literal } from "./specbook-verbose.js";
+/*  the fenced code block languages of the embedded diagrams  */
+const fenceLanguages = {
+    mermaid: "mermaid",
+    mmd: "mermaid",
+    d2: "d2"
+};
+/*  map the language of a fenced code block onto its diagram language
+    (undefined for a regular code block)  */
+export const fenceLanguage = (lang) => fenceLanguages[(lang ?? "").trim().toLowerCase()];
+/*  decode an embedded diagram source file, which the parser loads as a
+    base64 data: URL of its diagram MIME type (undefined for an image)  */
+export const embeddedSource = (content) => {
+    const m = content.match(/^data:text\/vnd\.(mermaid|d2);base64,(.*)$/s);
+    return m !== null ?
+        { language: m[1], source: Buffer.from(m[2], "base64").toString("utf8") } :
+        undefined;
+};
+/*  the key of an embedded diagram in the map of the rendered ones  */
+export const diagramKey = (language, source) => `${language}\u0000${source}`;
+/*  whether an embedded diagram of a language (a Mermaid/D2 one being of
+    the type "code"), an image, or a code listing, carried by an object of
+    a nesting level, is omitted (exactly like a Gradia diagram: by its
+    type, or from an object tree nesting level on)  */
+export const omittedDiagram = (language, level, omit) => omit.has(language === "image" ? "diagram:image" : language === "listing" ? "diagram:listing" : "diagram:code")
+    || [1, 2, 3].some((n) => n <= level && omit.has(`diagram:${n}`));
+/*  the object tree nesting levels of the objects of a specification
+    (the top-level objects of an artifact being level 1)  */
+export const objectLevels = (specification) => {
+    const levels = new Map();
+    const walk = (object, level) => {
+        levels.set(object, level);
+        for (const child of object.children)
+            walk(child, level + 1);
+    };
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            walk(object, 1);
+    return levels;
+};
+/*  collect the embedded diagrams of an object and its descendants: the
+    fenced code blocks of a diagram language inside its description
+    statement and elaboration and the diagram source files embedded into
+    its description and property values  */
+const collect = (object, level, diagrams) => {
+    for (const text of [object.description?.description ?? "", object.description?.elaboration ?? ""])
+        marked.walkTokens(marked.lexer(text), (token) => {
+            const language = token.type === "code" ? fenceLanguage(token.lang) : undefined;
+            if (language !== undefined)
+                diagrams.push({ language, source: token.text, object, level });
+        });
+    const contents = [...object.description?.embedding ?? [],
+        ...object.properties.flatMap((property) => property.embedding ?? [])];
+    for (const content of contents) {
+        const embedded = embeddedSource(content);
+        if (embedded !== undefined)
+            diagrams.push({ ...embedded, object, level });
+    }
+    for (const child of object.children)
+        collect(child, level + 1, diagrams);
+};
+/*  the colors of the Mermaid diagrams per theme style, picked out of the
+    theme color spreads like the layer-2 mapping of the HTML rendering
+    (Mermaid derives all further colors of a diagram from these)  */
+const mermaidColors = (colors, style) => {
+    const [b, a] = [colors.base, colors.accent];
+    return style === "dark" ?
+        { bg: b[6], fg: b[28], line: b[21], accent: a[21], muted: b[21], surface: a[7], border: a[13] } :
+        { bg: b[31], fg: b[5], line: b[21], accent: a[11], muted: b[21], surface: a[30], border: a[23] };
+};
+/*  the colors of the D2 diagrams per theme style, picked out of the
+    theme color spreads after the shape of the D2 themes "Neutral
+    Default" (light) and "Dark Mauve" (dark): the neutrals "N1" (text)
+    to "N7" (background), the base colors "B1" (strokes) to "B6"
+    (fills), and the alternative accents "AA*"/"AB*"  */
+const d2Colors = (colors, style) => {
+    const [b, a, s] = [colors.base, colors.accent, colors.signal];
+    return style === "dark" ? {
+        N1: b[28], N2: b[25], N3: b[22], N4: b[13], N5: b[10], N6: b[8], N7: b[6],
+        B1: a[21], B2: a[21], B3: a[13], B4: a[10], B5: a[8], B6: a[7],
+        AA2: s[19], AA4: s[10], AA5: s[8], AB4: s[10], AB5: s[8]
+    } : {
+        N1: b[3], N2: b[13], N3: b[19], N4: b[25], N5: b[27], N6: b[29], N7: b[31],
+        B1: a[7], B2: a[11], B3: a[27], B4: a[28], B5: a[29], B6: a[30],
+        AA2: s[13], AA4: s[28], AA5: s[30], AB4: s[28], AB5: s[30]
+    };
+};
+/*  render a Mermaid diagram, stripping the web font import the SVG
+    carries, as an SVG embedded through an <img> never loads it and it
+    would be the only external reference of the exported document  */
+const renderMermaid = async (source, colors) => {
+    const { renderMermaidSVG } = await import("beautiful-mermaid");
+    return renderMermaidSVG(source, { ...colors, transparent: true, padding: 4 })
+        .replace(/^\s*@import url\([^)]*\);\s*$/m, "");
+};
+/*  the D2 compiler, created on first use (as it spins up its WebAssembly
+    build in a worker thread), and the chain of its requests, as it
+    resolves just the latest pending one and hence has to be fed one
+    request at a time: the worker is referenced during a request only,
+    as it would otherwise keep the process alive forever  */
+let d2 = null;
+let d2Chain = Promise.resolve();
+/*  turn a D2 compile failure (a JSON-encoded list of the errors, whose
+    source lines are shifted by the prepended theme line) into a message  */
+const d2Error = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+        return JSON.parse(message)
+            .map((error) => error.errmsg.replace(/^index:(\d+):/, (_, line) => `line ${Number(line) - 1}:`))
+            .join("; ");
+    }
+    catch {
+        return message;
+    }
+};
+/*  render a D2 diagram, with the theme colors prepended as one line of
+    theme overrides (on the theme of the style), so the overrides of the
+    diagram itself still win  */
+const renderD2 = (source, colors, style) => {
+    const overrides = Object.entries(colors).map(([key, color]) => `${key}: "${color}"`).join("; ");
+    const request = d2Chain.then(async () => {
+        d2 ??= import("@terrastruct/d2").then((module) => new module.D2())
+            .catch((err) => {
+            d2 = null;
+            throw err;
+        });
+        const compiler = await d2;
+        const worker = () => compiler.worker;
+        worker()?.ref();
+        try {
+            const result = await compiler.compile({
+                fs: { index: `vars: { d2-config: { theme-overrides: { ${overrides} } } }\n${source}` },
+                options: { themeID: style === "dark" ? 200 : 0, scale: 1, pad: 0, noXMLTag: true }
+            });
+            return await compiler.render(result.diagram, result.renderOptions);
+        }
+        catch (err) {
+            throw new Error(d2Error(err), { cause: err });
+        }
+        finally {
+            worker()?.unref();
+        }
+    });
+    d2Chain = request.catch(() => undefined);
+    return request;
+};
+/*  the in-memory cache of the rendered embedded diagrams, keyed by theme
+    tone and diagram, and swept to the diagrams of the latest rendering,
+    exactly like the one of the Gradia diagrams  */
+let diagramCache = new Map();
+/*  render the embedded diagrams of a specification (the fenced code blocks
+    of a diagram language and the embedded diagram source files) into their
+    theme variants, drawn in the theme colors of the document and keyed by
+    "diagramKey" (a rendering failure omits the diagram and is surfaced as
+    a notice only, like the one of a Gradia diagram), served from the cache
+    where possible; the omitted diagrams are skipped  */
+export const renderEmbeddedDiagrams = async (specification, verbose, omit = new Set()) => {
+    const diagrams = new Array();
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            collect(object, 1, diagrams);
+    const tone = documentThemeTone(specification) ?? themeToneDefault;
+    const colors = themeColors(tone);
+    const cache = new Map();
+    const rendered = new Map();
+    const failed = new Set();
+    let cached = 0;
+    for (const { language, source, object, level } of diagrams) {
+        const key = diagramKey(language, source);
+        if (rendered.has(key) || failed.has(key) || omittedDiagram(language, level, omit))
+            continue;
+        let variants = diagramCache.get(`${tone}\u0000${key}`) ?? cache.get(`${tone}\u0000${key}`);
+        if (variants !== undefined)
+            cached++;
+        else {
+            try {
+                variants = language === "mermaid" ? {
+                    light: await renderMermaid(source, mermaidColors(colors, "light")),
+                    dark: await renderMermaid(source, mermaidColors(colors, "dark"))
+                } : {
+                    light: await renderD2(source, d2Colors(colors, "light"), "light"),
+                    dark: await renderD2(source, d2Colors(colors, "dark"), "dark")
+                };
+            }
+            catch (err) {
+                verbose?.(`rendering ${language} diagram of ${object.kind} ` +
+                    `"${literal(plainText(object.name))}" failed: ` +
+                    (err instanceof Error ? err.message : String(err)));
+                failed.add(key);
+                continue;
+            }
+        }
+        cache.set(`${tone}\u0000${key}`, variants);
+        rendered.set(key, variants);
+    }
+    diagramCache = cache;
+    if (rendered.size > 0)
+        verbose?.(cached === rendered.size ?
+            `reusing ${literal(cached)} cached embedded diagram(s)` :
+            `rendering ${literal(rendered.size)} embedded diagram(s) (${literal(cached)} cached)`);
+    return rendered;
+};

package/dst/specbook-export-html-fold.d.ts

@@ -0,0 +1,20 @@
+import type nunjucks from "nunjucks";
+import type { OmitAspect } from "./specbook-export-common.js";
+export declare const foldScript: (standins: boolean, textless: boolean) => string;
+export declare const omitLong: (omit: Set<OmitAspect> | null, cells: nunjucks.runtime.SafeString[], shares: number[], percent?: number) => nunjucks.runtime.SafeString[];
+export declare const omittedControls: (omit: Set<OmitAspect>) => {
+    omitted: {
+        graph: boolean;
+        hub: boolean;
+        grid: boolean;
+        code: boolean;
+        image: boolean;
+        listing: boolean;
+        level1: boolean;
+        level2: boolean;
+        level3: boolean;
+        text: boolean;
+        all: boolean;
+    };
+    css: string;
+};