@rse/specbook 1.2.14 → 1.2.16

package/dst/specbook-export-common.js

@@ -17,6 +17,24 @@ export const searchScript = () => fs.readFileSync(new URL("specbook-export-html-
     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");
+/*  the content aspects an export can omit, each matching the set of a
+    folding control of the HTML export: the diagrams of a type, the
+    diagrams from an object tree nesting level on, and the long texts  */
+export const omitAspects = ["diagram:graph", "diagram:hub", "diagram:grid",
+    "diagram:1", "diagram:2", "diagram:3", "text:long"];
+/*  parse the (comma-separated) aspects to omit, where the
+    plain "diagram" is the alias of "diagram:1", hence of all diagrams  */
+export const parseOmit = (omit = []) => {
+    const aspects = new Set();
+    for (const item of omit.flatMap((list) => list.split(",")).map((item) => item.trim())) {
+        const aspect = item === "diagram" ? "diagram:1" : item;
+        if (!omitAspects.includes(aspect))
+            throw new Error(`unknown omit aspect "${item}" ` +
+                `(expected "diagram" or one of "${omitAspects.join("\", \"")}")`);
+        aspects.add(aspect);
+    }
+    return aspects;
+};
 /*  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, searched at any
@@ -34,8 +52,14 @@ export const titleObject = (specification) => {
     };
     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 a property value of the title object (a present but empty
+    value counting as an absent property, so every consumer falls back
+    onto its own default)  */
+const titleProperty = (specification, name) => {
+    const value = titleObject(specification)
+        ?.properties.find((property) => property.key === name)?.value;
+    return value !== undefined && value.trim() !== "" ? value : undefined;
+};
 /*  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  */
@@ -76,10 +100,18 @@ export const documentPaperSize = (specification) => {
     sized diagram could not share its page with the heading, which
     would defeat the "break-after: avoid" bundling of the stylesheet  */
 const headingReserve = 6;
+/*  the vertical room (in rem) the "Diagram of Contents" heading claims
+    above its diagram: this <h1> opens its page and hence carries its
+    full margins (3rem above, 2rem below) plus its own 2.4rem line and
+    the 2rem margins of the diagram, which the flat reserve above
+    underestimates, so the diagram would be pushed onto the next page  */
+const docHeadingReserve = 10;
 /*  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  */
+    heading reserve above it) and is never broken across a page boundary,
+    where the diagram of the "Diagram of Contents" page gets the larger
+    reserve its own heading demands  */
 export const paperStylesheet = (paper) => {
     const setup = paperSetup(paper);
     const avail = setup.height - setup.margin.top - setup.margin.bottom;
@@ -87,6 +119,7 @@ export const paperStylesheet = (paper) => {
         "div.diagram { break-inside: avoid; }\n" +
         `div.diagram svg { max-height: calc(${paperLength(setup, avail)} - ${headingReserve}rem);` +
         " width: auto; height: auto; }\n" +
+        `nav.doc div.diagram svg { max-height: calc(${paperLength(setup, avail)} - ${docHeadingReserve}rem); }\n` +
         "}\n";
 };
 /*  generate a contiguous codepoint range  */

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

@@ -50,34 +50,37 @@
     let indexed = false
 
     /*  fill the unit and vocabulary indices once on first use: a unit
-        is an outermost paragraph-level element within an article, i.e.
-        one not nested inside another unit (like a paragraph or diagram
-        in a table cell, which is covered by its table row), where a
-        diagram is searched by its SVG text labels, joined by spaces,
-        as its raw text content would run them together, and where the
-        explicit anchor id of an object heading or table row joins the
-        searched text  */
+        is an outermost paragraph-level element within an article or
+        the title page abstract (a lone paragraph being the unit itself),
+        i.e. one not nested inside another unit (like a paragraph in a
+        table cell, covered by its table row), where a diagram is
+        searched by its space-joined SVG text labels (its raw text
+        content runs them together), and where the explicit anchor id
+        of an object heading or table row joins the searched text  */
     const index = () => {
         if (indexed)
             return
         indexed = true
-        document.querySelectorAll("article").forEach((article) => {
-            article.querySelectorAll("p, li, tr, pre, blockquote, h1, h2, h3, h4, h5, h6, div.diagram")
-                .forEach((el) => {
-                    let parent = el.parentElement
-                    while (parent !== null && parent.tagName !== "ARTICLE") {
-                        if (/^(TR|TD|TH|LI|P|BLOCKQUOTE)$/.test(parent.tagName))
-                            return
-                        parent = parent.parentElement
-                    }
-                    const id    = (el.dataset.id ?? "").toLowerCase()
-                    const text  = ((el.classList.contains("diagram") ?
-                        Array.from(el.querySelectorAll("text")).map((t) => t.textContent ?? "").join(" ") :
-                        (el.textContent ?? "")) + " " + id).toLowerCase()
-                    const words = new Set(text.split(/[^\p{L}\p{N}]+/u).filter((w) => w !== ""))
-                    words.forEach((w) => { vocab.add(w) })
-                    units.push({ el, id, text, words, keep: false })
-                })
+        document.querySelectorAll("article, div.titlepage > .description").forEach((root) => {
+            const els = Array.from(root.querySelectorAll(
+                "p, li, tr, pre, blockquote, h1, h2, h3, h4, h5, h6, div.diagram"))
+            if (root.tagName === "P")
+                els.unshift(root)
+            els.forEach((el) => {
+                let parent = el.parentElement
+                while (parent !== null && parent !== root) {
+                    if (/^(TR|TD|TH|LI|P|BLOCKQUOTE)$/.test(parent.tagName))
+                        return
+                    parent = parent.parentElement
+                }
+                const id    = (el.dataset.id ?? "").toLowerCase()
+                const text  = ((el.classList.contains("diagram") ?
+                    Array.from(el.querySelectorAll("text")).map((t) => t.textContent ?? "").join(" ") :
+                    (el.textContent ?? "")) + " " + id).toLowerCase()
+                const words = new Set(text.split(/[^\p{L}\p{N}]+/u).filter((w) => w !== ""))
+                words.forEach((w) => { vocab.add(w) })
+                units.push({ el, id, text, words, keep: false })
+            })
         })
 
         /*  let a hyperlink whose target the filtering hid leave the

package/dst/specbook-export-html.css

@@ -73,8 +73,8 @@ html.theme-light {
   --theme-color-specbook-tint-deep: var(--theme-color-accent-28);
   --theme-color-specbook-accent: var(--theme-color-accent-12);
   --theme-color-specbook-accent-soft: var(--theme-color-accent-18);
-  --theme-color-specbook-mark-text: var(--theme-color-search-32);
-  --theme-color-specbook-mark-back: var(--theme-color-search-16);
+  --theme-color-specbook-mark-text: var(--theme-color-signal-32);
+  --theme-color-specbook-mark-back: var(--theme-color-signal-16);
   --theme-color-specbook-field: var(--theme-color-accent-8);
   --theme-color-specbook-error: #c00;
   --theme-color-specbook-popup-schema-path: var(--theme-color-accent-30);
@@ -84,6 +84,15 @@ html.theme-light {
   --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";
+/*  the font sizes the diagram layout was sized for (kept in sync
+        with "diagramPresets" of specbook-diagram.ts, which feeds the
+        layout): an override here keeps that layout and hence has to
+        stay close to them  */
+  --gradia-size-font-node: 30px;
+  --gradia-size-font-type: 19px;
+  --gradia-size-font-prop: 22px;
+  --gradia-size-font-edge: 19px;
+  --gradia-size-font-arity: 19px;
   --gradia-color-node-regular-name: var(--theme-color-accent-12);
   --gradia-color-node-regular-box: var(--theme-color-accent-30);
   --gradia-color-node-regular-border: var(--theme-color-accent-26);
@@ -93,6 +102,9 @@ html.theme-light {
   --gradia-color-node-ghost-name: var(--theme-color-base-22);
   --gradia-color-node-ghost-box: var(--theme-color-base-31);
   --gradia-color-node-ghost-border: var(--theme-color-base-24);
+  --gradia-color-node-self-name: var(--theme-color-base-14);
+  --gradia-color-node-self-box: var(--theme-color-base-28);
+  --gradia-color-node-self-border: var(--theme-color-base-18);
   --gradia-color-group-name: var(--theme-color-accent-18);
   --gradia-color-group-box: var(--theme-color-accent-32);
   --gradia-color-group-border: var(--theme-color-accent-26);
@@ -117,27 +129,30 @@ html.theme-light {
     --theme-color-specbook-tint: var(--theme-color-accent-1);
     --theme-color-specbook-tint-stripe: var(--theme-color-accent-3);
     --theme-color-specbook-tint-deep: var(--theme-color-accent-5);
-    --theme-color-specbook-accent: var(--theme-color-accent-24);
+    --theme-color-specbook-accent: var(--theme-color-accent-22);
     --theme-color-specbook-accent-soft: var(--theme-color-accent-16);
-    --theme-color-specbook-mark-text: var(--theme-color-search-32);
-    --theme-color-specbook-mark-back: var(--theme-color-search-4);
+    --theme-color-specbook-mark-text: var(--theme-color-signal-32);
+    --theme-color-specbook-mark-back: var(--theme-color-signal-4);
     --theme-color-specbook-field: var(--theme-color-accent-16);
     --theme-color-specbook-error: #c00;
     --theme-color-specbook-popup-schema-path: var(--theme-color-accent-4);
     --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-path: var(--theme-color-accent-22);
     --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-done: var(--theme-color-accent-22);
     --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);
     --gradia-color-node-primary-name: var(--theme-color-base-1);
-    --gradia-color-node-primary-box: var(--theme-color-accent-21);
-    --gradia-color-node-primary-border: var(--theme-color-accent-25);
+    --gradia-color-node-primary-box: var(--theme-color-accent-20);
+    --gradia-color-node-primary-border: var(--theme-color-accent-24);
     --gradia-color-node-ghost-name: var(--theme-color-base-24);
     --gradia-color-node-ghost-box: var(--theme-color-base-12);
     --gradia-color-node-ghost-border: var(--theme-color-base-16);
+    --gradia-color-node-self-name: var(--theme-color-base-28);
+    --gradia-color-node-self-box: var(--theme-color-base-15);
+    --gradia-color-node-self-border: var(--theme-color-base-22);
     --gradia-color-group-name: var(--theme-color-accent-15);
     --gradia-color-group-box: var(--theme-color-accent-1);
     --gradia-color-group-border: var(--theme-color-accent-7);
@@ -413,12 +428,13 @@ div.info-popup.spec a.link-compact::before {
 /*  the folding tab (screen-only): the tab riding right of the brand
     bar between the search tab and the table of contents tab (as wide
     as those, fixed independent of the content scrolling), showing a
-    fold icon (drawn like the search icon), which slides the two
+    fold icon (drawn like the search icon), which slides the
     controls out to the right (and back in), where the tab follows the
     bar when the table of contents panel shifts it aside; the controls
-    fold and unfold all diagrams and all over-long cell texts of the
-    content at once and carry, like the fold icon itself, the mark
-    colors in a rounded box while anything of their kind is folded  */
+    fold and unfold all diagrams of a type, all diagrams from a nesting
+    level on, and all over-long cell texts of the content at once and
+    carry, like the fold icon itself, the mark colors in a rounded box
+    while anything of their kind is folded  */
 div.fold-switch {
   position: fixed;
   top: 10.66rem;
@@ -465,7 +481,7 @@ div.fold-switch div.fold-controls {
   transition: max-width 0.3s ease, padding 0.3s ease;
 }
 div.fold-switch.open div.fold-controls {
-  max-width: 6rem;
+  max-width: 15rem;
   padding: 0 0.5rem 0 0.2rem;
 }
 div.fold-switch div.fold-controls > div {
@@ -1155,10 +1171,18 @@ table.objects table.chunks th:not(.property-name) {
 }
 /*  the diagram leading the chunks of an object, kept in one piece  */
 table.objects table.chunks div.diagram {
-  margin: 0.3rem 0;
+  margin: 0.15rem 0;
   page-break-inside: avoid;
   break-inside: avoid;
 }
+/*  bundle a chunk header row with its value row, so neither the
+    "Diagram" header nor the property names are orphaned at a page end  */
+@media print {
+  table.objects table.chunks tr:has(> th) {
+    page-break-after: avoid;
+    break-after: avoid;
+  }
+}
 /*  keep the cells of empty property values one text line high  */
 table.objects td:empty::after {
   content: "\00A0";
@@ -1182,6 +1206,11 @@ table.chunks {
   table-layout: fixed;
   width: 100%;
 }
+table.objects table.chunks th {
+  font-size: 80%;
+  padding-top: 0.27rem;
+  padding-bottom: 0.27rem;
+}
 table.objects table.chunks tr td {
   background-color: transparent;
 }
@@ -1298,13 +1327,19 @@ div.diagram {
   margin: 1rem 0;
 }
 div.diagram svg {
+  display: block;
   max-width: 100%;
   height: auto;
-}
-div.diagram svg.hub {
-  display: block;
   margin: 0 auto;
 }
+/*  the halo of the diagram edge labels is dropped for print, as Chromium
+    prints a stroked text as the curve outlines of its glyphs instead of
+    as text, which alone made up nearly half of the size of the PDF  */
+@media print {
+  div.diagram svg text {
+    stroke: none;
+  }
+}
 span.rationale {
   color: var(--theme-color-specbook-muted);
 }
@@ -1579,6 +1614,17 @@ nav.doc h1 {
   color: var(--theme-color-specbook-accent);
   font-weight: normal;
 }
+/*  in print, both front matter headings and the first artifact one
+    open a fresh page, where their top margin is kept after the forced
+    page break  */
+@media print {
+  nav.toc h1,
+  nav.doc h1,
+  article:first-of-type > section:first-child,
+  article:first-of-type > section:first-child > h1 {
+    margin-top: 0;
+  }
+}
 @keyframes realtime-blink {
   from {
     background-color: var(--theme-color-specbook-accent-soft);

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

@@ -1,5 +1,6 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
+import { type ExportOptions } from "./specbook-export-common.js";
 import type { Verbose } from "./specbook-verbose.js";
 export type OutlineEntry = {
     title: string;
@@ -9,4 +10,4 @@ export type OutlineEntry = {
 export declare const htmlOutline: (specification: Spec, config?: Schema) => OutlineEntry[];
 export declare const titlePageObject: (specification: Spec) => SpecObject | undefined;
 export declare const renderPlaceholder: (message: string) => string;
-export declare const renderHtml: (specification: Spec, config?: Schema, tocPages?: Map<string, number>, css?: string, realtime?: boolean, verbose?: Verbose) => Promise<string>;
+export declare const renderHtml: (specification: Spec, config?: Schema, tocPages?: Map<string, number>, css?: string, options?: ExportOptions, verbose?: Verbose, print?: boolean) => Promise<string>;