@rse/specbook 1.2.2 → 1.2.4

package/dst/specbook-diagram.js

@@ -109,7 +109,7 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents,
         const walk = (object) => {
             objects.push(object);
             if (diagram.deep === true)
-                for (const child of object.childs)
+                for (const child of object.children)
                     if (!nodeSet.has(child))
                         walk(child);
         };
@@ -213,9 +213,12 @@ const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors,
         if (diagram.onlyConnected === true)
             errors.push({ reason: "\"grid\" diagram cannot carry an \"onlyConnected\" configuration" });
     }
-    /*  deduplicate the edges (a containment or object edge can coincide
-        with a reference edge, and several edge objects can describe
-        the very same edge)  */
+    return edges;
+};
+/*  deduplicate the edges (a containment, object, or center edge can
+    coincide with a reference edge, and several edge objects can
+    describe the very same edge)  */
+const dedupEdges = (edges, anchors) => {
     const seenEdges = new Set();
     return edges.filter((edge) => {
         const key = `${anchors.get(edge.source) ?? edge.source.id}` +
@@ -307,7 +310,7 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, parenProp
         /*  inject the synthetic center node into the node set, with a
             collision-free id ("@" never occurs in an anchor path)  */
         const center = { kind: centerCfg.kind ?? "",
-            id: `${anchors.get(object) ?? object.id}-@center`, name: label, properties: [], childs: [] };
+            id: `${anchors.get(object) ?? object.id}-@center`, name: label, properties: [], children: [] };
         nodes.unshift(center);
         nodeSet.add(center);
         return { center, centerUrl };
@@ -360,7 +363,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
         nodes = new Array();
         const walk = (o) => {
             nodes.push(o);
-            o.childs.forEach(walk);
+            o.children.forEach(walk);
         };
         walk(object);
     }
@@ -368,7 +371,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
     const edgeSet = new Set(edgeObjects);
     nodes = nodes.filter((node) => !edgeSet.has(node));
     const nodeSet = new Set(nodes);
-    /*  derive the (deduplicated) edges of the diagram  */
+    /*  derive the edges of the diagram  */
     let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors);
     /*  determine the center of a "hub" diagram (the only shape
         carrying a center at all)  */
@@ -384,9 +387,12 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
         return { errors };
     const { center, centerUrl } = derived;
     /*  synthesize the center edges of a "hub" diagram, as the nodes
-        carry no "[[...]]" reference to a synthetic center  */
+        carry no "[[...]]" reference to a synthetic center, and only
+        then deduplicate all edges, as a center edge of a real center
+        can coincide with a reference edge of a node onto it  */
     if (type === "hub" && diagram.centerEdges !== undefined)
         edges.push(...deriveCenterEdges(diagram.centerEdges, nodes, center, index, parenProps, errors));
+    edges = dedupEdges(edges, anchors);
     /*  a "hub" diagram is the hub-projection onto its center object:
         only the edges incident to the center and only the nodes
         connected through them remain, with self-loops dropped, as
@@ -513,11 +519,11 @@ export const validateDiagrams = (ctx, specification, config) => {
                 object itself and report it just once, as a wildcard
                 "edges" pattern lets every diagram walk the very same
                 edge objects again  */
-            const meta = ctx.objectMeta.get(error.object ?? object) ?? { file: "", line: 1 };
+            const meta = ctx.metaOf(error.object ?? object);
             const message = error.object !== undefined ?
                 `invalid diagram edge on ${error.object.kind} "${error.object.name}": ${error.reason}` :
                 `invalid diagram on ${object.kind} "${object.name}": ${error.reason}`;
-            const key = `${meta.file}${meta.line}${message}`;
+            const key = `${meta.file}\u0000${meta.line}\u0000${message}`;
             if (seen.has(key))
                 continue;
             seen.add(key);

package/dst/specbook-export-ast.js

@@ -23,7 +23,7 @@ export const renderAst = (specification, format, config) => {
             const result = diagrams.get(object);
             if (result?.spec !== undefined && !isTitleObject(object))
                 node.diagram = result.spec;
-            object.childs.forEach((child, i) => walk(child, node.childs[i]));
+            object.children.forEach((child, i) => walk(child, node.children[i]));
         };
         specification.artifacts.forEach((artifact, i) => artifact.objects.forEach((object, j) => walk(object, plain.artifacts[i].objects[j])));
     }

package/dst/specbook-export-common.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import fs from "node:fs";
+import { plainText } from "./specbook-link.js";
 /*  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;");
@@ -25,7 +26,7 @@ export const titleObject = (specification) => {
         for (const object of objects) {
             if (isTitleObject(object))
                 return object;
-            const found = search(object.childs);
+            const found = search(object.children);
             if (found !== undefined)
                 return found;
         }
@@ -128,24 +129,16 @@ const typographyGlyphs = [
     0x00A0, 0x00AB, 0x00BB, 0x2013, 0x2014, 0x2018, 0x2019,
     0x201A, 0x201C, 0x201D, 0x201E, 0x2022, 0x2026, 0x2039, 0x203A
 ];
-/*  the memoized subsetted stylesheets, keyed by the (shared) codepoint
-    set of the charset, as the font subsetting is expensive and the
-    formats of a single export, the watch and preview re-exports, and
-    the MCP service request the very same subset over and over again  */
+/*  the memoized subsetted stylesheets (as pending or settled promises,
+    so concurrent requests share a single subsetting), keyed by the
+    (shared) codepoint set of the charset, as the font subsetting is
+    expensive and the formats of a single export, the watch and preview
+    re-exports, and the MCP service request the very same subset over
+    and over again  */
 const subsetCache = new Map();
-/*  provide the stylesheet with its embedded fonts subsetted to the
-    codepoints of a charset plus the always-used symbol and typography
-    glyphs (no charset or a full Unicode charset keeps the fonts complete)  */
-export const subsetStylesheet = async (charset) => {
-    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
-    if (codepoints === undefined)
-        return stylesheet();
-    const cached = subsetCache.get(codepoints);
-    if (cached !== undefined)
-        return cached;
-    const css = stylesheet();
+/*  subset the embedded fonts of a stylesheet to the glyphs of a text  */
+const subsetFonts = async (css, text) => {
     const { default: subsetFont } = await import("subset-font");
-    const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
     let result = "";
     let last = 0;
     for (const m of css.matchAll(/url\("data:font\/woff2;base64,([^"]+)"\)/g)) {
@@ -154,18 +147,36 @@ export const subsetStylesheet = async (charset) => {
             `url("data:font/woff2;base64,${subset.toString("base64")}")`;
         last = m.index + m[0].length;
     }
-    const subsetted = result + css.slice(last);
-    subsetCache.set(codepoints, subsetted);
+    return result + css.slice(last);
+};
+/*  provide the stylesheet with its embedded fonts subsetted to the
+    codepoints of a charset plus the always-used symbol and typography
+    glyphs (no charset or a full Unicode charset keeps the fonts complete),
+    where a failed subsetting leaves the cache, so the next request retries  */
+export const subsetStylesheet = async (charset) => {
+    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
+    if (codepoints === undefined)
+        return stylesheet();
+    let subsetted = subsetCache.get(codepoints);
+    if (subsetted === undefined) {
+        const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
+        subsetted = subsetFonts(stylesheet(), text);
+        subsetted.catch(() => { subsetCache.delete(codepoints); });
+        subsetCache.set(codepoints, subsetted);
+    }
     return subsetted;
 };
 /*  determine the document title and subtitle from the title object (an
-    empty TITLE counts as absent, exactly like for the title page)  */
+    empty TITLE counts as absent, exactly like for the title page), with
+    the inline code markup stripped, as the plain-text targets (the HTML
+    <title>, the PDF metadata and page header) render no Markdown  */
 export const documentTitle = (specification) => {
     const title = titleProperty(specification, "TITLE")?.trim();
+    const subtitle = titleProperty(specification, "SUBTITLE")?.trim();
     return {
-        title: title !== undefined && title !== "" ? title :
-            titleObject(specification)?.name ?? "Specification",
-        subtitle: titleProperty(specification, "SUBTITLE")?.trim()
+        title: plainText(title !== undefined && title !== "" ? title :
+            titleObject(specification)?.name ?? "Specification"),
+        subtitle: subtitle !== undefined ? plainText(subtitle) : undefined
     };
 };
 /*  determine the document logo as a self-contained data: URL, taken from the

package/dst/specbook-export-html.css

@@ -81,6 +81,8 @@ html.theme-light {
   --theme-color-specbook-popup-schema-desc: var(--theme-color-base-32);
   --theme-color-specbook-popup-spec-path: var(--theme-color-accent-12);
   --theme-color-specbook-popup-spec-desc: var(--theme-color-base-5);
+  --theme-color-specbook-progress-done: var(--theme-color-accent-12);
+  --theme-color-specbook-progress-todo: var(--theme-color-accent-31);
   --gradia-font-family: "Source Sans 3";
   --gradia-color-node-regular-name: var(--theme-color-accent-12);
   --gradia-color-node-regular-box: var(--theme-color-accent-30);
@@ -122,6 +124,8 @@ html.theme-light {
     --theme-color-specbook-popup-schema-desc: var(--theme-color-base-7);
     --theme-color-specbook-popup-spec-path: var(--theme-color-accent-24);
     --theme-color-specbook-popup-spec-desc: var(--theme-color-base-29);
+    --theme-color-specbook-progress-done: var(--theme-color-accent-24);
+    --theme-color-specbook-progress-todo: var(--theme-color-accent-4);
     --gradia-color-node-regular-name: var(--theme-color-accent-21);
     --gradia-color-node-regular-box: var(--theme-color-accent-3);
     --gradia-color-node-regular-border: var(--theme-color-accent-7);
@@ -437,6 +441,64 @@ div.realtime-status.reloaded svg.realtime-icon {
     display: none;
   }
 }
+/*  the scroll progress meter (screen-only): a ring at the bottom right
+    corner of the viewport (fixed independent of the content scrolling),
+    whose DONE part (the arc drawn clockwise from the top, together with
+    the upward arrow in its center, drawn like the tab icons) reflects
+    the scrolled fraction of the document over the TODO part (the full
+    circle in the lighter progress color beneath), which stays hidden
+    while the page is scrolled near the top (fading in once scrolled
+    beyond 400px) and scrolls the page back to the top on click, where
+    the DONE part and the arrow brighten on hover like the tabs  */
+div.scroll-progress {
+  position: fixed;
+  right: 1.5rem;
+  bottom: 1.5rem;
+  z-index: 30;
+  width: 3rem;
+  height: 3rem;
+  line-height: 0;
+  color: var(--theme-color-specbook-progress-done);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s ease;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+div.scroll-progress.shown {
+  opacity: 1;
+  pointer-events: auto;
+}
+div.scroll-progress:hover {
+  color: var(--theme-color-specbook-accent-soft);
+}
+div.scroll-progress svg.scroll-ring {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  transform: rotate(-90deg);
+}
+div.scroll-progress svg.scroll-ring circle.scroll-todo {
+  stroke: var(--theme-color-specbook-progress-todo);
+}
+div.scroll-progress svg.scroll-ring circle.scroll-done {
+  stroke: currentColor;
+}
+div.scroll-progress svg.scroll-icon {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 1.1rem;
+  height: 1.1rem;
+  transform: translate(-50%, -50%);
+}
+@media print {
+  div.scroll-progress {
+    display: none;
+  }
+}
 /*  the side panel of the table of contents (screen-only): a fixed
     full-height drawer at the left viewport edge, carrying a replica of
     the brand bar on its right edge, which exactly covers the brand bar

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

@@ -4,7 +4,7 @@ import type { Verbose } from "./specbook-verbose.js";
 export type OutlineEntry = {
     title: string;
     anchor: string;
-    childs: OutlineEntry[];
+    children: OutlineEntry[];
 };
 export declare const htmlOutline: (specification: Spec, config?: Schema) => OutlineEntry[];
 export declare const titlePageObject: (specification: Spec) => SpecObject | undefined;