@rse/gradia 0.9.8 → 1.0.0

package/README.md

@@ -24,6 +24,23 @@ graphs:
   output nodes.
 - `grid`: a compact grid of tiles for an edge-less graph.
 
+Examples
+--------
+
+Here are examples of the three graph diagram renderings:
+
+- [broadcast-graph](smp/broadcast-graph.txt):
+
+  ![broadcast-graph](smp/broadcast-graph.svg)
+
+- [broadcast-hub](smp/broadcast-hub.txt):
+
+  ![broadcast-hub](smp/broadcast-hub.svg)
+
+- [broadcast-grid](smp/broadcast-grid.txt):
+
+  ![broadcast-grid](smp/broadcast-grid.svg)
+
 Playground
 ----------
 
@@ -179,7 +196,9 @@ separated by `|`.
 - Four attribute keys are reserved and consumed by the renderer instead
   of being displayed as a regular `<key>: <val>` line:
 
-    - `url: <url>` renders the node box as a hyperlink,
+    - `url: <url>` renders the node box as a hyperlink. Only relative URLs
+      and the schemes `http`, `https`, and `mailto` are honored; any other
+      URL is silently dropped and the node box then simply stays unlinked,
     - `type: <name>` renders `<name>` as a smaller text above the node
       label inside the node box,
     - `primary: true` renders the node in the primary node colors
@@ -195,6 +214,38 @@ separated by `|`.
 - All remaining attributes are displayed as `<key>: <val>` lines inside
   the node box.
 
+### Diagram Type Constraints
+
+The diagram type `graph` imposes no constraints on the topology: it
+accepts self-loops and free-standing nodes alike, and hence is the safe
+choice whenever the topology is not known to fit `hub` or `grid`.
+
+The diagram type `hub` rejects the input with an error unless all of the
+following conditions hold:
+
+- Exactly one node carries the attribute `primary: true`.
+
+- 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.
+
+A node which is both an input and an output of the primary node is placed
+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.
+
+The diagram type `grid` rejects the input with an error as soon as the
+graph contains at least one edge.
+
+As the groups of a grouped graph are laid out individually with the
+selected diagram type, these constraints apply to every single group. For
+the type `hub` this especially means that every group needs its own
+primary node.
+
 ### Directives
 
 A `#type` directive sets the diagram type (`graph`, `hub`, or `grid`),
@@ -204,28 +255,30 @@ type is silently ignored. Without both, the type defaults to `graph`.
 
 A `#config` directive sets one of the rendering options, which otherwise
 are settable through the corresponding `--config <option>=<value>`
-command-line options. The recognized options are:
+command-line options (`font-embed` being command-line only, see below).
+The recognized options are:
 
 ```
-font-family                  color-edge-line              graph-columns-max
-color-node-regular-name      color-edge-name              graph-channel-width-max
-color-node-regular-box       color-edge-arity             graph-gutter-height-max
-color-node-regular-border    color-edge-halo              graph-node-separation
-color-node-primary-name      size-canvas-margin           graph-rank-separation
-color-node-primary-box       size-node-width-min          graph-node-degree-max
-color-node-primary-border    size-node-width-max          hub-channel-width-max
-color-node-ghost-name        size-node-height-scale       hub-channel-width-min
-color-node-ghost-box         size-edge-corner-radius      hub-node-gap
-color-node-ghost-border      size-edge-hop-radius         hub-node-degree-max
-color-group-name             size-edge-track-gap          grid-columns-max
-color-group-box              group-box-padding            grid-gap-horizontal
-color-group-border           group-box-gap                grid-gap-vertical
+font-family                  color-edge-line              graph-channel-width-max
+font-embed                   color-edge-name              graph-gutter-height-max
+color-node-regular-name      color-edge-arity             graph-node-separation
+color-node-regular-box       color-edge-halo              graph-rank-separation
+color-node-regular-border    size-canvas-margin           graph-node-degree-max
+color-node-primary-name      size-node-width-min          hub-channel-width-max
+color-node-primary-box       size-node-width-max          hub-channel-width-min
+color-node-primary-border    size-node-height-scale       hub-node-gap
+color-node-ghost-name        size-edge-corner-radius      hub-node-degree-max
+color-node-ghost-box         size-edge-hop-radius         grid-columns-max
+color-node-ghost-border      size-edge-track-gap          grid-columns-min
+color-group-name             group-box-padding            grid-gap-horizontal
+color-group-box              group-box-gap                grid-gap-vertical
+color-group-border           graph-columns-max            grid-node-width-equal
 ```
 
 The `size-*`, `group-*`, `graph-*`, `hub-*`, and `grid-*` options
 control the rendering geometry (canvas margin, node box sizing, edge
 routing, group box spacing, and the per-diagram-type layout) and take
-non-negative numbers.
+non-negative numbers, except the boolean `grid-node-width-equal`.
 
 The `size-node-width-max` option additionally enables the word-wrapping
 of the node box texts: given a positive value, the node name, its type,
@@ -235,6 +288,19 @@ default `0` disables the wrapping entirely and hence lets a node box
 become as wide as its longest text. A single word wider than the
 maximum is never broken and still widens the box beyond the maximum.
 
+The `grid-columns-min` and `grid-columns-max` options control the column
+count of a `grid` diagram, which by default is derived from the node
+count as a roughly square grid: `grid-columns-min` (default `3`) raises
+the derived count, so that a few nodes still share a single row instead
+of being stacked, while `grid-columns-max` (default `4`) caps it, so
+that larger diagrams grow in height only. The column count never
+exceeds the node count and the maximum always wins over the minimum.
+
+The `grid-node-width-equal` option controls the tile widths of a `grid`
+diagram: its default `true` forces all node boxes to the width of the
+widest one and hence yields a strictly regular grid, while `false` lets
+each column become only as wide as its own widest node box.
+
 The `font-family` and `color-*` options are embedded directly into the
 generated SVG. When such an option is *not* explicitly configured, the
 SVG references the CSS custom property `--gradia-<option>` (definable by

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

@@ -37,8 +37,10 @@ export declare const configDefaults: {
     "hub-node-gap": number;
     "hub-node-degree-max": number;
     "grid-columns-max": number;
+    "grid-columns-min": number;
     "grid-gap-horizontal": number;
     "grid-gap-vertical": number;
+    "grid-node-width-equal": boolean;
 };
 export type Config = typeof configDefaults;
 export type ConfigEmbedded = {

package/dst/gradia-api-config.js

@@ -36,19 +36,21 @@ export const configDefaults = {
     "size-edge-track-gap": 12, /*  offset between parallel edge routes    */
     "group-box-padding": 30, /*  inner padding of group boxes           */
     "group-box-gap": 40, /*  vertical gap between group boxes       */
-    "graph-columns-max": 5, /*  graph: max side-by-side nodes          */
+    "graph-columns-max": 4, /*  graph: max side-by-side nodes          */
     "graph-channel-width-max": 140, /*  graph: max width of column channels    */
     "graph-gutter-height-max": 90, /*  graph: max height of row gutters       */
     "graph-node-separation": 30, /*  graph: layered layout node separation  */
     "graph-rank-separation": 60, /*  graph: layered layout rank separation  */
-    "graph-node-degree-max": 3, /*  graph: max edges per side before growth  */
+    "graph-node-degree-max": 3, /*  graph: max edges/side before growth    */
     "hub-channel-width-max": 340, /*  hub: max width of column channels      */
     "hub-channel-width-min": 240, /*  hub: min width of column channels      */
     "hub-node-gap": 20, /*  hub: vertical gap of stacked nodes     */
-    "hub-node-degree-max": 3, /*  hub: max edges per side before growth  */
+    "hub-node-degree-max": 3, /*  hub: max edges/side before growth      */
     "grid-columns-max": 4, /*  grid: max side-by-side tiles           */
+    "grid-columns-min": 3, /*  grid: min side-by-side tiles           */
     "grid-gap-horizontal": 40, /*  grid: horizontal gap between tiles     */
-    "grid-gap-vertical": 20 /*  grid: vertical gap between tiles       */
+    "grid-gap-vertical": 20, /*  grid: vertical gap between tiles       */
+    "grid-node-width-equal": true /*  grid: force equal width of node boxes  */
 };
 /*  resolve a directly embedded configuration option into a CSS value:
     an explicitly configured value is hard-coded (stripped of the
@@ -73,8 +75,13 @@ export const parseDirectives = (input) => {
             description, as they would let it read arbitrary local WOFF2 files  */
         if (key === "font-embed" || (key === "font-family" && val.endsWith(".woff2")))
             continue;
-        if (typeof configDefaults[key] === "boolean")
+        if (typeof configDefaults[key] === "boolean") {
+            /*  silently skip invalid boolean values, as directives are
+                lines of an untrusted input and never abort the rendering  */
+            if (val !== "true" && val !== "false")
+                continue;
             partial[key] = val === "true";
+        }
         else if (typeof configDefaults[key] === "number") {
             /*  silently skip invalid numeric values, as directives are
                 lines of an untrusted input and never abort the rendering  */

package/dst/gradia-api-parser.js

@@ -126,17 +126,17 @@ export const parse = (input) => {
         if (name !== null)
             node.name = name;
         for (const attr of attrs) {
-            const k = node.attrs.findIndex((a) => a.key === attr.key);
-            if (k === -1)
+            const idx = node.attrs.findIndex((a) => a.key === attr.key);
+            if (idx === -1)
                 node.attrs.push(attr);
             else {
                 /*  a node has to stay in a single group, so reject any
                     attempt to re-assign it to a different group  */
-                if (attr.key === "group" && node.attrs[k].val !== attr.val)
+                if (attr.key === "group" && node.attrs[idx].val !== attr.val)
                     throw new Error(`node "${id}" cannot be a member of more than one group ` +
-                        `("${node.attrs[k].val}" vs "${attr.val}") ` +
+                        `("${node.attrs[idx].val}" vs "${attr.val}") ` +
                         `at line ${start.line}, column ${start.col}`);
-                node.attrs[k] = attr;
+                node.attrs[idx] = attr;
             }
         }
         graph.nodes.set(id, node);
@@ -144,10 +144,12 @@ export const parse = (input) => {
     };
     /*  parse the statements (one node/edge chain per line)  */
     while (pos < tokens.length) {
+        /*  skip the empty lines  */
         if (tokens[pos].type === "newline") {
             pos++;
             continue;
         }
+        /*  parse the chain of node references, connected by edge operators  */
         let source = parseNodeRef();
         let t = peek();
         while (t !== null && t.type === "edge") {
@@ -157,6 +159,7 @@ export const parse = (input) => {
             source = target;
             t = peek();
         }
+        /*  ensure the statement ends at the end of the line  */
         if (t !== null && t.type !== "newline")
             bail("edge operator or end of line");
     }

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

@@ -21,7 +21,7 @@ export const textWrap = (text, size, maxWidth) => {
     const words = text.split(/\s+/).filter((word) => word !== "");
     if (maxWidth <= 0 || words.length <= 1 || textWidth(text, size) <= maxWidth)
         return [text];
-    const lines = new Array();
+    const lines = [];
     let line = words[0];
     for (const word of words.slice(1)) {
         if (textWidth(`${line} ${word}`, size) > maxWidth) {
@@ -34,8 +34,10 @@ export const textWrap = (text, size, maxWidth) => {
     lines.push(line);
     return lines;
 };
-/*  escape a string for use in XML/SVG content  */
-export const escapeXML = (text) => text.replace(/&/g, "&amp;")
+/*  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, "")
+    .replace(/&/g, "&amp;")
     .replace(/</g, "&lt;")
     .replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;");

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

@@ -141,10 +141,11 @@ export const computeHops = (polys) => {
         return result;
     });
 };
+/*  the Manhattan length of an orthogonal polyline segment  */
+const len = (a, b) => Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]);
 /*  convert an edge polyline into an SVG path with rounded corners
     at the bends and semi-circular hops at the crossing points  */
 export const pathOf = (poly, hop, rounding, hopRadius) => {
-    const len = (a, b) => Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]);
     const radius = (k) => {
         if (k <= 0 || k >= poly.length - 1)
             return 0;
@@ -214,7 +215,7 @@ export const pathOf = (poly, hop, rounding, hopRadius) => {
 };
 /*  determine a point on a polyline at a given fraction of its length  */
 export const pointAt = (poly, fraction) => {
-    const lens = poly.slice(0, -1).map((p, k) => Math.abs(poly[k + 1][0] - p[0]) + Math.abs(poly[k + 1][1] - p[1]));
+    const lens = poly.slice(0, -1).map((p, k) => len(p, poly[k + 1]));
     const total = lens.reduce((a, b) => a + b, 0);
     let want = total * fraction;
     for (let k = 0; k < lens.length; k++) {

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

@@ -36,7 +36,7 @@ export const partitionGroups = (graph) => {
                 `crosses groups "${sg}" and "${tg}"`);
         parts.get(sg).edges.push(edge);
     }
-    return Array.from(parts.entries()).map(([name, graph]) => ({ name, graph }));
+    return Array.from(parts.entries()).map(([name, subgraph]) => ({ name, graph: subgraph }));
 };
 /*  determine the bounding box of a laid out group (nodes and edges)  */
 const boundsOf = (layout) => {

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

@@ -18,10 +18,11 @@ export const defaultStyleOf = (node) => isPrimary(node) ? {
 };
 /*  the special "type" annotation (rendered above the node name)  */
 export const typeOf = (node) => node.attrs.findLast((attr) => attr.key === "type")?.val;
-/*  split the attributes rendered as text lines from the special
-    "url", "type", "primary", and "group" attributes consumed by the renderers  */
-export const attrsOfNode = (node) => node.attrs.filter((attr) => attr.key !== "url" && attr.key !== "type"
-    && attr.key !== "primary" && attr.key !== "group");
+/*  the special attributes consumed by the renderers instead of being
+    rendered as node box text lines  */
+const ATTRS_SPECIAL = new Set(["url", "type", "primary", "group"]);
+/*  split the attributes rendered as text lines from the special ones  */
+export const attrsOfNode = (node) => node.attrs.filter((attr) => !ATTRS_SPECIAL.has(attr.key));
 /*  the special "url" attribute (rendered as a hyperlink on the whole node
     box, restricted to relative URLs and safe schemes, as the generated
     SVG anchor would otherwise execute an injected "javascript:" URL)  */

package/dst/gradia-api-render-svg.d.ts

@@ -20,4 +20,4 @@ export interface Layout {
     styleOf?: (node: Node) => NodeStyle;
     groups?: GroupBox[];
 }
-export declare const renderSVG: (layout: Layout, config: Config, explicit: Partial<Config>) => string;
+export declare const renderSVG: (layout: Layout, config: Config, explicit: Partial<Config>, seed: string) => string;

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

@@ -4,21 +4,27 @@
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
 /*  external dependencies  */
-import { customAlphabet } from "nanoid";
+import UUID from "pure-uuid";
 import { resolveFont, cssValueOf } from "./gradia-api-config.js";
 import { FS_NAME, FS_TYPE, FS_ATTR, FS_EDGE, FS_ARITY, FS_GROUP, textWidth, escapeXML } from "./gradia-api-render-base.js";
 import { linesOfNode, urlOf, defaultStyleOf, MIN_H, NAME_H, ATTR_H, ATTR_P, TYPE_H, TYPE_D } from "./gradia-api-render-node.js";
 import { computeHops, pathOf, pointAt } from "./gradia-api-render-edge.js";
 /*  escape a string for use inside a CSS string literal (the XML escaping
     is resolved by the parser before the CSS is parsed, so quotes and
-    backslashes have to be neutralized to prevent a CSS injection)  */
-const escapeCSS = (text) => text.replace(/[\\"']/g, "\\$&").replace(/[\r\n]/g, " ");
-/*  generate a per-document identifier prefix, as the SVG identifiers
-    are DOM-global and would collide once multiple diagrams are embedded
-    into the very same document (the alphabet is restricted to
-    alphanumerics to stay a valid XML name and CSS/URL fragment)  */
-const nanoid = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", 12);
-const idPrefix = () => `gradia-${nanoid()}`;
+    backslashes have to be neutralized to prevent a CSS injection, and
+    the CSS newline characters LF, CR and FF have to be replaced, as
+    they would end the string literal as an invalid "bad string")  */
+const escapeCSS = (text) => text.replace(/[\\"']/g, "\\$&").replace(/[\r\n\f]/g, " ");
+/*  the UUID namespace of Gradia, under which the per-document
+    identifier prefixes are derived  */
+const NS_GRADIA = new UUID(5, "ns:URL", "https://github.com/rse/gradia").format();
+/*  derive a per-document identifier prefix from a seed, as the SVG
+    identifiers are DOM-global and would collide once multiple diagrams
+    are embedded into the very same document. The prefix is a UUID v5 of
+    the seed and hence stays stable across regenerations of an unchanged
+    diagram (the Base16 format keeps it alphanumeric and thus a valid XML
+    name and CSS/URL fragment)  */
+const idPrefix = (seed) => `gradia-${new UUID(5, NS_GRADIA, seed).format("b16").toLowerCase()}`;
 /*  the placement of a group tag in the top-left corner of its group box  */
 const TAG_DX = 18; /*  left offset of the group tag  */
 const TAG_DY = 12; /*  top offset of the group tag   */
@@ -117,8 +123,59 @@ const viewBoxOf = (layout, boxes, margin) => {
         h: Math.ceil(maxY - minY + margin)
     };
 };
-/*  render a laid out graph into an SVG document  */
-export const renderSVG = (layout, config, explicit) => {
+/*  generate the SVG fragments for the labels of a single edge: its
+    optional name, placed near the middle of the route, and its optional
+    arity, placed near the arrow head (both dodging into a collision-free
+    position through the "claim" of the label placer)  */
+const renderEdgeLabels = (edge, poly, claim, font, color) => {
+    /*  the halo rendered behind the edge labels for readability
+        (its color is emitted into the style attribute below, as only
+        there the CSS custom property lookup can be resolved)  */
+    const halo = "stroke-width=\"4.5\" paint-order=\"stroke\" stroke-linejoin=\"round\"";
+    const parts = [];
+    if (edge.name !== undefined) {
+        const w = textWidth(edge.name, FS_EDGE);
+        const candidates = [];
+        for (const f of [0.50, 0.40, 0.60, 0.30, 0.70, 0.20, 0.80]) {
+            const p = pointAt(poly, f);
+            if (p.horizontal) {
+                candidates.push([p.x - w / 2, p.y - 23, p.x + w / 2, p.y - 3]);
+                candidates.push([p.x - w / 2, p.y + 3, p.x + w / 2, p.y + 23]);
+            }
+            else {
+                candidates.push([p.x + 5, p.y - 10, p.x + 5 + w, p.y + 10]);
+                candidates.push([p.x - 5 - w, p.y - 10, p.x - 5, p.y + 10]);
+            }
+        }
+        const box = claim(candidates);
+        parts.push(`<text x="${(box[0] + box[2]) / 2}" y="${box[3] - 3}" text-anchor="middle" ` +
+            `font-size="${FS_EDGE}" ` +
+            `style="font-family: ${font}; fill: ${color("color-edge-name")}; ` +
+            `stroke: ${color("color-edge-halo")}" ` +
+            `${halo}>${escapeXML(edge.name)}</text>`);
+    }
+    if (edge.arity !== undefined) {
+        const w = textWidth(edge.arity, FS_ARITY);
+        const p = pointAt(poly, 1.0);
+        const prev = pointAt(poly, 0.999);
+        const dx = Math.sign(p.x - prev.x) || 1;
+        const ax = p.x - dx * (24 + w / 2);
+        const box = claim([
+            [ax - w / 2, p.y - 17, ax + w / 2, p.y - 4],
+            [ax - w / 2, p.y + 4, ax + w / 2, p.y + 17],
+            [ax - w / 2 - dx * 14, p.y - 17, ax + w / 2 - dx * 14, p.y - 4]
+        ]);
+        parts.push(`<text x="${(box[0] + box[2]) / 2}" y="${box[3] - 3}" text-anchor="middle" ` +
+            `font-size="${FS_ARITY}" ` +
+            `style="font-family: ${font}; fill: ${color("color-edge-arity")}; ` +
+            `stroke: ${color("color-edge-halo")}" ` +
+            `${halo}>${escapeXML(edge.arity)}</text>`);
+    }
+    return parts;
+};
+/*  render a laid out graph into an SVG document (the seed determines the
+    identifier prefix of the document, see "idPrefix" above)  */
+export const renderSVG = (layout, config, explicit, seed) => {
     const { nodes, edges, polys } = layout;
     const groups = layout.groups ?? [];
     const styleOf = layout.styleOf ?? defaultStyleOf;
@@ -128,7 +185,7 @@ export const renderSVG = (layout, config, explicit) => {
         CSS custom properties, falling back to the built-in defaults  */
     const color = (key) => escapeXML(cssValueOf(explicit, key));
     /*  derive the collision-free identifiers of this SVG document  */
-    const prefix = idPrefix();
+    const prefix = idPrefix(seed);
     const idArrow = `${prefix}-arrow`;
     /*  resolve the configured font into the rendered font family stack  */
     const { family, embed, weight } = resolveFont(config);
@@ -143,51 +200,10 @@ export const renderSVG = (layout, config, explicit) => {
     /*  generate the SVG fragments for the edges (paths below, labels above)  */
     const svgEdges = [];
     const svgLabels = [];
-    /*  the halo rendered behind the edge labels for readability
-        (its color is emitted into the style attribute below, as only
-        there the CSS custom property lookup can be resolved)  */
-    const halo = "stroke-width=\"4.5\" paint-order=\"stroke\" stroke-linejoin=\"round\"";
     edges.forEach((edge, i) => {
         svgEdges.push(`<path d="${pathOf(polys[i], hops[i], config["size-edge-corner-radius"], config["size-edge-hop-radius"])}" fill="none" ` +
             `style="stroke: ${color("color-edge-line")}" stroke-width="3.0" marker-end="url(#${idArrow})"/>`);
-        if (edge.name !== undefined) {
-            const w = textWidth(edge.name, FS_EDGE);
-            const candidates = [];
-            for (const f of [0.50, 0.40, 0.60, 0.30, 0.70, 0.20, 0.80]) {
-                const p = pointAt(polys[i], f);
-                if (p.horizontal) {
-                    candidates.push([p.x - w / 2, p.y - 23, p.x + w / 2, p.y - 3]);
-                    candidates.push([p.x - w / 2, p.y + 3, p.x + w / 2, p.y + 23]);
-                }
-                else {
-                    candidates.push([p.x + 5, p.y - 10, p.x + 5 + w, p.y + 10]);
-                    candidates.push([p.x - 5 - w, p.y - 10, p.x - 5, p.y + 10]);
-                }
-            }
-            const box = claim(candidates);
-            svgLabels.push(`<text x="${(box[0] + box[2]) / 2}" y="${box[3] - 3}" text-anchor="middle" ` +
-                `font-size="${FS_EDGE}" ` +
-                `style="font-family: ${font}; fill: ${color("color-edge-name")}; ` +
-                `stroke: ${color("color-edge-halo")}" ` +
-                `${halo}>${escapeXML(edge.name)}</text>`);
-        }
-        if (edge.arity !== undefined) {
-            const w = textWidth(edge.arity, FS_ARITY);
-            const p = pointAt(polys[i], 1.0);
-            const prev = pointAt(polys[i], 0.999);
-            const dx = Math.sign(p.x - prev.x) || 1;
-            const ax = p.x - dx * (24 + w / 2);
-            const box = claim([
-                [ax - w / 2, p.y - 17, ax + w / 2, p.y - 4],
-                [ax - w / 2, p.y + 4, ax + w / 2, p.y + 17],
-                [ax - w / 2 - dx * 14, p.y - 17, ax + w / 2 - dx * 14, p.y - 4]
-            ]);
-            svgLabels.push(`<text x="${(box[0] + box[2]) / 2}" y="${box[3] - 3}" text-anchor="middle" ` +
-                `font-size="${FS_ARITY}" ` +
-                `style="font-family: ${font}; fill: ${color("color-edge-arity")}; ` +
-                `stroke: ${color("color-edge-halo")}" ` +
-                `${halo}>${escapeXML(edge.arity)}</text>`);
-        }
+        svgLabels.push(...renderEdgeLabels(edge, polys[i], claim, font, color));
     });
     /*  generate the SVG fragments for the node boxes  */
     const svgNodes = nodes.flatMap((node) => renderNode(node, layout, styleOf(node), font, color, config));

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

@@ -8,8 +8,15 @@ import { DagreLayout } from "@antv/layout";
 import { measureNodes } from "./gradia-api-render-node.js";
 import { PORT_SEP, simplifyPoly, assignPorts, assignTracks } from "./gradia-api-render-edge.js";
 /*  rendering geometry constants  */
-const CLUSTX = 26; /*  max X distance within a grid column  */
-const CLUSTY = 72; /*  max Y distance within a grid row     */
+const CLUSTX = 26; /*  max X distance within a grid column         */
+const CLUSTY = 72; /*  max Y distance within a grid row            */
+const CHAN_W0 = 24; /*  width of an edge-less inter-column channel  */
+const CHAN_W1 = 28; /*  width of a one-edge inter-column channel    */
+const CHAN_PAD = 16; /*  cross-axis padding inside a channel         */
+const GUT_H0 = 20; /*  height of an edge-less inter-row gutter     */
+const GUT_H1 = 24; /*  height of a one-edge inter-row gutter       */
+const GUT_PAD = 12; /*  cross-axis padding inside a gutter          */
+const LOOP_GAP = 24; /*  detour of a self-loop right of its node box */
 /*  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) => {
@@ -23,18 +30,19 @@ 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);
-    const indexOf = (reps, v) => {
+    const nearestIndexOf = (reps, v) => {
         let best = 0;
         for (let i = 1; i < reps.length; i++)
             if (Math.abs(reps[i] - v) < Math.abs(reps[best] - v))
                 best = i;
         return best;
     };
+    /*  assign every node to its nearest column and row  */
     const col = new Map();
     const row = new Map();
     for (const node of nodes) {
-        col.set(node.id, indexOf(colReps, rawX.get(node.id)));
-        row.set(node.id, indexOf(rowReps, rawY.get(node.id)));
+        col.set(node.id, nearestIndexOf(colReps, rawX.get(node.id)));
+        row.set(node.id, nearestIndexOf(rowReps, rawY.get(node.id)));
     }
     return { col, row, ncols: colReps.length, nrows: rowReps.length };
 };
@@ -120,6 +128,7 @@ const planRoutes = (edges, col, row) => {
         }
         return { chans, guts };
     });
+    /*  count the edges occupying each channel and gutter  */
     const chanCnt = new Map();
     const gutCnt = new Map();
     for (const plan of plans) {
@@ -143,11 +152,11 @@ const computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt,
     /*  size the channels and gutters by their actual edge usage  */
     const chanW = Array.from({ length: ncols }, (_, c) => {
         const cnt = chanCnt.get(c) ?? 0;
-        return cnt === 0 ? 24 : Math.min(config["graph-channel-width-max"], 28 + (cnt - 1) * config["size-edge-track-gap"]);
+        return cnt === 0 ? CHAN_W0 : Math.min(config["graph-channel-width-max"], CHAN_W1 + (cnt - 1) * config["size-edge-track-gap"]);
     });
     const gutH = Array.from({ length: nrows }, (_, g) => {
         const cnt = gutCnt.get(g) ?? 0;
-        return cnt === 0 ? 20 : Math.min(config["graph-gutter-height-max"], 24 + (cnt - 1) * config["size-edge-track-gap"]);
+        return cnt === 0 ? GUT_H0 : Math.min(config["graph-gutter-height-max"], GUT_H1 + (cnt - 1) * config["size-edge-track-gap"]);
     });
     /*  derive the column and row center positions  */
     const colCX = [];
@@ -192,7 +201,7 @@ const assignTrackCoords = (edges, plans, col, portPos, grid, config) => {
     });
     const chanOff = new Map();
     for (const [c, users] of chanUsers)
-        for (const [edge, off] of assignTracks(users, chanW[c], 16, config["size-edge-track-gap"]))
+        for (const [edge, off] of assignTracks(users, chanW[c], CHAN_PAD, config["size-edge-track-gap"]))
             chanOff.set(`${c}:${edge}`, off);
     const chanX = (c, edge) => colCX[c] + colWidth[c] / 2 + chanW[c] / 2 +
         chanOff.get(`${c}:${edge}`);
@@ -212,7 +221,7 @@ const assignTrackCoords = (edges, plans, col, portPos, grid, config) => {
     });
     const gutOff = new Map();
     for (const [g, users] of gutUsers)
-        for (const [edge, off] of assignTracks(users, gutH[g], 12, config["size-edge-track-gap"]))
+        for (const [edge, off] of assignTracks(users, gutH[g], GUT_PAD, config["size-edge-track-gap"]))
             gutOff.set(`${g}:${edge}`, off);
     const gutY = (g, edge) => gutBase(g) + gutOff.get(`${g}:${edge}`);
     return { chanX, gutY };
@@ -231,7 +240,8 @@ const routePolys = (edges, plans, col, portPos, boxW, cx, chanX, gutY, config) =
         if (edge.source === edge.target) {
             const k = loopUse.get(edge.source) ?? 0;
             loopUse.set(edge.source, k + 1);
-            const ox = cx(edge.source) + boxW.get(edge.source) / 2 + 24 + k * config["size-edge-track-gap"];
+            const ox = cx(edge.source) + boxW.get(edge.source) / 2 + LOOP_GAP +
+                k * config["size-edge-track-gap"];
             pts = [[sp.x, sp.y], [ox, sp.y], [ox, tp.y], [tp.x, tp.y]];
         }
         else if (chans.length === 1) {

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

@@ -12,23 +12,30 @@ export const render = async (graph, config) => {
     const gapH = config["grid-gap-horizontal"];
     const gapV = config["grid-gap-vertical"];
     const maxCols = Math.max(Math.floor(config["grid-columns-max"]), 1);
+    const minCols = Math.max(Math.floor(config["grid-columns-min"]), 1);
     /*  ensure the graph is completely edge-less  */
     if (graph.edges.length > 0) {
         const edge = graph.edges[0];
         throw new Error("diagram type \"grid\" does not support edges " +
             `(found ${graph.edges.length}, first is "${edge.source}" --> "${edge.target}")`);
     }
-    /*  determine node box sizes (keeping the individual widths)
-        and unify only their heights into a single tile height  */
+    /*  determine node box sizes and unify their heights into a single
+        tile height and, if configured, their widths into a single tile width  */
     const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 2);
     const tileH = nodes.reduce((a, node) => Math.max(a, boxH.get(node.id)), 0);
-    for (const node of nodes)
+    const tileW = nodes.reduce((a, node) => Math.max(a, boxW.get(node.id)), 0);
+    for (const node of nodes) {
         boxH.set(node.id, tileH);
+        if (config["grid-node-width-equal"])
+            boxW.set(node.id, tileW);
+    }
     /*  place the nodes in declaration order onto a roughly square,
-        row-major grid (capped at the configured maximum of columns, so
-        larger graphs grow only in height), with each column as wide as
-        its widest tile and each tile left-aligned within its column  */
-    const cols = Math.max(Math.min(Math.ceil(Math.sqrt(nodes.length)), maxCols), 1);
+        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
+        height), with each column as wide as its widest tile and each
+        tile left-aligned within its column  */
+    const cols = Math.max(Math.min(Math.max(Math.ceil(Math.sqrt(nodes.length)), minCols), maxCols, nodes.length), 1);
     const colWidth = Array.from({ length: cols }, () => 0);
     nodes.forEach((node, i) => {
         colWidth[i % cols] = Math.max(colWidth[i % cols], boxW.get(node.id));