prographs 0.12.0 → 0.13.0

package/dist/charts/softwarediagrams/DeploymentDiagram.js

@@ -0,0 +1,419 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { DeploymentArtifactForm, DeploymentKind, DeploymentNodeForm, SoftwareRouting } from "./softwareEnums.js";
+import { SoftwareDiagram } from "./SoftwareDiagram.js";
+import { SoftwareGraph } from "./SoftwareGraph.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/DeploymentDiagram.ts
+var SIZE = 10.5;
+var PAD = 8;
+var LEAD = 13;
+/** How far the top and side faces of a node box reach up and to the right. */
+var DEPTH = 7;
+var TOP = "";
+var KINDS = new Set(Object.values(DeploymentKind));
+var NAME = {
+	node: "Node",
+	device: "Device",
+	environment: "Execution environment",
+	artifact: "Artifact"
+};
+var STEREOTYPE = {
+	node: "",
+	device: "«device»",
+	environment: "«executionEnvironment»",
+	artifact: "«artifact»"
+};
+var { Artifact } = DeploymentKind;
+var n = (value) => Math.round(value * 100) / 100;
+/** A connector path, which holds absolute coordinate pairs only, moved by `(dx, dy)`. */
+var shifted = (d, dx, dy) => d.replace(/(-?[\d.]+),(-?[\d.]+)/g, (_, x, y) => `${n(+x + dx)},${n(+y + dy)}`);
+/**
+* UML deployment diagram: devices and execution environments as node boxes that nest, the artifacts deployed on them,
+* and communication paths labelled with their protocols. Use it to show which software runs on which hardware. For a
+* network drawn with device icons use the network topology diagram.
+*/
+var DeploymentDiagram = class DeploymentDiagram extends SoftwareDiagram {
+	static meta = {
+		id: "uml-deployment-diagram",
+		name: "UML deployment diagram",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Nests devices, execution environments and their artifacts as UML node boxes, joined by communication paths labelled with protocols.",
+		tags: [
+			"uml",
+			"deployment",
+			"node",
+			"device",
+			"execution environment",
+			"artifact",
+			"communication path",
+			"infrastructure"
+		],
+		sample: (seed) => SoftwareSamples.deployment(seed),
+		variants: {
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			routing: [SoftwareRouting.Orthogonal, SoftwareRouting.Curved],
+			form: [DeploymentNodeForm.Cube, DeploymentNodeForm.Flat],
+			artifacts: [DeploymentArtifactForm.Symbol, DeploymentArtifactForm.Listed]
+		}
+	};
+	defaults() {
+		return {
+			nodeId: "id",
+			label: "label",
+			kind: "kind",
+			parent: "parent",
+			source: "source",
+			target: "target",
+			protocol: "protocol",
+			orientation: Orientation.Horizontal,
+			routing: SoftwareRouting.Orthogonal,
+			form: DeploymentNodeForm.Cube,
+			artifacts: DeploymentArtifactForm.Symbol
+		};
+	}
+	legendItems() {
+		return this.palette.items();
+	}
+	#graph() {
+		const { nodeId, source, target } = this.options;
+		return SoftwareGraph.read(this.options.data, {
+			nodeId,
+			source,
+			target
+		});
+	}
+	table() {
+		const { source, target, protocol } = this.options;
+		return this.rowsOf(this.#graph().arcs.map((arc) => arc.raw), [
+			source,
+			target,
+			protocol
+		]);
+	}
+	/** Every element with its parent and children. A parent that is unknown, or that would close a loop, is ignored. */
+	static tree(graph, columns) {
+		const elements = new Map(graph.vertices.map(({ id, raw }) => {
+			const kind = String(raw[columns.kind] ?? "").toLowerCase();
+			return [id, {
+				id,
+				raw,
+				label: SoftwareGraph.text(raw[columns.label]) ?? id,
+				kind: KINDS.has(kind) ? kind : DeploymentKind.Node,
+				parent: null,
+				children: []
+			}];
+		}));
+		for (const element of elements.values()) {
+			const holder = elements.get(SoftwareGraph.text(element.raw[columns.parent]) ?? TOP);
+			let up = holder ?? null;
+			while (up && up !== element) up = up.parent;
+			if (!holder || up) continue;
+			element.parent = holder;
+			holder.children.push(element);
+		}
+		return elements;
+	}
+	/**
+	* Sizes every node from the inside out, then places it from the outside in. The children of one node are layered by
+	* the paths among them, and a path between elements of different nodes is drawn at the level where their holders are siblings.
+	*/
+	static layout(elements, links, look) {
+		const { vertical, routing, depth, listed } = look;
+		const symbol = (element) => element.kind === Artifact && !element.children.length;
+		const named = (element) => listed && symbol(element) && !!element.parent;
+		/** The drawn elements that hold `id`, outermost first, ending with the element itself. */
+		const chain = (id) => {
+			const out = [];
+			for (let element = elements.get(id) ?? null; element; element = element.parent) if (!named(element)) out.unshift(element);
+			return out;
+		};
+		const levels = /* @__PURE__ */ new Map();
+		links.forEach((link, index) => {
+			const a = chain(link.source), b = chain(link.target);
+			let k = 0;
+			while (k < a.length && k < b.length && a[k] === b[k]) k++;
+			if (k >= a.length || k >= b.length) return;
+			const level = k ? a[k - 1].id : TOP;
+			levels.set(level, [...levels.get(level) ?? [], {
+				link: index,
+				source: a[k].id,
+				target: b[k].id
+			}]);
+		});
+		const size = (element) => {
+			if (symbol(element)) {
+				const title = SoftwareText.fit(element.label, 110, SIZE);
+				return {
+					element,
+					symbol: true,
+					width: Math.max(64, SoftwareText.width(title, SIZE) + 32),
+					height: 24,
+					head: 0,
+					title,
+					names: [],
+					inner: null
+				};
+			}
+			const title = SoftwareText.fit(element.label, 150, 11, true), names = element.children.filter(named).map((child) => SoftwareText.fit(child.label, 140, 10)).filter(Boolean);
+			const head = STEREOTYPE[element.kind] ? 30 : 22, kids = element.children.filter((child) => !named(child)), inner = kids.length ? group(kids, element.id) : null;
+			const text = Math.max(SoftwareText.width(STEREOTYPE[element.kind], 9), SoftwareText.width(title, 11, true), ...names.map((name) => SoftwareText.width(name, 10)));
+			return {
+				element,
+				symbol: false,
+				head,
+				title,
+				names,
+				inner,
+				width: Math.max(80, text + 16, (inner?.plan.width ?? 0) + 16),
+				height: head + (names.length ? names.length * LEAD + 2 : 0) + (inner ? inner.plan.height + PAD : names.length ? 4 : 2)
+			};
+		};
+		const group = (kids, level, room) => {
+			const sized = kids.map(size), own = levels.get(level) ?? [], words = own.map(({ link }) => SoftwareText.width(links[link].text, 10));
+			const wide = Math.max(0, ...sized.filter((entry) => entry.symbol).map((entry) => entry.width));
+			for (const entry of sized) if (entry.symbol) entry.width = wide;
+			return {
+				sized,
+				plan: SoftwareWiring.build({
+					nodes: sized.map((entry) => {
+						const width = entry.width + (entry.symbol ? 0 : depth), height = entry.height + (entry.symbol ? 0 : depth);
+						return {
+							id: entry.element.id,
+							along: vertical ? height : width,
+							across: vertical ? width : height,
+							ports: "spread"
+						};
+					}),
+					links: own,
+					vertical,
+					routing,
+					nodeGap: 12,
+					inset: 0,
+					room,
+					rankGap: vertical ? 30 : Math.max(36, Math.min(110, Math.max(0, ...words) + 20)),
+					labelRoom: words.map((width) => width ? width + 16 : 0)
+				}),
+				links: own.map(({ link }) => link)
+			};
+		};
+		const blocks = [], runs = [], areas = /* @__PURE__ */ new Map();
+		const put = (inner, left, top, level) => {
+			areas.set(level, {
+				x0: left,
+				y0: top,
+				x1: left + inner.plan.width,
+				y1: top + inner.plan.height
+			});
+			inner.plan.wires.forEach((wire, i) => runs.push({
+				key: `${level}/${i}`,
+				level,
+				link: inner.links[i],
+				wire: {
+					...wire,
+					d: shifted(wire.d, left, top),
+					points: wire.points.map(([x, y]) => [x + left, y + top]),
+					tip: [wire.tip[0] + left, wire.tip[1] + top]
+				}
+			}));
+			for (const entry of inner.sized) {
+				const box = inner.plan.boxes.get(entry.element.id), x = left + box.x - box.width / 2, y = top + box.y - box.height / 2 + (entry.symbol ? 0 : depth);
+				blocks.push({
+					element: entry.element,
+					symbol: entry.symbol,
+					level,
+					x,
+					y,
+					width: entry.width,
+					height: entry.height,
+					title: entry.title,
+					names: entry.names
+				});
+				if (entry.inner) put(entry.inner, x + (entry.width - entry.inner.plan.width) / 2, y + entry.head + (entry.names.length ? entry.names.length * LEAD + 2 : 0), entry.element.id);
+			}
+		};
+		const root = group([...elements.values()].filter((element) => !element.parent), TOP, look.room);
+		put(root, 0, 0, TOP);
+		return {
+			blocks,
+			runs,
+			areas,
+			width: root.plan.width,
+			height: root.plan.height
+		};
+	}
+	draw(ctx) {
+		const { orientation, routing, form, artifacts, label, kind, parent, protocol } = this.options;
+		const vertical = orientation === Orientation.Vertical, depth = form === DeploymentNodeForm.Cube ? DEPTH : 0, { theme, palette } = ctx;
+		const graph = this.#graph(), elements = DeploymentDiagram.tree(graph, {
+			label,
+			kind,
+			parent
+		});
+		const words = graph.arcs.map((arc) => SoftwareText.fit(SoftwareGraph.text(arc.raw[protocol]) ?? "", 90, 10));
+		const plan = DeploymentDiagram.layout(elements, graph.arcs.map((arc, i) => ({
+			source: arc.source,
+			target: arc.target,
+			text: words[i]
+		})), {
+			vertical,
+			routing,
+			depth,
+			listed: artifacts === DeploymentArtifactForm.Listed,
+			room: vertical ? {
+				length: ctx.plot.height,
+				breadth: ctx.plot.width
+			} : {
+				length: ctx.plot.width,
+				breadth: ctx.plot.height
+			}
+		});
+		const stage = this.stage(ctx, plan.width, plan.height);
+		const shapes = [], labels = [];
+		for (const { element, symbol, x, y, width: w, height: h, title, names } of plan.blocks) {
+			const sort = symbol ? NAME.artifact : NAME[element.kind], fill = palette.color(sort), main = {
+				key: element.id,
+				raw: element.raw
+			};
+			const held = element.children.map((child) => child.label);
+			const tip = {
+				title: element.label,
+				color: fill,
+				rows: [
+					["Kind", sort],
+					...element.parent ? [["On", element.parent.label]] : [],
+					...held.length ? [["Holds", held.join(", ")]] : []
+				]
+			};
+			if (symbol) {
+				const on = palette.inkOn(fill), gx = x + w - 16, gy = y + 6;
+				shapes.push({
+					...main,
+					d: SoftwareShapes.rect(x, y, w, h, 2),
+					fill,
+					tip
+				});
+				shapes.push({
+					key: `${element.id}/page`,
+					d: `M${n(gx)},${n(gy)}h5.5l3.5,3.5v8.5h-9ZM${n(gx + 5.5)},${n(gy)}v3.5h3.5`,
+					stroke: on,
+					strokeWidth: 1.2
+				});
+				labels.push({
+					key: element.id,
+					x: x + 8,
+					y: y + h / 2 + 3.5,
+					text: title,
+					size: SIZE,
+					fill: on
+				});
+				continue;
+			}
+			if (depth) {
+				shapes.push({
+					key: `${element.id}/top`,
+					d: SoftwareShapes.polygon([
+						[x, y],
+						[x + depth, y - depth],
+						[x + w + depth, y - depth],
+						[x + w, y]
+					]),
+					fill,
+					opacity: .5,
+					stroke: theme.surface,
+					strokeWidth: 1
+				});
+				shapes.push({
+					key: `${element.id}/side`,
+					d: SoftwareShapes.polygon([
+						[x + w, y],
+						[x + w + depth, y - depth],
+						[x + w + depth, y + h - depth],
+						[x + w, y + h]
+					]),
+					fill,
+					opacity: .8,
+					stroke: theme.surface,
+					strokeWidth: 1
+				});
+			}
+			shapes.push({
+				...main,
+				d: SoftwareShapes.rect(x, y, w, h),
+				fill,
+				opacity: .2,
+				stroke: theme.surface,
+				strokeWidth: 1,
+				tip
+			});
+			const stereotype = STEREOTYPE[element.kind], base = y + (stereotype ? 30 : 22);
+			if (stereotype) labels.push({
+				key: `${element.id}/kind`,
+				x: x + w / 2,
+				y: y + 12,
+				text: stereotype,
+				anchor: "middle",
+				size: 9,
+				fill: theme.inkSecondary
+			});
+			labels.push({
+				key: element.id,
+				x: x + w / 2,
+				y: base - 6,
+				text: title,
+				anchor: "middle",
+				size: 11,
+				weight: 600
+			});
+			names.forEach((name, i) => labels.push({
+				key: `${element.id}/${i}`,
+				x: x + w / 2,
+				y: base + 8 + i * LEAD,
+				text: name,
+				anchor: "middle",
+				size: 10
+			}));
+		}
+		const marks = [];
+		for (const [level, area] of plan.areas) {
+			const own = plan.runs.filter((run) => run.level === level), placer = new SoftwarePlacer(area);
+			for (const block of plan.blocks) {
+				if (block.level !== level) continue;
+				const lift = block.symbol ? 0 : depth;
+				placer.block({
+					x0: block.x - 2,
+					y0: block.y - lift - 2,
+					x1: block.x + block.width + lift + 2,
+					y1: block.y + block.height + 2
+				});
+			}
+			for (const run of own) placer.avoid(run.wire.points);
+			marks.push(...this.wireLabels(placer, own.map((run) => run.wire), (i) => words[own[i].link]).map((mark) => ({
+				...mark,
+				key: `${level}/${mark.key}`
+			})));
+		}
+		const wires = plan.runs.map(({ key, link, wire }) => {
+			const arc = graph.arcs[link];
+			return {
+				key,
+				raw: arc.raw,
+				d: wire.d,
+				tip: {
+					title: `${elements.get(arc.source).label} ↔ ${elements.get(arc.target).label}`,
+					rows: words[link] ? [["Protocol", words[link]]] : []
+				}
+			};
+		});
+		this.paths(stage, ctx, "nodes", shapes);
+		this.wires(stage, ctx, wires);
+		this.texts(stage, ctx, "node-text", labels);
+		this.texts(stage, ctx, "wire-text", marks);
+	}
+};
+export { DeploymentDiagram };

package/dist/charts/softwarediagrams/SoftwareSamples.js

@@ -1,5 +1,5 @@
 import { SampleData } from "../../data/SampleData.js";
-import { ActivityNodeKind, BpmnFlowKind, BpmnNodeKind, DataFlowKind, NassiKind, PetriNodeKind, UseCaseLinkKind, UseCaseNodeKind } from "./softwareEnums.js";
+import { ActivityNodeKind, BpmnFlowKind, BpmnNodeKind, ComponentLinkKind, ComponentNodeKind, DataFlowKind, DeploymentKind, NassiKind, PetriNodeKind, UseCaseLinkKind, UseCaseNodeKind } from "./softwareEnums.js";
 // src/charts/softwarediagrams/SoftwareSamples.ts
 var { Start, End, Action, Decision, Fork, Join } = ActivityNodeKind;
 var pick = (list, u) => list[Math.floor(u() * list.length)];
@@ -1074,5 +1074,287 @@ var SoftwareSamples = class {
 			count: Math.round(5 + u() * 90)
 		}));
 	}
+	/**
+	* A shop as UML components: `{ id, label, kind, package }` components and interfaces, and `{ source, target, kind, label }` links
+	* that say which component provides or requires which interface, plus one plain dependency. One interface is required and provided by nobody.
+	*/
+	static components(seed) {
+		const { u } = SampleData.rng(seed), { Component, Interface } = ComponentNodeKind, { Provides, Requires, Dependency } = ComponentLinkKind;
+		const front = pick([
+			"Web shop",
+			"Mobile app",
+			"Kiosk"
+		], u), gateway = pick([
+			"CardGateway",
+			"BankTransfer",
+			"Wallet"
+		], u), used = pick(["catalogue", "billing"], u);
+		const web = {
+			kind: Component,
+			package: "Front end"
+		}, services = {
+			kind: Component,
+			package: "Services"
+		}, data = {
+			kind: Component,
+			package: "Data"
+		};
+		return {
+			nodes: [
+				{
+					id: "shop",
+					label: front,
+					...web
+				},
+				{
+					id: "admin",
+					label: "Admin console",
+					...web
+				},
+				{
+					id: "orders",
+					label: "Order service",
+					...services
+				},
+				{
+					id: "catalogue",
+					label: "Catalogue",
+					...services
+				},
+				{
+					id: "billing",
+					label: "Billing",
+					...services
+				},
+				{
+					id: "store",
+					label: "Order store",
+					...data
+				},
+				{
+					id: "index",
+					label: "Search index",
+					...data
+				},
+				...[
+					"Orders",
+					"Products",
+					"Payments",
+					"Persistence",
+					"Search",
+					gateway
+				].map((id) => ({
+					id,
+					kind: Interface
+				}))
+			],
+			links: [
+				{
+					source: "orders",
+					target: "Orders",
+					kind: Provides
+				},
+				{
+					source: "shop",
+					target: "Orders",
+					kind: Requires
+				},
+				{
+					source: "admin",
+					target: "Orders",
+					kind: Requires
+				},
+				{
+					source: "catalogue",
+					target: "Products",
+					kind: Provides
+				},
+				{
+					source: "shop",
+					target: "Products",
+					kind: Requires
+				},
+				{
+					source: "billing",
+					target: "Payments",
+					kind: Provides
+				},
+				{
+					source: "orders",
+					target: "Payments",
+					kind: Requires
+				},
+				{
+					source: "store",
+					target: "Persistence",
+					kind: Provides
+				},
+				{
+					source: "orders",
+					target: "Persistence",
+					kind: Requires
+				},
+				{
+					source: "index",
+					target: "Search",
+					kind: Provides
+				},
+				{
+					source: "catalogue",
+					target: "Search",
+					kind: Requires
+				},
+				{
+					source: "billing",
+					target: gateway,
+					kind: Requires
+				},
+				{
+					source: "admin",
+					target: used,
+					kind: Dependency,
+					label: "«use»"
+				}
+			]
+		};
+	}
+	/**
+	* Where a shop runs, as a UML deployment: `{ id, label, kind, parent }` devices, execution environments and artifacts, nested
+	* by `parent`, and `{ source, target, protocol }` communication paths.
+	*/
+	static deployment(seed) {
+		const { u } = SampleData.rng(seed), { Device, Environment, Artifact } = DeploymentKind;
+		const client = pick([
+			["Customer phone", "shop.apk"],
+			["Till", "till.exe"],
+			["Customer laptop", "shop.js"]
+		], u), wire = pick([
+			"JDBC",
+			"TCP/IP",
+			"TLS"
+		], u);
+		const extra = pick([
+			[
+				"Payment host",
+				"gateway.war",
+				"HTTPS"
+			],
+			[
+				"Mail relay",
+				"relay.conf",
+				"SMTP"
+			],
+			[
+				"Report server",
+				"reports.jar",
+				"gRPC"
+			]
+		], u);
+		return {
+			nodes: [
+				{
+					id: "client",
+					label: client[0],
+					kind: Device
+				},
+				{
+					id: "client-app",
+					label: client[1],
+					kind: Artifact,
+					parent: "client"
+				},
+				{
+					id: "web",
+					label: "Web server",
+					kind: Device
+				},
+				{
+					id: "site",
+					label: "site.conf",
+					kind: Artifact,
+					parent: "web"
+				},
+				{
+					id: "assets",
+					label: "assets.zip",
+					kind: Artifact,
+					parent: "web"
+				},
+				{
+					id: "app",
+					label: "Application server",
+					kind: Device
+				},
+				{
+					id: "runtime",
+					label: "Servlet container",
+					kind: Environment,
+					parent: "app"
+				},
+				{
+					id: "orders",
+					label: "orders.war",
+					kind: Artifact,
+					parent: "runtime"
+				},
+				{
+					id: "billing",
+					label: "billing.war",
+					kind: Artifact,
+					parent: "runtime"
+				},
+				{
+					id: "db",
+					label: "Database server",
+					kind: Device
+				},
+				{
+					id: "dbms",
+					label: "SQL database",
+					kind: Environment,
+					parent: "db"
+				},
+				{
+					id: "schema",
+					label: "schema.sql",
+					kind: Artifact,
+					parent: "dbms"
+				},
+				{
+					id: "extra",
+					label: extra[0],
+					kind: Device
+				},
+				{
+					id: "extra-app",
+					label: extra[1],
+					kind: Artifact,
+					parent: "extra"
+				}
+			],
+			links: [
+				{
+					source: "client",
+					target: "web",
+					protocol: "HTTPS"
+				},
+				{
+					source: "web",
+					target: "app",
+					protocol: "HTTP"
+				},
+				{
+					source: "app",
+					target: "db",
+					protocol: wire
+				},
+				{
+					source: "app",
+					target: "extra",
+					protocol: extra[2]
+				}
+			]
+		};
+	}
 };
 export { SoftwareSamples };