@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/structure/UmlClassDiagram.js

@@ -0,0 +1,435 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { StructureText } from "./StructureText.js";
+import { UmlDetail, UmlDirection, UmlRelation, UmlRouting } from "./structureEnums.js";
+import { UmlLayout } from "./UmlLayout.js";
+// src/charts/structure/UmlClassDiagram.ts
+var LINE = 14;
+var MEMBER = 10.5;
+var MAX_WIDTH = 216;
+var PRIORITY = {
+	[UmlRelation.Inheritance]: 0,
+	[UmlRelation.Realization]: 0,
+	[UmlRelation.Composition]: 1,
+	[UmlRelation.Aggregation]: 1,
+	[UmlRelation.Association]: 2,
+	[UmlRelation.Dependency]: 3
+};
+var DASHED = /* @__PURE__ */ new Set([UmlRelation.Realization, UmlRelation.Dependency]);
+var UPWARD = /* @__PURE__ */ new Set([UmlRelation.Inheritance, UmlRelation.Realization]);
+/** UML class diagram in layers: generalisations point up, wholes sit above their parts, and boxes never overlap. */
+var UmlClassDiagram = class UmlClassDiagram extends Chart2D {
+	static meta = {
+		id: "uml-class-diagram",
+		name: "UML class diagram",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Lays out classes with their fields and methods, joined by correctly marked generalisation, whole-part and association edges.",
+		tags: [
+			"uml",
+			"class",
+			"software",
+			"inheritance"
+		],
+		sample: (seed) => UmlClassDiagram.ordering(seed),
+		variants: {
+			direction: [UmlDirection.TopDown, UmlDirection.LeftRight],
+			routing: [UmlRouting.Orthogonal, UmlRouting.Direct],
+			detail: [
+				UmlDetail.Full,
+				UmlDetail.Public,
+				UmlDetail.Names
+			],
+			adornments: [true, false]
+		}
+	};
+	/** An order-taking domain model; the seed decides which optional payment type it includes. */
+	static ordering(seed) {
+		const voucher = +SampleData.categories(seed, 1, 1)[0].value % 2 === 0;
+		const nodes = [
+			{
+				id: "Customer",
+				fields: ["- id: UUID", "- email: string"],
+				methods: ["+ placeOrder(): Order"]
+			},
+			{
+				id: "Order",
+				fields: ["- placedAt: Date", "- status: Status"],
+				methods: ["+ total(): Money", "+ cancel(): void"]
+			},
+			{
+				id: "OrderLine",
+				fields: ["- quantity: int"],
+				methods: ["+ subtotal(): Money"]
+			},
+			{
+				id: "Product",
+				fields: ["- sku: string", "- price: Money"],
+				methods: ["+ inStock(): bool"]
+			},
+			{
+				id: "Payment",
+				abstract: true,
+				fields: ["# amount: Money"],
+				methods: ["+ capture(): bool"]
+			},
+			{
+				id: "CardPayment",
+				fields: ["- token: string"],
+				methods: ["+ capture(): bool"]
+			},
+			{
+				id: "BankTransfer",
+				fields: ["- iban: string"],
+				methods: ["+ capture(): bool"]
+			},
+			{
+				id: "Refundable",
+				stereotype: "interface",
+				methods: ["+ refund(): bool"]
+			}
+		];
+		const links = [
+			{
+				source: "Customer",
+				target: "Order",
+				kind: UmlRelation.Association,
+				label: "places",
+				sourceEnd: "1",
+				targetEnd: "0..*"
+			},
+			{
+				source: "Order",
+				target: "OrderLine",
+				kind: UmlRelation.Composition,
+				sourceEnd: "1",
+				targetEnd: "1..*"
+			},
+			{
+				source: "OrderLine",
+				target: "Product",
+				kind: UmlRelation.Association,
+				sourceEnd: "0..*",
+				targetEnd: "1"
+			},
+			{
+				source: "Order",
+				target: "Payment",
+				kind: UmlRelation.Aggregation,
+				sourceEnd: "1",
+				targetEnd: "0..*"
+			},
+			{
+				source: "CardPayment",
+				target: "Payment",
+				kind: UmlRelation.Inheritance
+			},
+			{
+				source: "BankTransfer",
+				target: "Payment",
+				kind: UmlRelation.Inheritance
+			},
+			{
+				source: "CardPayment",
+				target: "Refundable",
+				kind: UmlRelation.Realization
+			}
+		];
+		if (voucher) {
+			nodes.push({
+				id: "Voucher",
+				fields: ["- code: string"],
+				methods: ["+ capture(): bool"]
+			});
+			links.push({
+				source: "Voucher",
+				target: "Payment",
+				kind: UmlRelation.Inheritance
+			});
+		}
+		return {
+			nodes,
+			links
+		};
+	}
+	defaults() {
+		return {
+			direction: UmlDirection.TopDown,
+			routing: UmlRouting.Orthogonal,
+			detail: UmlDetail.Full,
+			adornments: true
+		};
+	}
+	plotMargin() {
+		return {
+			top: 8,
+			right: 12,
+			bottom: 8,
+			left: 12
+		};
+	}
+	legendItems() {
+		return [];
+	}
+	boxView(node) {
+		const { detail } = this.options;
+		const keep = (members) => detail === UmlDetail.Names ? [] : (members ?? []).filter((member) => detail === UmlDetail.Full || !/^[-#~]/.test(member.trim()));
+		const fields = keep(node.fields), methods = keep(node.methods);
+		const name = String(node.id);
+		const head = 24 + (node.stereotype ? 12 : 0);
+		const widest = Math.max(name.length * 7, (node.stereotype?.length ?? 0) * 5.6 + 12, ...[...fields, ...methods].map((member) => StructureText.width(member, MEMBER)));
+		const width = Math.min(MAX_WIDTH, Math.max(84, Math.ceil(widest) + 16));
+		if (detail === UmlDetail.Names) return {
+			node,
+			id: name,
+			width,
+			height: head,
+			head,
+			fields,
+			methods,
+			dividers: []
+		};
+		const upper = fields.length ? fields.length * LINE + 6 : 8, lower = methods.length ? methods.length * LINE + 6 : 8;
+		return {
+			node,
+			id: name,
+			width,
+			height: head + upper + lower,
+			head,
+			fields,
+			methods,
+			dividers: [head, head + upper]
+		};
+	}
+	draw(ctx) {
+		const { direction, routing, adornments } = this.options;
+		const data = this.options.data ?? {
+			nodes: [],
+			links: []
+		};
+		const horizontal = direction === UmlDirection.LeftRight;
+		const seen = /* @__PURE__ */ new Set();
+		const nodes = (data.nodes ?? []).filter((node) => {
+			if (node?.id === null || node?.id === void 0 || seen.has(String(node.id))) return false;
+			seen.add(String(node.id));
+			return true;
+		});
+		const links = (data.links ?? []).filter((link) => seen.has(String(link.source)) && seen.has(String(link.target)));
+		const views = nodes.map((node) => this.boxView(node));
+		const edges = links.map((link) => {
+			const kind = link.kind ?? UmlRelation.Association, source = String(link.source), target = String(link.target);
+			const up = UPWARD.has(kind);
+			return {
+				upper: up ? target : source,
+				lower: up ? source : target,
+				priority: PRIORITY[kind],
+				trunk: up ? `${target}:${kind}` : null
+			};
+		});
+		const plan = UmlLayout.place(views, edges, {
+			horizontal,
+			orthogonal: routing === UmlRouting.Orthogonal,
+			clearance: adornments ? 30 : 18
+		});
+		const reach = 2;
+		const scale = plan.width ? Math.min(1, (ctx.plot.width - reach) / plan.width, (ctx.plot.height - reach) / plan.height) : 1;
+		const left = (ctx.plot.width - plan.width * scale) / 2, top = (ctx.plot.height - plan.height * scale) / 2;
+		const stage = ctx.nest(`translate(${left},${top}) scale(${scale})`, "uml");
+		const byId = new Map(views.map((view) => [view.id, view]));
+		const placed = plan.boxes.map((box) => ({
+			view: byId.get(box.id),
+			box
+		}));
+		const routes = links.map((link, i) => {
+			const kind = link.kind ?? UmlRelation.Association;
+			const points = edges[i].upper === String(link.source) ? plan.routes[i] : [...plan.routes[i]].reverse();
+			return {
+				key: `${i}:${link.source}>${link.target}`,
+				link,
+				kind,
+				points
+			};
+		});
+		const lines = stage.marks("edges", "path", routes, (d) => d.key).attr("fill", "none").attr("stroke", ctx.theme.inkSecondary).attr("stroke-width", 1.5).attr("stroke-linejoin", "round").attr("stroke-dasharray", (d) => DASHED.has(d.kind) ? "6 4" : null);
+		ctx.set(lines, { d: (d) => `M${d.points.map((point) => `${point.x},${point.y}`).join("L")}` });
+		ctx.hover(lines, (d) => ({
+			title: `${d.link.source} → ${d.link.target}`,
+			rows: [["Relation", d.kind], ...d.link.label ? [["Name", d.link.label]] : []]
+		}));
+		const heads = routes.flatMap((route) => this.heads(route));
+		const glyphs = stage.marks("heads", "path", heads, (d) => d.key).attr("stroke", ctx.theme.inkSecondary).attr("stroke-width", 1.5).attr("stroke-linejoin", "round").attr("fill", (d) => d.open ? "none" : d.filled ? ctx.theme.inkSecondary : ctx.theme.surface);
+		ctx.set(glyphs, { d: (d) => d.d });
+		const boxes = stage.marks("boxes", "rect", placed, (d) => d.box.id).attr("fill", ctx.theme.surface).attr("stroke", ctx.theme.axis).attr("stroke-width", 1.5).attr("rx", 3);
+		ctx.set(boxes, {
+			x: (d) => d.box.x,
+			y: (d) => d.box.y,
+			width: (d) => d.box.width,
+			height: (d) => d.box.height
+		});
+		ctx.hover(boxes, (d) => ({
+			title: d.box.id,
+			rows: [["Fields", d.view.node.fields?.length ?? 0], ["Methods", d.view.node.methods?.length ?? 0]]
+		}));
+		const heads2 = stage.marks("titles", "rect", placed, (d) => d.box.id).attr("fill", ctx.theme.grid).attr("rx", 3).attr("pointer-events", "none");
+		ctx.set(heads2, {
+			x: (d) => d.box.x + 1,
+			y: (d) => d.box.y + 1,
+			width: (d) => d.box.width - 2,
+			height: (d) => (d.view.dividers.length ? d.view.head : d.box.height) - 2
+		});
+		const dividers = placed.flatMap(({ box, view }) => view.dividers.map((at, i) => ({
+			key: `${box.id}:${i}`,
+			x1: box.x,
+			x2: box.x + box.width,
+			y: box.y + at
+		})));
+		const rules = stage.marks("dividers", "line", dividers, (d) => d.key).attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		ctx.set(rules, {
+			x1: (d) => d.x1,
+			x2: (d) => d.x2,
+			y1: (d) => d.y,
+			y2: (d) => d.y
+		});
+		const texts = ctx.text(stage.marks("text", "text", placed.flatMap((item) => this.lines(item)), (d) => d.key), MEMBER).attr("pointer-events", "none").attr("font-size", (d) => d.size).attr("font-weight", (d) => d.bold ? 600 : 400).attr("font-style", (d) => d.italic ? "italic" : null).attr("text-anchor", (d) => d.anchor).attr("fill", (d) => d.muted ? ctx.theme.inkSecondary : ctx.theme.ink).text((d) => d.text);
+		ctx.set(texts, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+		const notes = adornments ? routes.flatMap((route) => this.adornments(route)) : [];
+		const labels = ctx.text(stage.marks("adornments", "text", notes, (d) => d.key), 10).attr("text-anchor", (d) => d.anchor).attr("pointer-events", "none").attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").attr("font-style", (d) => d.italic ? "italic" : null).text((d) => d.text);
+		ctx.set(labels, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+	}
+	lines({ box, view }) {
+		const { node, head } = view;
+		const shared = {
+			size: MEMBER,
+			bold: false,
+			italic: false,
+			muted: false,
+			anchor: "start"
+		};
+		const middle = box.x + box.width / 2;
+		const drop = view.dividers.length ? 0 : (box.height - head) / 2;
+		const out = [];
+		if (node.stereotype) out.push({
+			...shared,
+			key: `${box.id}:s`,
+			text: `«${node.stereotype}»`,
+			x: middle,
+			y: box.y + drop + 13,
+			size: 9.5,
+			anchor: "middle",
+			muted: true
+		});
+		out.push({
+			...shared,
+			key: `${box.id}:n`,
+			text: StructureText.fit(box.id, box.width - 10, 12),
+			x: middle,
+			y: box.y + drop + head - 8,
+			size: 12,
+			bold: true,
+			italic: !!node.abstract || node.stereotype === "interface",
+			anchor: "middle"
+		});
+		const member = (text, tag, i, base) => ({
+			...shared,
+			key: `${box.id}:${tag}${i}`,
+			text: StructureText.fit(text, box.width - 12, MEMBER),
+			x: box.x + 7,
+			y: box.y + base + LINE * i + 13
+		});
+		if (view.dividers.length) {
+			view.fields.forEach((text, i) => out.push(member(text, "f", i, view.dividers[0])));
+			view.methods.forEach((text, i) => out.push(member(text, "m", i, view.dividers[1])));
+		}
+		return out;
+	}
+	/** Marks each end by UML's rules: triangles at the parent, diamonds at the whole, open arrows at the navigable end. */
+	heads(route) {
+		const { kind, points, key, link } = route;
+		const at = (tip, next) => {
+			const length = Math.hypot(next.x - tip.x, next.y - tip.y) || 1;
+			const ux = (next.x - tip.x) / length, uy = (next.y - tip.y) / length;
+			return (along, across) => `${tip.x + ux * along - uy * across},${tip.y + uy * along + ux * across}`;
+		};
+		const target = at(points.at(-1), points.at(-2)), source = at(points[0], points[1]);
+		if (kind === UmlRelation.Inheritance || kind === UmlRelation.Realization) return [{
+			key,
+			d: `M${target(0, 0)}L${target(12, 6)}L${target(12, -6)}Z`,
+			filled: false,
+			open: false
+		}];
+		if (kind === UmlRelation.Composition || kind === UmlRelation.Aggregation) return [{
+			key,
+			d: `M${source(0, 0)}L${source(8, 5)}L${source(16, 0)}L${source(8, -5)}Z`,
+			filled: kind === UmlRelation.Composition,
+			open: false
+		}];
+		if (link.navigable === false) return [];
+		return [{
+			key,
+			d: `M${target(10, 5)}L${target(0, 0)}L${target(10, -5)}`,
+			filled: false,
+			open: true
+		}];
+	}
+	adornments({ key, link, points }) {
+		const near = (tip, next, text, tag) => {
+			const dx = next.x - tip.x, dy = next.y - tip.y;
+			const upright = Math.abs(dy) >= Math.abs(dx);
+			const x = tip.x + Math.sign(dx) * (upright ? 0 : 15) + (upright ? 6 : 0);
+			const y = tip.y + Math.sign(dy) * (upright ? 15 : 0) + (upright ? 3 : -6);
+			return {
+				key: `${key}:${tag}`,
+				text,
+				x,
+				y,
+				anchor: upright ? "start" : "middle",
+				italic: false
+			};
+		};
+		const out = [];
+		if (link.sourceEnd) out.push(near(points[0], points[1], link.sourceEnd, "s"));
+		if (link.targetEnd) out.push(near(points.at(-1), points.at(-2), link.targetEnd, "t"));
+		if (link.label) {
+			const segments = points.slice(1).map((point, i) => ({
+				a: points[i],
+				b: point,
+				length: Math.hypot(point.x - points[i].x, point.y - points[i].y)
+			}));
+			const longest = segments.reduce((best, segment) => segment.length > best.length ? segment : best, segments[0]);
+			const upright = Math.abs(longest.b.y - longest.a.y) >= Math.abs(longest.b.x - longest.a.x);
+			const x = (longest.a.x + longest.b.x) / 2, y = (longest.a.y + longest.b.y) / 2;
+			out.push({
+				key: `${key}:l`,
+				text: link.label,
+				x: upright ? x - 6 : x,
+				y: upright ? y + 3 : y + 13,
+				anchor: upright ? "end" : "middle",
+				italic: true
+			});
+		}
+		return out;
+	}
+	table() {
+		return {
+			columns: [
+				"source",
+				"target",
+				"kind"
+			],
+			rows: (this.options.data?.links ?? []).map((link) => [
+				link.source,
+				link.target,
+				link.kind ?? UmlRelation.Association
+			])
+		};
+	}
+};
+export { UmlClassDiagram };