@rse/gradia 1.2.3 → 1.2.4

package/README.md

@@ -269,8 +269,6 @@ following conditions hold:
 - Every edge either points to or originates from that primary node. An
   edge between two non-primary nodes is rejected.
 
-- The primary node carries no self-loop.
-
 - Every non-primary node is an input or an output of the primary node,
   i.e., no node is free-standing.
 
@@ -279,6 +277,11 @@ twice, once in the input column and once in the output column. The second
 placement is rendered as a dashed "ghost" box, colored by the
 `color-node-ghost-*` options.
 
+A self-loop on the primary node is unrolled: the primary node is placed a
+second time on top of the output column, as the target of the self-loop.
+This second placement is rendered as a dashed "self" box, colored by the
+(darker grey) `color-node-self-*` options.
+
 The diagram type `grid` rejects the input with an error as soon as the
 graph contains at least one edge.
 
@@ -304,31 +307,33 @@ command-line options (`font-embed` being command-line only, see below).
 The recognized options, and their default values, are:
 
 ```
-font-family                Helvetica    size-edge-corner-radius    20
-font-embed                 false        size-edge-hop-radius       8
-color-node-regular-name    #336699      size-edge-track-gap        12
-color-node-regular-box     #e0f0ff      size-edge-port-gap         24
-color-node-regular-border  #c0d0e0      group-box-padding          30
-color-node-primary-name    #ffffff      group-box-gap              40
-color-node-primary-box     #336699      container-box-padding      30
-color-node-primary-border  #003366      graph-columns-max          4
-color-node-ghost-name      #666666      graph-channel-width-max    140
-color-node-ghost-box       #f0f0f0      graph-channel-width-min    24
-color-node-ghost-border    #a0a0a0      graph-gutter-height-max    90
-color-group-name           #6699cc      graph-gutter-height-min    20
-color-group-box            #f4f8fc      graph-node-separation      30
-color-group-border         #c0d0e0      graph-rank-separation      60
-color-container-name       #666666      graph-node-degree-max      3
-color-container-box        #f6f6f6      hub-channel-width-max      340
-color-container-border     #a0a0a0      hub-channel-width-min      240
-color-edge-line            #999999      hub-node-gap               20
-color-edge-name            #333333      hub-node-degree-max        3
-color-edge-arity           #333333      grid-columns-max           4
-color-edge-halo            #ffffff      grid-columns-min           3
-size-canvas-margin         40           grid-gap-horizontal        40
-size-node-width-min        220          grid-gap-vertical          20
-size-node-width-max        0            grid-node-width-equal      true
-size-node-height-scale     2.25         grid-node-height-equal     true
+font-family                Helvetica    size-node-height-scale     2.25
+font-embed                 false        size-edge-corner-radius    20
+color-node-regular-name    #336699      size-edge-hop-radius       8
+color-node-regular-box     #e0f0ff      size-edge-track-gap        12
+color-node-regular-border  #c0d0e0      size-edge-port-gap         24
+color-node-primary-name    #ffffff      group-box-padding          30
+color-node-primary-box     #336699      group-box-gap              40
+color-node-primary-border  #003366      container-box-padding      30
+color-node-ghost-name      #666666      graph-columns-max          4
+color-node-ghost-box       #f0f0f0      graph-channel-width-max    140
+color-node-ghost-border    #a0a0a0      graph-channel-width-min    24
+color-node-self-name       #444444      graph-gutter-height-max    90
+color-node-self-box        #e0e0e0      graph-gutter-height-min    20
+color-node-self-border     #707070      graph-node-separation      30
+color-group-name           #6699cc      graph-rank-separation      60
+color-group-box            #f4f8fc      graph-node-degree-max      3
+color-group-border         #c0d0e0      hub-channel-width-max      340
+color-container-name       #666666      hub-channel-width-min      240
+color-container-box        #f6f6f6      hub-node-gap               20
+color-container-border     #a0a0a0      hub-node-degree-max        3
+color-edge-line            #999999      grid-columns-max           4
+color-edge-name            #333333      grid-columns-min           3
+color-edge-arity           #333333      grid-gap-horizontal        40
+color-edge-halo            #ffffff      grid-gap-vertical          20
+size-canvas-margin         40           grid-node-width-equal      true
+size-node-width-min        220          grid-node-height-equal     true
+size-node-width-max        0
 ```
 
 The `size-*`, `group-*`, `container-*`, `graph-*`, `hub-*`, and

package/dst/gradia-api-config.d.ts

@@ -10,6 +10,9 @@ export declare const configDefaults: {
     "color-node-ghost-name": string;
     "color-node-ghost-box": string;
     "color-node-ghost-border": string;
+    "color-node-self-name": string;
+    "color-node-self-box": string;
+    "color-node-self-border": string;
     "color-group-name": string;
     "color-group-box": string;
     "color-group-border": string;

package/dst/gradia-api-config.js

@@ -20,6 +20,9 @@ export const configDefaults = {
     "color-node-ghost-name": "#666666",
     "color-node-ghost-box": "#f0f0f0",
     "color-node-ghost-border": "#a0a0a0",
+    "color-node-self-name": "#444444",
+    "color-node-self-box": "#e0e0e0",
+    "color-node-self-border": "#707070",
     "color-group-name": "#6699cc",
     "color-group-box": "#f4f8fc",
     "color-group-border": "#c0d0e0",
@@ -160,7 +163,7 @@ export const resolveFont = (config) => {
             return { family };
     }
     else if (config["font-embed"])
-        throw new Error("option \"font-embed\" requires option \"font-family\" to be a built-in font " +
+        throw new Error("configuration option \"font-embed\" requires configuration option \"font-family\" to be a built-in font " +
             `family (${Object.keys(fontsBuiltIn).map((name) => `"${name}"`).join(", ")}) ` +
             "or the path to a WOFF2 file");
     else

package/dst/gradia-api-render-base.js

@@ -38,9 +38,9 @@ export const textWrap = (text, size, maxWidth) => {
     lines.push(line);
     return lines;
 };
-/*  escape a string for use in XML/SVG content (control characters are
-    stripped, as XML forbids them even in their escaped form)  */
-export const escapeXML = (text) => text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
+/*  escape a string for use in XML/SVG content (control and non-characters
+    are stripped, as XML forbids them even in their escaped form)  */
+export const escapeXML = (text) => text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\uFFFE\uFFFF\p{Cs}]/gu, "")
     .replace(/&/g, "&")
     .replace(/</g, "&lt;")
     .replace(/>/g, "&gt;")

package/dst/gradia-api-render-container.js

@@ -12,6 +12,7 @@ import { simplifyPoly } from "./gradia-api-render-edge.js";
     container with one of its own members, and every "container"
     annotation has to name a valid diagram type  */
 export const containmentOf = (graph, types) => {
+    /*  collect the parent/children relations of the nodes  */
     const parentOfId = new Map();
     const childrenOf = new Map();
     for (const node of graph.nodes.values()) {
@@ -30,6 +31,7 @@ export const containmentOf = (graph, types) => {
         else
             children.push(node);
     }
+    /*  reject the containment cycles  */
     for (const id of parentOfId.keys()) {
         const seen = new Set([id]);
         for (let p = parentOfId.get(id); p !== undefined; p = parentOfId.get(p)) {
@@ -38,6 +40,7 @@ export const containmentOf = (graph, types) => {
             seen.add(p);
         }
     }
+    /*  reject the edges connecting a container with one of its own members  */
     const isAncestor = (a, id) => {
         for (let p = parentOfId.get(id); p !== undefined; p = parentOfId.get(p))
             if (p === a)
@@ -253,7 +256,7 @@ export const renderContained = async (graph, containment, type, types, config) =
             const tt = topOf(edge.target);
             if (ts === undefined && tt === undefined)
                 return;
-            if (ts !== undefined && tt !== undefined && ts === tt && inner.has(ts) && edge.source !== ts)
+            if (ts !== undefined && ts === tt && inner.has(ts) && edge.source !== ts)
                 return;
             let source;
             let target;

package/dst/gradia-api-render-edge.js

@@ -18,7 +18,8 @@ export const simplifyPoly = (pts) => {
     /*  drop the remaining duplicate points  */
     const out = [];
     for (const p of flat) {
-        if (out.length > 0 && out[out.length - 1][0] === p[0] && out[out.length - 1][1] === p[1])
+        const q = out.at(-1);
+        if (q !== undefined && q[0] === p[0] && q[1] === p[1])
             continue;
         out.push(p);
     }
@@ -70,10 +71,11 @@ export const assignPorts = (edges, sides, cx, cy, boxW, boxH, portGap, approachY
         const px = cx(id) + (side === "e" ? +1 : -1) * boxW.get(id) / 2;
         /*  place the fixed ports at their given offsets  */
         const fixedOf = (p) => fixedY?.(p.edge, p.role);
+        const place = (p, py) => portPos.set(`${p.edge}:${p.role}`, { x: px, y: py });
         const taken = [];
         for (const p of group.filter((p) => fixedOf(p) !== undefined)) {
             const py = cy(id) + fixedOf(p);
-            portPos.set(`${p.edge}:${p.role}`, { x: px, y: py });
+            place(p, py);
             taken.push(py);
         }
         taken.sort((a, b) => a - b);
@@ -86,7 +88,6 @@ export const assignPorts = (edges, sides, cx, cy, boxW, boxH, portGap, approachY
         free.sort((a, b) => (keyOf(a) - keyOf(b)) || (a.edge - b.edge));
         const n = free.length + taken.length;
         const spacing = Math.min(portGap, (boxH.get(id) - PORT_PAD) / n);
-        const place = (p, py) => portPos.set(`${p.edge}:${p.role}`, { x: px, y: py });
         if (taken.length === 0) {
             free.forEach((p, idx) => place(p, cy(id) + (idx - (n - 1) / 2) * spacing));
             continue;
@@ -348,15 +349,15 @@ export const pathOf = (poly, hop, rounding, hopRadius) => {
                 their individual hops would be shorter than 14px)  */
             const groups = [];
             for (const hx of xs) {
-                const g = groups[groups.length - 1];
-                if (g !== undefined && Math.abs(hx - g[g.length - 1]) <= hopRadius * 2 + 14)
+                const g = groups.at(-1);
+                if (g !== undefined && Math.abs(hx - g.at(-1)) <= hopRadius * 2 + 14)
                     g.push(hx);
                 else
                     groups.push([hx]);
             }
             for (const g of groups) {
                 let x1 = g[0] - dir * hopRadius;
-                let x2 = g[g.length - 1] + dir * hopRadius;
+                let x2 = g.at(-1) + dir * hopRadius;
                 /*  clamp the arc into the drawable segment part, so
                     crossings close to a corner still get their hop  */
                 if ((x1 - p0[0]) * dir < 0)

package/dst/gradia-api-render-group.js

@@ -17,9 +17,11 @@ export const groupOf = (node) => node.attrs.findLast((attr) => attr.key === "gro
     deviating group of its own. Edges have to stay within a single
     group, so reject any group-crossing edge  */
 export const partitionGroups = (graph, containment) => {
+    /*  short-circuit when no node uses a group at all  */
     const nodes = Array.from(graph.nodes.values());
     if (!nodes.some((node) => groupOf(node) !== undefined))
         return null;
+    /*  assign every node to the group of its outermost container  */
     const parts = new Map();
     const nameOf = new Map();
     for (const node of nodes) {
@@ -37,6 +39,7 @@ export const partitionGroups = (graph, containment) => {
         }
         part.nodes.set(node.id, node);
     }
+    /*  assign every edge to the common group of its endpoints  */
     for (const edge of graph.edges) {
         const sg = nameOf.get(edge.source);
         const tg = nameOf.get(edge.target);
@@ -45,6 +48,7 @@ export const partitionGroups = (graph, containment) => {
                 `crosses groups "${sg}" and "${tg}"`);
         parts.get(sg).edges.push(edge);
     }
+    /*  provide the partitions in order of first appearance  */
     return Array.from(parts.entries()).map(([name, subgraph]) => ({ name, graph: subgraph }));
 };
 /*  compose the per-group layouts into a single layout: the groups are

package/dst/gradia-api-render-node.js

@@ -79,12 +79,11 @@ export const linesOfNode = (node, config) => {
         attrs: attrsOfNode(node).flatMap((attr) => textWrap(`${attr.key}: ${attr.val}`, FS_ATTR, max))
     };
 };
-/*  determine node box sizes from their textual content
-    (boxes are scaled up in height by a per-node factor, but never
-    below the content height, to give the edges more attachment
-    room), except for the nodes
-    of a fixed size (the container placeholders and gate nodes
-    of a containment level), which are taken as given  */
+/*  determine node box sizes from their textual content (boxes are
+    scaled up in height by a per-node factor, but never below the
+    content height, to give the edges more attachment room), except
+    for the nodes of a fixed size (the container placeholders and gate
+    nodes of a containment level), which are taken as given  */
 export const measureNodes = (nodes, config, scaleOf, fixed) => {
     /*  the resulting node box dimensions  */
     const boxW = new Map();

package/dst/gradia-api-render-svg.js

@@ -66,12 +66,12 @@ const labelPlacer = (layout, hops, hopRadius) => {
     const collisions = (boxes, box) => boxes.filter((o) => box[0] < o[2] && box[2] > o[0] && box[1] < o[3] && box[3] > o[1]).length;
     const claim = (candidates) => {
         let box = candidates[0];
-        let worst = Infinity;
+        let lowest = Infinity;
         for (const c of candidates) {
             const score = collisions(occupied, c) * (lines.length + 1) + collisions(lines, c);
-            if (score < worst) {
+            if (score < lowest) {
                 box = c;
-                worst = score;
+                lowest = score;
             }
             if (score === 0)
                 break;

package/dst/gradia-api-type-graph.js

@@ -26,6 +26,7 @@ const NUDGE_PASSES = 3; /*  max number of node nudging passes
 /*  snap raw node positions onto a discrete grid by clustering the
     distinct X coordinates into columns and Y coordinates into rows  */
 const snapToGrid = (nodes, rawX, rawY) => {
+    /*  cluster the distinct values into representatives more than a threshold apart  */
     const cluster = (values, threshold) => {
         const sorted = Array.from(new Set(values)).sort((a, b) => a - b);
         const reps = [];
@@ -36,6 +37,7 @@ const snapToGrid = (nodes, rawX, rawY) => {
     };
     const colReps = cluster(nodes.map((node) => rawX.get(node.id)), CLUSTX);
     const rowReps = cluster(nodes.map((node) => rawY.get(node.id)), CLUSTY);
+    /*  determine the index of the representative nearest to a value  */
     const nearestIndexOf = (reps, v) => {
         let best = 0;
         for (let i = 1; i < reps.length; i++)
@@ -304,7 +306,7 @@ const planRoutes = (edges, col, row, sides, gates) => {
             chanNeed(plan.chans[0], textWidth(name, FS_EDGE) + 2 * CHAN_LBL);
         else if (name !== undefined && plan.guts.length > 0)
             gutLbl.set(plan.guts[0], (gutLbl.get(plan.guts[0]) ?? 0) + 1);
-        if (arity !== undefined && chans.length > 0)
+        if (arity !== undefined)
             chanNeed(chans[chans.length - 1], ARITY_OFF + textWidth(arity, FS_ARITY) + CHAN_LBL);
     });
     /*  count the self-loops of every node, as their detours stack up
@@ -375,8 +377,6 @@ const assignTrackCoords = (edges, plans, portPos, grid, config) => {
     const chanUsers = new Map();
     edges.forEach((edge, i) => {
         const { chans, guts, flags, gate } = plans[i];
-        if (chans.length === 0)
-            return;
         const sp = portPos.get(`${i}:s`);
         const tp = portPos.get(`${i}:t`);
         if (edge.source === edge.target)
@@ -433,7 +433,7 @@ const routePolys = (edges, plans, portPos, boxH, cy, chanX, gutY) => {
     return edges.map((edge, i) => {
         const sp = portPos.get(`${i}:s`);
         const tp = portPos.get(`${i}:t`);
-        const { chans, guts, flags } = plans[i];
+        const { chans, guts, flags, gate } = plans[i];
         let pts;
         if (edge.source === edge.target) {
             /*  route the self-loop counter-clockwise around the top-right
@@ -460,9 +460,9 @@ const routePolys = (edges, plans, portPos, boxH, cy, chanX, gutY) => {
             const ch1 = chanX(chans[0], i);
             const ch2 = chanX(chans[1], i);
             const gy = gutY(guts[0], i);
-            if (plans[i].gate === "t")
+            if (gate === "t")
                 pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [tp.x, gy]];
-            else if (plans[i].gate === "s")
+            else if (gate === "s")
                 pts = [[sp.x, gy], [ch2, gy], [ch2, tp.y], [tp.x, tp.y]];
             else
                 pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [ch2, gy], [ch2, tp.y], [tp.x, tp.y]];
@@ -499,11 +499,13 @@ const routeEdges = (edges, plans, sides, boxW, boxH, cx, cy, grid, config, level
     rises above the box of its node), and only as long as its own
     gutter-routed edges keep approaching it from their gutter side  */
 const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route) => {
+    /*  whether neither a gutter track nor a self-loop detour crosses a column within a gutter  */
     const gutterFree = (g, c) => !plans.some((plan) => plan.guts[0] === g
         && Math.min(...plan.chans) < c
         && c <= Math.max(...plan.chans) + (plan.gate === "t" ? 1 : 0))
         && !edges.some((edge) => edge.source === edge.target
             && row.get(edge.source) === g + 1 && col.get(edge.source) === c);
+    /*  the vertical shift range of a node: its row slack plus the room of its free adjacent gutters  */
     const shiftRange = (id) => {
         const r = row.get(id);
         const c = col.get(id);
@@ -512,6 +514,7 @@ const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route)
         const down = r < nrows - 1 && gutterFree(r, c) ? grid.gutH[r] - GUT_H0 : 0;
         return [-(slack + up), slack + down];
     };
+    /*  whether the gutter-routed edges of a node still approach it from their gutter side  */
     const approachesSanely = (id, routing) => edges.every((edge, i) => {
         const role = edge.source === id ? "s" : edge.target === id ? "t" : null;
         if (role === null || plans[i].guts.length === 0)
@@ -520,6 +523,7 @@ const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route)
         const gap = routing.portPos.get(`${i}:${role}`).y - routing.gutY(g, i);
         return row.get(id) > g ? gap >= NUDGE_GAP : gap <= -NUDGE_GAP;
     });
+    /*  rank the routings: fewer crossings first, then fewer jogged direct same-row edges  */
     const direct = edges.map((edge, i) => plans[i].chans.length === 1
         && !plans[i].flags[0].hairpin
         && row.get(edge.source) === row.get(edge.target));

package/dst/gradia-api-type-grid.js

@@ -10,6 +10,7 @@ import { measureNodes, orderOf } from "./gradia-api-render-node.js";
     declaration order, or in the order of their "order" attributes
     (the tiles without one trailing)  */
 export const render = async (graph, config, level = {}) => {
+    /*  determine the tiles in their rendering order  */
     const nodes = Array.from(graph.nodes.values())
         .sort((a, b) => (orderOf(a) ?? Infinity) - (orderOf(b) ?? Infinity) || 0);
     /*  resolve the configurable rendering geometry  */
@@ -39,7 +40,7 @@ export const render = async (graph, config, level = {}) => {
         if (config["grid-node-width-equal"])
             boxW.set(node.id, tileW);
     }
-    /*  place the nodes in declaration order onto a roughly square,
+    /*  place the nodes in their rendering order onto a roughly square,
         row-major grid (raised to the configured minimum of columns, so
         few nodes still share a row, and capped at the configured maximum
         of columns and the node count, so larger graphs grow only in

package/dst/gradia-api-type-hub.js

@@ -6,7 +6,8 @@
 import { isPrimary, measureNodes, defaultStyleOf } from "./gradia-api-render-node.js";
 import { simplifyPoly, assignPorts, assignTracks } from "./gradia-api-render-edge.js";
 /*  the separator between a node id and its placement suffix,
-    distinguishing the two clones of a twice-placed node  */
+    distinguishing the two clones of a twice-placed node and the
+    output clone of a self-referencing primary node  */
 const CLONE = "\u0000";
 /*  rendering geometry constants  */
 const CHAN_W1 = 28; /*  width of a one-edge inter-column channel  */
@@ -18,8 +19,10 @@ const CHAN_PAD = 16; /*  cross-axis padding inside a channel       */
     (edges originate from the primary); a node referenced in both
     directions is placed twice, once in the input column and once in
     the output column, with its edges rewritten to attach to the
-    corresponding placement  */
+    corresponding placement. A self-loop on the primary is unrolled
+    likewise, onto a clone of the primary in the output column  */
 const classifyTopology = (graph) => {
+    /*  determine the primary node and the ids of its input and output nodes  */
     const declared = Array.from(graph.nodes.values());
     for (const node of declared)
         if (node.id.includes(CLONE))
@@ -30,9 +33,10 @@ const classifyTopology = (graph) => {
     const center = primaries[0];
     const inSet = new Set();
     const outSet = new Set();
+    let selfLoop = false;
     for (const edge of graph.edges) {
         if (edge.source === center.id && edge.target === center.id)
-            throw new Error(`self-loop on primary node "${center.id}" not supported`);
+            selfLoop = true;
         else if (edge.target === center.id)
             inSet.add(edge.source);
         else if (edge.source === center.id)
@@ -61,9 +65,16 @@ const classifyTopology = (graph) => {
         else
             outputs.push(node);
     }
+    /*  place the clone of a self-referencing primary node (stripped of
+        its "primary" annotation) on top of the output column  */
+    if (selfLoop)
+        outputs.unshift({ ...center, id: center.id + CLONE + "self",
+            attrs: center.attrs.filter((attr) => attr.key !== "primary") });
     /*  rewrite the edges of the twice-placed nodes onto their clones  */
     const edges = graph.edges.map((edge) => {
-        if (edge.target === center.id && dual.has(edge.source))
+        if (edge.source === center.id && edge.target === center.id)
+            return { ...edge, target: edge.target + CLONE + "self" };
+        else if (edge.target === center.id && dual.has(edge.source))
             return { ...edge, source: edge.source + CLONE + "in" };
         else if (edge.source === center.id && dual.has(edge.target))
             return { ...edge, target: edge.target + CLONE + "out" };
@@ -195,12 +206,19 @@ export const render = async (graph, config, level = {}) => {
     });
     /*  hand over the laid out graph for SVG rendering (the output copy
         of a twice-placed node is rendered as a dashed grey "ghost" box,
-        all other boxes get the default primary/regular coloring)  */
+        the output clone of a self-referencing primary node as a dashed,
+        darker grey "self" box, and all other boxes get the default
+        primary/regular coloring)  */
     const styleOf = (node) => node.id.endsWith(CLONE + "out") ? {
         fill: "color-node-ghost-box",
         stroke: "color-node-ghost-border",
         text: "color-node-ghost-name",
         dash: "10 6"
+    } : node.id.endsWith(CLONE + "self") ? {
+        fill: "color-node-self-box",
+        stroke: "color-node-self-border",
+        text: "color-node-self-name",
+        dash: "10 6"
     } : defaultStyleOf(node);
     return { nodes, edges, cx, cy, boxW, boxH, contentH, polys, styleOf };
 };

package/dst/gradia-api.js

@@ -122,7 +122,7 @@ export class Gradia {
     static async render(spec, options = {}) {
         const graph = Gradia.parse(spec);
         const type = options.type ?? parseTypeDirective(spec);
-        const config = { ...parseDirectives(spec), ...(options.config ?? {}) };
+        const config = { ...parseDirectives(spec), ...validateConfig(options.config ?? {}, { trusted: true }) };
         return Gradia.generate(graph, { ...options, type, config });
     }
 }