@adecore/diagram 0.0.0-stage → 0.17.0-beta.1

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @adecore/diagram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Directed graph schemas, deterministic layered layout, orthogonal routes, SVG export and reading order. The core has no DOM or canvas state. It depends on Zod and `@adecore/drawing` for shared schemas, geometry and palette defaults.
+
+The package is private at `0.0.0` pending initial publication. Use local source exports or build drawing before diagram for default compiled JavaScript/declarations. The transferred code retains FSL-1.1-MIT in [LICENSE](./LICENSE).
+
+```ts
+import { layoutOf, readingOrder, toSvg } from '@adecore/diagram';
+import { DiagramDocumentSchema, diagramProblemIn } from '@adecore/diagram/protocol';
+
+const document = DiagramDocumentSchema.parse({
+    version: 1,
+    rev: 0,
+    meta: { title: 'Delivery', direction: 'right' },
+    nodes: [
+        { id: 'draft', label: 'Draft' },
+        { id: 'review', label: 'Review', shape: 'diamond' }
+    ],
+    groups: [],
+    edges: [{ from: 'draft', to: 'review' }]
+});
+const problem = diagramProblemIn(document);
+if (problem !== null) {
+    throw new Error(problem);
+}
+const layout = layoutOf(document);
+const svg = toSvg(document, { layout });
+const lines = readingOrder(document);
+```
+
+Graph validation is separate from parsing. It caps documents at 100 nodes/120 edges and checks ids and references. Cycles, loops and parallel edges are supported. Pins keep manual positions but do not reserve automatic-layout space. The host owns dragging, collision policy, fonts, persistence and revision checks.
+
+Read the [overview](https://adecore.dev/diagram/), [getting started](https://adecore.dev/diagram/getting-started), [layout guide](https://adecore.dev/diagram/layout), [painting/output guide](https://adecore.dev/diagram/rendering), [API reference](https://adecore.dev/diagram/api), [protocol](https://adecore.dev/diagram/protocol) and [integration/testing guide](https://adecore.dev/diagram/migration).
+
+From the repository root, run `bun run --cwd packages/diagram test`, `typecheck` or `build`. A standalone source-relative example is in [examples/export-graph.ts](./examples/export-graph.ts).

package/dist/across.d.ts

@@ -0,0 +1,2 @@
+import { type Layering } from './graph.ts';
+export declare function placeAcross(layering: Layering): number[];

package/dist/across.js

@@ -0,0 +1,202 @@
+import { BAND_MARGIN, bandOfCode } from './graph.js';
+/* Rounds that pull every unit towards the units it is joined to, alternating the direction of the sweep. */
+const ROUNDS = 8;
+function clamp(value, low, high) {
+    return Math.min(high, Math.max(low, value));
+}
+/*
+ * Where every unit sits across the flow, as the top of its box, with the order of `orderLayers` kept.
+ * A group's block has one top in every layer it spans and its members sit inside it. It starts from
+ * the middle of the tightest packing towards either end, which is always a valid place, and then
+ * moves every unit towards the median of its neighbors as far as its own neighbors in the layer let
+ * it, so a chain lines up straight. Every step is clamped to whole numbers.
+ */
+export function placeAcross(layering) {
+    const { units, bands, lines, items } = layering;
+    const unitCount = units.length;
+    const variableCount = unitCount + bands.length;
+    // A free unit is its own variable; a band is one variable for all its layers, its members sit at an offset from it.
+    const top = new Array(variableCount).fill(0);
+    const local = new Array(unitCount).fill(0);
+    const variableOf = (code) => (code >= 0 ? code : unitCount + bandOfCode(code));
+    const codeOf = (variable) => (variable < unitCount ? variable : -(variable - unitCount + 1));
+    const sizeOf = (code) => (code >= 0 ? units[code].h : bands[bandOfCode(code)].height);
+    const marginOf = (code) => (code >= 0 ? units[code].margin : BAND_MARGIN);
+    const topOf = (code) => top[variableOf(code)];
+    const absoluteTop = (unit) => {
+        const band = units[unit].band;
+        return band >= 0 ? top[unitCount + band] + local[unit] : top[unit];
+    };
+    const successors = Array.from({ length: variableCount }, () => []);
+    const incoming = new Array(variableCount).fill(0);
+    const present = new Array(variableCount).fill(false);
+    for (const row of items) {
+        row.forEach((code, index) => {
+            present[variableOf(code)] = true;
+            if (index > 0) {
+                successors[variableOf(row[index - 1])].push(code);
+                incoming[variableOf(code)] += 1;
+            }
+        });
+    }
+    // The band order is the same in every layer, so these constraints never form a cycle.
+    const lowest = new Array(variableCount).fill(0);
+    const queue = [];
+    for (let variable = 0; variable < variableCount; variable++) {
+        if (present[variable] && incoming[variable] === 0) {
+            queue.push(variable);
+        }
+    }
+    for (let i = 0; i < queue.length; i++) {
+        const variable = queue[i];
+        const code = codeOf(variable);
+        for (const next of successors[variable]) {
+            const target = variableOf(next);
+            lowest[target] = Math.max(lowest[target], lowest[variable] + sizeOf(code) + marginOf(code) + marginOf(next));
+            incoming[target] -= 1;
+            if (incoming[target] === 0) {
+                queue.push(target);
+            }
+        }
+    }
+    const tail = new Array(variableCount).fill(0);
+    let total = 0;
+    for (let i = queue.length - 1; i >= 0; i--) {
+        const variable = queue[i];
+        const code = codeOf(variable);
+        let length = sizeOf(code);
+        for (const next of successors[variable]) {
+            length = Math.max(length, sizeOf(code) + marginOf(code) + marginOf(next) + tail[variableOf(next)]);
+        }
+        tail[variable] = length;
+        total = Math.max(total, lowest[variable] + length);
+    }
+    for (const variable of queue) {
+        top[variable] = Math.floor((lowest[variable] + total - tail[variable]) / 2);
+    }
+    for (const band of bands) {
+        for (const slot of band.members) {
+            const low = [];
+            let at = band.before;
+            slot.forEach((unit, index) => {
+                if (index > 0) {
+                    const previous = units[slot[index - 1]];
+                    at += previous.h + previous.margin + units[unit].margin;
+                }
+                low.push(at);
+            });
+            let high = band.height - band.after;
+            for (let index = slot.length - 1; index >= 0; index--) {
+                const unit = units[slot[index]];
+                if (index < slot.length - 1) {
+                    high -= unit.margin + units[slot[index + 1]].margin;
+                }
+                high -= unit.h;
+                local[slot[index]] = Math.floor((low[index] + high) / 2);
+            }
+        }
+    }
+    const medianOf = (values) => {
+        values.sort((left, right) => left - right);
+        const middle = values.length >> 1;
+        return values.length % 2 === 1 ? values[middle] : (values[middle - 1] + values[middle]) / 2;
+    };
+    const desiredTop = (unit) => {
+        const self = units[unit];
+        if (self.line >= 0) {
+            // The points of one long edge pull towards each other rather than their neighbors, so the edge runs straight
+            // instead of stepping a little in every layer it passes.
+            const line = lines[self.line];
+            const ends = [units[line[0]].up[0], units[line.at(-1)].down[0]].map((end) => absoluteTop(end) + units[end].h / 2);
+            if (line.length === 1) {
+                const here = absoluteTop(unit);
+                return Math.round(Math.abs(ends[1] - here) < Math.abs(ends[0] - here) ? ends[1] : ends[0]);
+            }
+            return Math.round(medianOf([...line.filter((other) => other !== unit).map(absoluteTop), ...ends]));
+        }
+        const neighbors = [...self.up, ...self.down];
+        if (neighbors.length === 0) {
+            return null;
+        }
+        return Math.round(medianOf(neighbors.map((neighbor) => absoluteTop(neighbor) + units[neighbor].h / 2)) - self.h / 2);
+    };
+    for (let round = 0; round < ROUNDS; round++) {
+        for (let step = 0; step < items.length; step++) {
+            const layer = round % 2 === 0 ? step : items.length - 1 - step;
+            const row = items[layer];
+            row.forEach((code, index) => {
+                if (code >= 0) {
+                    const want = desiredTop(code);
+                    if (want === null) {
+                        return;
+                    }
+                    const previous = row[index - 1];
+                    const next = row[index + 1];
+                    const low = previous === undefined ? -Infinity : topOf(previous) + sizeOf(previous) + marginOf(previous) + marginOf(code);
+                    const high = next === undefined ? Infinity : topOf(next) - marginOf(next) - marginOf(code) - sizeOf(code);
+                    top[code] = clamp(want, low, high);
+                    return;
+                }
+                const bandIndex = bandOfCode(code);
+                const band = bands[bandIndex];
+                const slot = band.members[layer - band.first];
+                slot.forEach((unit, position) => {
+                    const want = desiredTop(unit);
+                    if (want === null) {
+                        return;
+                    }
+                    const self = units[unit];
+                    const previous = slot[position - 1];
+                    const next = slot[position + 1];
+                    const low = previous === undefined ? band.before : local[previous] + units[previous].h + units[previous].margin + self.margin;
+                    const high = next === undefined ? band.height - band.after - self.h : local[next] - units[next].margin - self.margin - self.h;
+                    local[unit] = clamp(want - top[unitCount + bandIndex], low, high);
+                });
+            });
+        }
+        bands.forEach((band, bandIndex) => {
+            const shifts = [];
+            for (const unit of band.members.flat()) {
+                const want = desiredTop(unit);
+                if (want !== null) {
+                    shifts.push(want - absoluteTop(unit));
+                }
+            }
+            if (shifts.length === 0) {
+                return;
+            }
+            const code = -(bandIndex + 1);
+            let low = -Infinity;
+            let high = Infinity;
+            for (let layer = band.first; layer <= band.last; layer++) {
+                const row = items[layer];
+                const index = row.indexOf(code);
+                const previous = row[index - 1];
+                const next = row[index + 1];
+                if (previous !== undefined) {
+                    low = Math.max(low, topOf(previous) + sizeOf(previous) + marginOf(previous) + BAND_MARGIN);
+                }
+                if (next !== undefined) {
+                    high = Math.min(high, topOf(next) - marginOf(next) - BAND_MARGIN - band.height);
+                }
+            }
+            const shift = Math.round(shifts.reduce((sum, value) => sum + value, 0) / shifts.length);
+            top[unitCount + bandIndex] = clamp(top[unitCount + bandIndex] + shift, low, high);
+        });
+    }
+    let least = Infinity;
+    for (const row of items) {
+        for (const code of row) {
+            least = Math.min(least, topOf(code));
+        }
+    }
+    if (Number.isFinite(least)) {
+        for (let variable = 0; variable < variableCount; variable++) {
+            top[variable] = top[variable] - least || 0;
+        }
+    }
+    bands.forEach((band, index) => {
+        band.top = top[unitCount + index];
+    });
+    return units.map((_, unit) => absoluteTop(unit));
+}

package/dist/graph.d.ts

@@ -0,0 +1,40 @@
+export interface Unit {
+    layer: number;
+    node: number;
+    band: number;
+    w: number;
+    h: number;
+    margin: number;
+    line: number;
+    up: number[];
+    down: number[];
+}
+export interface Hop {
+    edge: number;
+    from: number;
+    to: number;
+}
+export interface Band {
+    group: number;
+    first: number;
+    last: number;
+    members: number[][];
+    top: number;
+    height: number;
+    before: number;
+    after: number;
+    rank: number;
+    labelWidth: number;
+}
+export interface Layering {
+    units: Unit[];
+    hops: Hop[];
+    bands: Band[];
+    lines: number[][];
+    items: number[][];
+}
+export declare function bandCode(band: number): number;
+export declare function bandOfCode(code: number): number;
+export declare const NODE_MARGIN = 16;
+export declare const DUMMY_MARGIN = 8;
+export declare const BAND_MARGIN = 16;

package/dist/graph.js

@@ -0,0 +1,14 @@
+/*
+ * The graph the layout works on once every edge that skips a layer has a point per layer it passes
+ * through. Internal to the package: the coordinates it ends in are what `layoutOf` hands out.
+ */
+export function bandCode(band) {
+    return -(band + 1);
+}
+export function bandOfCode(code) {
+    return -code - 1;
+}
+export const NODE_MARGIN = 16;
+export const DUMMY_MARGIN = 8;
+/* A node beside a group is this plus its own margin away from the border. */
+export const BAND_MARGIN = 16;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type NodeBox, type GroupBox, type EdgeLabelBox, type EdgeRoute, type DiagramLayout, NODE_MAX_WIDTH, CYLINDER_LID, EDGE_LABEL_MAX_WIDTH, EDGE_LABEL_PADDING, GROUP_PADDING, GROUP_LABEL_BAND, GROUP_LABEL_INSET, type NodeSize, sizeOfNode, sizeOfEdgeLabel, layersOf, layoutOf, LABEL_LINE, LABEL_SIZE, SUB_LINE, SUB_SIZE, estimateTextWidth, wrapText, type Point, type Rect } from './layout.ts';
+export { readingOrder } from './reading-order.ts';
+export { type ShapePaths, shapePaths, type TextLine, textLinesOf, edgeLabelLinesOf, edgePath, arrowHeadPath, dashOf } from './shapes.ts';
+export { type DiagramSvgOptions, DEFAULT_DIAGRAM_MARGIN, DEFAULT_NODE_TONE, DEFAULT_GROUP_TONE, DEFAULT_EDGE_TONE, toSvg } from './svg.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { NODE_MAX_WIDTH, CYLINDER_LID, EDGE_LABEL_MAX_WIDTH, EDGE_LABEL_PADDING, GROUP_PADDING, GROUP_LABEL_BAND, GROUP_LABEL_INSET, sizeOfNode, sizeOfEdgeLabel, layersOf, layoutOf, LABEL_LINE, LABEL_SIZE, SUB_LINE, SUB_SIZE, estimateTextWidth, wrapText } from './layout.js';
+export { readingOrder } from './reading-order.js';
+export { shapePaths, textLinesOf, edgeLabelLinesOf, edgePath, arrowHeadPath, dashOf } from './shapes.js';
+export { DEFAULT_DIAGRAM_MARGIN, DEFAULT_NODE_TONE, DEFAULT_GROUP_TONE, DEFAULT_EDGE_TONE, toSvg } from './svg.js';

package/dist/layout.d.ts

@@ -0,0 +1,55 @@
+import type { DiagramDocument, DiagramEdge, DiagramNode } from './protocol.ts';
+import { type Point, type Rect } from '@adecore/drawing';
+export { LABEL_LINE, LABEL_SIZE, SUB_LINE, SUB_SIZE, estimateTextWidth, wrapText } from './text.ts';
+export type { Point, Rect } from '@adecore/drawing';
+export interface NodeBox extends Rect {
+    id: string;
+    layer: number;
+    pinned: boolean;
+    label: string[];
+    sub: string[];
+}
+export interface GroupBox extends Rect {
+    id: string;
+    labelBox: Rect;
+}
+export interface EdgeLabelBox extends Rect {
+    lines: string[];
+}
+export interface EdgeRoute {
+    index: number;
+    from: string;
+    to: string;
+    points: Point[];
+    label: EdgeLabelBox | null;
+}
+export interface DiagramLayout {
+    nodes: NodeBox[];
+    groups: GroupBox[];
+    edges: EdgeRoute[];
+    bounds: Rect;
+}
+export declare const NODE_MAX_WIDTH = 280;
+export declare const CYLINDER_LID = 10;
+export declare const EDGE_LABEL_MAX_WIDTH = 160;
+export declare const EDGE_LABEL_PADDING: {
+    x: number;
+    y: number;
+};
+export declare const GROUP_PADDING = 20;
+export declare const GROUP_LABEL_BAND = 24;
+export declare const GROUP_LABEL_INSET = 12;
+export interface NodeSize {
+    w: number;
+    h: number;
+    label: string[];
+    sub: string[];
+}
+export declare function sizeOfNode(node: Pick<DiagramNode, 'label' | 'sub' | 'shape'>): NodeSize;
+export declare function sizeOfEdgeLabel(text: string): {
+    w: number;
+    h: number;
+    lines: string[];
+};
+export declare function layersOf(nodes: readonly Pick<DiagramNode, 'id'>[], edges: readonly Pick<DiagramEdge, 'from' | 'to'>[]): Map<string, number>;
+export declare function layoutOf(document: Pick<DiagramDocument, 'meta' | 'nodes' | 'groups' | 'edges'>): DiagramLayout;