ts-prorm-orm 1.1.0

package/dist/diagrams/state-diagram.js

@@ -0,0 +1,344 @@
+"use strict";
+/**
+ * StateDiagram — generates a UML state-machine diagram as an SVG.
+ *
+ * Renders:
+ *  - normal states as rounded rectangles
+ *  - an initial pseudo-state as a filled black circle
+ *  - a final state as a ringed (double) circle
+ *  - transitions as arrows between states, labeled with their trigger/event
+ *  - self-transitions as loop arrows
+ *
+ * Great for showing a record lifecycle (e.g. draft → active → archived →
+ * deleted). States are auto-placed left-to-right in a wrapping grid unless
+ * explicit x/y hints are supplied per state. The SVG viewBox is auto-sized.
+ *
+ * Both `--theme light|dark` and `--color <name|hex>` genuinely change the
+ * output: the accent drives state fills + arrowheads, the theme drives the
+ * canvas background, text and borders.
+ *
+ * Usage:
+ *   const diag = new StateDiagram({
+ *     states: [
+ *       { name: 'start', initial: true },
+ *       { name: 'draft' },
+ *       { name: 'active' },
+ *       { name: 'archived', final: true },
+ *     ],
+ *     transitions: [
+ *       { from: 'start', to: 'draft' },
+ *       { from: 'draft', to: 'active', event: 'publish' },
+ *       { from: 'active', to: 'active', event: 'edit' },
+ *       { from: 'active', to: 'archived', event: 'archive' },
+ *     ],
+ *   });
+ *   diag.save('./diagrams/lifecycle.svg');
+ *   // or:
+ *   const svgString = diag.generate();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateDiagram = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const palette_1 = require("./palette");
+const svg_dom_1 = require("./svg-dom");
+// ─── Main class ────────────────────────────────────────────────────────────
+class StateDiagram {
+    constructor(options) {
+        this.opts = {
+            states: options.states ?? [],
+            transitions: options.transitions ?? [],
+            title: options.title ?? '',
+            theme: options.theme ?? 'light',
+            color: options.color ?? '',
+        };
+    }
+    // ── Auto-place states in a wrapping row/grid (honoring x/y hints) ─────────
+    layout() {
+        const { states } = this.opts;
+        const PAD = StateDiagram.PAD;
+        const TITLE_H = this.opts.title ? StateDiagram.TITLE_H : 0;
+        const BOX_W = StateDiagram.BOX_W;
+        const BOX_H = StateDiagram.BOX_H;
+        const GAP_X = StateDiagram.GAP_X;
+        const GAP_Y = StateDiagram.GAP_Y;
+        const PER_ROW = StateDiagram.PER_ROW;
+        const CELL_W = BOX_W + GAP_X;
+        const CELL_H = BOX_H + GAP_Y;
+        const topBase = PAD + TITLE_H + StateDiagram.GAP_Y / 2;
+        const placed = new Map();
+        let maxX = 0;
+        let maxY = 0;
+        states.forEach((node, i) => {
+            const col = i % PER_ROW;
+            const row = Math.floor(i / PER_ROW);
+            // Auto cell top-left, or explicit hint.
+            const boxLeft = node.x ?? PAD + col * CELL_W;
+            const boxTop = node.y ?? topBase + row * CELL_H;
+            const isMarker = !!(node.initial || node.final);
+            const hw = isMarker ? StateDiagram.PSEUDO_R : BOX_W / 2;
+            const hh = isMarker ? StateDiagram.PSEUDO_R : BOX_H / 2;
+            // Center within the nominal box footprint so markers align with rows.
+            const cx = boxLeft + BOX_W / 2;
+            const cy = boxTop + BOX_H / 2;
+            placed.set(node.name, { node, cx, cy, hw, hh });
+            maxX = Math.max(maxX, cx + BOX_W / 2);
+            maxY = Math.max(maxY, cy + BOX_H / 2);
+        });
+        const width = maxX + PAD;
+        const height = maxY + PAD;
+        return { placed, width, height };
+    }
+    // ── Compute a point on the box perimeter toward a target point ────────────
+    edgePoint(p, tx, ty) {
+        const dx = tx - p.cx;
+        const dy = ty - p.cy;
+        if (dx === 0 && dy === 0)
+            return { x: p.cx, y: p.cy };
+        const scaleX = dx !== 0 ? p.hw / Math.abs(dx) : Infinity;
+        const scaleY = dy !== 0 ? p.hh / Math.abs(dy) : Infinity;
+        const s = Math.min(scaleX, scaleY);
+        return { x: p.cx + dx * s, y: p.cy + dy * s };
+    }
+    // ── Generate full SVG string (built via a real DOM document) ──────────────
+    generate() {
+        const { title, theme, color } = this.opts;
+        const accent = (0, palette_1.resolveAccent)(color);
+        const t = (0, palette_1.resolveTheme)(theme);
+        const { placed, width, height } = this.layout();
+        const PAD = StateDiagram.PAD;
+        const R = StateDiagram.R;
+        const doc = new svg_dom_1.SvgDocument(width, height);
+        const svg = doc.root;
+        // ── Background ──────────────────────────────────────────────────────
+        svg.child('rect', { width, height, fill: t.canvasBg });
+        // ── Defs: arrowhead marker + state fill gradient ────────────────────
+        doc.linearGradient('stateFill', [
+            [0, accent.mid],
+            [100, accent.from],
+        ]);
+        const marker = doc.defs().child('marker', {
+            id: 'arrow',
+            markerWidth: 10,
+            markerHeight: 10,
+            refX: 8,
+            refY: 3,
+            orient: 'auto',
+            markerUnits: 'strokeWidth',
+        });
+        marker.child('path', { d: 'M0,0 L8,3 L0,6 Z', fill: accent.mid });
+        // ── Title ───────────────────────────────────────────────────────────
+        if (title) {
+            svg
+                .child('text', {
+                x: PAD,
+                y: PAD + 8,
+                'font-family': 'system-ui,-apple-system,sans-serif',
+                'font-size': 22,
+                'font-weight': 800,
+                fill: t.textPrimary,
+            })
+                .text(title);
+        }
+        // ── Transitions (drawn first so states sit on top) ──────────────────
+        this.opts.transitions.forEach((tr) => {
+            const from = placed.get(tr.from);
+            const to = placed.get(tr.to);
+            if (!from || !to)
+                return;
+            if (tr.from === tr.to) {
+                this.drawSelfLoop(svg, from, tr.event, accent.mid, t.textSecondary);
+            }
+            else {
+                this.drawTransition(svg, from, to, tr.event, accent.mid, t.textSecondary);
+            }
+        });
+        // ── States ──────────────────────────────────────────────────────────
+        placed.forEach((p) => {
+            const node = p.node;
+            if (node.initial) {
+                // Filled black circle (initial pseudo-state).
+                svg.child('circle', {
+                    cx: p.cx,
+                    cy: p.cy,
+                    r: StateDiagram.PSEUDO_R,
+                    fill: '#111111',
+                    stroke: t.border,
+                    'stroke-width': 1,
+                });
+            }
+            else if (node.final) {
+                // Ringed circle (final state): outer ring + filled accent core.
+                svg.child('circle', {
+                    cx: p.cx,
+                    cy: p.cy,
+                    r: StateDiagram.PSEUDO_R,
+                    fill: 'none',
+                    stroke: t.textPrimary,
+                    'stroke-width': 2,
+                });
+                svg.child('circle', {
+                    cx: p.cx,
+                    cy: p.cy,
+                    r: StateDiagram.PSEUDO_R - 6,
+                    fill: accent.mid,
+                });
+            }
+            else {
+                // Normal state: rounded rectangle with accent fill.
+                svg.child('rect', {
+                    x: p.cx - p.hw,
+                    y: p.cy - p.hh,
+                    width: p.hw * 2,
+                    height: p.hh * 2,
+                    rx: R,
+                    fill: 'url(#stateFill)',
+                    stroke: accent.from,
+                    'stroke-width': 2,
+                });
+                svg
+                    .child('text', {
+                    x: p.cx,
+                    y: p.cy + 5,
+                    'font-family': 'system-ui,-apple-system,sans-serif',
+                    'font-size': 15,
+                    'font-weight': 700,
+                    fill: '#FFFFFF',
+                    'text-anchor': 'middle',
+                })
+                    .text(node.name);
+            }
+            // Label markers (initial/final) beneath the circle.
+            if (node.initial || node.final) {
+                svg
+                    .child('text', {
+                    x: p.cx,
+                    y: p.cy + StateDiagram.PSEUDO_R + 16,
+                    'font-family': 'system-ui,sans-serif',
+                    'font-size': 11,
+                    'font-weight': 600,
+                    fill: t.textSecondary,
+                    'text-anchor': 'middle',
+                })
+                    .text(node.name);
+            }
+        });
+        return doc.toString('Generated by ts-prorm-orm StateDiagram');
+    }
+    // ── Draw a straight transition arrow with an optional event label ─────────
+    drawTransition(svg, from, to, event, stroke, labelColor) {
+        const start = this.edgePoint(from, to.cx, to.cy);
+        const end = this.edgePoint(to, from.cx, from.cy);
+        svg.child('line', {
+            x1: start.x,
+            y1: start.y,
+            x2: end.x,
+            y2: end.y,
+            stroke,
+            'stroke-width': 2,
+            'marker-end': 'url(#arrow)',
+        });
+        if (event) {
+            const mx = (start.x + end.x) / 2;
+            const my = (start.y + end.y) / 2;
+            this.drawEventLabel(svg, mx, my - 6, event, labelColor);
+        }
+    }
+    // ── Draw a self-transition loop arrow above the state ─────────────────────
+    drawSelfLoop(svg, p, event, stroke, labelColor) {
+        const topY = p.cy - p.hh;
+        const x1 = p.cx - p.hw * 0.4;
+        const x2 = p.cx + p.hw * 0.4;
+        const loopH = 34;
+        const d = `M${x1},${topY} C${x1 - 20},${topY - loopH} ${x2 + 20},${topY - loopH} ${x2},${topY}`;
+        svg.child('path', {
+            d,
+            fill: 'none',
+            stroke,
+            'stroke-width': 2,
+            'marker-end': 'url(#arrow)',
+        });
+        if (event) {
+            this.drawEventLabel(svg, p.cx, topY - loopH - 4, event, labelColor);
+        }
+    }
+    // ── Draw an event label with a subtle background pill for legibility ───────
+    drawEventLabel(svg, x, y, event, color) {
+        const w = event.length * 7 + 12;
+        svg.child('rect', {
+            x: x - w / 2,
+            y: y - 13,
+            width: w,
+            height: 18,
+            rx: 6,
+            fill: '#FFFFFF',
+            opacity: 0.85,
+        });
+        svg
+            .child('text', {
+            x,
+            y: y - 1,
+            'font-family': "'SF Mono','Fira Code',monospace",
+            'font-size': 11,
+            'font-weight': 600,
+            fill: color,
+            'text-anchor': 'middle',
+        })
+            .text(event);
+    }
+    /**
+     * Write the SVG to a file. Creates parent directories if needed.
+     */
+    save(outputPath) {
+        const resolved = path.resolve(outputPath);
+        const dir = path.dirname(resolved);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(resolved, this.generate(), 'utf-8');
+        return resolved;
+    }
+}
+exports.StateDiagram = StateDiagram;
+// Layout constants (px)
+StateDiagram.PAD = 40;
+StateDiagram.TITLE_H = 44;
+StateDiagram.BOX_W = 150;
+StateDiagram.BOX_H = 60;
+StateDiagram.PSEUDO_R = 14; // radius for initial/final markers
+StateDiagram.GAP_X = 90;
+StateDiagram.GAP_Y = 80;
+StateDiagram.PER_ROW = 4;
+StateDiagram.R = 16; // box border-radius

package/dist/diagrams/svg-dom.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * svg-dom — a small DOM-backed SVG builder shared by every diagram generator.
+ *
+ * Diagrams are constructed against a real DOM document (via `@xmldom/xmldom`)
+ * using `createElement`/`setAttribute`/`appendChild`, then serialized once with
+ * `XMLSerializer`. This replaces hand-concatenated markup strings: attribute
+ * values are escaped by the serializer, element nesting can't be malformed, and
+ * every generator shares one construction API.
+ *
+ * The `El` wrapper is a thin fluent facade over a DOM `Element` — `.attr()`,
+ * `.text()`, `.child()` — so generator code reads declaratively while the
+ * underlying nodes remain inspectable/testable as real DOM.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SvgDocument = exports.El = void 0;
+const xmldom_1 = require("@xmldom/xmldom");
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/** Fluent wrapper around a DOM Element. */
+class El {
+    constructor(node, doc) {
+        this.node = node;
+        this.doc = doc;
+    }
+    /** Set one attribute (skipped when value is null/undefined). */
+    attr(name, value) {
+        if (value !== undefined && value !== null)
+            this.node.setAttribute(name, String(value));
+        return this;
+    }
+    /** Set many attributes at once. */
+    attrs(map) {
+        for (const [k, v] of Object.entries(map))
+            this.attr(k, v);
+        return this;
+    }
+    /** Append a text node (returns this for chaining). */
+    text(value) {
+        this.node.appendChild(this.doc.createTextNode(String(value)));
+        return this;
+    }
+    /** Create + append a child element, returning the CHILD. */
+    child(tag, attrs) {
+        const c = new El(this.doc.createElementNS(SVG_NS, tag), this.doc);
+        if (attrs)
+            c.attrs(attrs);
+        this.node.appendChild(c.node);
+        return c;
+    }
+    /** Append an already-built El as a child; returns this (the parent). */
+    append(...children) {
+        for (const c of children)
+            this.node.appendChild(c.node);
+        return this;
+    }
+}
+exports.El = El;
+/** A DOM-backed SVG document builder. */
+class SvgDocument {
+    constructor(width, height, viewBox) {
+        this.doc = new xmldom_1.DOMImplementation().createDocument(SVG_NS, 'svg', null);
+        this.root = new El(this.doc.documentElement, this.doc);
+        this.root.attrs({
+            xmlns: SVG_NS,
+            width,
+            height,
+            viewBox: viewBox ?? `0 0 ${width} ${height}`,
+        });
+    }
+    /** Create a standalone element not yet attached to the tree. */
+    create(tag, attrs) {
+        const el = new El(this.doc.createElementNS(SVG_NS, tag), this.doc);
+        if (attrs)
+            el.attrs(attrs);
+        return el;
+    }
+    /** Get (creating on first use) the shared <defs> block. */
+    defs() {
+        if (!this._defs) {
+            this._defs = this.create('defs');
+            // defs should be the first child so gradients/filters resolve.
+            this.doc.documentElement.insertBefore(this._defs.node, this.doc.documentElement.firstChild);
+        }
+        return this._defs;
+    }
+    /**
+     * Convenience: add a linear gradient to <defs> and return its id.
+     * `stops` is a list of [offsetPercent, color] pairs.
+     */
+    linearGradient(id, stops, opts) {
+        const g = this.defs().child('linearGradient', {
+            id,
+            x1: opts?.x1 ?? 0,
+            y1: opts?.y1 ?? 0,
+            x2: opts?.x2 ?? 1,
+            y2: opts?.y2 ?? 1,
+            gradientUnits: 'objectBoundingBox',
+        });
+        for (const [offset, color] of stops) {
+            g.child('stop', { offset: `${offset}%`, 'stop-color': color });
+        }
+        return id;
+    }
+    /** Serialize the whole document to an XML/SVG string (with XML prolog). */
+    toString(comment) {
+        const body = new xmldom_1.XMLSerializer().serializeToString(this.doc);
+        const prolog = `<?xml version="1.0" encoding="UTF-8"?>`;
+        return comment ? `${prolog}\n<!-- ${comment} -->\n${body}` : `${prolog}\n${body}`;
+    }
+}
+exports.SvgDocument = SvgDocument;