prographs 0.12.0 → 0.13.0

package/dist/charts/softwarediagrams/ComponentDiagram.js

@@ -0,0 +1,504 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { ComponentGrouping, ComponentInterfaceForm, ComponentLinkKind, ComponentNodeKind, SoftwareRouting } from "./softwareEnums.js";
+import { SoftwareDiagram } from "./SoftwareDiagram.js";
+import { SoftwareGraph } from "./SoftwareGraph.js";
+import { SoftwareLayers } from "./SoftwareLayers.js";
+import { SoftwarePlacer } from "./SoftwarePlacer.js";
+import { SoftwareSamples } from "./SoftwareSamples.js";
+import { SoftwareShapes } from "./SoftwareShapes.js";
+import { SoftwareText } from "./SoftwareText.js";
+import { SoftwareWiring } from "./SoftwareWiring.js";
+// src/charts/softwarediagrams/ComponentDiagram.ts
+var SIZE = 10.5;
+var FACE = 10;
+var BALL = 5;
+var SOCKET = 8;
+var PORT = 3.5;
+var PAD = 8;
+var TAB = 16;
+/** How far an interface name may reach past the drawing along the flow. */
+var REACH = 40;
+var { Provides, Requires, Dependency } = ComponentLinkKind;
+var stated = (raw, column) => String(raw[column] ?? "").toLowerCase();
+var apart = (a, b, by = 0) => a[1] + by < b[0] || b[1] + by < a[0];
+var list = (names) => names.join(", ") || "none";
+/**
+* UML component diagram: components wired through the interfaces they provide (a ball) and require (a socket), with
+* ports where interfaces attach, dashed dependencies, and packages as enclosing frames. Use it to show how the parts
+* of a system plug together. For the C4 view of the same system use the architecture diagram.
+*/
+var ComponentDiagram = class ComponentDiagram extends SoftwareDiagram {
+	static meta = {
+		id: "uml-component-diagram",
+		name: "UML component diagram",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Wires components through provided and required interfaces in ball and socket notation, with ports, dependencies and package frames.",
+		tags: [
+			"uml",
+			"component",
+			"interface",
+			"ball and socket",
+			"lollipop",
+			"port",
+			"package",
+			"software"
+		],
+		sample: (seed) => SoftwareSamples.components(seed),
+		variants: {
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			routing: [SoftwareRouting.Curved, SoftwareRouting.Orthogonal],
+			interfaces: [ComponentInterfaceForm.BallSocket, ComponentInterfaceForm.Dependency],
+			grouping: [ComponentGrouping.Frames, ComponentGrouping.Flat]
+		}
+	};
+	defaults() {
+		return {
+			nodeId: "id",
+			label: "label",
+			kind: "kind",
+			group: "package",
+			source: "source",
+			target: "target",
+			linkKind: "kind",
+			linkLabel: "label",
+			orientation: Orientation.Horizontal,
+			routing: SoftwareRouting.Curved,
+			interfaces: ComponentInterfaceForm.BallSocket,
+			grouping: ComponentGrouping.Frames,
+			ports: true
+		};
+	}
+	legendItems() {
+		return this.options.grouping === ComponentGrouping.Frames ? [] : this.palette.items();
+	}
+	#graph() {
+		const { nodeId, source, target } = this.options;
+		return SoftwareGraph.read(this.options.data, {
+			nodeId,
+			source,
+			target
+		});
+	}
+	table() {
+		const { source, target, linkKind, linkLabel } = this.options;
+		return this.rowsOf(this.#graph().arcs.map((arc) => arc.raw), [.../* @__PURE__ */ new Set([
+			source,
+			target,
+			linkKind,
+			linkLabel
+		])]);
+	}
+	/**
+	* Components, interfaces and the links between them. A link between two components is a dependency, one between a
+	* component and an interface provides or requires it whichever end names the component, and the rest are dropped.
+	*/
+	static model(graph, columns) {
+		const offered = new Set(graph.arcs.filter((arc) => [Provides, Requires].includes(stated(arc.raw, columns.linkKind))).map((arc) => arc.target));
+		const parts = graph.vertices.map(({ id, raw }) => {
+			const kind = stated(raw, columns.kind);
+			return {
+				id,
+				raw,
+				label: SoftwareGraph.text(raw[columns.label]) ?? id,
+				face: kind === ComponentNodeKind.Interface || !kind && offered.has(id),
+				group: SoftwareGraph.text(raw[columns.group]) ?? "",
+				shared: false
+			};
+		});
+		const byId = new Map(parts.map((part) => [part.id, part]));
+		const joins = graph.arcs.flatMap((arc) => {
+			const a = byId.get(arc.source), b = byId.get(arc.target);
+			if (a === b || a.face && b.face) return [];
+			if (!a.face && !b.face) return [{
+				key: arc.key,
+				kind: Dependency,
+				component: a.id,
+				other: b.id,
+				raw: arc.raw
+			}];
+			const [component, face] = a.face ? [b, a] : [a, b];
+			return [{
+				key: arc.key,
+				kind: stated(arc.raw, columns.linkKind) === Provides ? Provides : Requires,
+				component: component.id,
+				other: face.id,
+				raw: arc.raw
+			}];
+		});
+		for (const part of parts) {
+			if (!part.face) continue;
+			const users = joins.filter((join) => join.other === part.id), owner = users.find((join) => join.kind === Provides) ?? users[0];
+			part.group = owner ? byId.get(owner.component).group : "";
+			part.shared = !users.some((join) => join.kind === Provides) || !users.some((join) => join.kind === Requires) || users.some((join) => byId.get(join.component).group !== part.group);
+		}
+		return {
+			parts,
+			joins
+		};
+	}
+	/**
+	* The lane across the flow that each package takes. Packages share a lane when their frames sit at least a rank
+	* apart along the flow and neither frame takes in an interface of the other, so frames in one lane never touch.
+	*/
+	static lanes(spans) {
+		const lanes = [];
+		for (const span of spans) {
+			const fits = (other) => (!other.frame || apart(span.owned, other.frame)) && (!span.frame || apart(other.owned, span.frame)) && (!span.frame || !other.frame || apart(span.frame, other.frame, 1));
+			const free = lanes.find((lane) => lane.every(fits));
+			if (free) free.push(span);
+			else lanes.push([span]);
+		}
+		return new Map(lanes.flatMap((lane, at) => lane.map((span) => [span.name, at])));
+	}
+	/** The half circle of a required interface, cupped around the ball at `centre` and open along `angle`, the way its connector runs. */
+	static socket([cx, cy], angle, radius = SOCKET) {
+		const end = (turn) => `${+(cx + radius * Math.cos(angle + turn)).toFixed(2)},${+(cy + radius * Math.sin(angle + turn)).toFixed(2)}`;
+		return `M${end(Math.PI / 2)}A${radius},${radius} 0 0 1 ${end(-Math.PI / 2)}`;
+	}
+	draw(ctx) {
+		const { orientation, routing, interfaces, grouping, ports, label, kind, group, linkKind, linkLabel } = this.options;
+		const vertical = orientation === Orientation.Vertical, socketed = interfaces === ComponentInterfaceForm.BallSocket;
+		const { theme, palette } = ctx, ink = theme.inkSecondary;
+		const { parts, joins } = ComponentDiagram.model(this.#graph(), {
+			label,
+			kind,
+			group,
+			linkKind
+		});
+		const byId = new Map(parts.map((part) => [part.id, part]));
+		const links = joins.map((join) => join.kind === Provides ? {
+			source: join.other,
+			target: join.component
+		} : {
+			source: join.component,
+			target: join.other
+		});
+		const framed = grouping === ComponentGrouping.Frames && parts.some((part) => part.group);
+		const rank = SoftwareLayers.ranks(parts.map((part) => part.id), links);
+		const reach = (members) => members.length ? [Math.min(...members.map((part) => rank.get(part.id))), Math.max(...members.map((part) => rank.get(part.id)))] : null;
+		const lanes = ComponentDiagram.lanes(framed ? [...new Set(parts.map((part) => part.group))].map((name) => {
+			const owned = parts.filter((part) => part.group === name);
+			return {
+				name,
+				owned: reach(owned),
+				frame: name ? reach(owned.filter((part) => !part.shared)) : null
+			};
+		}) : []);
+		const lane = (part) => lanes.get(part.group) ?? 0, count = Math.max(1, ...[...lanes.values()].map((at) => at + 1));
+		const half = socketed ? SOCKET : BALL;
+		const lines = new Map(parts.map((part) => [part.id, part.face ? [SoftwareText.fit(part.label, framed && !vertical ? 64 : 78, FACE)] : SoftwareText.wrap(part.label, 96, SIZE)]));
+		const widest = (id, size) => Math.max(0, ...lines.get(id).map((line) => SoftwareText.width(line, size)));
+		const words = joins.map((join) => join.kind === Dependency ? SoftwareText.fit(SoftwareGraph.text(join.raw[linkLabel]) ?? "", 80, 10) : "");
+		const edge = framed ? 16 : 0;
+		const plan = SoftwareWiring.build({
+			nodes: parts.map((part) => {
+				if (part.face) {
+					const room = vertical ? widest(part.id, FACE) + 8 : 26;
+					return {
+						id: part.id,
+						along: 2 * half,
+						across: 2 * half,
+						slot: 2 * half + room,
+						shift: vertical ? -room / 2 : 0,
+						lane: lane(part)
+					};
+				}
+				const width = Math.max(80, widest(part.id, SIZE) + 42), height = lines.get(part.id).length > 1 ? 44 : 32;
+				return {
+					id: part.id,
+					along: vertical ? height : width,
+					across: vertical ? width : height,
+					ports: "spread",
+					lane: lane(part)
+				};
+			}),
+			links,
+			vertical,
+			routing,
+			nodeGap: 16,
+			rankGap: vertical ? 30 : 34,
+			inset: 0,
+			labelRoom: words.map((text) => text ? SoftwareText.width(text, 10) + 16 : 0),
+			lanes: count,
+			lanePad: framed ? vertical ? 10 : 28 : 0,
+			laneMin: framed && vertical ? Array.from({ length: count }, (_, at) => Math.max(0, ...[...lanes].filter(([name, own]) => name && own === at).map(([name]) => Math.min(130, SoftwareText.width(name, SIZE, true)) + 32 + 6))) : void 0,
+			room: vertical ? {
+				length: ctx.plot.height - edge - (framed ? TAB : 0),
+				breadth: ctx.plot.width
+			} : {
+				length: ctx.plot.width - edge,
+				breadth: ctx.plot.height
+			}
+		});
+		const placer = this.placer(plan, vertical ? {
+			x0: 0,
+			y0: -40,
+			x1: plan.width,
+			y1: plan.height + REACH
+		} : {
+			x0: -40,
+			y0: 0,
+			x1: plan.width + REACH,
+			y1: plan.height
+		});
+		const shapes = [], balls = [], squares = /* @__PURE__ */ new Map(), labels = [];
+		/** The room each package's frame must enclose, and everything drawn outside the plan's own box. */
+		const held = /* @__PURE__ */ new Map(), loose = [];
+		const hold = (part, box) => {
+			if (!part.shared) held.set(part.group, [...held.get(part.group) ?? [], box]);
+		};
+		/** Tooltips of the interfaces nobody provides: with no ball to point at, their socket carries it. */
+		const bare = /* @__PURE__ */ new Map();
+		const naming = (id, sort) => joins.filter((join) => join.kind === sort && join.component === id).map((join) => byId.get(join.other).label);
+		const users = (id, sort) => joins.filter((join) => join.kind === sort && join.other === id).map((join) => byId.get(join.component).label);
+		for (const part of parts) {
+			const { x, y, width: w, height: h } = plan.boxes.get(part.id);
+			hold(part, {
+				x0: x - w / 2,
+				y0: y - h / 2,
+				x1: x + w / 2,
+				y1: y + h / 2
+			});
+			if (part.face) {
+				const text = lines.get(part.id)[0], tip = {
+					title: part.label,
+					rows: [["Provided by", list(users(part.id, Provides))], ["Required by", list(users(part.id, Requires))]]
+				};
+				if (!socketed || users(part.id, Provides).length) balls.push({
+					key: part.id,
+					raw: part.raw,
+					d: SoftwareShapes.ellipse(x, y, 4.25),
+					fill: theme.surface,
+					stroke: ink,
+					tip
+				});
+				else bare.set(part.id, tip);
+				const spots = vertical ? [[
+					"start",
+					x + half + 4,
+					y + 3.5
+				]] : [[
+					"middle",
+					x,
+					y - half - 4
+				], [
+					"middle",
+					x,
+					y + half + 11
+				]];
+				const spot = text ? placer.claim(spots.map(([anchor, lx, ly]) => ({
+					anchor,
+					x: lx,
+					y: ly,
+					box: SoftwarePlacer.text(lx, ly, text, FACE, anchor)
+				}))) : null;
+				if (!spot) continue;
+				labels.push({
+					key: `${part.id}/name`,
+					x: spot.x,
+					y: spot.y,
+					text,
+					anchor: spot.anchor,
+					size: FACE,
+					halo: true
+				});
+				hold(part, spot.box);
+				loose.push(spot.box);
+				continue;
+			}
+			const fill = palette.color(part.group || "Component"), on = palette.inkOn(fill), text = lines.get(part.id), left = x - w / 2, top = y - h / 2;
+			shapes.push({
+				key: part.id,
+				raw: part.raw,
+				d: SoftwareShapes.rect(left, top, w, h, 2),
+				fill,
+				tip: {
+					title: part.label,
+					color: fill,
+					rows: [
+						...part.group ? [["Package", part.group]] : [],
+						["Provides", list(naming(part.id, Provides))],
+						["Requires", list(naming(part.id, Requires))]
+					]
+				}
+			});
+			const ix = left + w - 17, iy = top + 5;
+			shapes.push({
+				key: `${part.id}/icon`,
+				d: SoftwareShapes.rect(ix + 3, iy, 9, 11),
+				fill,
+				stroke: on,
+				strokeWidth: 1.2
+			});
+			shapes.push({
+				key: `${part.id}/tabs`,
+				d: `${SoftwareShapes.rect(ix, iy + 2, 6, 2.5)}${SoftwareShapes.rect(ix, iy + 6.5, 6, 2.5)}`,
+				fill,
+				stroke: on,
+				strokeWidth: 1.2
+			});
+			const centre = widest(part.id, SIZE) / 2 <= w / 2 - 20 ? x : x - 7;
+			text.forEach((line, i) => labels.push({
+				key: `${part.id}/${i}`,
+				x: centre,
+				y: y + 3.5 + (i - (text.length - 1) / 2) * 12,
+				text: line,
+				anchor: "middle",
+				size: SIZE,
+				weight: 600,
+				fill: on
+			}));
+		}
+		const port = ([px, py]) => {
+			if (ports) squares.set(`${px.toFixed(1)}/${py.toFixed(1)}`, {
+				key: `port/${squares.size}`,
+				d: SoftwareShapes.rect(px - PORT, py - PORT, 2 * PORT, 2 * PORT),
+				fill: theme.surface,
+				stroke: ink
+			});
+		};
+		const sockets = /* @__PURE__ */ new Map();
+		const wires = plan.wires.map((wire, i) => {
+			const join = joins[i], from = byId.get(join.component).label, to = byId.get(join.other).label;
+			const arrow = {
+				d: SoftwareShapes.arrow(wire.tip, wire.angle, 8, true),
+				fill: "none"
+			};
+			if (join.kind === Dependency) return {
+				key: join.key,
+				raw: join.raw,
+				d: wire.d,
+				dash: "5 4",
+				head: arrow,
+				tip: {
+					title: `${from} → ${to}`,
+					rows: [["Relation", words[i] || "dependency"]]
+				}
+			};
+			const face = plan.boxes.get(join.other), centre = [face.x, face.y];
+			if (join.kind === Requires) {
+				port(wire.points[0]);
+				const cup = ComponentDiagram.socket(centre, wire.angle);
+				if (socketed) sockets.set(cup, {
+					key: `${join.other}/socket/${sockets.size}`,
+					raw: byId.get(join.other).raw,
+					d: cup,
+					stroke: ink,
+					strokeWidth: 2,
+					tip: bare.get(join.other)
+				});
+				return {
+					key: join.key,
+					raw: join.raw,
+					d: wire.d,
+					dash: socketed ? void 0 : "5 4",
+					head: socketed ? void 0 : arrow,
+					tip: { title: `${from} requires ${to}` }
+				};
+			}
+			port(wire.tip);
+			const start = wire.points[0], away = Math.atan2(start[1] - centre[1], start[0] - centre[0]);
+			const stick = socketed ? SoftwareShapes.line([[centre[0] + BALL * Math.cos(away), centre[1] + BALL * Math.sin(away)], start]) : "";
+			return {
+				key: join.key,
+				raw: join.raw,
+				d: `${stick}${wire.d}`,
+				tip: { title: `${from} provides ${to}` }
+			};
+		});
+		const frames = [...held].flatMap(([name, boxes]) => {
+			if (!framed || !name) return [];
+			let x0 = Math.min(...boxes.map((box) => box.x0)) - PAD, x1 = Math.max(...boxes.map((box) => box.x1)) + PAD;
+			const y0 = Math.min(...boxes.map((box) => box.y0)) - PAD, y1 = Math.max(...boxes.map((box) => box.y1)) + PAD, band = plan.lanes[lanes.get(name)];
+			const title = SoftwareText.fit(name, vertical ? 130 : x1 - x0 - 16, SIZE, true), tab = SoftwareText.width(title, SIZE, true) + 16;
+			if (vertical) {
+				x1 = Math.max(x1, x0 + tab + 16);
+				const over = Math.max(0, Math.min(x1 - (band.start + band.size - 2), x0 - band.start - 2));
+				x0 -= over;
+				x1 -= over;
+			}
+			/** The tab slides along the frame's top edge to the first place no connector crosses. */
+			const spot = placer.claim(Array.from({ length: Math.floor(Math.max(0, x1 - x0 - tab) / 4) + 1 }, (_, k) => ({
+				at: x0 + k * 4,
+				box: {
+					x0: x0 + k * 4,
+					y0: y0 - TAB,
+					x1: x0 + k * 4 + tab,
+					y1: y0
+				}
+			})));
+			return [{
+				name,
+				title,
+				x0,
+				y0,
+				x1,
+				y1,
+				tab,
+				at: spot?.at ?? x0
+			}];
+		});
+		const marks = this.wireLabels(placer, plan.wires, (i) => words[i]);
+		const all = [
+			{
+				x0: 0,
+				y0: 0,
+				x1: plan.width,
+				y1: plan.height
+			},
+			...frames.map((frame) => ({
+				...frame,
+				y0: frame.y0 - TAB
+			})),
+			...loose
+		];
+		const x0 = Math.min(...all.map((box) => box.x0)), y0 = Math.min(...all.map((box) => box.y0));
+		const body = this.stage(ctx, Math.max(...all.map((box) => box.x1)) - x0, Math.max(...all.map((box) => box.y1)) - y0).nest(`translate(${+(-x0).toFixed(2)},${+(-y0).toFixed(2)})`, "body");
+		this.paths(body, ctx, "frames", frames.map((frame) => ({
+			key: frame.name,
+			fill: theme.grid,
+			opacity: .45,
+			d: SoftwareShapes.polygon([
+				[frame.at, frame.y0],
+				[frame.at, frame.y0 - TAB],
+				[frame.at + frame.tab, frame.y0 - TAB],
+				[frame.at + frame.tab, frame.y0],
+				[frame.x1, frame.y0],
+				[frame.x1, frame.y1],
+				[frame.x0, frame.y1],
+				[frame.x0, frame.y0]
+			])
+		})));
+		this.wires(body, ctx, wires);
+		/** Each tab again over the connectors, on a surface underlay, so a line that must cross a tab runs behind the package name. */
+		this.paths(body, ctx, "frame-tabs", frames.flatMap((frame) => {
+			const d = SoftwareShapes.rect(frame.at, frame.y0 - TAB, frame.tab, TAB);
+			return [{
+				key: `${frame.name}/under`,
+				d,
+				fill: theme.surface
+			}, {
+				key: frame.name,
+				d,
+				fill: theme.grid,
+				opacity: .45
+			}];
+		}));
+		this.texts(body, ctx, "frame-names", frames.map((frame) => ({
+			key: frame.name,
+			x: frame.at + PAD,
+			y: frame.y0 - 4.5,
+			text: frame.title,
+			size: SIZE,
+			weight: 600
+		})));
+		this.paths(body, ctx, "nodes", shapes);
+		this.paths(body, ctx, "interfaces", [...sockets.values(), ...balls]);
+		this.paths(body, ctx, "ports", [...squares.values()]);
+		this.texts(body, ctx, "node-text", labels);
+		this.texts(body, ctx, "wire-text", marks);
+	}
+};
+export { ComponentDiagram };