ts-prorm-orm 1.1.0

package/dist/diagrams/class-diagram.js

@@ -0,0 +1,384 @@
+"use strict";
+/**
+ * ClassDiagram — renders one or more classes as UML class boxes.
+ *
+ * Each class box has three compartments:
+ *  - a title bar (class name + optional «stereotype»),
+ *  - an attributes compartment (`+ name: type`, with +/-/# visibility markers),
+ *  - a methods compartment (`+ name(args): returnType`).
+ *
+ * Multiple classes are laid out in a responsive grid (wrapping after N
+ * columns). When a class declares `extends`, a UML inheritance connector
+ * (hollow triangle arrowhead) is drawn to its parent; when it declares plain
+ * associations, a simple line connector is drawn instead.
+ *
+ * `--theme light|dark` drives canvas/box/text colors and `--color <name|hex>`
+ * drives the accent used for title bars — both genuinely change fill/stroke
+ * values in the generated SVG.
+ *
+ * Usage:
+ *   const diag = new ClassDiagram({ classes: [ … ] });
+ *   diag.save('./diagrams/classes.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.ClassDiagram = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const palette_1 = require("./palette");
+const svg_dom_1 = require("./svg-dom");
+const VIS_MARK = {
+    public: '+',
+    private: '-',
+    protected: '#',
+};
+function visMark(v) {
+    return VIS_MARK[v ?? 'public'] ?? '+';
+}
+// ─── Main class ────────────────────────────────────────────────────────────
+class ClassDiagram {
+    constructor(options) {
+        this.opts = {
+            title: options.title ?? '',
+            theme: options.theme ?? 'light',
+            color: options.color ?? '',
+            columns: options.columns ?? 0,
+            ...options,
+            classes: options.classes ?? [],
+        };
+    }
+    boxHeight(cls) {
+        const attrs = cls.attributes ?? [];
+        const methods = cls.methods ?? [];
+        const titleH = ClassDiagram.TITLE_H + (cls.stereotype ? ClassDiagram.STEREO_EXTRA : 0);
+        const attrRows = Math.max(attrs.length, 1);
+        const methodRows = Math.max(methods.length, 1);
+        const attrH = attrRows * ClassDiagram.ROW_H + 2 * ClassDiagram.COMPARTMENT_PAD;
+        const methodH = methodRows * ClassDiagram.ROW_H + 2 * ClassDiagram.COMPARTMENT_PAD;
+        return { h: titleH + attrH + methodH, titleH, attrH };
+    }
+    layout() {
+        const classes = this.opts.classes;
+        const n = classes.length;
+        const cols = this.opts.columns && this.opts.columns > 0
+            ? this.opts.columns
+            : Math.max(1, Math.ceil(Math.sqrt(n)));
+        // Pre-measure heights per row to align rows to the tallest box.
+        const rows = Math.ceil(n / cols);
+        const rowHeights = new Array(rows).fill(0);
+        const measured = classes.map((c) => ({ c, ...this.boxHeight(c) }));
+        measured.forEach((m, i) => {
+            const r = Math.floor(i / cols);
+            if (m.h > rowHeights[r])
+                rowHeights[r] = m.h;
+        });
+        // Cumulative Y offset of each row.
+        const rowY = [];
+        let acc = ClassDiagram.PAD + (this.opts.title ? ClassDiagram.TITLE_BAR_H : 0);
+        for (let r = 0; r < rows; r++) {
+            rowY.push(acc);
+            acc += rowHeights[r] + ClassDiagram.GAP_Y;
+        }
+        const placed = [];
+        const byName = new Map();
+        measured.forEach((m, i) => {
+            const r = Math.floor(i / cols);
+            const c = i % cols;
+            const x = ClassDiagram.PAD + c * (ClassDiagram.BOX_W + ClassDiagram.GAP_X);
+            const y = rowY[r];
+            const p = {
+                cls: m.c,
+                x,
+                y,
+                w: ClassDiagram.BOX_W,
+                h: m.h,
+                titleH: m.titleH,
+                attrH: m.attrH,
+            };
+            placed.push(p);
+            byName.set(m.c.name, p);
+        });
+        return { placed, byName, cols, rowHeights };
+    }
+    generate() {
+        const { title, theme, color } = this.opts;
+        const accent = (0, palette_1.resolveAccent)(color);
+        const t = (0, palette_1.resolveTheme)(theme);
+        const { placed, byName, cols } = this.layout();
+        // Compute canvas bounds from placed boxes.
+        let maxRight = 0;
+        let maxBottom = 0;
+        for (const p of placed) {
+            maxRight = Math.max(maxRight, p.x + p.w);
+            maxBottom = Math.max(maxBottom, p.y + p.h);
+        }
+        const svgW = maxRight + ClassDiagram.PAD;
+        const svgH = maxBottom + ClassDiagram.PAD;
+        const doc = new svg_dom_1.SvgDocument(svgW, svgH);
+        const svg = doc.root;
+        // Background.
+        svg.child('rect', { width: svgW, height: svgH, fill: t.canvasBg });
+        // Accent gradient for title bars + a drop shadow.
+        doc.linearGradient('classHdr', [
+            [0, accent.from],
+            [55, accent.mid],
+            [100, accent.to],
+        ]);
+        const filter = doc
+            .defs()
+            .child('filter', { id: 'classShadow', x: '-8%', y: '-8%', width: '116%', height: '120%' });
+        filter.child('feDropShadow', { dx: 0, dy: 4, stdDeviation: 7, 'flood-color': '#00000022' });
+        // Optional diagram title.
+        if (title) {
+            svg
+                .child('text', {
+                x: ClassDiagram.PAD,
+                y: ClassDiagram.PAD + 8,
+                'font-family': 'system-ui,-apple-system,sans-serif',
+                'font-size': 20,
+                'font-weight': 800,
+                fill: t.textPrimary,
+            })
+                .text(title);
+        }
+        // ── Connectors (drawn first, under the boxes) ─────────────────────────
+        for (const p of placed) {
+            const cls = p.cls;
+            // Inheritance: hollow triangle at the parent.
+            if (cls.extends && byName.has(cls.extends)) {
+                const parent = byName.get(cls.extends);
+                this.drawInheritance(svg, p, parent, t, accent);
+            }
+            // Associations: plain line.
+            for (const assoc of cls.associations ?? []) {
+                const other = byName.get(assoc);
+                if (other && other !== p) {
+                    this.drawAssociation(svg, p, other, t);
+                }
+            }
+        }
+        // ── Class boxes (drawn on top of connectors) ──────────────────────────
+        for (const p of placed) {
+            this.drawClassBox(doc, svg, p, t, accent);
+        }
+        void cols;
+        return doc.toString('Generated by ts-prorm-orm ClassDiagram');
+    }
+    center(p) {
+        return { x: p.x + p.w / 2, y: p.y + p.h / 2 };
+    }
+    drawAssociation(svg, a, b, t) {
+        const c1 = this.center(a);
+        const c2 = this.center(b);
+        svg.child('line', {
+            x1: c1.x,
+            y1: c1.y,
+            x2: c2.x,
+            y2: c2.y,
+            stroke: t.textSecondary,
+            'stroke-width': 1.5,
+        });
+    }
+    drawInheritance(svg, child, parent, t, accent) {
+        const from = this.center(child);
+        const to = this.center(parent);
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const len = Math.hypot(dx, dy) || 1;
+        const ux = dx / len;
+        const uy = dy / len;
+        // Stop the line short of the parent so the arrowhead sits at the edge.
+        void parent;
+        const size = 12;
+        const lineEndX = to.x - ux * size * 1.6;
+        const lineEndY = to.y - uy * size * 1.6;
+        svg.child('line', {
+            x1: from.x,
+            y1: from.y,
+            x2: lineEndX,
+            y2: lineEndY,
+            stroke: accent.mid,
+            'stroke-width': 1.8,
+        });
+        // Hollow triangle arrowhead pointing at the parent center.
+        const tip = { x: to.x - ux * 2, y: to.y - uy * 2 };
+        // Perpendicular unit vector.
+        const px = -uy;
+        const py = ux;
+        const baseX = tip.x - ux * size;
+        const baseY = tip.y - uy * size;
+        const p1 = { x: baseX + px * (size * 0.7), y: baseY + py * (size * 0.7) };
+        const p2 = { x: baseX - px * (size * 0.7), y: baseY - py * (size * 0.7) };
+        svg.child('polygon', {
+            points: `${tip.x},${tip.y} ${p1.x},${p1.y} ${p2.x},${p2.y}`,
+            fill: t.cardBg,
+            stroke: accent.mid,
+            'stroke-width': 1.8,
+        });
+    }
+    drawClassBox(doc, svg, p, t, accent) {
+        const { cls, x, y, w, h, titleH, attrH } = p;
+        const attrs = cls.attributes ?? [];
+        const methods = cls.methods ?? [];
+        // Outer box.
+        svg.child('rect', {
+            x,
+            y,
+            width: w,
+            height: h,
+            rx: 8,
+            fill: t.cardBg,
+            stroke: t.border,
+            'stroke-width': 1.5,
+            filter: 'url(#classShadow)',
+        });
+        // Title bar (accent gradient).
+        svg.child('rect', {
+            x,
+            y,
+            width: w,
+            height: titleH,
+            rx: 8,
+            fill: 'url(#classHdr)',
+        });
+        // Square off the bottom of the rounded title bar.
+        svg.child('rect', { x, y: y + titleH - 8, width: w, height: 8, fill: 'url(#classHdr)' });
+        let titleTextY = y + 26;
+        if (cls.stereotype) {
+            svg
+                .child('text', {
+                x: x + w / 2,
+                y: y + 18,
+                'font-family': 'system-ui,sans-serif',
+                'font-size': 11,
+                'font-style': 'italic',
+                fill: 'rgba(255,255,255,0.85)',
+                'text-anchor': 'middle',
+            })
+                .text(`«${cls.stereotype}»`);
+            titleTextY = y + 34;
+        }
+        svg
+            .child('text', {
+            x: x + w / 2,
+            y: titleTextY,
+            'font-family': 'system-ui,-apple-system,sans-serif',
+            'font-size': 15,
+            'font-weight': 800,
+            fill: '#FFFFFF',
+            'text-anchor': 'middle',
+        })
+            .text(cls.name);
+        // Attributes compartment.
+        const attrTop = y + titleH;
+        svg.child('rect', { x, y: attrTop, width: w, height: attrH, fill: t.rowAlt });
+        svg.child('line', {
+            x1: x,
+            y1: attrTop,
+            x2: x + w,
+            y2: attrTop,
+            stroke: t.border,
+            'stroke-width': 1,
+        });
+        attrs.forEach((a, i) => {
+            const rowY = attrTop + ClassDiagram.COMPARTMENT_PAD + i * ClassDiagram.ROW_H + 15;
+            const typePart = a.type ? `: ${a.type}` : '';
+            const label = `${visMark(a.visibility)} ${a.name}${typePart}`;
+            svg
+                .child('text', {
+                x: x + 12,
+                y: rowY,
+                'font-family': "'SF Mono','Fira Code',monospace",
+                'font-size': 12,
+                'font-weight': 500,
+                'text-decoration': a.static ? 'underline' : undefined,
+                fill: t.textPrimary,
+            })
+                .text(label);
+        });
+        // Methods compartment.
+        const methodTop = attrTop + attrH;
+        svg.child('rect', { x, y: methodTop, width: w, height: h - titleH - attrH, fill: t.cardBg });
+        svg.child('line', {
+            x1: x,
+            y1: methodTop,
+            x2: x + w,
+            y2: methodTop,
+            stroke: t.border,
+            'stroke-width': 1,
+        });
+        methods.forEach((m, i) => {
+            const rowY = methodTop + ClassDiagram.COMPARTMENT_PAD + i * ClassDiagram.ROW_H + 15;
+            const retPart = m.returns ? `: ${m.returns}` : '';
+            const label = `${visMark(m.visibility)} ${m.name}(${m.args ?? ''})${retPart}`;
+            svg
+                .child('text', {
+                x: x + 12,
+                y: rowY,
+                'font-family': "'SF Mono','Fira Code',monospace",
+                'font-size': 12,
+                'font-weight': 500,
+                fill: t.textSecondary,
+            })
+                .text(label);
+        });
+        void doc;
+    }
+    /**
+     * 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 });
+        const svg = this.generate();
+        fs.writeFileSync(resolved, svg, 'utf-8');
+        return resolved;
+    }
+}
+exports.ClassDiagram = ClassDiagram;
+// Layout constants (px)
+ClassDiagram.BOX_W = 240;
+ClassDiagram.TITLE_H = 40;
+ClassDiagram.STEREO_EXTRA = 16;
+ClassDiagram.ROW_H = 22;
+ClassDiagram.COMPARTMENT_PAD = 8;
+ClassDiagram.GAP_X = 70;
+ClassDiagram.GAP_Y = 70;
+ClassDiagram.PAD = 32;
+ClassDiagram.TITLE_BAR_H = 44;