@rse/specbook 0.9.2 → 0.9.4

package/dst/specbook-diagram.js

@@ -4,6 +4,9 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths } from "./specbook-link.js";
+/*  the single Wiki-style reference match (the non-global sibling of
+    the imported, global "referenceRegex")  */
+const referenceOnce = /\[\[([^[\]]+)\]\]/;
 /*  strip the inline code markup of a name or property value
     (preserved in the AST for rendering) for labeling purposes  */
 const plainText = (text) => text.replace(/`/g, "");
@@ -27,7 +30,56 @@ const arityToken = (text) => /^[^\s[\]"]+$/.test(text) ? text : quoted(text);
     collapsed, as a directive is a single line)  */
 const configValue = (value) => {
     const text = String(value).replace(/\s+/g, " ").trim();
-    return /^\S+$/.test(text) ? text : quoted(text);
+    return /^[^\s"]+$/.test(text) ? text : quoted(text);
+};
+/*  generate the Gradia spec text of a derived diagram, opened by a
+    "#type" directive and the configured "#config" directives so every
+    embedded spec is self-contained: one node statement per object (the
+    unique anchor path as the node id, the object name as the displayed
+    label) and one edge statement per derived edge  */
+const renderSpec = (diagram, type, center, nodes, edges, index, anchors) => {
+    const lines = [`#type ${type}`];
+    const config = diagram.config ?? {};
+    for (const key of Object.keys(config)) {
+        const value = config[key];
+        if (value !== undefined)
+            lines.push(`#config ${key} ${configValue(value)}`);
+    }
+    lines.push("");
+    for (const node of nodes) {
+        const anchor = anchors.get(node) ?? node.id;
+        const attrs = [`url: ${atom(`#${anchor}`)}`];
+        if (diagram.qualified === true && node.kind !== "")
+            attrs.push(`type: ${atom(node.kind)}`);
+        if (type === "hub" ? node === center : node.primary === true)
+            attrs.push("primary: true");
+        /*  attach the values of the configured properties as Gradia
+            key/value attributes (a node lacking a property is fine, as
+            the node set can mix objects of different kinds), with every
+            "[[...]]" reference stripped to its target object name  */
+        for (const key of diagram.properties ?? []) {
+            const value = node.properties.find((property) => plainKey(property.key) === key)?.value;
+            if (value !== undefined) {
+                const text = value.replace(referenceRegex, (_, reference) => {
+                    const target = resolveUnique(index, reference.trim()).target;
+                    return target !== undefined ? target.name : reference.trim();
+                });
+                attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
+            }
+        }
+        lines.push(`${atom(anchor)}: ${atom(plainText(node.name))} [ ${attrs.join(", ")} ]`);
+    }
+    if (edges.length > 0) {
+        lines.push("");
+        for (const edge of edges) {
+            const op = "--" +
+                (edge.name !== undefined && edge.name !== "" ? `(${nameToken(edge.name)})--` : "") + ">" +
+                (edge.arity !== undefined && edge.arity !== "" ? `[${arityToken(edge.arity)}]` : "");
+            lines.push(`${atom(anchors.get(edge.source) ?? edge.source.id)} ${op} ` +
+                atom(anchors.get(edge.target) ?? edge.target.id));
+        }
+    }
+    return lines.join("\n") + "\n";
 };
 /*  derive the Gradia spec of a single object from its "diagram:"
     schema configuration (the returned spec is absent whenever the
@@ -69,7 +121,8 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         walk(object);
     }
     const edgeObjects = diagram.edges !== undefined ? resolvePatterns(diagram.edges, "edges") : [];
-    nodes = nodes.filter((node) => !edgeObjects.includes(node));
+    const edgeSet = new Set(edgeObjects);
+    nodes = nodes.filter((node) => !edgeSet.has(node));
     const nodeSet = new Set(nodes);
     /*  derive the edges: from the "[[...]]" references of the node
         objects (per the "links" selection) and from the edge objects by
@@ -98,8 +151,8 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             const value = diagram.edgeTarget !== undefined ?
                 edgeObject.properties.find((property) => plainKey(property.key) === diagram.edgeTarget)?.value :
                 edgeObject.properties.map((property) => property.value)
-                    .find((v) => /\[\[[^[\]]+\]\]/.test(v));
-            const reference = value?.match(/\[\[([^[\]]+)\]\]/)?.[1].trim();
+                    .find((v) => referenceOnce.test(v));
+            const reference = value?.match(referenceOnce)?.[1].trim();
             const target = reference !== undefined ? resolveUnique(index, reference).target : undefined;
             if (source === undefined) {
                 errors.push(`diagram edge object "${edgeObject.name}" has no parent object as source`);
@@ -124,15 +177,18 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
                     edges.push({ source: parent, target: node });
             }
     }
-    else if (diagram.edges !== undefined)
-        errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
-    else if (diagram.hierarchy === true)
-        errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+    else {
+        if (diagram.edges !== undefined)
+            errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
+        if (diagram.hierarchy === true)
+            errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+    }
     /*  deduplicate the edges (the same reference can occur in
         multiple texts of the same node object)  */
     const seenEdges = new Set();
     edges = edges.filter((edge) => {
-        const key = `${anchors.get(edge.source)}\u0000${anchors.get(edge.target)}` +
+        const key = `${anchors.get(edge.source) ?? edge.source.id}` +
+            `\u0000${anchors.get(edge.target) ?? edge.target.id}` +
             `\u0000${edge.name ?? ""}\u0000${edge.arity ?? ""}`;
         if (seenEdges.has(key))
             return false;
@@ -144,7 +200,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         resolved object of an explicit "[[...]]" reference otherwise  */
     let center = object;
     if (type === "hub" && diagram.center !== undefined && diagram.center !== "self") {
-        const reference = diagram.center.match(/\[\[([^[\]]+)\]\]/)?.[1].trim();
+        const reference = diagram.center.match(referenceOnce)?.[1].trim();
         const resolved = reference !== undefined ? resolveUnique(index, reference) : undefined;
         if (resolved?.target === undefined) {
             errors.push(`${resolved?.ambiguous === true ? "ambiguous" : "unresolvable"}` +
@@ -190,39 +246,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         diagram carries no information beyond the object itself  */
     if (diagram.collapse !== false && nodes.length === 1 && edges.length === 0)
         return { errors };
-    /*  generate the Gradia spec text, opened by a "#type" directive and
-        the configured "#config" directives so every embedded spec is
-        self-contained: one node statement per object (the unique anchor
-        path as the node id, the object name as the displayed label)
-        and one edge statement per derived edge  */
-    const lines = [`#type ${type}`];
-    const config = diagram.config ?? {};
-    for (const key of Object.keys(config)) {
-        const value = config[key];
-        if (value !== undefined)
-            lines.push(`#config ${key} ${configValue(value)}`);
-    }
-    lines.push("");
-    for (const node of nodes) {
-        const anchor = anchors.get(node) ?? node.id;
-        const attrs = [`url: ${atom(`#${anchor}`)}`];
-        if (diagram.qualified === true && node.kind !== "")
-            attrs.push(`type: ${atom(node.kind)}`);
-        if (type === "hub" ? node === center : node.primary === true)
-            attrs.push("primary: true");
-        lines.push(`${atom(anchor)}: ${atom(plainText(node.name))} [ ${attrs.join(", ")} ]`);
-    }
-    if (edges.length > 0) {
-        lines.push("");
-        for (const edge of edges) {
-            const op = "--" +
-                (edge.name !== undefined && edge.name !== "" ? `(${nameToken(edge.name)})--` : "") + ">" +
-                (edge.arity !== undefined && edge.arity !== "" ? `[${arityToken(edge.arity)}]` : "");
-            lines.push(`${atom(anchors.get(edge.source) ?? edge.source.id)} ${op} ` +
-                atom(anchors.get(edge.target) ?? edge.target.id));
-        }
-    }
-    return { spec: lines.join("\n") + "\n", errors };
+    return { spec: renderSpec(diagram, type, center, nodes, edges, index, anchors), errors };
 };
 /*  collect the objects whose schema configuration carries a "diagram:"
     field (the schema resolution mirrors the semantic validation)  */

package/dst/specbook-export-ast.js

@@ -25,10 +25,13 @@ export const renderAst = async (specification, format, config) => {
         };
         specification.artifacts.forEach((artifact, i) => artifact.objects.forEach((object, j) => walk(object, plain.artifacts[i].objects[j])));
     }
+    /*  serialize the plain specification into the target format
+        (JSON and JSON5 in compressed form, as they are intended
+        for machine consumption only)  */
     if (format === "json")
-        return Buffer.from(JSON.stringify(plain, null, 4) + "\n", "utf8");
+        return Buffer.from(JSON.stringify(plain) + "\n", "utf8");
     else if (format === "json5")
-        return Buffer.from(JSON5.stringify(plain, null, 4) + "\n", "utf8");
+        return Buffer.from(JSON5.stringify(plain) + "\n", "utf8");
     else if (format === "yaml")
         return Buffer.from(stringifyYaml(plain), "utf8");
     else

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

@@ -18,7 +18,6 @@ export type PaperSetup = {
         right: number;
     };
 };
-export declare const paperSizes: string[];
 export declare const paperSizeDefault = "A4";
 export declare const paperSetup: (paper: string) => PaperSetup;
 export declare const paperLength: (setup: PaperSetup, value: number) => string;

package/dst/specbook-export-common.js

@@ -6,8 +6,9 @@
 import path from "node:path";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-/*  escape a text for embedding into template HTML  */
-export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/*  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");
@@ -18,9 +19,10 @@ export const searchScript = () => fs.readFileSync(path.join(path.dirname(fileURL
 export const fallbackLogo = () => "data:image/svg+xml;base64," + fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-logo.svg")).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 a property value of the title object  */
-const titleProperty = (specification, name) => specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject)
-    ?.properties.find((property) => property.key === name)?.value;
+const titleProperty = (specification, name) => titleObject(specification)?.properties.find((property) => property.key === name)?.value;
 /*  determine the document language (LANG) from the title object  */
 export const documentLang = (specification) => titleProperty(specification, "LANG")?.trim();
 /*  determine the document character set (CHARSET) from the title object  */
@@ -37,28 +39,39 @@ const papers = {
     "Letter": { unit: "in", height: 11, margin: { top: 1, bottom: 1, left: 0.8, right: 0.8 } },
     "Legal": { unit: "in", height: 14, margin: { top: 1, bottom: 1, left: 0.8, right: 0.8 } }
 };
-export const paperSizes = Object.keys(papers);
+const paperSizes = Object.keys(papers);
 export const paperSizeDefault = "A4";
 /*  provide the setup of a paper size, falling back onto the default  */
 export const paperSetup = (paper) => papers[paper] ?? papers[paperSizeDefault];
 /*  render a paper dimension as its CSS length  */
 export const paperLength = (setup, value) => `${value}${setup.unit}`;
 /*  determine the document paper size (PAPER-SIZE) from the title object,
-    matched case-insensitively and falling back onto the default  */
+    matched case-insensitively, falling back onto the default if unset
+    and rejecting an unknown size  */
 export const documentPaperSize = (specification) => {
-    const value = titleProperty(specification, "PAPER-SIZE")?.trim().toLowerCase();
-    return paperSizes.find((name) => name.toLowerCase() === value) ?? paperSizeDefault;
+    const value = titleProperty(specification, "PAPER-SIZE")?.trim();
+    if (value === undefined)
+        return paperSizeDefault;
+    const paper = paperSizes.find((name) => name.toLowerCase() === value.toLowerCase());
+    if (paper === undefined)
+        throw new Error(`unknown paper size "${value}" ` +
+            `(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 and the own vertical margins of the diagram) and is
-    never broken across a page boundary  */
+    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
+    sized diagram could not share its page with the heading, which
+    would defeat the "break-after: avoid" bundling of the stylesheet  */
+const headingReserve = 6;
 export const paperStylesheet = (paper) => {
     const setup = paperSetup(paper);
     const avail = setup.height - setup.margin.top - setup.margin.bottom;
     return "@media print {\n" +
         "div.diagram { break-inside: avoid; }\n" +
-        `div.diagram svg { max-height: calc(${paperLength(setup, avail)} - 2rem);` +
+        `div.diagram svg { max-height: calc(${paperLength(setup, avail)} - ${headingReserve}rem);` +
         " width: auto; height: auto; }\n" +
         "}\n";
 };
@@ -87,7 +100,7 @@ export const charsetCodepoints = (charset) => {
     else if (name === "utf8" || name === "utf16" || name === "unicode")
         return undefined;
     throw new Error(`unknown charset "${charset}" ` +
-        "(expected US-ASCII, ISO-8859-1/ISO-Latin-1, ISO-8859-15/ISO-Latin-15, or UTF-8)");
+        "(expected US-ASCII, ISO-8859-1/ISO-Latin-1, ISO-8859-15/ISO-Latin-9, or UTF-8)");
 };
 /*  the symbol glyphs used by the HTML/PDF rendering (kind and property
     bullets, link symbol, primary marker, theme switch icon, anchor
@@ -123,18 +136,18 @@ export const subsetStylesheet = async (charset) => {
     return result + css.slice(last);
 };
 /*  determine the document title and subtitle from the title object  */
-export const documentTitle = (specification) => {
-    const object = specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
-    const prop = (name) => object?.properties.find((property) => property.key === name)?.value;
-    return { title: prop("TITLE") ?? object?.name ?? "Specification", subtitle: prop("SUBTITLE") };
-};
+export const documentTitle = (specification) => ({
+    title: titleProperty(specification, "TITLE") ??
+        titleObject(specification)?.name ?? "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)  */
 export const documentLogo = (specification) => {
-    const object = specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
-    const content = object?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
+    const content = titleObject(specification)
+        ?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
     if (content === undefined)
         return fallbackLogo();
     return content.startsWith("data:") ? content :

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

@@ -45,7 +45,7 @@
                             return
                         parent = parent.parentElement
                     }
-                    const text  = (el.textContent || "").toLowerCase()
+                    const text  = (el.textContent ?? "").toLowerCase()
                     const words = new Set(text.split(/[^\p{L}\p{N}]+/u).filter((w) => w !== ""))
                     words.forEach((w) => { vocab.add(w) })
                     units.push({ el, text, words, keep: false })
@@ -141,7 +141,7 @@
         keeps the tags and attributes untouched  */
     const highlight = (el, regex) => {
         const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT)
-        const nodes = []
+        const nodes  = []
         let node
         while ((node = walker.nextNode()) !== null)
             nodes.push(node)
@@ -231,13 +231,15 @@
         })
 
         /*  hide the units not kept, plus the objects and tables which
-            ran entirely empty in the process  */
+            ran entirely empty in the process (a table nested inside a
+            kept unit, like a chunked property table, stays visible)  */
         units.forEach((unit) => {
             if (!unit.el.classList.contains("search-keep"))
                 unit.el.classList.add("search-hide")
         })
         document.querySelectorAll("article section, article table").forEach((el) => {
-            if (el.querySelector(".search-keep") === null)
+            if (el.querySelector(".search-keep") === null
+                && el.closest(".search-keep") === null)
                 el.classList.add("search-hide")
         })
 

package/dst/specbook-export-html.css

@@ -137,6 +137,13 @@ section                     { margin: 0.5rem 0; }
 h1                          { margin: 3.0rem 0 2.0rem 0; border-bottom: 1px solid var(--theme-color-specbook-border); }
 h2, h3, h4                  { margin: 2.0rem 0 1.0rem 0; }
 
+/*  bundle a heading with the content it introduces (diagram, property
+    table, description), so no heading is left orphaned at the very
+    bottom of a page while its content starts on the next one  */
+@media print {
+h1, h2, h3, h4, h5, h6      { page-break-after: avoid; break-after: avoid; }
+}
+
 body                        { counter-reset: sec1; }
 article h1                  { counter-increment: sec1; counter-reset: sec2; }
 article h2                  { counter-increment: sec2; counter-reset: sec3; }
@@ -192,6 +199,20 @@ table.objects div.description { margin: 0; }
 table.objects div.description > :first-child { margin-top: 0; }
 table.objects div.description > :last-child  { margin-bottom: 0; }
 
+/*  the embedded per-object chunk tables of the over-wide compact tables  */
+table.objects td.chunks     { padding: 0; }
+table.chunks                { border-collapse: collapse; table-layout: fixed;
+                              width: 100%; }
+table.objects table.chunks tr td { background-color: transparent; }
+table.objects table.chunks td:first-child { font-weight: normal; }
+
+/*  the nested renderings inside the description cells of the compact
+    tables ("concise" sub-tables and pressed-in "complex" objects),
+    reduced in size to fit into the cell  */
+table.objects td table.objects { font-size: 85%; margin: 0.5rem 0; }
+table.objects td section    { font-size: 85%; margin: 0.5rem 0; }
+table.objects td section h6 { margin: 0.5rem 0 0.25rem 0; }
+
 p.description,
 div.description             { margin: 1.0rem 0 0.5rem 0; }
 div.description p           { margin: 0.5rem 0; }

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

@@ -5,5 +5,5 @@ export type OutlineEntry = {
     anchor: string;
     childs: OutlineEntry[];
 };
-export declare const htmlOutline: (specification: Specification, maxColumns: number) => OutlineEntry[];
-export declare const renderHtml: (specification: Specification, maxColumns: number, config?: SchemaSpecification, tocPages?: Map<string, number>, css?: string) => Promise<string>;
+export declare const htmlOutline: (specification: Specification, config?: SchemaSpecification) => OutlineEntry[];
+export declare const renderHtml: (specification: Specification, config?: SchemaSpecification, tocPages?: Map<string, number>, css?: string) => Promise<string>;