@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-export-ast.d.ts

@@ -1,4 +1,4 @@
-import type { Specification } from "./specbook-struct-spec.js";
-import type { SchemaSpecification } from "./specbook-struct-schema.js";
+import type { Spec } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.js";
 export type AstFormat = "json" | "json5" | "yaml" | "toon";
-export declare const renderAst: (specification: Specification, format: AstFormat, config?: SchemaSpecification) => Promise<Buffer>;
+export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema) => Buffer;

package/dst/specbook-export-ast.js

@@ -8,7 +8,7 @@ import { stringify as stringifyYaml } from "yaml";
 import { encode as encodeToon } from "@toon-format/toon";
 import { specDiagrams } from "./specbook-diagram.js";
 /*  render the specification AST into a serialization format  */
-export const renderAst = async (specification, format, config) => {
+export const renderAst = (specification, format, config) => {
     /*  reduce the specification to plain JSON values (ISO date strings)  */
     const plain = JSON.parse(JSON.stringify(specification));
     /*  attach the Gradia specs of the diagram-configured objects as

package/dst/specbook-export-common.d.ts

@@ -1,13 +1,15 @@
-import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
+import type { Spec, SpecObject } from "./specbook-format-spec.js";
+import type { embeddingThemes } from "./specbook-parse-common.js";
 export declare const escapeHtml: (text: string) => string;
 export declare const stylesheet: () => string;
 export declare const searchScript: () => string;
-export declare const fallbackLogo: () => string;
+export declare const fallbackLogo: (theme: (typeof embeddingThemes)[number]) => string;
 export declare const isTitleObject: (object: SpecObject) => boolean;
-export declare const documentLang: (specification: Specification) => string | undefined;
-export declare const documentCharset: (specification: Specification) => string | undefined;
-export declare const documentThemeStyle: (specification: Specification) => string | undefined;
-export declare const documentThemeTone: (specification: Specification) => string | undefined;
+export declare const titleObject: (specification: Spec) => SpecObject | undefined;
+export declare const documentLang: (specification: Spec) => string | undefined;
+export declare const documentCharset: (specification: Spec) => string | undefined;
+export declare const documentThemeStyle: (specification: Spec) => string | undefined;
+export declare const documentThemeTone: (specification: Spec) => string | undefined;
 export type PaperSetup = {
     unit: "mm" | "in";
     height: number;
@@ -21,12 +23,12 @@ export type PaperSetup = {
 export declare const paperSizeDefault = "A4";
 export declare const paperSetup: (paper: string) => PaperSetup;
 export declare const paperLength: (setup: PaperSetup, value: number) => string;
-export declare const documentPaperSize: (specification: Specification) => string;
+export declare const documentPaperSize: (specification: Spec) => string;
 export declare const paperStylesheet: (paper: string) => string;
 export declare const charsetCodepoints: (charset: string) => number[] | undefined;
 export declare const subsetStylesheet: (charset?: string) => Promise<string>;
-export declare const documentTitle: (specification: Specification) => {
+export declare const documentTitle: (specification: Spec) => {
     title: string;
     subtitle?: string;
 };
-export declare const documentLogo: (specification: Specification) => string;
+export declare const documentLogo: (specification: Spec) => string;

package/dst/specbook-export-common.js

@@ -3,24 +3,36 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import path from "node:path";
 import fs from "node:fs";
-import { fileURLToPath } from "node:url";
 /*  escape a text for embedding into template HTML (text and attributes)  */
 export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 /*  provide the build-time pre-assembled stylesheet (with the
     font faces already inlined as base64 data: URIs)  */
-export const stylesheet = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html.css"), "utf8");
+export const stylesheet = () => fs.readFileSync(new URL("specbook-export-html.css", import.meta.url), "utf8");
 /*  provide the build-time bundled client-side fuzzy search script  */
-export const searchScript = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html-search.js"), "utf8");
-/*  provide the build-time bundled fallback logo of SpecBook itself
-    (as a self-contained data: URL, to keep its styles isolated)  */
-export const fallbackLogo = () => "data:image/svg+xml;base64," + fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-logo.svg")).toString("base64");
+export const searchScript = () => fs.readFileSync(new URL("specbook-export-html-search.js", import.meta.url), "utf8");
+/*  provide a theme variant of the build-time bundled fallback logo of
+    SpecBook itself (as a self-contained data: URL, to keep its styles isolated)  */
+export const fallbackLogo = (theme) => "data:image/svg+xml;base64," +
+    fs.readFileSync(new URL(`specbook-export-logo-${theme}.svg`, import.meta.url)).toString("base64");
 /*  check whether an object is the specification title object  */
 export const isTitleObject = (object) => object.kind === "META" && object.name.toUpperCase() === "TITLE";
-/*  determine the title object of the specification  */
-const titleObject = (specification) => specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
+/*  determine the title object of the specification, searched at any
+    nesting level in document order, where the first match wins  */
+export const titleObject = (specification) => {
+    const search = (objects) => {
+        for (const object of objects) {
+            if (isTitleObject(object))
+                return object;
+            const found = search(object.childs);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    return search(specification.artifacts.flatMap((artifact) => artifact.objects));
+};
 /*  determine a property value of the title object  */
 const titleProperty = (specification, name) => titleObject(specification)?.properties.find((property) => property.key === name)?.value;
 /*  determine the document language (LANG) from the title object  */
@@ -58,14 +70,15 @@ export const documentPaperSize = (specification) => {
             `(expected ${paperSizes.join(", ")})`);
     return paper;
 };
-/*  provide the paper-dependent print stylesheet: a diagram is scaled
-    down to still fit onto a single page (the paper height less the
-    print margins, the own vertical margins of the diagram, and the
-    room its introducing heading claims above it) and is never broken
-    across a page boundary; without the heading reserve a maximally
+/*  the vertical room (in rem) the introducing heading of a diagram
+    claims above it on the same page: without this reserve a maximally
     sized diagram could not share its page with the heading, which
     would defeat the "break-after: avoid" bundling of the stylesheet  */
 const headingReserve = 6;
+/*  provide the paper-dependent print stylesheet: a diagram is scaled
+    down to still fit onto a single page (the paper height less the
+    print margins, the own vertical margins of the diagram, and the
+    heading reserve above it) and is never broken across a page boundary  */
 export const paperStylesheet = (paper) => {
     const setup = paperSetup(paper);
     const avail = setup.height - setup.margin.top - setup.margin.bottom;
@@ -118,9 +131,7 @@ const typographyGlyphs = [
     glyphs (no charset or a full Unicode charset keeps the fonts complete)  */
 export const subsetStylesheet = async (charset) => {
     const css = stylesheet();
-    if (charset === undefined)
-        return css;
-    const codepoints = charsetCodepoints(charset);
+    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
     if (codepoints === undefined)
         return css;
     const { default: subsetFont } = await import("subset-font");
@@ -142,14 +153,15 @@ export const documentTitle = (specification) => ({
     subtitle: titleProperty(specification, "SUBTITLE")
 });
 /*  determine the document logo as a self-contained data: URL, taken from the
-    embedded image of the LOGO property of the title object, and falling back
-    onto the built-in SpecBook logo (for use in isolated rendering contexts,
-    like the print header/footer, which load no external resources)  */
+    first embedded image of the LOGO property of the title object -- the light
+    variant of a "{theme}" reference -- and falling back onto the built-in
+    SpecBook logo (for use in isolated rendering contexts, like the print
+    header/footer, which load no external resources and are always light)  */
 export const documentLogo = (specification) => {
     const content = titleObject(specification)
         ?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
-    if (content === undefined)
-        return fallbackLogo();
+    if (content === undefined || content === "")
+        return fallbackLogo("light");
     return content.startsWith("data:") ? content :
         `data:image/svg+xml;base64,${Buffer.from(content, "utf8").toString("base64")}`;
 };

package/dst/specbook-export-html-search.js

@@ -18,7 +18,7 @@
 
     /*  shortest word still eligible for fuzzy matching: below it the
         edit distance would equate it with almost any short word  */
-    const FUZZY_MIN = 4
+    const fuzzyMin = 4
 
     /*  the searchable units (paragraphs, list items, table rows, and
         headings), the corpus vocabulary, and the per-word cache of the
@@ -101,7 +101,7 @@
         if (result !== undefined)
             return result
         result = []
-        if (word.length >= FUZZY_MIN)
+        if (word.length >= fuzzyMin)
             vocab.forEach((given) => {
                 if (Math.abs(word.length - given.length) <= 1
                     && (diceCoefficient(word, given) >= 0.50
@@ -115,19 +115,21 @@
     /*  match a query word against a unit, as a literal substring or as
         a fuzzy variant, remembering the variants for the highlighting  */
     const wordMatch = (word, unit, variants) => {
-        if (unit.text.indexOf(word) >= 0)
+        if (unit.text.includes(word))
             return true
         const near = fuzzyWords(word).filter((v) => unit.words.has(v))
         near.forEach((v) => { variants.add(v) })
         return near.length > 0
     }
 
+    /*  escape a text for its literal use inside a regular expression  */
+    const escapeRegex = (s) =>
+        s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
     /*  the alternation matching everything worth highlighting: the
         query words as plain substrings plus the fuzzy variants as
         whole words, longest alternative first, so a variant is never
         cut short by a query word nested inside it  */
-    const escapeRegex = (s) =>
-        s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
     const buildRegex = (words, variants) => {
         const alts = words.map((w) => ({ len: w.length, src: escapeRegex(w) }))
             .concat(variants.map((v) => ({ len: v.length,
@@ -203,7 +205,7 @@
         units.forEach((unit) => { unit.keep = false })
         parts.forEach((part) => {
             let matched = units.filter((unit) =>
-                part.every((word) => unit.text.indexOf(word) >= 0))
+                part.every((word) => unit.text.includes(word)))
             if (matched.length === 0)
                 matched = units.filter((unit) =>
                     part.every((word) => wordMatch(word, unit, variants)))
@@ -226,7 +228,7 @@
                 const heading = section.firstElementChild
                 if (heading !== null && /^H[1-6]$/.test(heading.tagName))
                     heading.classList.add("search-keep")
-                section = section.parentElement !== null ? section.parentElement.closest("section") : null
+                section = section.parentElement?.closest("section") ?? null
             }
         })
 
@@ -244,13 +246,7 @@
         })
 
         /*  highlight every matched word within the kept units  */
-        const words = []
-        parts.forEach((part) => {
-            part.forEach((word) => {
-                if (!words.includes(word))
-                    words.push(word)
-            })
-        })
+        const words = Array.from(new Set(parts.flat()))
         const regex = buildRegex(words, Array.from(variants))
         units.forEach((unit) => {
             if (unit.el.classList.contains("search-keep"))