@rse/specbook 1.2.3 → 1.2.5

package/dst/specbook-export-pdf.js

@@ -28,7 +28,7 @@ const anchorPages = async (pdf) => {
 };
 /*  attach a hierarchical PDF outline (the "bookmarks" of the viewer
     side-bar) to a document, resolving the entry anchors against the
-    named destinations and hoisting the childs of an unresolvable entry  */
+    named destinations and hoisting the children of an unresolvable entry  */
 const addOutline = async (doc, entries) => {
     const { PDFName, PDFDict, PDFArray, PDFRef, PDFHexString } = await import("pdf-lib");
     const context = doc.context;
@@ -48,8 +48,8 @@ const addOutline = async (doc, entries) => {
     }
     const resolve = (entries) => entries.flatMap((entry) => {
         const dest = targets.get(entry.anchor);
-        const childs = resolve(entry.childs);
-        return dest !== undefined ? [{ title: entry.title, dest, childs }] : childs;
+        const children = resolve(entry.children);
+        return dest !== undefined ? [{ title: entry.title, dest, children }] : children;
     });
     const items = resolve(entries);
     if (items.length === 0)
@@ -59,16 +59,16 @@ const addOutline = async (doc, entries) => {
     const materialize = (items, parent) => {
         const refs = items.map(() => context.nextRef());
         items.forEach((item, i) => {
-            const childs = item.childs.length > 0 ? materialize(item.childs, refs[i]) : undefined;
+            const children = item.children.length > 0 ? materialize(item.children, refs[i]) : undefined;
             context.assign(refs[i], context.obj({
                 Title: PDFHexString.fromText(item.title),
                 Parent: parent,
                 Prev: i > 0 ? refs[i - 1] : undefined,
                 Next: i < refs.length - 1 ? refs[i + 1] : undefined,
-                First: childs?.first,
-                Last: childs?.last,
+                First: children?.first,
+                Last: children?.last,
                 /*  a negative count keeps the sub-tree initially collapsed  */
-                Count: childs !== undefined ? -item.childs.length : undefined,
+                Count: children !== undefined ? -item.children.length : undefined,
                 Dest: item.dest
             }));
         });
@@ -133,11 +133,36 @@ const drawBrandBar = async (doc, accent) => {
     Chrome has to actually launch it and as the export preflight and the
     renderer both ask for the very same browser  */
 let browserOptions;
-/*  resolve the browser printing the PDF: the downloaded Playwright
-    Chromium is a plain file check, while a system-installed Google
-    Chrome is only detectable by launching it  */
+/*  the remedy of an unavailable Playwright Chromium, shared by the
+    fallback notice and the missing-browser error, as both have to point
+    at the very same one-time command  */
+const chromiumRemedy = `run "${literal("npx playwright install chromium")}" once to download the Playwright Chromium`;
+/*  resolve the browser printing the PDF: an explicitly configured one
+    wins, then the downloaded Playwright Chromium as a plain file check,
+    while a system-installed Google Chrome is only detectable by
+    launching it  */
 const resolveBrowser = async (verbose) => {
     const { chromium } = await import("playwright");
+    /*  an explicitly configured browser is taken as an executable path
+        once it carries a path separator and as a Playwright channel
+        name otherwise, and it never falls back onto another browser, as
+        an explicit choice has to be either honored or reported  */
+    const configured = process.env.SPECBOOK_BROWSER ?? "";
+    if (configured !== "") {
+        const options = /[\\/]/.test(configured) ?
+            { executablePath: configured } : { channel: configured };
+        try {
+            const browser = await chromium.launch(options);
+            await browser.close();
+        }
+        catch (err) {
+            throw new Error(`the browser "${literal(configured)}" configured by ` +
+                `"${literal("SPECBOOK_BROWSER")}" failed to launch`, { cause: err });
+        }
+        verbose(`using the browser "${literal(configured)}" configured by ` +
+            `"${literal("SPECBOOK_BROWSER")}"`);
+        return options;
+    }
     let executable = "";
     try {
         executable = chromium.executablePath();
@@ -151,7 +176,7 @@ const resolveBrowser = async (verbose) => {
         const chrome = await chromium.launch({ channel: "chrome" });
         await chrome.close();
         verbose("Playwright Chromium unavailable -- falling back to the " +
-            "system-installed Google Chrome", "notice");
+            `system-installed Google Chrome (${chromiumRemedy})`, "notice");
         return { channel: "chrome" };
     }
     catch {
@@ -166,8 +191,7 @@ export const requireBrowser = async (verbose) => {
     const options = await browserOptions;
     if (options === undefined)
         throw new Error("the PDF export requires a Chromium-class browser, but neither the " +
-            "Playwright Chromium nor a system-installed Google Chrome was found -- run " +
-            `"${literal("npx playwright install chromium")}" once to download the Playwright Chromium`);
+            `Playwright Chromium nor a system-installed Google Chrome was found -- ${chromiumRemedy}`);
     return options;
 };
 /*  the bound of the ToC page number fixpoint iteration, as the page

package/dst/specbook-format-schema.d.ts

@@ -14,7 +14,7 @@ export type SchemaObject = {
     diagram?: SchemaDiagram;
     format?: SchemaFormat;
     props?: SchemaProperty[];
-    childs?: SchemaObject[];
+    children?: SchemaObject[];
 };
 export type SchemaAutomaton = {
     nodes: string;
@@ -37,6 +37,13 @@ export type SchemaDiagramCenterEdges = {
     both?: string;
     labeled?: string;
 };
+export type SchemaDiagramNest = {
+    properties?: string[];
+    parent?: boolean;
+    kind?: boolean;
+    layout?: "graph" | "hub" | "grid";
+    crossing?: "nodes" | "target" | "both";
+};
 export type SchemaDiagram = {
     type?: "graph" | "hub" | "grid";
     nodes?: string;
@@ -53,12 +60,15 @@ export type SchemaDiagram = {
     onlyConnected?: boolean;
     collapse?: boolean;
     qualified?: boolean;
+    ordered?: boolean;
+    nest?: SchemaDiagramNest;
     properties?: string[];
     config?: Partial<GradiaConfig>;
 };
 export type SchemaFormat = {
     type?: "auto" | "complex" | "concise";
     maxTableColumns?: number;
+    maxCellHeight?: number;
     withUnusedProps?: boolean;
 };
 export type SchemaProperty = {

package/dst/specbook-format-schema.js

@@ -17,7 +17,7 @@ const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map
 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  */
+    kind schema referencing itself lazily for the nested children  */
 const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),
@@ -50,6 +50,13 @@ const SchemaDiagramCenterEdges = v.strictObject({
     both: v.optional(v.string()),
     labeled: v.optional(v.string())
 });
+const SchemaDiagramNest = v.strictObject({
+    properties: v.optional(v.array(v.string())),
+    parent: v.optional(v.boolean()),
+    kind: v.optional(v.boolean()),
+    layout: v.optional(v.picklist(["graph", "hub", "grid"])),
+    crossing: v.optional(v.picklist(["nodes", "target", "both"]))
+});
 const SchemaDiagram = v.strictObject({
     type: v.optional(v.picklist(["graph", "hub", "grid"])),
     nodes: v.optional(v.string()),
@@ -66,12 +73,15 @@ const SchemaDiagram = v.strictObject({
     onlyConnected: v.optional(v.boolean()),
     collapse: v.optional(v.boolean()),
     qualified: v.optional(v.boolean()),
+    ordered: v.optional(v.boolean()),
+    nest: v.optional(SchemaDiagramNest),
     properties: v.optional(v.array(v.string())),
     config: v.optional(SchemaDiagramConfig)
 });
 const SchemaFormat = v.strictObject({
     type: v.optional(v.picklist(["auto", "complex", "concise"])),
     maxTableColumns: v.optional(v.pipe(v.number(), v.integer(), v.minValue(2))),
+    maxCellHeight: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
     withUnusedProps: v.optional(v.boolean())
 });
 const SchemaObject = v.strictObject({
@@ -87,6 +97,6 @@ const SchemaObject = v.strictObject({
     diagram: v.optional(SchemaDiagram),
     format: v.optional(SchemaFormat),
     props: v.optional(v.array(SchemaProperty)),
-    childs: v.optional(v.array(v.lazy(() => SchemaObject)))
+    children: v.optional(v.array(v.lazy(() => SchemaObject)))
 });
 export const Schema = v.pipe(v.array(SchemaObject), v.minLength(1));

package/dst/specbook-format-spec.d.ts

@@ -16,7 +16,7 @@ export type SpecObject = {
     primary?: boolean;
     description?: SpecDescription;
     properties: SpecProperty[];
-    childs: SpecObject[];
+    children: SpecObject[];
 };
 export type SpecDescription = {
     description: string;

package/dst/specbook-format-spec.js

@@ -6,7 +6,7 @@
 import * as v from "valibot";
 /*  ==== Schema ====  */
 /*  the Valibot schemas mirroring the types above, with the object
-    schema referencing itself lazily for the nested childs  */
+    schema referencing itself lazily for the nested children  */
 const SpecProperty = v.object({
     key: v.string(),
     value: v.string(),
@@ -26,7 +26,7 @@ const SpecObject = v.object({
     primary: v.optional(v.boolean()),
     description: v.optional(SpecDescription),
     properties: v.array(SpecProperty),
-    childs: v.array(v.lazy(() => SpecObject))
+    children: v.array(v.lazy(() => SpecObject))
 });
 const SpecArtifact = v.object({
     created: v.date(),

package/dst/specbook-format.md

@@ -78,7 +78,7 @@ type SchemaObject = {
     diagram?:          SchemaDiagram
     format?:           SchemaFormat
     props?:            SchemaProperty[]
-    childs?:           SchemaObject[]
+    children?:         SchemaObject[]
 }
 type SchemaAutomaton = {
     nodes:             string
@@ -123,6 +123,7 @@ type SchemaDiagram = {
 type SchemaFormat = {
     type?:             "auto" | "complex" | "concise"
     maxTableColumns?:  number
+    maxCellHeight?:    number
     withUnusedProps?:  boolean
 }
 type SchemaProperty = {
@@ -251,7 +252,7 @@ type SchemaGradiaConfig = Partial<{
     properties allowed on objects of this kind,
     BECAUSE they carry the structured, machine-checkable content
 
--   `SchemaObject.childs?: SchemaObject[]`:
+-   `SchemaObject.children?: SchemaObject[]`:
     object kinds allowed one level below this object (RECURSION),
     BECAUSE the nesting defines and bounds the document structure
 
@@ -350,7 +351,7 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaDiagram.deep?: boolean`:
     whether the references of the descendants of a node count as its own,
-    lifted to their nearest node and counted as the arity (default: `false`),
+    counted as the arity (default: `false`),
     BECAUSE the relations between coarse objects live in their fine parts
 
 -   `SchemaDiagram.onlyConnected?: boolean`:
@@ -365,6 +366,40 @@ type SchemaGradiaConfig = Partial<{
     whether every node is labeled with its kind (default: `false`),
     BECAUSE names alone are ambiguous across multiple object kinds
 
+-   `SchemaDiagram.ordered?: boolean`:
+    whether the nodes are placed in document order instead of by the
+    layered layout, the top-level ones stacked top-down and the members
+    of a container lined up left-to-right (default: `false`),
+    BECAUSE in a coarse-to-fine specification the references then all
+    point backward, i.e. upward
+
+-   `SchemaDiagram.nest?: SchemaDiagramNest`:
+    nesting of the nodes into container nodes,
+    BECAUSE a containment drawn as a box beats one drawn as an edge
+
+-   `SchemaDiagramNest.properties?: string[]`:
+    properties whose single referenced object is the container of a node,
+    BECAUSE a `PART-OF` or `TIER` reference is a containment, not a relation
+
+-   `SchemaDiagramNest.parent?: boolean`:
+    whether the parent object is the container of a node (default: `false`),
+    BECAUSE the nesting of the objects is a containment, too
+
+-   `SchemaDiagramNest.kind?: boolean`:
+    whether a synthetic container per object kind holds the nodes
+    (default: `false`),
+    BECAUSE a kind is a grouping no object models
+
+-   `SchemaDiagramNest.layout?: "graph" | "hub" | "grid"`:
+    shape the members of every container are laid out with
+    (default: the diagram type),
+    BECAUSE the inside of a container may tell a different story than the whole
+
+-   `SchemaDiagramNest.crossing?: "nodes" | "target" | "both"`:
+    ends of a boundary-crossing edge lifted onto the containers
+    (default: `nodes`, i.e. none),
+    BECAUSE a bundle of references into a container reads as one edge onto it
+
 -   `SchemaDiagram.properties?: string[]`:
     property names attached to the nodes as key/value annotations,
     BECAUSE the node name alone rarely makes the nodes comparable
@@ -385,6 +420,10 @@ type SchemaGradiaConfig = Partial<{
     maximum column count of the table of the kind (default: `4`),
     BECAUSE the fixed print/PDF page width bounds the table width
 
+-   `SchemaFormat.maxCellHeight?: number`:
+    percent a table cell may tower over its row before it folds (default: `40`),
+    BECAUSE a cell of rich prose otherwise dwarfs the whole table
+
 -   `SchemaFormat.withUnusedProps?: boolean`:
     whether unused properties still render (default: `false`),
     BECAUSE empty entries are noise, unless the gap is the message
@@ -474,9 +513,10 @@ type SchemaGradiaConfig = Partial<{
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
-descriptions as well. With `deep: true` the references of all
-descendants of a node object count as its own, every referenced object
-is lifted to its nearest ancestor-or-self within the node set, and the
+descriptions as well. Every referenced object is lifted to its nearest
+ancestor-or-self within the node set, so a reference onto the scenario
+of a use case yields an edge onto the use case. With `deep: true` the
+references of all descendants of a node object count as its own and the
 number of references behind an edge becomes its arity, so a diagram of
 coarse objects (like the artifacts of a whole specification) shows the
 relations living in their fine-grained parts. With `labeled: true` an
@@ -527,6 +567,34 @@ nodes as key/value annotations (with every `[[xxx]]` reference stripped
 to its target object name), and `config` passes arbitrary Gradia
 rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
 
+`ordered` replaces the layered layout of a `graph` by the document
+order of the objects: the top-level nodes stack top-down in that order
+(a synthetic container at the position of its first member), while the
+members of a container line up left-to-right in it, wrapped by the
+Gradia option `graph-columns-max`, so the references of a coarse-to-fine
+specification all point backward, i.e. upward or leftward.
+
+`nest` nests the nodes into *container* nodes, drawn as boxes around
+their members with the edges crossing the box borders: the first of its
+`properties` carrying exactly one resolvable reference names the
+container of a node (a container outside the node set is added to it,
+labeled and linked like a node, and nested on its own in turn, so a
+`NODE` sits in its `TIER` and the tier in the tier it is `PART-OF`),
+else with `parent: true` the parent object is the container when part
+of the node set, else with `kind: true` a synthetic container per object
+kind is. An edge between a container and one of its own members is
+dropped, as the nesting already shows it, `layout` selects the shape
+the members of every container are laid out with (default: the diagram
+type), a `hub` carries no containers, as every container would need a
+primary node of its own, and a node nested into itself or into a cycle
+is reported. With `crossing: target` an edge crossing a container
+boundary ends at the outermost container of its target not enclosing
+its source, too, and with `crossing: both` it also starts at the
+corresponding container of its source, where the edges coinciding
+afterwards merge into one with their arities summed, so the edges
+inside a container stay node-to-node while the bundles of references
+into a container become single edges onto it.
+
 ### Format
 
 An object kind can furthermore carry a `format` field, which controls
@@ -542,7 +610,10 @@ Inside a `concise` table, unconfigured child kinds implicitly stay
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
 the columns of the compact table of the kind (a wider group chunks
-its properties into embedded per-object tables), and `withUnusedProps`
+its properties into embedded per-object tables), `maxCellHeight`
+(default: `40`) is the percentage a table cell of the kind may exceed
+the height of every other non-empty cell of its row before the HTML
+export folds its remaining text away, and `withUnusedProps`
 (default: `false`) unconditionally renders the defined but unused
 properties of that kind, as property table lines or table columns. In
 the HTML/PDF export, a property absent from an object shows an "empty
@@ -579,7 +650,7 @@ type SpecObject = {
     primary?:          boolean
     description?:      SpecDescription
     properties:        SpecProperty[]
-    childs:            SpecObject[]
+    children:          SpecObject[]
 }
 type SpecDescription = {
     description:       string
@@ -653,7 +724,7 @@ type SpecProperty = {
     key/value properties of the object, in canonical order,
     BECAUSE properties carry the structured, machine-checkable content
 
--   `SpecObject.childs: SpecObject[]`:
+-   `SpecObject.children: SpecObject[]`:
     child objects nested one level below this object (RECURSION),
     BECAUSE a specification is a tree, not a flat list of statements