@mstone6969/graph 0.1.0 → 0.2.0

package/dist/charts/diagrams/SequenceDiagram.js

@@ -0,0 +1,351 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { SequenceFragmentKind, SequenceMessageKind, SequenceNoteSide, SequenceNumbering, SequenceParticipantKind, SequenceSpacing } from "./sequenceEnums.js";
+import { SequenceLayout } from "./SequenceLayout.js";
+import { SequenceModel } from "./SequenceModel.js";
+// src/charts/diagrams/SequenceDiagram.ts
+var SIZE = 10.5;
+var { Sync, Async, Return, Self } = SequenceMessageKind;
+/**
+* UML 2 sequence diagram (OMG UML 2.5.1, clause 17.8): lifelines, synchronous calls with filled heads,
+* asynchronous messages with open heads, dashed replies, execution specifications and combined
+* fragments. Use it to show the order of messages between participants in one scenario.
+*/
+var SequenceDiagram = class SequenceDiagram extends Chart2D {
+	static meta = {
+		id: "uml-sequence-diagram",
+		name: "UML sequence diagram",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Orders the messages between participants top to bottom, with activation bars, combined fragments and notes.",
+		tags: [
+			"uml",
+			"sequence",
+			"software",
+			"lifeline",
+			"messages"
+		],
+		sample: (seed) => SequenceDiagram.checkout(seed),
+		variants: {
+			activations: [true, false],
+			numbering: [
+				SequenceNumbering.None,
+				SequenceNumbering.Flat,
+				SequenceNumbering.Nested
+			],
+			spacing: [SequenceSpacing.Fitted, SequenceSpacing.Even],
+			foot: [false, true]
+		}
+	};
+	/** A synthetic checkout scenario, invented for illustration; the seed decides whether a receipt is sent. */
+	static checkout(seed) {
+		const receipt = +SampleData.categories(seed, 1, 1)[0].value % 2 === 0;
+		const messages = [
+			{
+				from: "Customer",
+				to: "Web app",
+				label: "Place order",
+				kind: Sync
+			},
+			{
+				from: "Web app",
+				to: "Orders",
+				label: "POST /orders",
+				kind: Sync
+			},
+			{
+				from: "Orders",
+				to: "Orders",
+				label: "Validate cart",
+				kind: Self
+			},
+			{
+				from: "Orders",
+				to: "Stock",
+				label: "reserve(sku)",
+				kind: Sync
+			},
+			{
+				from: "Stock",
+				to: "Orders",
+				label: "reserved",
+				kind: Return
+			},
+			{
+				from: "Orders",
+				to: "Payments",
+				label: "charge(total)",
+				kind: Sync
+			},
+			{
+				from: "Payments",
+				to: "Orders",
+				label: "approved",
+				kind: Return
+			},
+			{
+				from: "Orders",
+				to: "Mailer",
+				label: receipt ? "send receipt" : "send order summary",
+				kind: Async
+			},
+			{
+				from: "Payments",
+				to: "Orders",
+				label: "declined",
+				kind: Return
+			},
+			{
+				from: "Orders",
+				to: "Stock",
+				label: "release(sku)",
+				kind: Async
+			},
+			{
+				from: "Orders",
+				to: "Web app",
+				label: "order status",
+				kind: Return
+			},
+			{
+				from: "Web app",
+				to: "Customer",
+				label: "Show result",
+				kind: Return
+			}
+		];
+		return {
+			participants: [
+				{
+					id: "Customer",
+					kind: SequenceParticipantKind.Actor
+				},
+				"Web app",
+				"Orders",
+				"Stock",
+				"Payments",
+				"Mailer"
+			],
+			messages,
+			fragments: [
+				{
+					kind: SequenceFragmentKind.Loop,
+					first: 3,
+					last: 4,
+					guard: "each line item"
+				},
+				{
+					kind: SequenceFragmentKind.Alt,
+					first: 6,
+					last: 9,
+					guard: "card accepted",
+					branches: [{
+						first: 8,
+						guard: "else"
+					}]
+				},
+				{
+					kind: SequenceFragmentKind.Opt,
+					first: 7,
+					last: 7,
+					guard: "wants receipt"
+				}
+			],
+			notes: [{
+				text: "Payment is idempotent on the order id",
+				over: "Payments",
+				side: SequenceNoteSide.Over,
+				after: 5
+			}]
+		};
+	}
+	defaults() {
+		return {
+			from: "from",
+			to: "to",
+			label: "label",
+			kind: "kind",
+			activations: true,
+			foot: false,
+			numbering: SequenceNumbering.None,
+			spacing: SequenceSpacing.Fitted
+		};
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 10,
+			bottom: 6,
+			left: 10
+		};
+	}
+	legendItems() {
+		return [];
+	}
+	#scene() {
+		const { from, to, label, kind } = this.options;
+		return SequenceModel.build(this.options.data, {
+			from,
+			to,
+			label,
+			kind
+		});
+	}
+	draw(ctx) {
+		const { activations, foot, numbering, spacing } = this.options;
+		const scene = this.#scene();
+		const plan = SequenceLayout.place(scene, {
+			width: ctx.plot.width,
+			height: ctx.plot.height,
+			activations,
+			foot,
+			numbering,
+			spacing
+		});
+		const x = (ctx.plot.width - plan.width * plan.scale) / 2 - plan.left * plan.scale;
+		const stage = ctx.nest(`translate(${x},0) scale(${plan.scale})`, "sequence");
+		const { theme } = ctx;
+		const lifelines = stage.marks("lifelines", "line", plan.lifelines, (d) => d.key).attr("stroke", theme.axis).attr("stroke-width", 1).attr("stroke-dasharray", "5 4");
+		ctx.set(lifelines, {
+			x1: (d) => d.x,
+			x2: (d) => d.x,
+			y1: (d) => d.y1,
+			y2: (d) => d.y2
+		});
+		const frames = stage.marks("frames", "rect", plan.frames, (d) => d.key).attr("fill", "none").attr("stroke", theme.inkMuted).attr("stroke-width", 1).attr("rx", 2);
+		ctx.set(frames, {
+			x: (d) => d.x,
+			y: (d) => d.y,
+			width: (d) => d.width,
+			height: (d) => d.height
+		});
+		const separators = stage.marks("separators", "line", plan.frames.flatMap((frame) => frame.separators), (d) => d.key).attr("stroke", theme.inkMuted).attr("stroke-width", 1).attr("stroke-dasharray", "6 4");
+		ctx.set(separators, {
+			x1: (d) => d.x1,
+			x2: (d) => d.x2,
+			y1: (d) => d.y,
+			y2: (d) => d.y
+		});
+		const bars = stage.marks("bars", "rect", plan.bars, (d) => d.key).attr("fill", theme.grid).attr("stroke", theme.inkSecondary).attr("stroke-width", 1);
+		ctx.set(bars, {
+			x: (d) => d.x,
+			y: (d) => d.y,
+			width: (d) => d.width,
+			height: (d) => d.height
+		});
+		ctx.hover(bars, (d) => ({
+			title: scene.lanes[d.bar.lane].label,
+			rows: [["Active", `messages ${d.bar.first + 1} to ${d.bar.last + 1}`], ["Ends", d.bar.returned ? "on return" : "implied"]]
+		}));
+		const lines = stage.marks("messages", "path", plan.arrows, (d) => d.key).attr("fill", "none").attr("stroke", theme.inkSecondary).attr("stroke-width", 2).attr("stroke-dasharray", (d) => d.dashed ? "6 4" : null).attr("stroke-linejoin", "round");
+		ctx.set(lines, { d: (d) => d.d });
+		const heads = stage.marks("arrowheads", "path", plan.arrows, (d) => d.key).attr("stroke", theme.inkSecondary).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-linecap", "round").attr("fill", (d) => d.filled ? theme.inkSecondary : "none");
+		ctx.set(heads, { d: (d) => d.head });
+		const pills = plan.arrows.filter((arrow) => arrow.pill);
+		const chips = stage.marks("pills", "rect", pills, (d) => d.key).attr("fill", theme.inkSecondary).attr("stroke", theme.surface).attr("stroke-width", 2).attr("rx", 7);
+		ctx.set(chips, {
+			x: (d) => d.pill.x,
+			y: (d) => d.pill.y,
+			width: (d) => d.pill.width,
+			height: 14
+		});
+		const numbers = ctx.text(stage.marks("numbers", "text", pills, (d) => d.key), 9).attr("fill", ctx.palette.inkOn(theme.inkSecondary)).attr("text-anchor", "middle").attr("pointer-events", "none").text((d) => d.number);
+		ctx.set(numbers, {
+			x: (d) => d.pill.x + d.pill.width / 2,
+			y: (d) => d.pill.y + 10.5
+		});
+		const hits = stage.marks("hits", "path", plan.arrows, (d) => d.key).attr("fill", "none").attr("stroke", "transparent").attr("stroke-width", 14).attr("pointer-events", "stroke");
+		ctx.set(hits, { d: (d) => d.d });
+		ctx.hover(hits, (d) => ({
+			title: `${scene.lanes[d.step.from].label} → ${scene.lanes[d.step.to].label}`,
+			rows: [
+				["Message", d.step.label || "none"],
+				["Kind", d.step.kind],
+				["Order", d.number || d.step.decimal || String(d.step.row + 1)]
+			]
+		}));
+		const labels = plan.arrows.filter((arrow) => arrow.label);
+		const words = ctx.text(stage.marks("labels", "text", labels, (d) => d.key), SIZE, "ink").attr("text-anchor", (d) => d.label.anchor).attr("pointer-events", "none").attr("stroke", theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").text((d) => d.label.text);
+		ctx.set(words, {
+			x: (d) => d.label.x,
+			y: (d) => d.label.y
+		});
+		const tabs = stage.marks("tabs", "path", plan.frames, (d) => d.key).attr("fill", theme.grid).attr("stroke", theme.inkMuted).attr("stroke-width", 1);
+		ctx.set(tabs, { d: (d) => d.tab });
+		ctx.hover(tabs, (d) => ({
+			title: d.tabText,
+			rows: [["Guard", d.frame.guard || "none"], ["Messages", `${d.frame.first + 1} to ${d.frame.last + 1}`]]
+		}));
+		const tabWords = ctx.text(stage.marks("tab-text", "text", plan.frames, (d) => d.key), SIZE, "ink").attr("font-weight", 600).attr("pointer-events", "none").text((d) => d.tabText);
+		ctx.set(tabWords, {
+			x: (d) => d.tabX,
+			y: (d) => d.tabY
+		});
+		const guards = ctx.text(stage.marks("guards", "text", plan.frames.flatMap((frame) => frame.guards), (d) => d.key), SIZE).attr("pointer-events", "none").attr("stroke", theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").text((d) => d.text);
+		ctx.set(guards, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+		const notes = stage.marks("notes", "path", plan.notes, (d) => d.key).attr("fill", theme.surface).attr("stroke", theme.inkMuted).attr("stroke-width", 1).attr("stroke-linejoin", "round");
+		ctx.set(notes, { d: (d) => d.d });
+		ctx.hover(notes, (d) => ({
+			title: "Note",
+			rows: [["Text", d.remark.text]]
+		}));
+		const noteWords = ctx.text(stage.marks("note-text", "text", plan.notes.flatMap((note) => note.lines), (d) => d.key), SIZE, "ink").attr("pointer-events", "none").text((d) => d.text);
+		ctx.set(noteWords, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+		this.#heads(ctx, stage, plan, scene);
+	}
+	#heads(ctx, stage, plan, scene) {
+		const { theme } = ctx;
+		const objects = plan.heads.filter((head) => !head.actor), actors = plan.heads.filter((head) => head.actor);
+		const boxes = stage.marks("head-boxes", "rect", objects, (d) => d.key).attr("fill", theme.surface).attr("stroke", theme.inkSecondary).attr("stroke-width", 1.5).attr("rx", 3);
+		ctx.set(boxes, {
+			x: (d) => d.x,
+			y: (d) => d.boxY,
+			width: (d) => d.width,
+			height: 28
+		});
+		const figures = stage.marks("head-actors", "path", actors, (d) => d.key).attr("fill", "none").attr("stroke", theme.inkSecondary).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		ctx.set(figures, { d: (d) => SequenceDiagram.figure(d.x + d.width / 2, d.y + 2) });
+		const tip = (d) => {
+			const lane = scene.lanes[d.lane];
+			const sent = scene.steps.filter((step) => step.from === d.lane).length, received = scene.steps.filter((step) => step.to === d.lane).length;
+			return {
+				title: lane.label,
+				rows: [["Sends", sent], ["Receives", received]]
+			};
+		};
+		ctx.hover(boxes, tip);
+		ctx.hover(figures, tip);
+		const names = ctx.text(stage.marks("head-text", "text", plan.heads, (d) => d.key), 11.5, "ink").attr("font-weight", 600).attr("text-anchor", "middle").attr("pointer-events", "none").text((d) => d.text);
+		ctx.set(names, {
+			x: (d) => d.x + d.width / 2,
+			y: (d) => d.textY
+		});
+	}
+	/** UML's stick figure for an actor, 28 tall. */
+	static figure(x, y) {
+		const r = 5;
+		return `M${x + r},${y + r}A${r},${r},0,1,1,${x - r},${y + r}A${r},${r},0,1,1,${x + r},${y + r}M${x},${y + 10}L${x},${y + 20}M${x - 8},${y + 14}L${x + 8},${y + 14}M${x},${y + 20}L${x - 7},${y + 28}M${x},${y + 20}L${x + 7},${y + 28}`;
+	}
+	table() {
+		const { from, to, label, kind } = this.options;
+		const columns = [
+			from,
+			to,
+			label,
+			kind
+		];
+		return {
+			columns,
+			rows: SequenceModel.rows(this.options.data).filter((row) => row && typeof row === "object").map((row) => columns.map((column) => row[column]))
+		};
+	}
+};
+export { SequenceDiagram };