@rse/specbook 1.5.2 → 1.6.1

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

@@ -2,4 +2,4 @@ import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
 import type { Verbose } from "./specbook-verbose.js";
 export type AstFormat = "json" | "json5" | "yaml" | "toon";
-export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Buffer>;
+export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:state" | "diagram:layer" | "diagram:slice" | "diagram:tree" | "diagram:matrix" | "diagram:sequence" | "diagram:petri" | "diagram:gantt" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Buffer>;

package/dst/specbook-export-ast.js

@@ -39,11 +39,12 @@ export const renderAst = async (specification, format, config, verbose, omit = n
             return sources.get(diagramKey(diagram.language, diagram.source))?.light ?? "";
         })));
     /*  attach the Gradia specs of the diagram-configured objects as
-        "diagram" fields onto the corresponding plain object nodes
-        (an invalid diagram situation omits the diagram, as it is
-        already reported as a lint diagnostic, the diagram of the
-        title object is reserved for the HTML/PDF export, and the
-        diagrams of the omitted aspects are left out), and
+        "diagram" fields onto the corresponding plain object nodes (a
+        single spec as a string, several ones as a list of strings; an
+        invalid diagram situation omits the diagram, as it is already
+        reported as a lint diagnostic, the diagram of the title object
+        is reserved for the HTML/PDF export, and the diagrams of the
+        omitted aspects are left out), and
         the reference coverage of the coverage-configured objects as
         "coverage" fields (the counts only, as the export is intended
         for machine consumption)  */
@@ -52,9 +53,11 @@ export const renderAst = async (specification, format, config, verbose, omit = n
         const omitted = omittedDiagrams(specification, config, omit);
         const coverages = specCoverage(buildLinkIndex(specification), collectSchemas(specification, config));
         const walk = (object, node) => {
-            const result = diagrams.get(object);
-            if (result?.spec !== undefined && !isTitleObject(object) && !omitted.has(object))
-                node.diagram = result.spec;
+            const specs = isTitleObject(object) ? [] : (diagrams.get(object) ?? [])
+                .filter((result) => !omitted.has(result))
+                .flatMap((result) => result.spec !== undefined ? [result.spec] : []);
+            if (specs.length > 0)
+                node.diagram = specs.length === 1 ? specs[0] : specs;
             const coverage = coverages.get(object);
             if (coverage !== undefined)
                 node.coverage = coverage.map(({ pattern, covered, uncovered }) => ({ pattern, covered: covered.length, total: covered.length + uncovered.length }));

package/dst/specbook-export-code.js

@@ -101,7 +101,7 @@ const renderListing = (shiki, listing) => {
     descendants: the fenced code blocks of a known language inside its
     description statement and elaboration and the source code files
     embedded into its description and property values  */
-const collect = (object, langs) => {
+const collectLanguages = (object, langs) => {
     for (const text of [object.description?.description ?? "", object.description?.elaboration ?? ""])
         marked.walkTokens(marked.lexer(text), (token) => {
             const listing = token.type === "code" ? fencedListing(token) : undefined;
@@ -116,7 +116,7 @@ const collect = (object, langs) => {
             langs.add(listing.lang);
     }
     for (const child of object.children)
-        collect(child, langs);
+        collectLanguages(child, langs);
 };
 /*  prepare the rendering of the code listings of a specification: the
     syntax highlighter is loaded (on first use) together with the grammars
@@ -127,7 +127,7 @@ export const prepareListings = async (specification, verbose) => {
     const langs = new Set();
     for (const artifact of specification.artifacts)
         for (const object of artifact.objects)
-            collect(object, langs);
+            collectLanguages(object, langs);
     if (langs.size === 0)
         return (listing) => renderListing(null, listing);
     let shiki = null;

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

@@ -4,7 +4,7 @@ export declare const escapeHtml: (text: string) => string;
 export declare const stylesheet: () => string;
 export declare const searchScript: () => string;
 export declare const fallbackLogo: (theme: (typeof embeddingThemes)[number]) => string;
-export declare const omitAspects: readonly ["diagram:graph", "diagram:hub", "diagram:grid", "diagram:code", "diagram:image", "diagram:listing", "diagram:1", "diagram:2", "diagram:3", "text:long"];
+export declare const omitAspects: readonly ["diagram:graph", "diagram:hub", "diagram:grid", "diagram:state", "diagram:layer", "diagram:slice", "diagram:tree", "diagram:matrix", "diagram:sequence", "diagram:petri", "diagram:gantt", "diagram:code", "diagram:image", "diagram:listing", "diagram:1", "diagram:2", "diagram:3", "text:long"];
 export type OmitAspect = typeof omitAspects[number];
 export declare const parseOmit: (omit?: string[]) => Set<OmitAspect>;
 export interface ExportOptions {

package/dst/specbook-export-common.js

@@ -25,8 +25,9 @@ export const fallbackLogo = (theme) => "data:image/svg+xml;base64," +
     embedded images and PDF pages as "image", and the code listings as
     "listing"), the diagrams from an object tree nesting level on, and the
     long texts  */
-export const omitAspects = ["diagram:graph", "diagram:hub", "diagram:grid",
-    "diagram:code", "diagram:image", "diagram:listing",
+export const omitAspects = ["diagram:graph", "diagram:hub", "diagram:grid", "diagram:state",
+    "diagram:layer", "diagram:slice", "diagram:tree", "diagram:matrix", "diagram:sequence", "diagram:petri",
+    "diagram:gantt", "diagram:code", "diagram:image", "diagram:listing",
     "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  */

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

@@ -12,4 +12,4 @@ export declare const embeddedSource: (content: string) => {
 export declare const diagramKey: (language: DiagramLanguage, source: string) => string;
 export declare const omittedDiagram: (language: DiagramLanguage | "image" | "listing", level: number, omit: Set<OmitAspect>) => boolean;
 export declare const objectLevels: (specification: Spec) => Map<SpecObject, number>;
-export declare const renderEmbeddedDiagrams: (specification: Spec, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Map<string, DiagramVariants>>;
+export declare const renderEmbeddedDiagrams: (specification: Spec, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:state" | "diagram:layer" | "diagram:slice" | "diagram:tree" | "diagram:matrix" | "diagram:sequence" | "diagram:petri" | "diagram:gantt" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Map<string, DiagramVariants>>;

package/dst/specbook-export-diagram.js

@@ -96,13 +96,30 @@ const d2Colors = (colors, style) => {
         AA2: s[13], AA4: s[28], AA5: s[30], AB4: s[28], AB5: s[30]
     };
 };
+const mermaidClassColors = (colors, style) => {
+    const [b, a] = [colors.base, colors.accent];
+    return style === "dark" ?
+        { header: a[3], title: b[31], body: b[9], name: a[27], type: a[22], mark: a[16] } :
+        { header: a[7], title: b[31], name: a[5], type: a[11], mark: a[17] };
+};
 /*  render a Mermaid diagram, stripping the web font import the SVG
     carries, as an SVG embedded through an <img> never loads it and it
-    would be the only external reference of the exported document  */
-const renderMermaid = async (source, colors) => {
+    would be the only external reference of the exported document, and
+    recoloring the class boxes of a class diagram (their header with its
+    stereotype and name, their body, and their members, inside every
+    "class-node" group)  */
+const renderMermaid = async (source, colors, cls) => {
     const { renderMermaidSVG } = await import("beautiful-mermaid");
     return renderMermaidSVG(source, { ...colors, transparent: true, padding: 4 })
-        .replace(/^\s*@import url\([^)]*\);\s*$/m, "");
+        .replace(/^\s*@import url\([^)]*\);\s*$/m, "")
+        .replace(/<g class="class-node"[^>]*>[\s\S]*?<\/g>/g, (group) => group
+        .replace("fill=\"var(--_node-fill)\"", `fill="${cls.body ?? "var(--_node-fill)"}"`)
+        .replace("fill=\"var(--_group-hdr)\"", `fill="${cls.header}"`)
+        .replace("fill=\"var(--_text-muted)\">&lt;&lt;", `fill="${cls.title}">&lt;&lt;`)
+        .replace("font-weight=\"700\" fill=\"var(--_text)\"", `font-weight="700" fill="${cls.title}"`)
+        .replaceAll("<tspan fill=\"var(--_text-sec)\">", `<tspan fill="${cls.name}">`)
+        .replaceAll("<tspan fill=\"var(--_text-muted)\">", `<tspan fill="${cls.type}">`)
+        .replaceAll("<tspan fill=\"var(--_text-faint)\">", `<tspan fill="${cls.mark}">`));
 };
 /*  the D2 compiler, created on first use (as it spins up its WebAssembly
     build in a worker thread), and the chain of its requests, as it
@@ -180,14 +197,15 @@ export const renderEmbeddedDiagrams = async (specification, verbose, omit = new
         const key = diagramKey(language, source);
         if (rendered.has(key) || failed.has(key) || omittedDiagram(language, level, omit))
             continue;
-        let variants = diagramCache.get(`${tone}\u0000${key}`) ?? cache.get(`${tone}\u0000${key}`);
+        const toned = `${tone}\u0000${key}`;
+        let variants = diagramCache.get(toned);
         if (variants !== undefined)
             cached++;
         else {
             try {
                 variants = language === "mermaid" ? {
-                    light: await renderMermaid(source, mermaidColors(colors, "light")),
-                    dark: await renderMermaid(source, mermaidColors(colors, "dark"))
+                    light: await renderMermaid(source, mermaidColors(colors, "light"), mermaidClassColors(colors, "light")),
+                    dark: await renderMermaid(source, mermaidColors(colors, "dark"), mermaidClassColors(colors, "dark"))
                 } : {
                     light: await renderD2(source, d2Colors(colors, "light"), "light"),
                     dark: await renderD2(source, d2Colors(colors, "dark"), "dark")
@@ -201,7 +219,7 @@ export const renderEmbeddedDiagrams = async (specification, verbose, omit = new
                 continue;
             }
         }
-        cache.set(`${tone}\u0000${key}`, variants);
+        cache.set(toned, variants);
         rendered.set(key, variants);
     }
     diagramCache = cache;

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

@@ -1,20 +1,30 @@
 import type nunjucks from "nunjucks";
 import type { OmitAspect } from "./specbook-export-common.js";
 export declare const foldScript: (standins: boolean, textless: boolean) => string;
+export declare const lineChars = 140;
 export declare const omitLong: (omit: Set<OmitAspect> | null, cells: nunjucks.runtime.SafeString[], shares: number[], percent?: number) => nunjucks.runtime.SafeString[];
 export declare const omittedControls: (omit: Set<OmitAspect>) => {
     omitted: {
-        graph: boolean;
-        hub: boolean;
-        grid: boolean;
-        code: boolean;
-        image: boolean;
-        listing: boolean;
+        gradia: boolean;
         level1: boolean;
         level2: boolean;
         level3: boolean;
         text: boolean;
         all: boolean;
+        code: boolean;
+        layer: boolean;
+        slice: boolean;
+        state: boolean;
+        petri: boolean;
+        graph: boolean;
+        hub: boolean;
+        grid: boolean;
+        tree: boolean;
+        matrix: boolean;
+        sequence: boolean;
+        gantt: boolean;
+        image: boolean;
+        listing: boolean;
     };
     css: string;
 };

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

@@ -18,7 +18,8 @@ const cellGainMin = 25;
     left corner, folds the text of every table cell towering over the
     other cells of its row behind a chevron mark of its own, and lets
     the controls of the fold tab fold and unfold all diagrams of a type
-    ("graph", "hub", "grid", plus the embedded Mermaid/D2 ones as "code",
+    ("graph", "hub", "grid", "state", "layer", "slice", "tree", "matrix", "sequence", "petri", "gantt",
+    plus the embedded Mermaid/D2 ones as "code",
     the embedded images and PDF pages as "image", and the code listings
     as "listing"), all diagrams from an object tree nesting level on
     (1, 2, 3), and all cell texts at once, with their state
@@ -36,16 +37,24 @@ export const foldScript = (standins, textless) => textframe `
         if (tab === null)
             return
         const controls = {
-            graph:   tab.querySelector("div.fold-graphs"),
-            hub:     tab.querySelector("div.fold-hubs"),
-            grid:    tab.querySelector("div.fold-grids"),
-            code:    tab.querySelector("div.fold-codes"),
-            image:   tab.querySelector("div.fold-images"),
-            listing: tab.querySelector("div.fold-listings"),
-            level1:  tab.querySelector("div.fold-level1"),
-            level2:  tab.querySelector("div.fold-level2"),
-            level3:  tab.querySelector("div.fold-level3"),
-            text:    tab.querySelector("div.fold-texts")
+            graph:    tab.querySelector("div.fold-graphs"),
+            hub:      tab.querySelector("div.fold-hubs"),
+            grid:     tab.querySelector("div.fold-grids"),
+            state:    tab.querySelector("div.fold-states"),
+            layer:    tab.querySelector("div.fold-layers"),
+            slice:    tab.querySelector("div.fold-slices"),
+            tree:     tab.querySelector("div.fold-trees"),
+            matrix:   tab.querySelector("div.fold-matrices"),
+            sequence: tab.querySelector("div.fold-sequences"),
+            petri:    tab.querySelector("div.fold-petris"),
+            gantt:    tab.querySelector("div.fold-gantts"),
+            code:     tab.querySelector("div.fold-codes"),
+            image:    tab.querySelector("div.fold-images"),
+            listing:  tab.querySelector("div.fold-listings"),
+            level1:   tab.querySelector("div.fold-level1"),
+            level2:   tab.querySelector("div.fold-level2"),
+            level3:   tab.querySelector("div.fold-level3"),
+            text:     tab.querySelector("div.fold-texts")
         }${standins ? `
         for (const kind of Object.keys(controls))
             controls[kind] ??= document.createElement("div")` : ""}
@@ -93,7 +102,8 @@ export const foldScript = (standins, textless) => textframe `
             control; a diagram joins the set of its type plus the sets
             of all nesting levels up to its own one (3 standing for all
             deeper ones), so the sets of the controls overlap  */
-        const folds = { graph: [], hub: [], grid: [], code: [], image: [], listing: [],
+        const folds = { graph: [], hub: [], grid: [], state: [], layer: [], slice: [], tree: [], matrix: [], sequence: [],
+            petri: [], gantt: [], code: [], image: [], listing: [],
             level1: [], level2: [], level3: [], text: [] }
         document.querySelectorAll("article div.diagram, nav.doc div.diagram").forEach((el) => {
             const type  = el.getAttribute("data-type") ?? "graph"
@@ -230,7 +240,10 @@ export const foldScript = (standins, textless) => textframe `
                 word position still fitting is found by a binary search over
                 the measured word positions, the text node is split there and
                 the chevron mark takes its place, followed by the remainder
-                hidden up the ancestor chain of the cell  */
+                hidden up the ancestor chain of the cell. All cells are
+                measured before the first cut and all cuts are applied before
+                their gain is measured, as every measurement after a change
+                of the document forces the browser to lay it out again  */
             for (const cut of cuts) {
                 const list = positions(cut.cell)
                 if (list.length === 0)
@@ -244,10 +257,14 @@ export const foldScript = (standins, textless) => textframe `
                     else
                         hi = mid - 1
                 }
-                const tail    = list[lo].node.splitText(list[lo].offset)
-                const chevron = mark("fold-more", "fold/unfold the remaining text")
-                tail.parentNode.insertBefore(chevron, tail)
-                let current = chevron
+                cut.word = list[lo]
+            }
+            const applied = cuts.filter((cut) => cut.word !== undefined)
+            for (const cut of applied) {
+                const tail = cut.word.node.splitText(cut.word.offset)
+                cut.chevron = mark("fold-more", "fold/unfold the remaining text")
+                tail.parentNode.insertBefore(cut.chevron, tail)
+                let current = cut.chevron
                 while (current !== cut.cell) {
                     let next = current.nextSibling
                     while (next !== null) {
@@ -257,20 +274,22 @@ export const foldScript = (standins, textless) => textframe `
                     }
                     current = current.parentNode
                 }
-
-                /*  the gain is measured on the applied fold, as only that
-                    one tells the real one, and a fold gaining less than the
-                    minimum share is taken back again, while a kept fold
-                    sheds the class again, as every cell starts out unfolded  */
                 cut.cell.classList.add("folded")
-                const gained = height(cut.cell) <= cut.full * (1 - cellGain / 100)
-                if (!gained) {
+            }
+
+            /*  the gain is measured on the applied fold, as only that
+                one tells the real one, and a fold gaining less than the
+                minimum share is taken back again, while a kept fold
+                sheds the class again, as every cell starts out unfolded  */
+            const gained = applied.map((cut) => height(cut.cell) <= cut.full * (1 - cellGain / 100))
+            applied.forEach((cut, i) => {
+                if (!gained[i]) {
                     uncut(cut.cell)
-                    continue
+                    return
                 }
                 cut.cell.classList.toggle("folded", state.get(cut.cell) ?? all)
                 folds.text.push(cut.cell)
-                chevron.addEventListener("click", (event) => {
+                cut.chevron.addEventListener("click", (event) => {
                     /*  the cut can land inside a hyperlink, whose navigation
                         the chevron has to suppress for its own click alone,
                         so the remaining link text still follows the link  */
@@ -278,7 +297,7 @@ export const foldScript = (standins, textless) => textframe `
                     cut.cell.classList.toggle("folded")
                     sync()
                 })
-            }
+            })
         }
         layout()
 
@@ -297,8 +316,9 @@ export const foldScript = (standins, textless) => textframe `
 
         /*  fold exactly the diagrams at least one active control covers  */
         const apply = () => {
+            const covered = new Set(Array.from(active).flatMap((kind) => folds[kind]))
             folds.level1.forEach((fold) => {
-                fold.classList.toggle("folded", Array.from(active).some((kind) => folds[kind].includes(fold)))
+                fold.classList.toggle("folded", covered.has(fold))
             })
         }
 
@@ -376,7 +396,7 @@ export const foldScript = (standins, textless) => textframe `
 `;
 /*  the estimated number of characters a text line spanning the
     entire content width holds (60rem at the document font)  */
-const lineChars = 140;
+export const lineChars = 140;
 /*  omit the long texts of the comparable cells of a table row, the
     server-side heuristic counterpart of the client-side cell text
     folding, judging a cell by its estimated number of text lines (its
@@ -392,14 +412,14 @@ export const omitLong = (omit, cells, shares, percent = 0) => {
     if (omit?.has("text:long") !== true)
         return cells;
     const htmls = cells.map(String);
-    const plain = (html) => html.replace(/<[^>]*>/g, "").trim().length;
-    const lengths = htmls.map((html) => (/<td[\s>]|<div class="diagram"/).test(html) ? 0 : plain(html));
+    const textLen = (html) => html.replace(/<[^>]*>/g, "").trim().length;
+    const lengths = htmls.map((html) => (/<td[\s>]|<div class="diagram"/).test(html) ? 0 : textLen(html));
     if (lengths.filter((length) => length > 0).length < 2)
         return cells;
     const chars = shares.map((share) => Math.max(1, Math.floor(lineChars * share)));
     const lines = htmls.map((html, i) => lengths[i] === 0 ? 0 :
         html.split(/<\/(?:p|li|div|pre)>|<br\s*\/?>/)
-            .reduce((sum, block) => sum + Math.ceil(plain(block) / chars[i]), 0));
+            .reduce((sum, block) => sum + Math.ceil(textLen(block) / chars[i]), 0));
     return htmls.map((html, i) => {
         const other = Math.max(...lines.filter((_, j) => j !== i)) *
             (1 + (percent > 0 ? percent : cellHeightDefault) / 100);
@@ -428,6 +448,10 @@ export const omitLong = (omit, cells, shares, percent = 0) => {
         return cells[i];
     });
 };
+/*  the diagram types of the fold controls, the Gradia ones first  */
+const gradiaTypes = ["graph", "hub", "grid", "state", "layer", "slice",
+    "tree", "matrix", "sequence", "petri", "gantt"];
+const diagramTypes = [...gradiaTypes, "code", "image", "listing"];
 /*  the fold controls the omitted aspects drop, along with the implied
     ones (no type control without diagrams of that type, no level
     control without diagrams from that level on, no fold tab without
@@ -435,24 +459,21 @@ export const omitLong = (omit, cells, shares, percent = 0) => {
     style rules the omission brings (the "[...]" mark of the omitted
     long texts and the moved-up tabs of a dropped fold tab)  */
 export const omittedControls = (omit) => {
-    const none = omit.has("diagram:1")
-        || (omit.has("diagram:graph") && omit.has("diagram:hub") && omit.has("diagram:grid")
-            && omit.has("diagram:code") && omit.has("diagram:image") && omit.has("diagram:listing"));
+    const none = omit.has("diagram:1") || diagramTypes.every((type) => omit.has(`diagram:${type}`));
+    const types = Object.fromEntries(diagramTypes.map((type) => [type, none || omit.has(`diagram:${type}`)]));
     const omitted = {
-        graph: none || omit.has("diagram:graph"),
-        hub: none || omit.has("diagram:hub"),
-        grid: none || omit.has("diagram:grid"),
-        code: none || omit.has("diagram:code"),
-        image: none || omit.has("diagram:image"),
-        listing: none || omit.has("diagram:listing"),
+        ...types,
         level1: none,
         level2: none || omit.has("diagram:2"),
         level3: none || omit.has("diagram:2") || omit.has("diagram:3"),
         text: omit.has("text:long"),
         all: none && omit.has("text:long")
     };
+    /*  the first row of the fold panel (the Gradia diagram types) is
+        dropped once all of its controls are  */
+    const gradia = gradiaTypes.every((type) => omitted[type]);
     const css = (omitted.text ? "\nspan.omit { color: var(--theme-color-specbook-muted) }" : "") +
-        (omitted.all ? "\nnav.toc-panel div.toc-tab { top: 10.66rem }" +
-            "\ndiv.realtime-status { top: 13.89rem }" : "");
-    return { omitted, css };
+        (omitted.all ? "\nnav.toc-panel div.toc-tab { top: 13.89rem }" +
+            "\ndiv.realtime-status { top: 17.12rem }" : "");
+    return { omitted: { ...omitted, gradia }, css };
 };

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

@@ -14,7 +14,7 @@ import { embeddedSource, fenceLanguage, diagramKey, omittedDiagram } from "./spe
 import { embeddedListing, fencedListing } from "./specbook-export-code.js";
 import { coverageRatio } from "./specbook-coverage.js";
 import { safe, render } from "./specbook-export-html-template.js";
-import { omitLong } from "./specbook-export-html-fold.js";
+import { omitLong, lineChars } from "./specbook-export-html-fold.js";
 /*  ==== Rendering ====  */
 /*  the per-language double quote styles for the smart typography
     (single quotes stay curly, as smartypants cannot distinguish a
@@ -37,6 +37,35 @@ const quoteStyles = {
 };
 /*  the active double quote style (set per document during rendering)  */
 let quotes = quoteStyles.en;
+/*  the per-language translations of the rationale keyword, rendered
+    behind the always English "BECAUSE" of the source syntax  */
+const rationaleKeywords = {
+    "de": "weil",
+    "nl": "omdat",
+    "fr": "parce que",
+    "it": "perché",
+    "es": "porque",
+    "pt": "porque",
+    "da": "fordi",
+    "no": "fordi",
+    "sv": "eftersom",
+    "fi": "koska",
+    "pl": "ponieważ",
+    "cs": "protože",
+    "sk": "pretože",
+    "hu": "mert",
+    "ro": "deoarece",
+    "tr": "çünkü",
+    "ru": "потому что",
+    "uk": "тому що",
+    "el": "επειδή",
+    "ja": "なぜなら",
+    "zh": "因为",
+    "ko": "왜냐하면"
+};
+/*  the active rationale keyword translation (set per document during
+    rendering, none for English and the unknown languages)  */
+let keyword;
 /*  the private Markdown renderer instance, as the hooks below must not
     leak into the "marked" singleton shared with the parser and with the
     application embedding SpecBook as a library  */
@@ -89,7 +118,9 @@ let omits = null;
     as it would otherwise retain the specification (and its embedded
     images) until the next rendering  */
 export const withDocument = (state, body) => {
-    quotes = quoteStyles[state.lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
+    const code = state.lang?.toLowerCase().split(/[-_]/)[0] ?? "en";
+    quotes = quoteStyles[code] ?? quoteStyles.en;
+    keyword = rationaleKeywords[code];
     linker = state.linker;
     anchors = state.anchors;
     members = state.members;
@@ -275,6 +306,13 @@ marked.use({ renderer: { code(token) {
             const listing = fencedListing(token);
             return listing !== undefined && listings !== null ? renderListingBlock(listings, listing) : false;
         } } });
+/*  render an inline code span with a line break opportunity behind every
+    separator (comma, semicolon, pipe), so an overlong span without any
+    space (like a long value expression) breaks there, ahead of breaking
+    inside a word (the last resort of the stylesheet)  */
+marked.use({ renderer: { codespan(token) {
+            return `<code>${escapeHtml(token.text).replace(/([,;|])(?=.)/g, "$1<wbr>")}</code>`;
+        } } });
 /*  strip the fenced code blocks of a diagram language or a code listing
     off a text  */
 const stripDiagrams = (text) => marked.lexer(text)
@@ -336,6 +374,7 @@ const renderDescription = (description) => {
             description: text !== "" ? (blocked ? block(text, true) : inline(text, true)) : "",
             rationale: description.rationale !== undefined ?
                 inline(description.rationale, true) : undefined,
+            keyword,
             elaboration: elaboration !== "" ? block(elaboration, true) : undefined,
             embeddings
         } });
@@ -520,6 +559,15 @@ const coverageOf = (object) => {
             even: i % 2 === 1
         })) }));
 };
+/*  the estimated width of the longest word of an HTML text, in average
+    characters, a capital counting double (as the property names and the
+    bold kind labels of the references are set in capitals)  */
+const longestWord = (html) => Math.max(0, ...html.replace(/<[^>]*>/g, " ").replace(/&[#a-z0-9]+;/gi, "x").split(/\s+/)
+    .map((text) => text.length + (text.match(/[A-Z]/g) ?? []).length));
+/*  the width share of a table column, for the width of its longest word
+    and the characters one share holds: one share, or up to two and a
+    half where the word needs more, so it never breaks inside  */
+const columnShare = (need, base) => Math.min(2.5, Math.max(1, (need + 5) / base));
 /*  render a single-kind group of children into one compact table:
     the name first, then the property columns, then the description;
     a group wider than maxColumns, or carrying diagrams, instead chunks
@@ -531,7 +579,18 @@ const renderTable = (children, maxColumns) => {
     const { keys, desc } = tableShape(children);
     const diagrammed = children.some((child) => diagrams?.has(child) === true);
     const fold = formatOf(children[0])?.maxCellHeight;
-    if (!diagrammed && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
+    if (!diagrammed && 1 + keys.length + (desc ? 1 : 0) <= maxColumns) {
+        /*  under the fixed table layout the name column takes a fixed
+            20% (via CSS), while the property columns and the description
+            column (two shares) split the remaining 80%, a property column
+            by the longest word of its values and its header, so a column
+            of short values (like a kind) yields room  */
+        const values = children.map((child) => scoped(child, () => keys.map((key) => inlineValue(child.kind, child.properties.find((property) => property.key === key)))));
+        const base = 0.8 * lineChars / (keys.length + (desc ? 2 : 0));
+        const shares = keys.map((key, k) => columnShare(Math.max(longestWord(key), ...values.map((row) => longestWord(String(row[k])))), base));
+        if (desc)
+            shares.push(2);
+        const total = shares.reduce((sum, share) => sum + share, 0);
         return render("Table", { Table: {
                 head: children[0].kind !== "" ? children[0].kind : "Name",
                 info: infoKeyOf(children[0]),
@@ -539,14 +598,9 @@ const renderTable = (children, maxColumns) => {
                 keys,
                 desc,
                 fold,
-                /*  under the fixed table layout the name column takes a fixed
-                    20% (via CSS) and the description column claims twice the
-                    share of a property column of the remaining 80%  */
-                width: Math.round(1600 / (keys.length + 2)) / 10,
+                widths: shares.map((share) => Math.round(800 * share / total) / 10),
                 rows: children.map((child, i) => scoped(child, () => {
-                    const values = keys.map((key) => inlineValue(child.kind, child.properties.find((property) => property.key === key)));
-                    const shares = desc ? [...keys.map(() => 1), 2] : keys.map(() => 1);
-                    const cells = omitLong(omits, desc ? [...values, safe(renderCell(child))] : values, shares.map((share) => 0.8 * share / (keys.length + (desc ? 2 : 0))), fold);
+                    const cells = omitLong(omits, desc ? [...values[i], safe(renderCell(child))] : values[i], shares.map((share) => 0.8 * share / total), fold);
                     return {
                         id: anchorOf(child),
                         anchor: child.anchor,
@@ -560,33 +614,59 @@ const renderTable = (children, maxColumns) => {
                     };
                 }))
             } });
+    }
     /*  the embedded rows hold at most maxColumns - 1 cells (of the
         group-wide union of property keys, plus the trailing description),
         with the last cell spanning the leftover columns of the final row,
         all of them sharing the 80% beside the fixed 20% name column  */
     const size = Math.max(1, maxColumns - 1);
+    const parts = children.map((child) => scoped(child, () => {
+        const cells = keys.map((key) => ({ key, desc: false, span: 1,
+            value: inlineValue(child.kind, child.properties.find((property) => property.key === key)) }));
+        if (desc)
+            cells.push({ key: "Description", desc: true, span: 1,
+                value: safe(renderCell(child)) });
+        const chunks = new Array();
+        for (let pos = 0; pos < cells.length; pos += size)
+            chunks.push(cells.slice(pos, pos + size));
+        if (chunks.length > 0) {
+            const last = chunks[chunks.length - 1];
+            last[last.length - 1].span = size - last.length + 1;
+        }
+        return chunks;
+    }));
+    /*  the columns of the embedded rows take their shares by the longest
+        word of their single property cells over all objects of the group,
+        exactly like the columns of a plain table, so the embedded rows
+        of all objects keep one common column grid  */
+    const needs = new Array(size).fill(0);
+    for (const chunks of parts)
+        for (const chunk of chunks)
+            chunk.forEach((cell, k) => {
+                if (!cell.desc && cell.span === 1)
+                    needs[k] = Math.max(needs[k], longestWord(cell.key), longestWord(String(cell.value)));
+            });
+    const shares = needs.map((need) => columnShare(need, 0.8 * lineChars / size));
+    const total = shares.reduce((sum, share) => sum + share, 0);
     return render("TableChunked", { Table: {
             head: children[0].kind !== "" ? children[0].kind : "Name",
             info: infoKeyOf(children[0]),
             infopath: infoRefOf(children[0], false),
             desc,
             fold,
+            widths: shares.map((share) => Math.round(1000 * share / total) / 10),
             rows: children.map((child, i) => scoped(child, () => {
-                const cells = keys.map((key) => ({ key, desc: false, span: 1,
-                    value: inlineValue(child.kind, child.properties.find((property) => property.key === key)) }));
-                if (desc)
-                    cells.push({ key: "Description", desc: true, span: 1,
-                        value: safe(renderCell(child)) });
-                const chunks = new Array();
-                for (let pos = 0; pos < cells.length; pos += size)
-                    chunks.push(cells.slice(pos, pos + size));
-                if (chunks.length > 0) {
-                    const last = chunks[chunks.length - 1];
-                    last[last.length - 1].span = size - last.length + 1;
-                }
-                for (const chunk of chunks)
-                    omitLong(omits, chunk.map((cell) => cell.value), chunk.map((cell) => 0.8 * cell.span / size), fold)
+                const chunks = parts[i];
+                for (const chunk of chunks) {
+                    let pos = 0;
+                    const spans = chunk.map((cell) => {
+                        const share = shares.slice(pos, pos + cell.span).reduce((sum, s) => sum + s, 0);
+                        pos += cell.span;
+                        return 0.8 * share / total;
+                    });
+                    omitLong(omits, chunk.map((cell) => cell.value), spans, fold)
                         .forEach((value, k) => { chunk[k].value = value; });
+                }
                 /*  the diagram leads the chunks as a full-width chunk of its
                     own, headed like the description  */
                 const diagram = diagramOf(child);
@@ -680,18 +760,19 @@ export const renderTitlePage = (object, created, modified) => {
         const value = prop(name);
         return value !== undefined && value.trim() !== "" ? inline(value) : "";
     };
-    const rest = object.properties.filter((property) => !titleProperties.some((prop) => prop.name === property.key));
+    const rest = object.properties.filter((property) => !titleProperties.some((entry) => entry.name === property.key));
     /*  the logo is rendered above the title, from the embedded image content
         of the LOGO property or, for a non-embeddable reference, as its inline
         Markdown; without a (non-empty) LOGO property the built-in SpecBook
         logo is used, in both its theme variants  */
     const logo = object.properties.find((property) => property.key === "LOGO" && property.value.trim() !== "");
     const image = logo !== undefined ? renderEmbeddings(logo.value, logo.embedding ?? [], false) : [];
+    const title = prop("TITLE")?.trim();
     return scoped(object, () => render("TitlePage", { TitlePage: {
             logo: logo === undefined ?
                 safe(renderThemed(embeddingThemes.map((theme) => `<img src="${fallbackLogo(theme)}" alt="SpecBook"/>`))) :
                 (image.length > 0 ? safe(image.join("")) : inline(logo.value)),
-            title: inline(prop("TITLE") ?? object.name),
+            title: inline(title !== undefined && title !== "" ? title : "Specification"),
             subtitle: inlineProp("SUBTITLE"),
             author: inlineProp("AUTHOR"),
             version: inlineProp("VERSION"),