@rse/gradia 1.1.9 → 1.2.1

package/README.md

@@ -41,6 +41,10 @@ Here are examples of the three graph diagram renderings:
 
   ![broadcast-grid](smp/broadcast-grid.svg)
 
+- [container-sample](smp/container-sample.txt) (nested containers):
+
+  ![container-sample](smp/container-sample.svg)
+
 Playground
 ----------
 
@@ -193,7 +197,7 @@ separated by `|`.
 - 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
+- Seven 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. Only relative URLs
@@ -204,12 +208,47 @@ separated by `|`.
     - `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>`.
+      `<name>`,
+    - `parent: <id>` nests the node into the container node `<id>` (a
+      node which is implicitly declared if never referenced otherwise),
+    - `container: <type>` marks the node as a container whose members
+      are laid out with the diagram type `<type>` (`graph`, `hub`, or
+      `grid`), even if it has no members at all,
+    - `order: <number>` places the node explicitly (see below).
+
+- A `graph` (a `graph` container level, too) with at least one node
+  carrying an `order` attribute is laid out in that explicit order
+  instead of by the layered algorithm: the distinct order values become
+  the rows, top-down in ascending order, the nodes of one value fill
+  their row left-to-right in declaration order (wrapped into further
+  rows beyond `graph-columns-max` nodes), and the nodes without an order
+  follow in the trailing rows. A `grid` places its tiles in the order of
+  the attribute, too, the tiles without one trailing. An invalid value
+  is ignored.
 
 - 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.
+  single group. A nested node belongs to the group of its outermost
+  container.
+
+- A node referenced as the `parent` of another node is a container: it
+  is rendered as a dashed grey box surrounding its members instead of as
+  a node box, with its label, `type`, and `url` in the box head (its
+  remaining attributes are not rendered). Containers nest to any depth,
+  but a node cannot be a member of more than one container, and cannot
+  be nested into itself.
+
+- The members of a container are laid out as a diagram of their own,
+  with the diagram type of the enclosing level unless overridden by
+  `container: <type>`, and the container then takes part in the layout
+  of the enclosing level as a single box. Edges may connect any two
+  nodes, across container boundaries and to container nodes themselves,
+  except a container with one of its own members. An edge crossing the
+  boundary of a container laid out as `graph` is routed through the box
+  border to the inner node (entering on the west and leaving on the east
+  side), while an edge crossing the boundary of a container laid out as
+  `hub` or `grid` ends at the box border instead.
 
 - All remaining attributes are displayed as `<key>: <val>` lines inside
   the node box.
@@ -241,10 +280,14 @@ placement is rendered as a dashed "ghost" box, colored by the
 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.
+As the groups of a grouped graph, and the members of every container,
+are laid out individually with the selected (or, for a container, the
+annotated) diagram type, these constraints apply to every single group
+and container level, with the edges crossing a container boundary
+counting at the level they are lifted to (the boundary-crossing edges of
+a `graph` container additionally count inside it, from the boundary to
+the inner node). For the type `hub` this especially means that every
+group and every `hub` container needs its own primary node.
 
 ### Directives
 
@@ -259,35 +302,38 @@ command-line options (`font-embed` being command-line only, see below).
 The recognized options, and their default values, are:
 
 ```
-font-family                Helvetica    size-edge-hop-radius       8
-font-embed                 false        size-edge-track-gap        12
-color-node-regular-name    #336699      size-edge-port-gap         24
-color-node-regular-box     #e0f0ff      group-box-padding          30
-color-node-regular-border  #c0d0e0      group-box-gap              40
-color-node-primary-name    #ffffff      graph-columns-max          4
-color-node-primary-box     #336699      graph-channel-width-max    140
-color-node-primary-border  #003366      graph-channel-width-min    24
-color-node-ghost-name      #666666      graph-gutter-height-max    90
-color-node-ghost-box       #f0f0f0      graph-gutter-height-min    20
-color-node-ghost-border    #a0a0a0      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-edge-line            #999999      hub-channel-width-min      240
-color-edge-name            #333333      hub-node-gap               20
-color-edge-arity           #333333      hub-node-degree-max        3
-color-edge-halo            #ffffff      grid-columns-max           4
-size-canvas-margin         40           grid-columns-min           3
-size-node-width-min        220          grid-gap-horizontal        40
-size-node-width-max        0            grid-gap-vertical          20
-size-node-height-scale     2.25         grid-node-width-equal      true
-size-edge-corner-radius    20
+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
 ```
 
-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, except the boolean `grid-node-width-equal`.
+The `size-*`, `group-*`, `container-*`, `graph-*`, `hub-*`, and
+`grid-*` options control the rendering geometry (canvas margin, node
+box sizing, edge routing, group and container box spacing, and the
+per-diagram-type layout) and take 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,
@@ -297,12 +343,19 @@ value `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 `group-box-padding` and `container-box-padding` options control the
+inner padding of the group and container boxes around their content.
+For a `graph` container, the content additionally includes the
+boundary channels along its west and east sides, through which the
+edges crossing the container boundary reach the inner nodes, sized
+like all channels by the edges routed through them.
+
 The `size-edge-port-gap` option controls the distance of the edge
 attachment ports along a node side, and hence the vertical distance of
 the parallel edges and their labels. It is a *maximum*: a node box too
 small to hold all its ports at that distance packs them closer together
 instead. A node side carrying more edges than `graph-node-degree-max`
-respectively `hub-node-degree-max` grows its box height by this very
+or `hub-node-degree-max` grows its box height by this very
 distance per additional edge.
 
 The `graph-channel-width-*` and `graph-gutter-height-*` options control
@@ -351,7 +404,7 @@ $ gradia -c font-family="Source Sans 3" -c font-embed=true -o graph.svg graph.tx
 
 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.
+as untrusted. Both are available on the command line only.
 
 ### Example
 

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

@@ -13,6 +13,9 @@ export declare const configDefaults: {
     "color-group-name": string;
     "color-group-box": string;
     "color-group-border": string;
+    "color-container-name": string;
+    "color-container-box": string;
+    "color-container-border": string;
     "color-edge-line": string;
     "color-edge-name": string;
     "color-edge-arity": string;
@@ -27,6 +30,7 @@ export declare const configDefaults: {
     "size-edge-port-gap": number;
     "group-box-padding": number;
     "group-box-gap": number;
+    "container-box-padding": number;
     "graph-columns-max": number;
     "graph-channel-width-max": number;
     "graph-channel-width-min": number;
@@ -50,6 +54,9 @@ export type ConfigEmbedded = {
     [K in keyof Config]: Config[K] extends string ? K : never;
 }[keyof Config];
 export declare const cssValueOf: (explicit: Partial<Config>, key: ConfigEmbedded) => string;
+export declare const validateConfig: (raw: Record<string, unknown>, options: {
+    trusted: boolean;
+}) => Partial<Config>;
 export declare const parseDirectives: (input: string) => Partial<Config>;
 export declare const resolveFont: (config: Config) => {
     family: string;

package/dst/gradia-api-config.js

@@ -23,6 +23,9 @@ export const configDefaults = {
     "color-group-name": "#6699cc",
     "color-group-box": "#f4f8fc",
     "color-group-border": "#c0d0e0",
+    "color-container-name": "#666666",
+    "color-container-box": "#f6f6f6",
+    "color-container-border": "#a0a0a0",
     "color-edge-line": "#999999",
     "color-edge-name": "#333333",
     "color-edge-arity": "#333333",
@@ -37,6 +40,7 @@ export const configDefaults = {
     "size-edge-port-gap": 24, /*  max separation of adjacent edge ports  */
     "group-box-padding": 30, /*  inner padding of group boxes           */
     "group-box-gap": 40, /*  vertical gap between group boxes       */
+    "container-box-padding": 30, /*  inner padding of container boxes       */
     "graph-columns-max": 4, /*  graph: max side-by-side nodes          */
     "graph-channel-width-max": 140, /*  graph: max width of column channels    */
     "graph-channel-width-min": 24, /*  graph: min width of column channels    */
@@ -64,37 +68,63 @@ export const configDefaults = {
 export const cssValueOf = (explicit, key) => Object.hasOwn(explicit, key) ?
     explicit[key].replace(/[;{}]/g, "") :
     `var(--gradia-${key}, ${configDefaults[key]})`;
+/*  validate and coerce rendering configuration options into their
+    types (coercing strings, as given on the command line): an unknown
+    option or an invalid value is rejected, an option set to "undefined"
+    is dropped, and an untrusted source may neither embed fonts nor name
+    a WOFF2 file, as this would let it read arbitrary local files  */
+export const validateConfig = (raw, options) => {
+    const config = {};
+    for (const [key, val] of Object.entries(raw)) {
+        if (!Object.hasOwn(configDefaults, key))
+            throw new Error(`unknown configuration option "${key}"`);
+        const k = key;
+        if (val === undefined)
+            continue;
+        if (k === "font-embed" && !options.trusted)
+            throw new Error(`configuration option "${key}" is not available in this context`);
+        else if (typeof configDefaults[k] === "boolean") {
+            if (typeof val !== "boolean" && val !== "true" && val !== "false")
+                throw new Error(`invalid value "${String(val)}" for boolean configuration option "${key}" ` +
+                    "(expected \"true\" or \"false\")");
+            config[k] = typeof val === "boolean" ? val : val === "true";
+        }
+        else if (typeof configDefaults[k] === "number") {
+            const num = Number(val);
+            if ((typeof val !== "number" && typeof val !== "string") || String(val).trim() === "" || !Number.isFinite(num) || num < 0)
+                throw new Error(`invalid value "${String(val)}" for numeric configuration option "${key}" ` +
+                    "(expected a non-negative number)");
+            config[k] = num;
+        }
+        else {
+            if (typeof val !== "string")
+                throw new Error(`invalid value "${String(val)}" for string configuration option "${key}" (expected a string)`);
+            if (val === "")
+                throw new Error(`invalid empty value for string configuration option "${key}"`);
+            if (k === "font-family" && val.endsWith(".woff2") && !options.trusted)
+                throw new Error("configuration option \"font-family\" must not be the path to a WOFF2 file in this context");
+            config[k] = val;
+        }
+    }
+    return config;
+};
 /*  parse "#config <option> <value>" configuration directives from a graph
-    description (lines which are otherwise treated as plain comments)  */
+    description (lines which are otherwise treated as plain comments),
+    validating them as untrusted and silently skipping an unknown option
+    or an invalid value, as directives never abort the rendering  */
 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]))
+        if (m === null)
             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;
-        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";
+        try {
+            Object.assign(partial, validateConfig({ [m[1]]: val }, { trusted: false }));
         }
-        else if (typeof configDefaults[key] === "number") {
-            /*  silently skip invalid numeric values, as directives are
-                lines of an untrusted input and never abort the rendering  */
-            const num = Number(val);
-            if (val === "" || !Number.isFinite(num) || num < 0)
-                continue;
-            partial[key] = num;
+        catch {
+            /*  skip the invalid directive  */
         }
-        else
-            partial[key] = val;
     }
     return partial;
 };
@@ -108,8 +138,8 @@ const fontsBuiltIn = {
 };
 /*  resolve the configured font family: either a built-in font family, a
     plain font family name, or a path to a WOFF2 file (the content of
-    the two former optionally embedded as base64, together with the
-    weight range of the embedded, potentially variable, font)  */
+    the built-in family or the WOFF2 file optionally embedded as base64,
+    the former together with the weight range of its variable font)  */
 export const resolveFont = (config) => {
     const spec = config["font-family"];
     if (Object.hasOwn(fontsBuiltIn, spec)) {

package/dst/gradia-api-parser.js

@@ -130,15 +130,21 @@ export const parse = (input) => {
             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[idx].val !== attr.val)
-                    throw new Error(`node "${id}" cannot be a member of more than one group ` +
+                /*  a node has to stay in a single group and container, so
+                    reject any attempt to re-assign it to a different one  */
+                if ((attr.key === "group" || attr.key === "parent") && node.attrs[idx].val !== attr.val)
+                    throw new Error(`node "${id}" cannot be a member of more than one ` +
+                        `${attr.key === "group" ? "group" : "container"} ` +
                         `("${node.attrs[idx].val}" vs "${attr.val}") ` +
                         `at line ${start.line}, column ${start.col}`);
                 node.attrs[idx] = attr;
             }
         }
+        /*  implicitly declare the container node a "parent" attribute
+            refers to, so a container needs no declaration of its own  */
+        const parent = node.attrs.find((attr) => attr.key === "parent")?.val;
+        if (parent !== undefined && !graph.nodes.has(parent))
+            graph.nodes.set(parent, { id: parent, name: parent, attrs: [] });
         graph.nodes.set(id, node);
         return id;
     };

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

@@ -1,3 +1,4 @@
+import { Node, Edge } from "./gradia-api-model.js";
 import { ConfigEmbedded } from "./gradia-api-config.js";
 export declare const FS_NAME = 30;
 export declare const FS_TYPE = 16;
@@ -16,3 +17,30 @@ export interface NodeStyle {
     text: ConfigEmbedded;
     dash?: string;
 }
+export interface GroupBox {
+    name: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ContainerBox {
+    node: Node;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface Layout {
+    nodes: Node[];
+    edges: Edge[];
+    cx: (id: string) => number;
+    cy: (id: string) => number;
+    boxW: Map<string, number>;
+    boxH: Map<string, number>;
+    contentH: Map<string, number>;
+    polys: Poly[];
+    styleOf?: (node: Node) => NodeStyle;
+    groups?: GroupBox[];
+    containers?: ContainerBox[];
+}

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

@@ -22,8 +22,9 @@ export const textWidth = (text, size) => text.length * size * 0.52;
     inside a word harms the readability more than an overlong box)  */
 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 norm = words.join(" ");
+    if (maxWidth <= 0 || words.length <= 1 || textWidth(norm, size) <= maxWidth)
+        return [norm];
     const lines = [];
     let line = words[0];
     for (const word of words.slice(1)) {

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

@@ -0,0 +1,31 @@
+import { Node, Graph } from "./gradia-api-model.js";
+import { Config } from "./gradia-api-config.js";
+import { Poly, Layout } from "./gradia-api-render-base.js";
+export type GateSide = "in" | "out";
+export interface LevelContext {
+    fixedSize?: Map<string, {
+        w: number;
+        h: number;
+    }>;
+    fixedPort?: (edge: number, role: "s" | "t") => number | undefined;
+    gates?: Map<string, GateSide>;
+}
+export type Renderer = (graph: Graph, config: Config, level?: LevelContext) => Promise<Layout>;
+export interface DiagramTypeSpec {
+    render: Renderer;
+    gated: boolean;
+}
+export interface Containment {
+    parentOf: Map<string, string>;
+    childrenOf: Map<string, Node[]>;
+}
+export declare const containmentOf: (graph: Graph, types: string[]) => Containment;
+export declare const rootOf: (containment: Containment, id: string) => string;
+export interface Bounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export declare const boundsOf: (layout: Layout, extra?: Poly[]) => Bounds;
+export declare const renderContained: (graph: Graph, containment: Containment, type: string, types: Record<string, DiagramTypeSpec>, config: Config) => Promise<Layout>;