@coldtea/pr-lens-renderer 0.1.0

package/src/svg/dataflow.ts

@@ -0,0 +1,408 @@
+import type { Flow, FlowMessage, GraphNode, MessageKind } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
+import {
+  DIAGRAM_MARGIN,
+  FLOW_CYCLE_MAX,
+  FLOW_MAX_PULSES_PER_MESSAGE,
+  FLOW_PULSE_RAMP,
+  FLOW_STEP_TRAVEL,
+  LANE_RADIUS,
+  PILL_HEIGHT,
+  PILL_PADDING_X,
+  PILL_TEXT_SIZE,
+  TITLE_SIZE,
+} from "../design.js";
+import { canvasFor, union } from "../bounds.js";
+import type { Box } from "../geometry.js";
+import { measure } from "../text.js";
+import { coord } from "../geometry.js";
+import {
+  ACTIVATION_HALF_WIDTH,
+  FLOW_BAND_PAD_X,
+  FLOW_BAND_PAD_Y,
+  layoutDataFlow,
+  MARKER_INSET,
+  PARTICIPANT_TOP,
+  SELF_LOOP_CORNER,
+  SELF_LOOP_DROP,
+  SELF_LOOP_EXTENT,
+  SELF_LOOP_REACH,
+  type FlowLayout,
+  type PlacedMessage,
+} from "../layout/dataflow.js";
+import type { Palette } from "../theme.js";
+import { paintCard, paintLabelPill } from "./architecture.js";
+import { markerFor, openMarkerFor, shifted, toneColour, toneFor, type Tone } from "./document.js";
+import { lines, tag, wrap } from "./primitives.js";
+import { PULSE_RADIUS, TRAIN_RADIUS } from "./pulse.js";
+
+/** A ratio inside the animation cycle, written to a fixed number of places. */
+const ratio = (value: number): string => String(Math.round(value * 10000) / 10000);
+
+/**
+ * How long the whole sequence takes. Every step would rather have a full
+ * crossing to itself; a flow long enough to overrun the ceiling shares it
+ * instead, and its steps go by faster.
+ */
+const cycleFor = (slotCount: number): number =>
+  Math.min(FLOW_CYCLE_MAX, slotCount * FLOW_STEP_TRAVEL);
+
+/** Whether a message crosses to another column, and which way. */
+const travelDirection = (kind: MessageKind, fromX: number, toX: number): -1 | 0 | 1 => {
+  switch (kind) {
+    case "self":
+      return 0;
+    case "sync":
+    case "async":
+    case "return":
+      return toX >= fromX ? 1 : -1;
+    default:
+      return assertNever(kind, "Unhandled message kind");
+  }
+};
+
+const messageClasses = (message: FlowMessage, tone: Tone): string => {
+  const classes = ["msg", `edge-${tone}`];
+  if (message.kind === "return") classes.push("msg-return");
+  if (message.delta === "added") classes.push("msg-strong");
+  return classes.join(" ");
+};
+
+/**
+ * Fire-and-forget gets the open head; everything else keeps the filled one.
+ *
+ * Deliberate deviation from strict UML 2, which draws replies with an open
+ * head as well: here each signal carries exactly one meaning, so a reader
+ * needs no legend. The dashed stroke is already the whole mark of "this is
+ * an answer", and the open head stays the exclusive mark of "nobody waits on
+ * this". Open-headed returns would put the async signature on every reply
+ * and dilute the one distinction the head shape exists to draw.
+ */
+const headFor = (kind: MessageKind, tone: Tone): string => {
+  switch (kind) {
+    case "async":
+      return openMarkerFor(tone);
+    case "sync":
+    case "return":
+    case "self":
+      return markerFor(tone);
+    default:
+      return assertNever(kind, "Unhandled message kind");
+  }
+};
+
+/** Whether an activation bar covers this column at this height. */
+type ActiveAt = (node: string, y: number) => boolean;
+
+const activationLookup = (layout: FlowLayout): ActiveAt => {
+  const byNode = new Map(
+    layout.participants.map((participant) => [participant.node.id, participant.activations]),
+  );
+  return (node, y) =>
+    (byNode.get(node) ?? []).some((bar) => bar.top <= y && y <= bar.bottom);
+};
+
+type Ends = { start: number; end: number };
+
+/**
+ * Where an arrow starts and stops horizontally. An activated column is a bar,
+ * not a line, so an arrow that touches one has to stop at its edge, and the
+ * arrowhead needs room of its own on top of that.
+ */
+const endsFor = (
+  placed: PlacedMessage,
+  activeAt: ActiveAt,
+  direction: -1 | 1,
+): Ends => ({
+  start:
+    placed.fromX +
+    direction * (activeAt(placed.message.from, placed.y) ? ACTIVATION_HALF_WIDTH : 0),
+  end:
+    placed.toX -
+    direction *
+      ((activeAt(placed.message.to, placed.y) ? ACTIVATION_HALF_WIDTH : 0) + MARKER_INSET),
+});
+
+const selfPath = (x: number, y: number, activated: boolean): string => {
+  const start = x + (activated ? ACTIVATION_HALF_WIDTH : 0);
+  return (
+    `M${coord(start)},${coord(y)} h${coord(SELF_LOOP_REACH)} ` +
+    `a${SELF_LOOP_CORNER},${SELF_LOOP_CORNER} 0 0 1 ${SELF_LOOP_CORNER},${SELF_LOOP_CORNER} ` +
+    `v${coord(SELF_LOOP_DROP)} ` +
+    `a${SELF_LOOP_CORNER},${SELF_LOOP_CORNER} 0 0 1 -${SELF_LOOP_CORNER},${SELF_LOOP_CORNER} ` +
+    `h-${coord(SELF_LOOP_REACH - MARKER_INSET)}`
+  );
+};
+
+/** How far a self message's pill stands off the loop it names. */
+const SELF_PILL_GAP = 8;
+
+const pillWidth = (label: string): number =>
+  measure(label, "sans-bold", PILL_TEXT_SIZE) + PILL_PADDING_X * 2;
+
+/** The pill of a straight message, settled onto the middle of its arrow. */
+const pillBox = (placed: PlacedMessage, ends: Ends): Box => {
+  const width = pillWidth(placed.label);
+  return {
+    x: (ends.start + ends.end) / 2 - width / 2,
+    y: placed.y - PILL_HEIGHT / 2,
+    width,
+    height: PILL_HEIGHT,
+  };
+};
+
+/** A self message's pill, beside the loop and centred on its height. */
+const selfPillBox = (placed: PlacedMessage, activated: boolean): Box => ({
+  x:
+    placed.fromX +
+    (activated ? ACTIVATION_HALF_WIDTH : 0) +
+    SELF_LOOP_REACH +
+    SELF_LOOP_CORNER +
+    SELF_PILL_GAP,
+  y: placed.y + SELF_LOOP_EXTENT / 2 - PILL_HEIGHT / 2,
+  width: pillWidth(placed.label),
+  height: PILL_HEIGHT,
+});
+
+/**
+ * Pulses for one message: the architecture lens's dot, on a sequence's own
+ * clock. Every pulse in the drawing shares one cycle and owns a slot of it
+ * outright, so the steps light in the order they happen, one at a time.
+ *
+ * A slot is spent entirely on the crossing — the dot enters as the previous
+ * one lands and leaves as the next departs. Nothing waits in the dark for its
+ * turn, which is the whole difference between a sequence that reads as a
+ * relay and one that reads as a still picture with an occasional blink.
+ */
+const pulsesFor = (
+  placed: PlacedMessage,
+  path: string,
+  slotCount: number,
+  palette: Palette,
+): string => {
+  if (slotCount === 0) return "";
+  const colour = toneColour(palette, toneFor(placed.message.delta));
+  // A repeated step keeps the heavier mark it has always carried; only when
+  // its crossings happen changed here, not what they look like.
+  const radius = placed.slot.count > 1 ? TRAIN_RADIUS : PULSE_RADIUS;
+  const width = 1 / slotCount;
+  const ramp = width * FLOW_PULSE_RAMP;
+  const duration = `${coord(cycleFor(slotCount))}s`;
+
+  return lines(
+    Array.from({ length: placed.slot.count }, (_, index) => {
+      const start = (placed.slot.start + index) * width;
+      const finish = start + width;
+
+      return wrap(
+        "circle",
+        { r: radius, fill: colour, opacity: 0 },
+        tag("animateMotion", {
+          dur: duration,
+          repeatCount: "indefinite",
+          keyPoints: "0;0;1;1",
+          keyTimes: `0;${ratio(start)};${ratio(finish)};1`,
+          calcMode: "linear",
+          path,
+        }) +
+          tag("animate", {
+            attributeName: "opacity",
+            dur: duration,
+            repeatCount: "indefinite",
+            values: "0;0;1;1;0;0",
+            keyTimes:
+              `0;${ratio(start)};${ratio(start + ramp)};` +
+              `${ratio(finish - ramp)};${ratio(finish)};1`,
+          }),
+      );
+    }),
+  );
+};
+
+/**
+ * Paints one message and the pill that names it. Like an architecture edge
+ * and its label, the two come back separately because they belong to
+ * different layers: the pill is opaque precisely so it can be read wherever
+ * it lands, so it passes in front of everything the arrows drew.
+ */
+const paintMessage = (
+  placed: PlacedMessage,
+  activeAt: ActiveAt,
+  slotCount: number,
+  palette: Palette,
+): { line: string; pill: string } => {
+  const tone = toneFor(placed.message.delta);
+  const direction = travelDirection(placed.message.kind, placed.fromX, placed.toX);
+  const head = headFor(placed.message.kind, tone);
+
+  if (direction === 0) {
+    const activated = activeAt(placed.message.from, placed.y);
+    const path = selfPath(placed.fromX, placed.y, activated);
+    return {
+      line: lines([
+        tag("path", { class: messageClasses(placed.message, tone), d: path, "marker-end": head }),
+        pulsesFor(placed, path, slotCount, palette),
+      ]),
+      pill: paintLabelPill(placed.label, selfPillBox(placed, activated), tone),
+    };
+  }
+
+  const ends = endsFor(placed, activeAt, direction);
+  const path = `M${coord(ends.start)},${coord(placed.y)} L${coord(ends.end)},${coord(placed.y)}`;
+
+  return {
+    line: lines([
+      tag("path", { class: messageClasses(placed.message, tone), d: path, "marker-end": head }),
+      pulsesFor(placed, path, slotCount, palette),
+    ]),
+    pill: paintLabelPill(placed.label, pillBox(placed, ends), tone),
+  };
+};
+
+/**
+ * The ground under one column: a band in the lane language, holding the
+ * card, its lifeline and its activation bars with the same breathing room a
+ * lane keeps around its cards.
+ */
+const bandBox = (centreX: number, columnWidth: number, layout: FlowLayout): Box => {
+  const top = layout.top + PARTICIPANT_TOP - FLOW_BAND_PAD_Y;
+  return {
+    x: centreX - columnWidth / 2 - FLOW_BAND_PAD_X,
+    y: top,
+    width: columnWidth + FLOW_BAND_PAD_X * 2,
+    height: layout.top + layout.height + FLOW_BAND_PAD_Y - top,
+  };
+};
+
+const paintFlow = (
+  layout: FlowLayout,
+  columnWidth: number,
+  slotCount: number,
+  palette: Palette,
+): string => {
+  const activeAt = activationLookup(layout);
+
+  const lifelineBottom = layout.top + layout.height;
+
+  const bands = layout.participants.map((participant) => {
+    const box = bandBox(participant.centreX, columnWidth, layout);
+    return tag("rect", {
+      class: "lanebox",
+      x: coord(box.x),
+      y: coord(box.y),
+      width: coord(box.width),
+      height: coord(box.height),
+      rx: LANE_RADIUS,
+    });
+  });
+
+  const columns = layout.participants.map((participant) =>
+    lines([
+      tag("line", {
+        class: "lifeline",
+        x1: coord(participant.centreX),
+        y1: coord(layout.lifelineTop),
+        x2: coord(participant.centreX),
+        y2: coord(lifelineBottom),
+      }),
+      ...participant.activations.map((bar) =>
+        tag("rect", {
+          class: "actbar",
+          x: coord(participant.centreX - ACTIVATION_HALF_WIDTH),
+          y: coord(bar.top),
+          width: ACTIVATION_HALF_WIDTH * 2,
+          height: coord(bar.bottom - bar.top),
+          rx: 4,
+        }),
+      ),
+    ]),
+  );
+
+  const cards = layout.participants.map((participant, index) =>
+    paintCard({
+      node: participant.node,
+      box: participant.card,
+      showIcon: true,
+      titleSize: TITLE_SIZE,
+      row: 0,
+      laneIndex: index,
+    }),
+  );
+
+  const lineMarkup: string[] = [];
+  const pillMarkup: string[] = [];
+  for (const message of layout.messages) {
+    const { line, pill } = paintMessage(message, activeAt, slotCount, palette);
+    lineMarkup.push(line);
+    pillMarkup.push(pill);
+  }
+
+  return lines([
+    wrap("g", {}, lines(bands)),
+    wrap("g", {}, lines(columns)),
+    wrap("g", {}, lines(cards)),
+    wrap("g", {}, lines(lineMarkup)),
+    wrap("g", {}, lines(pillMarkup)),
+  ]);
+};
+
+/**
+ * The room a flow's own drawing takes. The bands already hold the cards and
+ * columns, but a pill is centred on its arrow and a self message's sits off
+ * to the right of one, so either can reach past what the layout sized the
+ * canvas from.
+ */
+const flowBounds = (layout: FlowLayout, columnWidth: number): Box[] => {
+  const activeAt = activationLookup(layout);
+
+  const bands = layout.participants.map((participant) =>
+    bandBox(participant.centreX, columnWidth, layout),
+  );
+
+  const pills = layout.messages.map((placed) => {
+    const direction = travelDirection(placed.message.kind, placed.fromX, placed.toX);
+
+    if (direction === 0) return selfPillBox(placed, activeAt(placed.message.from, placed.y));
+    return pillBox(placed, endsFor(placed, activeAt, direction));
+  });
+
+  const loops = layout.messages
+    .filter((placed) => placed.message.kind === "self")
+    .map((placed) => ({
+      x: placed.fromX,
+      y: placed.y,
+      width: SELF_LOOP_REACH + SELF_LOOP_CORNER + ACTIVATION_HALF_WIDTH,
+      height: SELF_LOOP_DROP + SELF_LOOP_CORNER * 2,
+    }));
+
+  return [...bands, ...pills, ...loops];
+};
+
+export type DataFlowPainting = { width: number; height: number; body: string };
+
+export const paintDataFlow = (
+  flows: readonly Flow[],
+  nodes: readonly GraphNode[],
+  palette: Palette,
+): DataFlowPainting => {
+  const layout = layoutDataFlow(flows, nodes, FLOW_MAX_PULSES_PER_MESSAGE);
+
+  const canvas = canvasFor(
+    layout,
+    union(layout.flows.flatMap((flow) => flowBounds(flow, layout.columnWidth))),
+    DIAGRAM_MARGIN,
+  );
+
+  return {
+    width: canvas.width,
+    height: canvas.height,
+    body: shifted(
+      canvas,
+      lines(
+        layout.flows.map((flow) =>
+          paintFlow(flow, layout.columnWidth, layout.slotCount, palette),
+        ),
+      ),
+    ),
+  };
+};

package/src/svg/document.ts

@@ -0,0 +1,198 @@
+import type { Delta } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
+import type { Canvas } from "../bounds.js";
+import { coord } from "../geometry.js";
+import type { Palette } from "../theme.js";
+import { MONO_STACK, SANS_STACK } from "../text.js";
+import { escapeXml, lines, tag, wrap } from "./primitives.js";
+
+/**
+ * The colour family an element is drawn in. It follows the delta rather than
+ * the element type, because the one question a reviewer asks of a diagram is
+ * what changed.
+ */
+export type Tone = "added" | "modified" | "removed" | "neutral";
+
+export const toneFor = (delta: Delta): Tone => {
+  switch (delta) {
+    case "added":
+      return "added";
+    case "modified":
+      return "modified";
+    case "removed":
+      return "removed";
+    case "unchanged":
+      return "neutral";
+    default:
+      return assertNever(delta, "Unhandled delta");
+  }
+};
+
+export const toneColour = (palette: Palette, tone: Tone): string => {
+  switch (tone) {
+    case "added":
+      return palette.added;
+    case "modified":
+      return palette.modified;
+    case "removed":
+      return palette.removed;
+    case "neutral":
+      return palette.edge;
+    default:
+      return assertNever(tone, "Unhandled tone");
+  }
+};
+
+const TONES = ["added", "modified", "removed", "neutral"] as const satisfies readonly Tone[];
+
+const stylesheet = (palette: Palette): string =>
+  [
+    `text{font-family:${SANS_STACK}}`,
+    `.lanebox{fill:${palette.lane}}`,
+    `.lanelabel{font-size:10px;font-weight:700;letter-spacing:.12em;fill:${palette.muted}}`,
+    `.card{fill:${palette.card};stroke:${palette.cardBorder};stroke-width:1}`,
+    `.card-added{stroke:${palette.added};stroke-opacity:.55}`,
+    `.card-modified{stroke:${palette.modified};stroke-opacity:.5}`,
+    `.ghost{opacity:.55}`,
+    `.ghost .card{stroke:${palette.removed};stroke-dasharray:4 3;stroke-opacity:.6}`,
+    `.context{opacity:.82}`,
+    `.ntitle{font-weight:600;fill:${palette.foreground}}`,
+    `.strike{text-decoration:line-through}`,
+    `.nsub{font-size:9.5px;fill:${palette.muted};font-family:${MONO_STACK}}`,
+    `.chip{fill:${palette.chip}}`,
+    `.glyph{fill:${palette.muted}}`,
+    `.glyph-stroke{stroke:${palette.muted};stroke-width:1.4;fill:none}`,
+    `.bdg text{font-size:8.5px;font-weight:700;letter-spacing:.06em}`,
+    `.bdg rect{stroke-width:1}`,
+    `.bdg-added rect{fill:${palette.addedFill};stroke:${palette.addedBorder}}`,
+    `.bdg-added text{fill:${palette.added}}`,
+    `.bdg-modified rect{fill:${palette.modifiedFill};stroke:${palette.modifiedBorder}}`,
+    `.bdg-modified text{fill:${palette.modified}}`,
+    `.bdg-removed rect{fill:${palette.removedFill};stroke:${palette.removedBorder}}`,
+    `.bdg-removed text{fill:${palette.removed}}`,
+    `.bdg-neutral rect{fill:${palette.neutralFill};stroke:${palette.cardBorder}}`,
+    `.bdg-neutral text{fill:${palette.muted}}`,
+    `.edge{fill:none;stroke-width:1.5}`,
+    `.edge-added{stroke:${palette.added}}`,
+    `.edge-modified{stroke:${palette.modified}}`,
+    `.edge-removed{stroke:${palette.removed};stroke-dasharray:5 4;opacity:.7}`,
+    `.edge-neutral{stroke:${palette.edge}}`,
+    `.hero{stroke-width:2.25}`,
+    `.faded{opacity:.45}`,
+    `.glow{fill:none;stroke-width:7;opacity:.14}`,
+    `.msg-self{font-size:11px;fill:${palette.foreground}}`,
+    `.lpill{fill:${palette.pill};stroke:${palette.pillBorder};stroke-width:1}`,
+    `.ltext{font-size:9.5px;font-weight:600;fill:${palette.muted}}`,
+    `.ltext-added{fill:${palette.added}}`,
+    `.ltext-modified{fill:${palette.modified}}`,
+    `.ltext-removed{fill:${palette.removed}}`,
+    `.cardsh{filter:drop-shadow(0 1px 2px ${palette.shadow})}`,
+    `.lifeline{stroke:${palette.lifeline};stroke-width:1;stroke-dasharray:3 4}`,
+    `.actbar{fill:${palette.addedFill};stroke:${palette.addedBorder}}`,
+    `.msg{fill:none;stroke-width:1.5}`,
+    `.msg-return{stroke-dasharray:4 3;opacity:.8}`,
+    `.msg-strong{stroke-width:2.25}`,
+  ].join("");
+
+/**
+ * Two arrowhead forms per tone, the classic sequence-diagram pair: a filled
+ * head for a message the sender waits on, an open line-form head for one it
+ * fires and forgets. The open head anchors at its tip so the line runs all
+ * the way into the point, where a filled head covers its own line end.
+ */
+const markers = (palette: Palette): string =>
+  TONES.map(
+    (tone) =>
+      wrap(
+        "marker",
+        {
+          id: `mk-${tone}`,
+          viewBox: "0 0 10 10",
+          refX: 8,
+          refY: 5,
+          markerWidth: 6.5,
+          markerHeight: 6.5,
+          orient: "auto-start-reverse",
+        },
+        tag("path", { d: "M0,0 L10,5 L0,10 z", fill: toneColour(palette, tone) }),
+      ) +
+      wrap(
+        "marker",
+        {
+          id: `mko-${tone}`,
+          viewBox: "0 0 10 10",
+          refX: 10,
+          refY: 5,
+          markerWidth: 6.5,
+          markerHeight: 6.5,
+          orient: "auto-start-reverse",
+        },
+        tag("path", {
+          d: "M2,1 L10,5 L2,9",
+          fill: "none",
+          stroke: toneColour(palette, tone),
+          "stroke-width": 1.6,
+          "stroke-linecap": "round",
+          "stroke-linejoin": "round",
+        }),
+      ),
+  ).join("");
+
+export const markerFor = (tone: Tone): string => `url(#mk-${tone})`;
+
+export const openMarkerFor = (tone: Tone): string => `url(#mko-${tone})`;
+
+const DOT_PITCH = 18;
+
+/**
+ * Wraps painted content in a standalone SVG file.
+ *
+ * Nothing outside the file is referenced: it is served through an image proxy
+ * where the page it lands in does not exist, and it is served as an image, so
+ * script would not run even if it were there. Colours are literal for the
+ * same reason — the theme is chosen by picking a file, not by asking the page.
+ */
+export const svgDocument = (input: {
+  width: number;
+  height: number;
+  palette: Palette;
+  title: string;
+  description?: string;
+  body: string;
+}): string => {
+  const { width, height, palette, title, description, body } = input;
+
+  const defs = wrap(
+    "defs",
+    {},
+    wrap(
+      "pattern",
+      { id: "dots", width: DOT_PITCH, height: DOT_PITCH, patternUnits: "userSpaceOnUse" },
+      tag("circle", { cx: 1.5, cy: 1.5, r: 1, fill: palette.dot }),
+    ) + markers(palette),
+  );
+
+  return lines([
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${coord(width)} ${coord(height)}" ` +
+      `width="${coord(width)}" height="${coord(height)}" role="img" aria-label="${escapeXml(title)}">`,
+    wrap("title", {}, escapeXml(title)),
+    description === undefined ? "" : wrap("desc", {}, escapeXml(description)),
+    wrap("style", {}, stylesheet(palette)),
+    defs,
+    tag("rect", { x: 0, y: 0, width: coord(width), height: coord(height), rx: 12, fill: palette.background }),
+    tag("rect", { x: 0, y: 0, width: coord(width), height: coord(height), rx: 12, fill: "url(#dots)" }),
+    body,
+    "</svg>",
+  ]);
+};
+
+/**
+ * Moves painted content clear of the canvas edge when something was drawn
+ * above or to the left of the origin. Wrapping rather than re-deriving every
+ * coordinate keeps the geometry — and so the bytes — unchanged whenever the
+ * shift is zero, which is the ordinary case.
+ */
+export const shifted = (canvas: Canvas, body: string): string =>
+  canvas.shiftX === 0 && canvas.shiftY === 0
+    ? body
+    : wrap("g", { transform: `translate(${coord(canvas.shiftX)},${coord(canvas.shiftY)})` }, body);