@rse/specbook 1.2.3 → 1.2.5

package/dst/specbook-diagram.js

@@ -40,26 +40,47 @@ const propValue = (parenProps, object, key) => propsOf(parenProps, object).find(
     "#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, centerUrl, nodes, edges, index, anchors, parenProps) => {
+    label, the container node as the parent) and one edge statement per
+    derived edge  */
+const renderSpec = (diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps) => {
     const lines = [`#type ${type}`];
     const config = diagram.config ?? {};
     for (const [key, value] of Object.entries(config))
         if (value !== undefined)
             lines.push(`#config ${key} ${configValue(value)}`);
     lines.push("");
+    /*  the explicit top-down order of an "ordered" diagram: the members
+        of a container share one row (which Gradia wraps), while the
+        top-level nodes stack in document order, a synthetic container
+        taking the position of its first member  */
+    const orderOf = (node) => {
+        if (nesting.parentOf.has(node))
+            return 0;
+        let order = positions.get(node) ?? Number.MAX_SAFE_INTEGER;
+        for (const [member, container] of nesting.parentOf)
+            if (container === node)
+                order = Math.min(order, positions.get(member) ?? order);
+        return order;
+    };
     for (const node of nodes) {
         const anchor = anchors.get(node);
         const attrs = new Array();
-        /*  a synthetic center node (the only node without an anchor
-            path) links to its source object, or nowhere at all  */
-        const url = anchor !== undefined ? `#${anchor}` : centerUrl;
+        /*  a synthetic center or container node (the only nodes without
+            an anchor path) links to its source object, or nowhere at all  */
+        const url = anchor !== undefined ? `#${anchor}` : (node === center ? centerUrl : undefined);
         if (url !== undefined)
             attrs.push(`url: ${atom(url)}`);
         if (diagram.qualified === true && node.kind !== "")
             attrs.push(`type: ${atom(node.kind)}`);
         if (type === "hub" ? node === center : node.primary === true)
             attrs.push("primary: true");
+        const container = nesting.parentOf.get(node);
+        if (container !== undefined)
+            attrs.push(`parent: ${atom(anchors.get(container) ?? container.id)}`);
+        if (diagram.nest?.layout !== undefined && nesting.containers.has(node))
+            attrs.push(`container: ${diagram.nest.layout}`);
+        if (diagram.ordered === true)
+            attrs.push(`order: ${orderOf(node)}`);
         /*  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
@@ -89,13 +110,13 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, ancho
 /*  derive the reference edges of a diagram from the "[[...]]" references
     of the node objects (per the "links" selection, named with the
     property key when "labeled", and for a "deep" diagram also of their
-    descendants, with every target lifted to its nearest node and the
-    reference count as the arity)  */
+    descendants, with the reference count as the arity), with every
+    target lifted to its nearest node  */
 const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents, parenProps) => {
     const edges = new Array();
     /*  lift an object to its nearest ancestor-or-self within the
-        node set, as a "deep" diagram attributes the references of
-        the descendants to their nearest node object  */
+        node set, as a reference onto a descendant of a node object
+        (like the scenario of a use case) is a reference onto the node  */
     const lift = (object) => {
         while (object !== undefined && !nodeSet.has(object))
             object = parents.get(object);
@@ -109,7 +130,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);
         };
@@ -127,9 +148,7 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents,
             }
             for (const { text, name } of texts)
                 for (const m of text.matchAll(referenceRegex)) {
-                    let target = resolveUnique(index, m[1].trim(), object).target;
-                    if (diagram.deep === true)
-                        target = lift(target);
+                    const target = lift(resolveUnique(index, m[1].trim(), object).target);
                     if (target !== undefined && target !== node && nodeSet.has(target)) {
                         const key = `${anchors.get(target) ?? target.id}\u0000${name ?? ""}`;
                         const entry = counts.get(key) ?? { target, name, count: 0 };
@@ -310,7 +329,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 };
@@ -347,10 +366,104 @@ const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
     }
     return edges;
 };
+/*  derive the nesting of the nodes into container nodes: per node the
+    first configured property carrying exactly one resolvable reference
+    names its container (added to the node set when absent, and nested
+    on its own in turn), else its parent object when part of the node
+    set, else a synthetic container per object kind; a node nested into
+    itself or into a cycle stays un-nested and is reported  */
+const deriveNesting = (nest, nodes, nodeSet, index, parents, parenProps, errors) => {
+    const parentOf = new Map();
+    const byKind = new Map();
+    /*  the iteration also visits the containers appended underway  */
+    for (const node of nodes) {
+        let container;
+        for (const key of nest.properties ?? []) {
+            const value = propValue(parenProps, node, key);
+            const refs = value !== undefined ? Array.from(value.matchAll(referenceRegex)) : [];
+            if (refs.length !== 1)
+                continue;
+            container = resolveUnique(index, refs[0][1].trim(), node).target;
+            if (container !== undefined)
+                break;
+        }
+        if (container === undefined && nest.parent === true) {
+            const parent = parents.get(node);
+            if (parent !== undefined && nodeSet.has(parent))
+                container = parent;
+        }
+        if (container === undefined && nest.kind === true && node.kind !== "") {
+            container = byKind.get(node.kind);
+            if (container === undefined) {
+                container = { kind: "", id: `@kind-${node.kind}`, name: node.kind, properties: [], children: [] };
+                byKind.set(node.kind, container);
+            }
+        }
+        if (container === undefined)
+            continue;
+        /*  a container chain leading back to the node would close a
+            cycle, which Gradia rejects exactly like a self-nesting  */
+        let ancestor = container;
+        while (ancestor !== undefined && ancestor !== node)
+            ancestor = parentOf.get(ancestor);
+        if (ancestor === node) {
+            errors.push({ reason: `node "${plainText(node.name)}" is nested into itself` });
+            continue;
+        }
+        parentOf.set(node, container);
+        if (!nodeSet.has(container)) {
+            nodes.push(container);
+            nodeSet.add(container);
+        }
+    }
+    return { parentOf, containers: new Set(parentOf.values()) };
+};
+/*  lift the edges crossing a container boundary onto the containers:
+    an end is replaced by its outermost ancestor container not enclosing
+    the other end as well (the target end only, or both ends), and the
+    edges coinciding afterwards merge into one, with their arities summed
+    where numeric, so a bundle of references into a container becomes a
+    single edge onto it  */
+const liftEdges = (edges, parentOf, mode, anchors) => {
+    const ancestors = (object) => {
+        const chain = new Array();
+        for (let p = parentOf.get(object); p !== undefined; p = parentOf.get(p))
+            chain.push(p);
+        return chain;
+    };
+    const lift = (end, other) => {
+        const enclosing = new Set([other, ...ancestors(other)]);
+        let lifted = end;
+        for (const ancestor of ancestors(end)) {
+            if (enclosing.has(ancestor))
+                break;
+            lifted = ancestor;
+        }
+        return lifted;
+    };
+    const merged = new Map();
+    for (const edge of edges) {
+        const target = lift(edge.target, edge.source);
+        const source = mode === "both" ? lift(edge.source, edge.target) : edge.source;
+        if (source === target)
+            continue;
+        const key = `${anchors.get(source) ?? source.id}${anchors.get(target) ?? target.id}` +
+            `${edge.name ?? ""}`;
+        const known = merged.get(key);
+        if (known === undefined)
+            merged.set(key, { source, target, name: edge.name, arity: edge.arity });
+        else if (known.arity !== undefined && edge.arity !== undefined
+            && /^\d+$/.test(known.arity) && /^\d+$/.test(edge.arity))
+            known.arity = String(Number(known.arity) + Number(edge.arity));
+        else if (known.arity !== edge.arity)
+            known.arity = undefined;
+    }
+    return Array.from(merged.values());
+};
 /*  derive the Gradia spec of a single object from its "diagram:"
     schema configuration (the returned spec is absent whenever the
     configured diagram situation is invalid)  */
-const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) => {
+const deriveDiagram = (object, diagram, index, anchors, positions, parents, parenProps) => {
     const type = diagram.type ?? "graph";
     const errors = new Array();
     /*  determine the node objects (default: the current object plus
@@ -363,7 +476,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);
     }
@@ -418,15 +531,32 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
                 (edges.some((edge) => edge.source === center) ? 1 : 0);
         }
     }
+    /*  nest the nodes into container nodes (except in a "hub" diagram,
+        where every container would need a primary node of its own),
+        dropping the edges between a container and its own members,
+        which Gradia rejects, as the nesting already shows them  */
+    let nesting = { parentOf: new Map(), containers: new Set() };
+    if (diagram.nest !== undefined) {
+        if (type === "hub")
+            errors.push({ reason: "\"hub\" diagram cannot carry a \"nest\" configuration" });
+        else {
+            nesting = deriveNesting(diagram.nest, nodes, nodeSet, index, parents, parenProps, errors);
+            if (diagram.nest.crossing !== undefined && diagram.nest.crossing !== "nodes")
+                edges = liftEdges(edges, nesting.parentOf, diagram.nest.crossing, anchors);
+            edges = edges.filter((edge) => nesting.parentOf.get(edge.source) !== edge.target
+                && nesting.parentOf.get(edge.target) !== edge.source);
+        }
+    }
     /*  the "onlyConnected" filtering keeps only the nodes with at
-        least one incident edge (sensible for "graph" diagrams only)  */
+        least one incident edge (sensible for "graph" diagrams only),
+        and the container nodes, whose members connect them  */
     if (diagram.onlyConnected === true && type === "graph") {
         const connected = new Set();
         for (const edge of edges) {
             connected.add(edge.source);
             connected.add(edge.target);
         }
-        nodes = nodes.filter((node) => connected.has(node));
+        nodes = nodes.filter((node) => connected.has(node) || nesting.containers.has(node));
     }
     if (errors.length > 0)
         return { errors };
@@ -438,8 +568,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents, parenProps) =>
     if (nodes.length === 0
         || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
         return { errors };
-    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps),
-        config: diagram.config, columns, errors };
+    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps), config: diagram.config, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
     lint validation and every renderer of an export derive the very
@@ -454,8 +583,11 @@ export const specDiagrams = (specification, config) => {
     const index = buildLinkIndex(specification);
     const anchors = anchorPaths(index);
     const parents = new Map();
-    for (const node of index)
+    const positions = new Map();
+    index.forEach((node, position) => {
         parents.set(node.object, node.parent?.object);
+        positions.set(node.object, position);
+    });
     const schemas = collectSchemas(specification, config);
     /*  re-derive the synthetic properties of the consumed parenthesized
         name tokens, as the derivation sees the AST alone, while the
@@ -464,7 +596,7 @@ export const specDiagrams = (specification, config) => {
     const results = new Map();
     for (const [object, schema] of schemas)
         if (schema.diagram !== undefined)
-            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents, parenProps));
+            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, positions, parents, parenProps));
     derivations.set(specification, { config, results });
     return results;
 };

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

@@ -26,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;
         }

package/dst/specbook-export-html.css

@@ -96,6 +96,9 @@ html.theme-light {
   --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);
+  --gradia-color-container-name: var(--theme-color-base-12);
+  --gradia-color-container-box: var(--theme-color-base-31);
+  --gradia-color-container-border: var(--theme-color-base-24);
   --gradia-color-edge-line: var(--theme-color-base-22);
   --gradia-color-edge-name: var(--theme-color-base-5);
   --gradia-color-edge-arity: var(--theme-color-base-5);
@@ -138,6 +141,9 @@ html.theme-light {
     --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);
+    --gradia-color-container-name: var(--theme-color-base-24);
+    --gradia-color-container-box: var(--theme-color-base-4);
+    --gradia-color-container-border: var(--theme-color-base-16);
     --gradia-color-edge-line: var(--theme-color-base-20);
     --gradia-color-edge-name: var(--theme-color-base-29);
     --gradia-color-edge-arity: var(--theme-color-base-29);
@@ -395,6 +401,173 @@ div.info-popup.spec a.link-compact::before {
     display: none;
   }
 }
+/*  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
+    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  */
+div.fold-switch {
+  position: fixed;
+  top: 10.66rem;
+  left: calc(0.6rem - 1px);
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  border-radius: 0 0.3rem 0.3rem 0;
+  color: var(--theme-color-specbook-background);
+  background-color: var(--theme-color-specbook-accent);
+  transition: left 0.3s ease;
+}
+body:has(nav.toc-panel.open) div.fold-switch {
+  left: calc(31rem - 1px);
+  box-shadow: 0.2rem 0 0.6rem rgba(0,0,0,0.3);
+}
+div.fold-switch div.fold-toggle {
+  padding: 0.65rem 0.1rem;
+  line-height: 0;
+  border-radius: 0 0.3rem 0.3rem 0;
+  cursor: pointer;
+}
+div.fold-switch div.fold-toggle:hover {
+  background-color: var(--theme-color-specbook-accent-soft);
+}
+div.fold-switch svg.fold-icon {
+  width: 1.1rem;
+  height: 1.1rem;
+  padding: 0.25rem;
+  border-radius: 0.3rem;
+  margin-right: 0.15rem;
+}
+div.fold-switch.folded svg.fold-icon {
+  color: var(--theme-color-specbook-mark-text);
+  background-color: var(--theme-color-specbook-mark-back);
+}
+div.fold-switch div.fold-controls {
+  display: flex;
+  align-items: center;
+  gap: 0.3rem;
+  overflow: hidden;
+  max-width: 0;
+  padding: 0;
+  transition: max-width 0.3s ease, padding 0.3s ease;
+}
+div.fold-switch.open div.fold-controls {
+  max-width: 6rem;
+  padding: 0 0.5rem 0 0.2rem;
+}
+div.fold-switch div.fold-controls > div {
+  padding: 0.25rem;
+  line-height: 0;
+  border-radius: 0.3rem;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+div.fold-switch div.fold-controls > div:hover {
+  background-color: var(--theme-color-specbook-accent-soft);
+}
+div.fold-switch div.fold-controls > div.folded {
+  color: var(--theme-color-specbook-mark-text);
+  background-color: var(--theme-color-specbook-mark-back);
+}
+div.fold-switch div.fold-controls svg {
+  width: 1.1rem;
+  height: 1.1rem;
+}
+@media print {
+  div.fold-switch {
+    display: none;
+  }
+}
+/*  the folding of the diagrams and the over-long table cells
+    (screen-only): a diagram sits in a fold container carrying a chevron
+    mark in the muted symbol color of the anchors at its top left corner
+    -- in the page margin beside the content, and in the flow left of
+    the diagram inside a table cell, where no margin is left -- while an
+    over-long cell carries its own chevron in a rounded grey box behind
+    the last still shown word; a folded diagram leaves the icon of its
+    tab control behind in the muted color, and a running search unfolds
+    everything, so no match hides inside  */
+div.fold {
+  position: relative;
+}
+span.fold-mark,
+span.fold-more {
+  color: var(--theme-color-specbook-symbol);
+  line-height: 0;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+span.fold-mark:hover,
+span.fold-more:hover {
+  color: var(--theme-color-specbook-accent);
+}
+span.fold-mark {
+  position: absolute;
+  top: 0.35rem;
+  left: -1.15rem;
+}
+span.fold-more {
+  display: inline-block;
+  margin-left: 0.2rem;
+  padding: 0.1rem 0.25rem;
+  vertical-align: -0.05em;
+  border: 1px solid var(--theme-color-specbook-border);
+  border-radius: 0.25rem;
+}
+span.fold-more:hover {
+  border-color: var(--theme-color-specbook-accent);
+}
+span.fold-mark svg,
+span.fold-more svg {
+  width: 0.8rem;
+  height: 0.8rem;
+}
+div.fold.folded > span.fold-mark svg,
+td.folded span.fold-more svg {
+  transform: rotate(-90deg);
+}
+span.fold-label {
+  display: none;
+  line-height: 0;
+  margin-bottom: 1rem;
+  color: var(--theme-color-specbook-muted);
+}
+span.fold-label svg {
+  width: 1.1rem;
+  height: 1.1rem;
+}
+@media screen {
+  td div.fold > span.fold-mark {
+    position: static;
+    display: inline-block;
+    vertical-align: middle;
+    margin-right: 0.3rem;
+  }
+  body:not(.searching) div.fold.folded > span.fold-label {
+    display: block;
+  }
+  body:not(.searching) td div.fold.folded > span.fold-label {
+    display: inline-block;
+    vertical-align: middle;
+    margin-bottom: 0;
+  }
+  body:not(.searching) div.fold.folded > div.diagram,
+  body:not(.searching) td.folded .fold-rest {
+    display: none;
+  }
+}
+@media print {
+  span.fold-mark,
+  span.fold-more {
+    display: none;
+  }
+}
 /*  the connection status tab of the live preview (screen-only): the
     bottommost tab riding right of the brand bar below the table of
     contents tab (sized like the search tab, fixed independent of the
@@ -406,7 +579,7 @@ div.info-popup.spec a.link-compact::before {
     for 2s (toggling every 250ms) after a content reload  */
 div.realtime-status {
   position: fixed;
-  top: 13.89rem;
+  top: 17.12rem;
   left: calc(0.6rem - 2px);
   z-index: 30;
   padding: 0.65rem 0.1rem;
@@ -506,7 +679,7 @@ div.scroll-progress svg.scroll-icon {
     left of the brand bar and to shift it aside when slid out, with its
     tab (a menu icon drawn like the search icon, as none of the bundled
     fonts carries the U+2630 glyph, and sized like the search tab)
-    riding right of the bar below the search tab  */
+    riding right of the bar below the folding tab  */
 nav.toc-panel {
   position: fixed;
   top: 0;
@@ -536,7 +709,7 @@ nav.toc-panel.open div.toc-tab {
 }
 nav.toc-panel div.toc-tab {
   position: absolute;
-  top: 10.66rem;
+  top: 13.89rem;
   left: calc(100% - 1px);
   padding: 0.9rem 0.35rem;
   line-height: 0;
@@ -1042,8 +1215,8 @@ div.titlepage table.meta td {
   text-align: left;
 }
 /*  the fuzzy search tab (screen-only): the middle tab riding right of
-    the brand bar between the info tab and the table of
-    contents tab (as wide as those, fixed independent of the content
+    the brand bar between the info tab and the folding
+    tab (as wide as those, fixed independent of the content
     scrolling), showing the search icon, which slides the input field
     and its clear symbol out to the right (and back in), where the tab
     follows the bar when the table of contents panel shifts it aside

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;