@rse/specbook 1.2.2 → 1.2.3

package/dst/specbook-export-html.js

@@ -43,12 +43,14 @@ const templates = {
                         <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
                     </div>
                 </div>
+                <div class="scroll-progress" title="scroll to top"><svg class="scroll-ring" viewBox="0 0 44 44" fill="none" stroke-width="2.5"><circle class="scroll-todo" cx="22" cy="22" r="20"/><circle class="scroll-done" cx="22" cy="22" r="20" stroke-linecap="round" pathLength="1" stroke-dasharray="1" stroke-dashoffset="1"/></svg><svg class="scroll-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19V5"/><path d="M5 12l7-7 7 7"/></svg></div>
                 {{ Document.tocpanel }}
                 {{ Document.titlepage }}
                 {{ Document.toc }}
                 {{ Document.doc }}
                 {{ Document.artifacts }}
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
+                <script>{{ Document.progress }}</script>
                 {% if Document.tocpanel %}<script>{{ Document.tocscript }}</script>{% endif %}
                 {% if Document.info %}<script>{{ Document.info }}</script>{% endif %}
                 {% if Document.realtime %}<script class="realtime">{{ Document.realtime }}</script>{% endif %}
@@ -251,8 +253,8 @@ const placeholderStylesheet = textframe `
     div.placeholder { position: absolute; top: 50%; left: 0; right: 0;
         transform: translateY(-50%); text-align: center; opacity: 0.6 }
 `;
-/*  the client-side script of the live preview: it connects back to the
-    own page over WebSocket (the URL scheme "http"/"https" replaced with
+/*  the client-side script of the live preview: it connects back to
+    its own page over WebSocket (the URL scheme "http"/"https" replaced with
     "ws"/"wss"), re-connects every second after a lost connection, and
     updates the page on a received "RELOAD" command as well as on every
     re-established connection (as the server was restarted meanwhile).
@@ -275,7 +277,11 @@ const realtimeScript = textframe `
                 icon.className = "realtime-status " + state
         }
         let blink = 0
+        let seq   = 0
         const update = async () => {
+            /*  a superseded update (an overlapping newer one started
+                meanwhile) is dropped, as its stale page could arrive last  */
+            const mine = ++seq
             let response
             try {
                 response = await fetch(window.location.pathname, { cache: "no-store" })
@@ -286,7 +292,10 @@ const realtimeScript = textframe `
             }
             if (!response.ok)
                 return
-            const doc = new DOMParser().parseFromString(await response.text(), "text/html")
+            const html = await response.text()
+            if (mine !== seq)
+                return
+            const doc = new DOMParser().parseFromString(html, "text/html")
             const x = window.scrollX
             const y = window.scrollY
             document.title = doc.title
@@ -332,6 +341,47 @@ const realtimeScript = textframe `
         connect()
     })()
 `;
+/*  the client-side script of the scroll progress meter: it drives the
+    DONE arc of the ring (through the dash offset of its unit-length
+    circle) with the scrolled fraction of the document, shows the meter
+    once the page is scrolled beyond 400px, and scrolls the page back
+    to the top on a click (stripping the URL hash, so a later reload
+    stays at the top). The updates are throttled onto animation frames,
+    and the window-bound listeners retire themselves once a live preview
+    body swap replaced the meter (whose fresh script re-attaches)  */
+const scrollProgressScript = textframe `
+    (function () {
+        const meter = document.querySelector("div.scroll-progress")
+        const ring  = meter.querySelector("circle.scroll-done")
+        let ticking = false
+        const update = () => {
+            ticking = false
+            if (!meter.isConnected) {
+                window.removeEventListener("scroll", schedule)
+                window.removeEventListener("resize", schedule)
+                return
+            }
+            const doc = document.documentElement
+            const max = doc.scrollHeight - doc.clientHeight
+            ring.setAttribute("stroke-dashoffset", String(1 - (max > 0 ? doc.scrollTop / max : 0)))
+            meter.classList.toggle("shown", doc.scrollTop > 400)
+        }
+        const schedule = () => {
+            if (!ticking) {
+                ticking = true
+                requestAnimationFrame(update)
+            }
+        }
+        meter.addEventListener("click", () => {
+            window.scrollTo({ top: 0, behavior: "smooth" })
+            if (window.location.hash)
+                history.replaceState(null, "", window.location.pathname + window.location.search)
+        })
+        window.addEventListener("scroll", schedule, { passive: true })
+        window.addEventListener("resize", schedule)
+        update()
+    })()
+`;
 /*  the client-side script of the table of contents side panel: it
     slides the panel out of and back into the viewport edge (closing it
     also on a jump, on "Escape", and on a click outside), remembers the
@@ -656,8 +706,19 @@ const env = new nunjucks.Environment(null, { autoescape: true });
 nunjucksAddons(env);
 /*  mark pre-rendered HTML as safe for template interpolation  */
 const safe = (html) => new nunjucks.runtime.SafeString(html);
+/*  the built-in Nunjucks templates compiled on first use, as
+    renderString() would re-compile a template on every single call
+    (i.e. for every rendered object, property table, and description)  */
+const compiled = new Map();
 /*  render one of the built-in Nunjucks templates with a context  */
-const render = (name, context) => env.renderString(templates[name], context);
+const render = (name, context) => {
+    let template = compiled.get(name);
+    if (template === undefined) {
+        template = new nunjucks.Template(templates[name], env, undefined, true);
+        compiled.set(name, template);
+    }
+    return template.render(context);
+};
 /*  the active per-document reference expander, fully-qualified
     anchor paths, member-carrying property value constraints, object
     schema nodes, pre-rendered diagram SVGs, description popup keys
@@ -982,8 +1043,8 @@ const diagramOf = (object) => {
     headers of a plain table  */
 const renderTable = (childs, maxColumns) => {
     const { keys, desc } = tableShape(childs);
-    const diagrams = childs.some((child) => diagramOf(child) !== "");
-    if (!diagrams && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
+    const diagrammed = childs.some((child) => diagramOf(child) !== "");
+    if (!diagrammed && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
         return render("Table", { Table: {
                 head: childs[0].kind !== "" ? childs[0].kind : "Name",
                 info: infoKeyOf(childs[0]),
@@ -1242,47 +1303,48 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
     /*  the document language selects the smart typography quote style  */
     const lang = documentLang(specification);
     quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
-    /*  establish the per-document rendering state  */
+    /*  establish the per-document rendering state (released again
+        below, also on a failure of the collecting or rendering)  */
     const index = buildLinkIndex(specification);
-    anchors = anchorPaths(index);
-    members = config !== undefined ? collectMembers(config, new Map()) : null;
-    schemas = config !== undefined ? collectSchemas(specification, config) : null;
-    diagrams = rendered;
-    /*  collect the schema descriptions for the description popups,
-        plus the object parents composing their title paths  */
-    let info = null;
-    if (config !== undefined) {
-        infoKeys = new Map();
-        info = {};
-        collectInfo(config, "", infoKeys, info);
-        const parents = new Map();
-        for (const node of index)
-            if (node.parent !== undefined)
-                parents.set(node.object, node.parent.object);
-        infoParents = parents;
-    }
-    linker = makeLinker(index);
-    /*  collect the corpus descriptions of the object instances for the
-        description popups (after the linker is in place, as the
-        pre-rendered descriptions expand their references, too)  */
-    let spec = null;
-    if (info !== null) {
-        spec = {};
-        for (const artifact of specification.artifacts)
-            collectSpec(artifact.objects, spec);
-    }
-    /*  the artifact timestamps aggregate into the earliest creation
-        and the latest modification timestamp of the document  */
-    const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
-    const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
-    /*  a "META: Title" object becomes the title page and leaves the regular
-        flow, while its diagram becomes the "Diagram of Contents" page  */
-    const title = titlePageObject(specification);
-    const artifacts = specification.artifacts
-        .filter((artifact) => !artifact.objects.some(isTitleObject));
-    const meta = titleObject(specification);
-    const doc = meta !== undefined ? rendered?.get(meta) : undefined;
     try {
+        anchors = anchorPaths(index);
+        members = config !== undefined ? collectMembers(config, new Map()) : null;
+        schemas = config !== undefined ? collectSchemas(specification, config) : null;
+        diagrams = rendered;
+        /*  collect the schema descriptions for the description popups,
+            plus the object parents composing their title paths  */
+        let info = null;
+        if (config !== undefined) {
+            infoKeys = new Map();
+            info = {};
+            collectInfo(config, "", infoKeys, info);
+            const parents = new Map();
+            for (const node of index)
+                if (node.parent !== undefined)
+                    parents.set(node.object, node.parent.object);
+            infoParents = parents;
+        }
+        linker = makeLinker(index);
+        /*  collect the corpus descriptions of the object instances for the
+            description popups (after the linker is in place, as the
+            pre-rendered descriptions expand their references, too)  */
+        let spec = null;
+        if (info !== null) {
+            spec = {};
+            for (const artifact of specification.artifacts)
+                collectSpec(artifact.objects, spec);
+        }
+        /*  the artifact timestamps aggregate into the earliest creation
+            and the latest modification timestamp of the document  */
+        const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
+        const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
+        /*  a "META: Title" object becomes the title page and leaves the regular
+            flow, while its diagram becomes the "Diagram of Contents" page  */
+        const title = titlePageObject(specification);
+        const artifacts = specification.artifacts
+            .filter((artifact) => !artifact.objects.some(isTitleObject));
+        const meta = titleObject(specification);
+        const doc = meta !== undefined ? rendered?.get(meta) : undefined;
         const objects = artifacts.flatMap((artifact) => artifact.objects);
         const entries = tocEntries(objects, tocPages);
         return render("Document", { Document: {
@@ -1294,6 +1356,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                 titlepage: title !== undefined ?
                     safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
                 search: safe(searchScript()),
+                progress: safe(scrollProgressScript),
                 info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",

package/dst/specbook-export-md.js

@@ -33,13 +33,15 @@ const renderDescriptionMd = (description) => description.description + (descript
 const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
     (object.paren !== undefined ? ` (${object.paren})` : "") +
     (object.anchor !== undefined ? ` {{${object.anchor}}}` : "");
-/*  whether any descendant of an object carries a description which no
-    Concise Format item can carry -- a multi-line one (a fenced code
-    block, an ordered list, a blockquote, or multiple paragraphs) or one
-    carrying a ";", as only a ";"-free description stays a single segment
-    on re-parsing instead of splitting off a spurious property  */
-const complexBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
-    && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
+/*  whether any descendant of an object carries a name or a description
+    which no Concise Format item can carry -- a name carrying a ";" (it
+    would split the head segment), or a multi-line description (a fenced
+    code block, an ordered list, a blockquote, or multiple paragraphs) or
+    one carrying a ";", as only a ";"-free description stays a single
+    segment on re-parsing instead of splitting off a spurious property  */
+const complexBelowMd = (object) => object.childs.some((child) => child.name.includes(";")
+    || (child.description !== undefined
+        && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
 /*  render an object in the Concise Format as a list item of the
     given nesting depth, with its childs as nested list items  */
 const renderConciseMd = (object, depth = 0) => {

package/dst/specbook-export-pdf.js

@@ -39,8 +39,10 @@ const addOutline = async (doc, entries) => {
     if (dests !== undefined) {
         for (const [name] of dests.entries()) {
             const dest = dests.lookup(name);
-            const page = dest instanceof PDFArray ? dest.get(0) : undefined;
-            if (dest instanceof PDFArray && page instanceof PDFRef && live.has(page.toString()))
+            if (!(dest instanceof PDFArray))
+                continue;
+            const page = dest.get(0);
+            if (page instanceof PDFRef && live.has(page.toString()))
                 targets.set(name.decodeText(), dest);
         }
     }

package/dst/specbook-format-schema.js

@@ -16,6 +16,8 @@ const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map
         typeof value === "number" ? v.pipe(v.number(), v.finite(), v.minValue(0)) : v.string()]));
 const SchemaDiagramConfig = v.partial(v.strictObject(GradiaConfigSchemas, (issue) => issue.expected === "never" ? "unknown Gradia rendering option" :
     "expected a map of Gradia rendering options"));
+/*  the Valibot schemas mirroring the types above, with the object
+    kind schema referencing itself lazily for the nested childs  */
 const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),

package/dst/specbook-format-spec.js

@@ -5,6 +5,8 @@
 */
 import * as v from "valibot";
 /*  ==== Schema ====  */
+/*  the Valibot schemas mirroring the types above, with the object
+    schema referencing itself lazily for the nested childs  */
 const SpecProperty = v.object({
     key: v.string(),
     value: v.string(),