@adecore/diagram 0.0.1 → 0.17.0-beta.1

package/src/shapes.ts

@@ -0,0 +1,119 @@
+import type { DiagramEdgeStyle, DiagramShape } from './protocol.ts';
+import { CYLINDER_LID, EDGE_LABEL_PADDING, type EdgeLabelBox, type NodeBox, type Point, type Rect } from './layout.ts';
+import { LABEL_LINE, LABEL_SIZE, SUB_LINE, SUB_SIZE } from './text.ts';
+
+const ROUND_RADIUS = 10;
+/* How deep the lid of a cylinder is, as a share of its height. */
+const LID_RATIO = 0.18;
+const HEAD_LENGTH = 10;
+const HEAD_WIDTH = 6;
+
+export interface ShapePaths {
+    body: string;
+    /* A line drawn on top of the body and never filled: the front edge of a cylinder's lid. */
+    detail: string | null;
+}
+
+function roundedRect(box: Rect, radius: number): string {
+    const r = Math.round(Math.min(radius, box.w / 2, box.h / 2));
+    const right = box.x + box.w;
+    const bottom = box.y + box.h;
+    return [
+        `M${box.x + r} ${box.y}`,
+        `H${right - r}`,
+        `A${r} ${r} 0 0 1 ${right} ${box.y + r}`,
+        `V${bottom - r}`,
+        `A${r} ${r} 0 0 1 ${right - r} ${bottom}`,
+        `H${box.x + r}`,
+        `A${r} ${r} 0 0 1 ${box.x} ${bottom - r}`,
+        `V${box.y + r}`,
+        `A${r} ${r} 0 0 1 ${box.x + r} ${box.y}`,
+        'Z'
+    ].join(' ');
+}
+
+export function shapePaths(shape: DiagramShape | undefined, box: Rect): ShapePaths {
+    const right = box.x + box.w;
+    const bottom = box.y + box.h;
+    const middleX = Math.round(box.x + box.w / 2);
+    const middleY = Math.round(box.y + box.h / 2);
+    switch (shape ?? 'rect') {
+        case 'round':
+            return { body: roundedRect(box, ROUND_RADIUS), detail: null };
+        case 'pill':
+            return { body: roundedRect(box, box.h / 2), detail: null };
+        case 'diamond':
+            return { body: `M${middleX} ${box.y} L${right} ${middleY} L${middleX} ${bottom} L${box.x} ${middleY} Z`, detail: null };
+        case 'cylinder': {
+            const lid = Math.round(box.h * LID_RATIO);
+            const rx = Math.round(box.w / 2);
+            const ry = Math.round(lid / 2);
+            const top = box.y + ry;
+            const base = bottom - ry;
+            return {
+                body: `M${box.x} ${top} A${rx} ${ry} 0 0 1 ${right} ${top} V${base} A${rx} ${ry} 0 0 1 ${box.x} ${base} Z`,
+                detail: `M${box.x} ${top} A${rx} ${ry} 0 0 0 ${right} ${top}`
+            };
+        }
+        default:
+            return { body: `M${box.x} ${box.y} H${right} V${bottom} H${box.x} Z`, detail: null };
+    }
+}
+
+export interface TextLine {
+    text: string;
+    x: number;
+    y: number;
+    size: number;
+    bold: boolean;
+    muted: boolean;
+}
+
+export function textLinesOf(box: Pick<NodeBox, 'x' | 'y' | 'w' | 'h' | 'label' | 'sub'>, shape?: DiagramShape): TextLine[] {
+    const x = Math.round(box.x + box.w / 2);
+    const height = box.label.length * LABEL_LINE + box.sub.length * SUB_LINE;
+    // The lid of a cylinder takes the top of the box, so its text sits below it.
+    const top = Math.round(box.y + (box.h - height) / 2) + (shape === 'cylinder' ? CYLINDER_LID / 2 : 0);
+    const label = box.label.map((text, index) => ({ text, x, y: top + index * LABEL_LINE + 14, size: LABEL_SIZE, bold: true, muted: false }));
+    const subTop = top + box.label.length * LABEL_LINE;
+    const sub = box.sub.map((text, index) => ({ text, x, y: subTop + index * SUB_LINE + 12, size: SUB_SIZE, bold: false, muted: true }));
+    return [...label, ...sub];
+}
+
+export function edgeLabelLinesOf(label: EdgeLabelBox): TextLine[] {
+    const x = Math.round(label.x + label.w / 2);
+    return label.lines.map((text, index) => ({
+        text,
+        x,
+        y: label.y + EDGE_LABEL_PADDING.y + index * SUB_LINE + 12,
+        size: SUB_SIZE,
+        bold: false,
+        muted: false
+    }));
+}
+
+export function edgePath(points: readonly Point[]): string {
+    return points.map((point, index) => `${index === 0 ? 'M' : 'L'}${point.x} ${point.y}`).join(' ');
+}
+
+export function arrowHeadPath(points: readonly Point[]): string {
+    const tip = points.at(-1)!;
+    const before = points.at(-2) ?? tip;
+    const length = Math.hypot(tip.x - before.x, tip.y - before.y) || 1;
+    const ux = (tip.x - before.x) / length;
+    const uy = (tip.y - before.y) / length;
+    const baseX = tip.x - ux * HEAD_LENGTH;
+    const baseY = tip.y - uy * HEAD_LENGTH;
+    const round = Math.round;
+    return `M${tip.x} ${tip.y} L${round(baseX - uy * HEAD_WIDTH)} ${round(baseY + ux * HEAD_WIDTH)} L${round(baseX + uy * HEAD_WIDTH)} ${round(baseY - ux * HEAD_WIDTH)} Z`;
+}
+
+export function dashOf(style: DiagramEdgeStyle | undefined): string | null {
+    if (style === 'dashed') {
+        return '8 6';
+    }
+    if (style === 'dotted') {
+        return '2 5';
+    }
+    return null;
+}

package/src/svg.ts

@@ -0,0 +1,103 @@
+import type { DrawingColor } from '@adecore/drawing/protocol';
+import type { DiagramDocument } from './protocol.ts';
+import { DEFAULT_FONT_STACKS, DEFAULT_PALETTE, DEFAULT_PAPER } from '@adecore/drawing';
+import { GROUP_LABEL_BAND, layoutOf, type DiagramLayout } from './layout.ts';
+import { arrowHeadPath, dashOf, edgeLabelLinesOf, edgePath, shapePaths, textLinesOf } from './shapes.ts';
+import { SUB_SIZE } from './text.ts';
+
+export interface DiagramSvgOptions {
+    /* What every palette name is in the theme this export is made in. */
+    palette?: Record<DrawingColor, string>;
+    /* The pale fill behind a node of each tone. */
+    paper?: Record<DrawingColor, string>;
+    /* The page behind the diagram, or null for a transparent one; edge labels are haloed in it. */
+    background?: string | null;
+    /* World units around the diagram, so nothing touches the edge. */
+    margin?: number;
+    font?: string;
+    /* A layout already computed for this document, so a caller that drew it does not compute it twice. */
+    layout?: DiagramLayout;
+}
+
+export const DEFAULT_DIAGRAM_MARGIN = 32;
+
+/* What a node, a group and an edge wear when the file names no tone. */
+export const DEFAULT_NODE_TONE: DrawingColor = 'ink';
+export const DEFAULT_GROUP_TONE: DrawingColor = 'muted';
+export const DEFAULT_EDGE_TONE: DrawingColor = 'muted';
+
+// XML has no way to write a control character other than tab and the line breaks, not even escaped.
+// oxlint-disable-next-line no-control-regex
+const NOT_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g;
+
+function escapeXml(value: string): string {
+    return value.replace(NOT_XML, '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+
+/*
+ * The whole diagram as one SVG string, for an export and for what the daemon hands an agent. The
+ * view in the app draws the same layout and the same paths as elements of its own, so the two only
+ * differ in where the colors come from.
+ */
+export function toSvg(document: Pick<DiagramDocument, 'meta' | 'nodes' | 'groups' | 'edges'>, options: DiagramSvgOptions = {}): string {
+    const palette = options.palette ?? DEFAULT_PALETTE;
+    const paper = options.paper ?? DEFAULT_PAPER;
+    const margin = options.margin ?? DEFAULT_DIAGRAM_MARGIN;
+    const font = escapeXml(options.font ?? DEFAULT_FONT_STACKS.sans);
+    const layout = options.layout ?? layoutOf(document);
+    const nodes = new Map(document.nodes.map((node) => [node.id, node]));
+    const groups = new Map(document.groups.map((group) => [group.id, group]));
+
+    const x = layout.bounds.x - margin;
+    const y = layout.bounds.y - margin;
+    const w = layout.bounds.w + margin * 2;
+    const h = layout.bounds.h + margin * 2;
+    const parts: string[] = [];
+    if (options.background) {
+        parts.push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="${options.background}"/>`);
+    }
+
+    for (const box of layout.groups) {
+        const group = groups.get(box.id)!;
+        const tone = palette[group.tone ?? DEFAULT_GROUP_TONE];
+        parts.push(
+            `<rect x="${box.x}" y="${box.y}" width="${box.w}" height="${box.h}" rx="12" fill="none" stroke="${tone}" stroke-width="1" stroke-dasharray="6 4"/>`,
+            `<text x="${box.labelBox.x}" y="${box.y + Math.round(GROUP_LABEL_BAND * 0.7)}" font-size="${SUB_SIZE}" font-weight="600" fill="${tone}">${escapeXml(group.label)}</text>`
+        );
+    }
+
+    for (const route of layout.edges) {
+        const edge = document.edges[route.index]!;
+        const tone = palette[edge.tone ?? DEFAULT_EDGE_TONE];
+        const dash = dashOf(edge.style);
+        parts.push(
+            `<path d="${edgePath(route.points)}" fill="none" stroke="${tone}" stroke-width="2" stroke-linejoin="round"${dash ? ` stroke-dasharray="${dash}"` : ''}/>`,
+            `<path d="${arrowHeadPath(route.points)}" fill="${tone}"/>`
+        );
+        if (route.label) {
+            const halo = options.background ? ` stroke="${options.background}" stroke-width="4" paint-order="stroke"` : '';
+            for (const line of edgeLabelLinesOf(route.label)) {
+                parts.push(
+                    `<text x="${line.x}" y="${line.y}" font-size="${line.size}" text-anchor="middle" fill="${tone}"${halo}>${escapeXml(line.text)}</text>`
+                );
+            }
+        }
+    }
+
+    for (const box of layout.nodes) {
+        const node = nodes.get(box.id)!;
+        const tone = node.tone ?? DEFAULT_NODE_TONE;
+        const paths = shapePaths(node.shape, box);
+        parts.push(`<path d="${paths.body}" fill="${paper[tone]}" stroke="${palette[tone]}" stroke-width="2"/>`);
+        if (paths.detail) {
+            parts.push(`<path d="${paths.detail}" fill="none" stroke="${palette[tone]}" stroke-width="2"/>`);
+        }
+        for (const line of textLinesOf(box, node.shape)) {
+            parts.push(
+                `<text x="${line.x}" y="${line.y}" font-size="${line.size}"${line.bold ? ' font-weight="600"' : ''} text-anchor="middle" fill="${line.muted ? palette.muted : palette.ink}">${escapeXml(line.text)}</text>`
+            );
+        }
+    }
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="${x} ${y} ${w} ${h}" font-family="${font}">${parts.join('')}</svg>`;
+}

package/src/text.ts

@@ -0,0 +1,92 @@
+export const LABEL_SIZE = 14;
+export const SUB_SIZE = 12;
+export const LABEL_LINE = 18;
+export const SUB_LINE = 16;
+
+const NARROW = new Set([..."ijl.,:;!|'"]);
+const SEMI = new Set([...' ftrI-()[]{}/\\`"*']);
+const WIDE_LOWER = new Set([...'mw']);
+const WIDE = new Set([...'MW@%&']);
+
+/*
+ * The width of a glyph as a share of the font size, per class of character. Measured in Chromium
+ * for the system face (SF on macOS) and Helvetica as a stand-in for Inter and Segoe UI, taking the
+ * wider of the two at weight 600, so an estimate errs towards a box that is a little too wide.
+ */
+function ratioOf(char: string): number {
+    if (NARROW.has(char)) {
+        return 0.3;
+    }
+    if (SEMI.has(char)) {
+        return 0.4;
+    }
+    if (WIDE_LOWER.has(char)) {
+        return 0.86;
+    }
+    if (WIDE.has(char)) {
+        return 1;
+    }
+    if (char >= 'a' && char <= 'z') {
+        return 0.6;
+    }
+    if (char >= 'A' && char <= 'Z') {
+        return 0.74;
+    }
+    if (char >= '0' && char <= '9') {
+        return 0.64;
+    }
+    // CJK and everything after it is set on a full em; any other letter is taken as a wide Latin one.
+    return char.codePointAt(0)! >= 0x2e80 ? 1 : 0.64;
+}
+
+const REGULAR = 0.94;
+
+/* No DOM in this package, so text is estimated rather than measured, the same way on every machine. */
+export function estimateTextWidth(text: string, size: number, bold = false): number {
+    let units = 0;
+    for (const char of text) {
+        units += ratioOf(char);
+    }
+    return Math.ceil(units * size * (bold ? 1 : REGULAR));
+}
+
+function breakWord(word: string, size: number, bold: boolean, maxWidth: number): string[] {
+    const pieces: string[] = [];
+    let piece = '';
+    for (const char of word) {
+        if (piece !== '' && estimateTextWidth(piece + char, size, bold) > maxWidth) {
+            pieces.push(piece);
+            piece = '';
+        }
+        piece += char;
+    }
+    pieces.push(piece);
+    return pieces;
+}
+
+export function wrapText(text: string, size: number, bold: boolean, maxWidth: number): string[] {
+    const words = text
+        .trim()
+        .split(/\s+/)
+        .filter((word) => word !== '');
+    const lines: string[] = [];
+    let line = '';
+    for (const word of words) {
+        const pieces = estimateTextWidth(word, size, bold) > maxWidth ? breakWord(word, size, bold, maxWidth) : [word];
+        for (const piece of pieces) {
+            const joined = line === '' ? piece : `${line} ${piece}`;
+            if (line !== '' && estimateTextWidth(joined, size, bold) > maxWidth) {
+                lines.push(line);
+                line = piece;
+            } else {
+                line = joined;
+            }
+        }
+    }
+    lines.push(line);
+    return lines;
+}
+
+export function widestLine(lines: readonly string[], size: number, bold: boolean): number {
+    return lines.reduce((widest, line) => Math.max(widest, estimateTextWidth(line, size, bold)), 0);
+}