@rse/gradia 0.9.0

package/README.md

@@ -0,0 +1,190 @@
+
+Gradia
+======
+
+**Object Graph Diagram Rendering**
+
+<p/>
+<img src="https://nodei.co/npm/@rse/gradia.png?downloads=true&stars=true" alt=""/>
+
+<p/>
+[![github (author stars)](https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa)](https://github.com/rse)
+[![github (author followers)](https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa)](https://github.com/rse)
+
+About
+-----
+
+**Gradia** is a small API and CLI for rendering directed graphs,
+described in a concise textual input language, as SVG diagrams. Three
+diagram types are supported which fit the scenario of visualizing object
+graphs:
+
+- `graph`: a loosly grid-snapped layered layout of the whole graph,
+  based on the Dagre algorithm of [@antv/layout](https://github.com/antvis/layout).
+- `hub`: a hub graph, placing one primary hub node between its input and
+  output nodes.
+- `grid`: a compact grid of tiles for an edge-less graph.
+
+Installation
+------------
+
+```sh
+$ npm install @rse/gradia
+```
+
+Usage
+-----
+
+```sh
+$ gradia [-t graph|hub|grid] [-f <format>] [-c <name>=<value>] -o <file>.svg <graph>.txt
+```
+
+The output format is `svg:standalone` (a standalone SVG/XML document,
+the default), `svg:embedded` (the SVG without the `<?xml?>` declaration,
+for direct embedding into HTML), `url:xml` (a `data:image/svg+xml` URL
+with URL-encoded XML), or `url:base64` (a `data:image/svg+xml` URL with
+Base64-encoded XML).
+
+Input Syntax
+------------
+
+The input is a plain-text graph description: one node/edge chain per
+line, plus optional comments and rendering directives.
+
+### Grammar
+
+The following BNF grammar describes the input syntax. Non-terminals are
+written as `<name>`, terminals as `"..."`, optional parts as `[ ... ]`,
+repeatable parts as `{ ... }` (zero or more times), and alternatives are
+separated by `|`.
+
+```bnf
+<graph>          ::= { <statement> | <newline> }
+<statement>      ::= <node> { <edge> <node> } ( <newline> | <eof> )
+<node>           ::= <atom> [ ":" <atom> ] [ <attributes> ]
+<attributes>     ::= "[" <attribute> { "," <attribute> } "]"
+<attribute>      ::= <atom> ":" <atom>
+<edge>           ::= "--" [ "(" <edge-name> ")" "--" ] ">" [ "[" <edge-arity> "]" ]
+<edge-name>      ::= <string> | <name-word>
+<edge-arity>     ::= <string> | <arity-word>
+<atom>           ::= <bareword> | <string>
+<bareword>       ::= <bareword-char> { <bareword-char> }
+<bareword-char>  ::= <char> - ( <whitespace> | "[" | "]" | "(" | ")" | "," | ":" | "\"" | ">" | "#" )
+<name-word>      ::= <name-char> { <name-char> }
+<name-char>      ::= <char> - ( <whitespace> | "(" | ")" | "\"" )
+<arity-word>     ::= <arity-char> { <arity-char> }
+<arity-char>     ::= <char> - ( <whitespace> | "[" | "]" | "\"" )
+<string>         ::= "\"" { <string-char> } "\""
+<string-char>    ::= ( <char> - ( "\"" | "\\" | <newline> ) ) | ( "\\" ( <char> - <newline> ) )
+<comment>        ::= "#" { <char> - <newline> }
+<directive>      ::= "#config" <whitespace> { <whitespace> } <option> <whitespace> { <whitespace> } ( <string> | <word> )
+<option>         ::= <letter> { <letter> | <digit> | "-" }
+<word>           ::= <char> - <whitespace> { <char> - <whitespace> }
+<newline>        ::= "\n"
+<whitespace>     ::= " " | "\t" | "\r"
+```
+
+### Lexical Rules
+
+- A `<bareword>` must not contain the character sequence `--` at any
+  position, as `--` always starts an edge operator.
+
+- An `<edge>` is a single lexical token: no whitespace and no comment is
+  allowed anywhere inside it, especially not between `>` and `[`.
+
+- Whitespace (except `<newline>`) is insignificant between all other
+  tokens and never part of a token.
+
+- A `<newline>` terminates a `<statement>`: statements cannot span
+  multiple lines.
+
+- A `<comment>` starts at an unquoted `#` and extends to the end of the
+  line. Inside a `<string>`, `#` is an ordinary character.
+
+- A `<string>` cannot span lines. Inside it, `\` escapes the following
+  character (especially `\"` and `\\`).
+
+- A `<directive>` is a `<comment>` which occupies its entire line,
+  starts with the keyword `#config`, and whose `<option>` is one of the
+  recognized rendering options (see below). All other comments are
+  ignored.
+
+### Semantic Rules
+
+- In `<node>`, the first `<atom>` is the node id and the optional
+  `<atom>` after `:` is the displayed node label. Without a label, the
+  id is displayed.
+
+- A node can be referenced multiple times. All references address the
+  same node and merge their label and attributes into it, with later
+  values overriding earlier ones for the same attribute key.
+
+- Nodes which are never part of an `<edge>` are rendered free-standing.
+
+- In a chain `a --> b --> c`, each `<edge>` connects its immediately
+  preceding and following node, i.e., the chain is equivalent to the
+  two statements `a --> b` and `b --> c`.
+
+- The `<edge-name>` is rendered as the label of the edge and the
+  `<edge-arity>` as its cardinality label.
+
+- 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,
+    - `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
+      (and, for diagram type `hub`, marks the single central hub node),
+    - `group: <name>` places the node into the surrounding group box
+      `<name>`.
+
+- A node cannot be a member of more than one group. As soon as at least
+  one node carries a `group` attribute, all nodes without one implicitly
+  belong to the group `default`, and every edge has to stay within a
+  single group.
+
+- All remaining attributes are displayed as `<key>: <val>` lines inside
+  the node box.
+
+### Directives
+
+A `<directive>` sets one of the rendering options, which otherwise are
+settable through the corresponding `--config <option>=<value>`
+command-line options. The recognized options are:
+
+```
+font-family                  color-node-ghost-name        color-group-name
+                             color-node-ghost-box         color-group-box
+color-node-regular-name      color-node-ghost-border      color-group-border
+color-node-regular-box
+color-node-regular-border    color-node-primary-name      color-edge-line
+                             color-node-primary-box       color-edge-name
+                             color-node-primary-border    color-edge-arity
+```
+
+The option `font-embed`, and a `font-family` value pointing to a WOFF2
+file, are intentionally rejected in directives, as the input is treated
+as untrusted. Both are available on the command-line only.
+
+### Example
+
+```
+#config color-node-primary-box  #336699
+#config color-edge-line         #999999
+
+Animal: animal [ type: "abstract class", kind: base, url: "#animal", primary: true ]
+Dog: dog
+Cat: cat
+
+Dog --(isa)--> Animal
+Cat --(isa)--> Animal
+"Pet Owner" --(owns)-->[0..*] Dog --(chases)-->[0..n] Cat
+```
+
+License
+-------
+
+Copyright &copy; 2026 Dr. Ralf S. Engelschall (http://engelschall.com/)<br/>
+Distributed under MIT license (https://spdx.org/licenses/MIT.html)
+

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

@@ -0,0 +1,25 @@
+export declare const configDefaults: {
+    "font-family": string;
+    "font-embed": boolean;
+    "color-node-regular-name": string;
+    "color-node-regular-box": string;
+    "color-node-regular-border": string;
+    "color-node-primary-name": string;
+    "color-node-primary-box": string;
+    "color-node-primary-border": string;
+    "color-node-ghost-name": string;
+    "color-node-ghost-box": string;
+    "color-node-ghost-border": string;
+    "color-group-name": string;
+    "color-group-box": string;
+    "color-group-border": string;
+    "color-edge-line": string;
+    "color-edge-name": string;
+    "color-edge-arity": string;
+};
+export type Config = typeof configDefaults;
+export declare const parseDirectives: (input: string) => Partial<Config>;
+export declare const resolveFont: (config: Config) => {
+    family: string;
+    embed?: string;
+};

package/dst/gradia-api-config.js

@@ -0,0 +1,63 @@
+/*
+**  Gradia -- Object Graph Diagram Rendering
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
+*/
+/*  built-in dependencies  */
+import fs from "node:fs";
+import path from "node:path";
+/*  the rendering configuration and its default values  */
+export const configDefaults = {
+    "font-family": "Helvetica",
+    "font-embed": false,
+    "color-node-regular-name": "#336699",
+    "color-node-regular-box": "#e0f0ff",
+    "color-node-regular-border": "#c0d0e0",
+    "color-node-primary-name": "#ffffff",
+    "color-node-primary-box": "#336699",
+    "color-node-primary-border": "#003366",
+    "color-node-ghost-name": "#666666",
+    "color-node-ghost-box": "#f0f0f0",
+    "color-node-ghost-border": "#a0a0a0",
+    "color-group-name": "#6699cc",
+    "color-group-box": "#f4f8fc",
+    "color-group-border": "#c0d0e0",
+    "color-edge-line": "#999999",
+    "color-edge-name": "#333333",
+    "color-edge-arity": "#333333"
+};
+/*  parse "#config <option> <value>" configuration directives from a graph
+    description (lines which are otherwise treated as plain comments)  */
+export const parseDirectives = (input) => {
+    const partial = {};
+    for (const line of input.split(/\r?\n/)) {
+        const m = /^[ \t]*#config[ \t]+([a-z][a-z0-9-]*)[ \t]+(?:"((?:[^"\\]|\\.)*)"|(\S+))[ \t]*$/.exec(line);
+        if (m === null || !Object.hasOwn(configDefaults, m[1]))
+            continue;
+        const key = m[1];
+        const val = m[2] !== undefined ? m[2].replace(/\\(.)/g, "$1") : m[3];
+        /*  reject font file paths and font embedding from the untrusted graph
+            description, as they would let it read arbitrary local WOFF2 files  */
+        if (key === "font-embed" || (key === "font-family" && val.endsWith(".woff2")))
+            continue;
+        partial[key] = typeof configDefaults[key] === "boolean" ?
+            val === "true" : val;
+    }
+    return partial;
+};
+/*  resolve the configured font family: either a plain family name or a
+    path to a WOFF2 file (its content optionally embedded as base64)  */
+export const resolveFont = (config) => {
+    const spec = config["font-family"];
+    if (spec.endsWith(".woff2")) {
+        const family = path.basename(spec, ".woff2");
+        if (config["font-embed"])
+            return { family, embed: fs.readFileSync(spec).toString("base64") };
+        else
+            return { family };
+    }
+    else if (config["font-embed"])
+        throw new Error("option \"font-embed\" requires option \"font-family\" to be the path to a WOFF2 file");
+    else
+        return { family: spec };
+};

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

@@ -0,0 +1,19 @@
+export interface Attr {
+    key: string;
+    val: string;
+}
+export interface Node {
+    id: string;
+    name: string;
+    attrs: Attr[];
+}
+export interface Edge {
+    source: string;
+    target: string;
+    name?: string;
+    arity?: string;
+}
+export interface Graph {
+    nodes: Map<string, Node>;
+    edges: Edge[];
+}

package/dst/gradia-api-model.js

@@ -0,0 +1,6 @@
+/*
+**  Gradia -- Object Graph Diagram Rendering
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
+*/
+export {};

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

@@ -0,0 +1,2 @@
+import { Graph } from "./gradia-api-model.js";
+export declare const parse: (input: string) => Graph;

package/dst/gradia-api-parser.js

@@ -0,0 +1,164 @@
+/*
+**  Gradia -- Object Graph Diagram Rendering
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
+*/
+/*  tokenize the graph description language  */
+const tokenize = (input) => {
+    const tokens = [];
+    let line = 1;
+    let col = 1;
+    let i = 0;
+    /*  reusable regular expressions  */
+    const reEdge = /--(?:\((?:"((?:[^"\\\n]|\\.)*)"|([^()"\s]+))\)--)?>(?:\[(?:"((?:[^"\\\n]|\\.)*)"|([^[\]"\s]+))\])?/y;
+    const reString = /"((?:[^"\\\n]|\\.)*)"/y;
+    const reWord = /(?:(?!--)[^\s[\](),:">#])+/y;
+    /*  helper functions  */
+    const match = (re) => {
+        re.lastIndex = i;
+        return re.exec(input);
+    };
+    const unquote = (s) => s.replace(/\\(.)/g, "$1");
+    /*  iterate over input  */
+    while (i < input.length) {
+        const ch = input[i];
+        let m;
+        /*  whitespace, line breaks, and comments  */
+        if (ch === "\n") {
+            tokens.push({ type: "newline", text: "\n", line, col });
+            line++;
+            col = 1;
+            i++;
+        }
+        else if (ch === " " || ch === "\t" || ch === "\r") {
+            col++;
+            i++;
+        }
+        else if (ch === "#") {
+            while (i < input.length && input[i] !== "\n") {
+                col++;
+                i++;
+            }
+        }
+        /*  edge operators, quoted strings, punctuation, and barewords  */
+        else if ((m = match(reEdge)) !== null) {
+            const name = m[1] !== undefined ? unquote(m[1]) : m[2];
+            const arity = m[3] !== undefined ? unquote(m[3]) : m[4];
+            tokens.push({ type: "edge", text: m[0], name, arity, line, col });
+            col += m[0].length;
+            i += m[0].length;
+        }
+        else if ((m = match(reString)) !== null) {
+            tokens.push({ type: "string", text: unquote(m[1]), line, col });
+            col += m[0].length;
+            i += m[0].length;
+        }
+        else if (ch === "\"")
+            throw new Error(`unterminated string at line ${line}, column ${col}`);
+        else if ("[](),:".includes(ch)) {
+            tokens.push({ type: "punct", text: ch, line, col });
+            col++;
+            i++;
+        }
+        else if ((m = match(reWord)) !== null) {
+            tokens.push({ type: "word", text: m[0], line, col });
+            col += m[0].length;
+            i += m[0].length;
+        }
+        else
+            throw new Error(`invalid character ${JSON.stringify(ch)} at line ${line}, column ${col}`);
+    }
+    return tokens;
+};
+/*  parse the token stream into the graph model  */
+export const parse = (input) => {
+    const tokens = tokenize(input);
+    const graph = { nodes: new Map(), edges: [] };
+    let pos = 0;
+    /*  helper functions  */
+    const peek = () => pos < tokens.length ? tokens[pos] : null;
+    const accept = (text) => {
+        const t = peek();
+        if (t === null || t.type !== "punct" || t.text !== text)
+            return false;
+        pos++;
+        return true;
+    };
+    const bail = (what) => {
+        const t = peek();
+        const loc = t !== null ? `line ${t.line}, column ${t.col}` : "end of input";
+        throw new Error(`expected ${what} at ${loc}`);
+    };
+    /*  parse a single atom (bareword or quoted string)  */
+    const parseAtom = () => {
+        const t = peek();
+        if (t === null || (t.type !== "word" && t.type !== "string"))
+            return bail("bareword or quoted string");
+        pos++;
+        return t.text;
+    };
+    /*  parse a node reference with optional label and attributes,
+        merging the information into the already known node (if any)  */
+    const parseNodeRef = () => {
+        const start = tokens[pos];
+        const id = parseAtom();
+        /*  parse the optional node label  */
+        let name = null;
+        if (accept(":"))
+            name = parseAtom();
+        /*  parse the optional node attributes  */
+        const attrs = [];
+        if (accept("[")) {
+            while (true) {
+                const key = parseAtom();
+                if (!accept(":"))
+                    bail("\":\" in key/value attribute");
+                const val = parseAtom();
+                attrs.push({ key, val });
+                if (!accept(","))
+                    break;
+            }
+            if (!accept("]"))
+                bail("\"]\" after key/value attributes");
+        }
+        /*  merge the parsed information into the graph node  */
+        const node = graph.nodes.get(id) ?? { id, name: id, attrs: [] };
+        if (name !== null)
+            node.name = name;
+        for (const attr of attrs) {
+            const k = node.attrs.findIndex((a) => a.key === attr.key);
+            if (k === -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)
+                    throw new Error(`node "${id}" cannot be member of more than one group ` +
+                        `("${node.attrs[k].val}" vs "${attr.val}") ` +
+                        `at line ${start.line}, column ${start.col}`);
+                node.attrs[k] = attr;
+            }
+        }
+        graph.nodes.set(id, node);
+        return id;
+    };
+    /*  parse the statements (one node/edge chain per line)  */
+    while (pos < tokens.length) {
+        if (tokens[pos].type === "newline") {
+            pos++;
+            continue;
+        }
+        let source = parseNodeRef();
+        let t = peek();
+        while (t !== null && t.type === "edge") {
+            pos++;
+            const target = parseNodeRef();
+            graph.edges.push({ source, target, name: t.name, arity: t.arity });
+            source = target;
+            t = peek();
+        }
+        if (t !== null && t.type !== "newline")
+            bail("edge operator or end of line");
+    }
+    return graph;
+};

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

@@ -0,0 +1,20 @@
+export declare const FS_NAME = 30;
+export declare const FS_TYPE = 16;
+export declare const FS_ATTR = 22;
+export declare const FS_EDGE = 16;
+export declare const FS_ARITY = 16;
+export declare const FS_GROUP = 24;
+export declare const MARGIN = 40;
+export declare const SLOT = 12;
+export declare const RADIUS = 20;
+export declare const HOP = 8;
+export declare const SCALE_H = 2.25;
+export declare const textWidth: (text: string, size: number) => number;
+export declare const escapeXML: (text: string) => string;
+export type Poly = [number, number][];
+export interface NodeStyle {
+    fill: string;
+    stroke: string;
+    text: string;
+    dash?: string;
+}

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

@@ -0,0 +1,25 @@
+/*
+**  Gradia -- Object Graph Diagram Rendering
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
+*/
+/*  rendering geometry constants  */
+export const FS_NAME = 30; /*  font size of node names          */
+export const FS_TYPE = 16; /*  font size of node types          */
+export const FS_ATTR = 22; /*  font size of node attributes     */
+export const FS_EDGE = 16; /*  font size of edge labels         */
+export const FS_ARITY = 16; /*  font size of edge arities        */
+export const FS_GROUP = 24; /*  font size of group tags          */
+export const MARGIN = 40; /*  outer margin of the canvas       */
+export const SLOT = 12; /*  offset between parallel routes   */
+export const RADIUS = 20; /*  corner rounding radius of edges  */
+export const HOP = 8; /*  radius of edge crossing hops     */
+export const SCALE_H = 2.25; /*  height scale of node boxes       */
+/*  estimate rendered text width (no canvas available under Node,
+    factor tuned for the average glyph advance of Source Sans 3)  */
+export const textWidth = (text, size) => text.length * size * 0.52;
+/*  escape a string for use in XML/SVG content  */
+export const escapeXML = (text) => text.replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");

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

@@ -0,0 +1,25 @@
+import { Edge } from "./gradia-api-model.js";
+import { Poly } from "./gradia-api-render-base.js";
+export declare const simplifyPoly: (pts: Poly) => Poly;
+export type Side = "e" | "w";
+export declare const assignPorts: (edges: Edge[], sides: {
+    s: Side;
+    t: Side;
+}[], cx: (id: string) => number, cy: (id: string) => number, boxW: Map<string, number>, boxH: Map<string, number>) => Map<string, {
+    x: number;
+    y: number;
+}>;
+export interface TrackUser {
+    edge: number;
+    posIn: number;
+    posOut: number;
+    mirror: boolean;
+}
+export declare const assignTracks: (users: TrackUser[], width: number, pad: number) => Map<number, number>;
+export declare const computeHops: (polys: Poly[]) => Map<number, number[]>[];
+export declare const pathOf: (poly: Poly, hop: Map<number, number[]>) => string;
+export declare const pointAt: (poly: Poly, fraction: number) => {
+    x: number;
+    y: number;
+    horizontal: boolean;
+};