---
import DomainIcon from "./domain/DomainIcon.astro";
import DomainNode from "./domain/DomainNode.astro";
import { KIND_ORDER, KINDS, type Kind } from "./domain/kinds.ts";
/**
* `<DAG />` — server-rendered SVG of a small directed acyclic graph.
*
* Used in concept docs to illustrate resource dependency graphs and
* lifecycle flows. Auto-layouts nodes left-to-right using longest-path
* layering, then positions each node within its layer to minimize
* crossings (centered, tie-broken by input order).
*
* Styled to match the brand (parchment panel, moss accents, walnut
* text, JetBrains Mono labels).
*
* Usage in MDX:
* import DAG from "../../../components/DAG.astro";
* <DAG
* nodes={[
* { id: "Bucket", label: "Bucket", type: "Cloudflare.R2Bucket" },
* { id: "Sessions", label: "Sessions", type: "Cloudflare.KVNamespace" },
* { id: "Queue", label: "Queue", type: "AWS.SQS.Queue" },
* { id: "Worker", label: "Worker", type: "Cloudflare.Worker" },
* ]}
* edges={[
* { from: "Bucket", to: "Queue" },
* { from: "Bucket", to: "Worker" },
* { from: "Sessions", to: "Worker" },
* { from: "Queue", to: "Worker" },
* ]}
* />
*/
export interface NodeIn {
id: string;
/** Visible label inside the node (defaults to `id`). */
label?: string;
/** Smaller subtitle below the label (e.g. resource type). */
type?: string;
/** Optional layer override (0-indexed left-to-right). Otherwise computed. */
layer?: number;
/**
* Fixed grid placement. When every node has `col` and `row`, auto-layout is
* skipped and edges are routed by direction: straight along a row or a
* column, or an elbow (down, then across) between rows.
*/
col?: number;
row?: number;
/** Visual tone for the node. Defaults to "default". */
tone?: "default" | "accent" | "warn" | "danger";
/**
* What the node is in a domain model. Draws it with that kind's shape, icon
* and colour (see `./domain/kinds.ts`), and adds a legend of the kinds shown.
*/
kind?: Kind;
}
export type { Kind } from "./domain/kinds.ts";
export interface EdgeIn {
from: string;
to: string;
/** Optional small label drawn near the edge midpoint. */
label?: string;
/** Render as a dashed line (e.g. for "later" / "deferred" edges). */
dashed?: boolean;
}
interface Props {
nodes: NodeIn[];
edges: EdgeIn[];
/** Layout direction. Defaults to "LR" (left-to-right). */
direction?: "LR" | "TB";
/** Optional caption rendered below the graph. */
caption?: string;
}
const { nodes, edges, direction = "LR", caption } = Astro.props as Props;
const kindsShown = KIND_ORDER.filter((k) => nodes.some((n) => n.kind === k));
// ---------- Layout ----------
// Domain nodes carry an icon beside their label, so they get a little more room.
const NODE_W = nodes.some((n) => n.kind) ? 164 : 140;
const NODE_H = 56;
const NODE_H_TYPED = 64; // slightly taller when subtitle present
const COL_GAP = 80;
const ROW_GAP = 28;
const PAD = 24;
const idIndex = new Map(nodes.map((n, i) => [n.id, i]));
// Longest-path layering: layer(v) = 1 + max(layer(u)) over predecessors.
const incoming = new Map<string, string[]>();
const outgoing = new Map<string, string[]>();
for (const n of nodes) {
incoming.set(n.id, []);
outgoing.set(n.id, []);
}
for (const e of edges) {
outgoing.get(e.from)?.push(e.to);
incoming.get(e.to)?.push(e.from);
}
// Longest-path layering, cycle-safe: any predecessor edge that would
// re-enter a node currently on the recursion stack is treated as a
// back-edge and ignored for the purposes of layer assignment. This
// keeps cyclic graphs (A binds B, B binds A) layoutable side-by-side.
const layerOf = new Map<string, number>();
const visiting = new Set<string>();
const visit = (id: string): number => {
const cached = layerOf.get(id);
if (cached !== undefined) return cached;
const override = nodes[idIndex.get(id)!]?.layer;
if (override !== undefined) {
layerOf.set(id, override);
return override;
}
if (visiting.has(id)) {
// Back-edge: caller will Math.max with our placeholder; returning
// -1 means "don't push my dependent down a layer for this edge".
return -1;
}
visiting.add(id);
const preds = incoming.get(id) ?? [];
const predLayers = preds.map(visit).filter((l) => l >= 0);
const l = predLayers.length === 0 ? 0 : Math.max(...predLayers) + 1;
visiting.delete(id);
layerOf.set(id, l);
return l;
};
nodes.forEach((n) => visit(n.id));
const layers: string[][] = [];
for (const n of nodes) {
const l = layerOf.get(n.id)!;
if (!layers[l]) layers[l] = [];
layers[l].push(n.id);
}
// Heights — bump rows that have a subtitle.
const heightOf = (id: string): number =>
nodes[idIndex.get(id)!]?.type ? NODE_H_TYPED : NODE_H;
// Position nodes within each layer; center on the tallest layer.
const colMaxHeight = layers.map((col) =>
col.reduce((acc, id) => acc + heightOf(id) + ROW_GAP, -ROW_GAP),
);
const tallest = Math.max(...colMaxHeight);
const positions = new Map<string, { x: number; y: number; h: number }>();
const GRID_ROW_GAP = 56;
const grid = nodes.every((n) => n.col !== undefined && n.row !== undefined);
if (grid) {
for (const n of nodes) {
positions.set(n.id, {
x: PAD + n.col! * (NODE_W + COL_GAP),
y: PAD + n.row! * (NODE_H_TYPED + GRID_ROW_GAP),
h: NODE_H_TYPED,
});
}
} else if (direction === "LR") {
layers.forEach((col, ci) => {
const colH = colMaxHeight[ci]!;
let y = PAD + (tallest - colH) / 2;
for (const id of col) {
const h = heightOf(id);
positions.set(id, {
x: PAD + ci * (NODE_W + COL_GAP),
y,
h,
});
y += h + ROW_GAP;
}
});
} else {
// TB — swap roles: each "layer" becomes a row.
layers.forEach((row, ri) => {
const rowW = row.length * (NODE_W + COL_GAP) - COL_GAP;
const totalW = Math.max(
...layers.map((r) => r.length * (NODE_W + COL_GAP) - COL_GAP),
);
let x = PAD + (totalW - rowW) / 2;
for (const id of row) {
const h = heightOf(id);
positions.set(id, {
x,
y: PAD + ri * (NODE_H_TYPED + 60),
h,
});
x += NODE_W + COL_GAP;
}
});
}
const hasBackEdge = edges.some(
(e) => (layerOf.get(e.to) ?? 0) <= (layerOf.get(e.from) ?? 0),
);
const BACK_EDGE_GUTTER = 56;
const gridCols = grid ? Math.max(...nodes.map((n) => n.col!)) + 1 : 0;
const gridRows = grid ? Math.max(...nodes.map((n) => n.row!)) + 1 : 0;
const W = grid
? PAD * 2 + gridCols * NODE_W + (gridCols - 1) * COL_GAP
:
direction === "LR"
? PAD * 2 +
layers.length * NODE_W +
(layers.length - 1) * COL_GAP +
(hasBackEdge ? BACK_EDGE_GUTTER : 0)
: PAD * 2 +
Math.max(...layers.map((r) => r.length * (NODE_W + COL_GAP) - COL_GAP));
const H = grid
? PAD * 2 + gridRows * NODE_H_TYPED + (gridRows - 1) * GRID_ROW_GAP
:
direction === "LR"
? PAD * 2 + tallest + (hasBackEdge ? BACK_EDGE_GUTTER : 0)
: PAD * 2 +
layers.length * (NODE_H_TYPED + 60) -
60 +
(hasBackEdge ? BACK_EDGE_GUTTER : 0);
// ---------- Edge geometry ----------
interface Edge {
d: string;
midX: number;
midY: number;
label?: string;
dashed?: boolean;
}
const TIP = 6;
const gridEdge = (e: EdgeIn): Edge => {
const a = positions.get(e.from)!;
const b = positions.get(e.to)!;
const done = (d: string, midX: number, midY: number): Edge => ({
d,
midX,
midY,
label: e.label,
dashed: e.dashed,
});
const ay = a.y + a.h / 2;
const by = b.y + b.h / 2;
if (a.y === b.y) {
// Along a row, either way.
const [x1, x2] = b.x > a.x ? [a.x + NODE_W, b.x - TIP] : [a.x, b.x + NODE_W + TIP];
return done(`M ${x1} ${ay} L ${x2} ${by}`, (x1 + x2) / 2, ay);
}
const ax = a.x + NODE_W / 2;
if (a.x === b.x) {
// Along a column, either way.
const [y1, y2] = b.y > a.y ? [a.y + a.h, b.y - TIP] : [a.y, b.y + b.h + TIP];
return done(`M ${ax} ${y1} L ${ax} ${y2}`, ax, (y1 + y2) / 2);
}
// An elbow: leave from the top or bottom, then run across into the target's side.
const y1 = b.y > a.y ? a.y + a.h : a.y;
const x2 = b.x > a.x ? b.x - TIP : b.x + NODE_W + TIP;
return done(`M ${ax} ${y1} L ${ax} ${by} L ${x2} ${by}`, (ax + x2) / 2, by);
};
const buildEdges = (): Edge[] =>
edges.map((e) => {
if (grid) return gridEdge(e);
const a = positions.get(e.from)!;
const b = positions.get(e.to)!;
const aLayer = layerOf.get(e.from)!;
const bLayer = layerOf.get(e.to)!;
const isBack =
direction === "LR" ? bLayer <= aLayer : bLayer <= aLayer;
if (direction === "LR") {
if (!isBack) {
// Forward edge — straight cubic from source.right to target.left.
const x1 = a.x + NODE_W;
const y1 = a.y + a.h / 2;
const x2 = b.x - TIP;
const y2 = b.y + b.h / 2;
const cx = x1 + (x2 - x1) * 0.5;
const d = `M ${x1} ${y1} C ${cx} ${y1}, ${cx} ${y2}, ${x2} ${y2}`;
return {
d,
midX: (x1 + x2) / 2,
midY: (y1 + y2) / 2,
label: e.label,
dashed: e.dashed,
};
}
// Back-edge — arc beneath both nodes from source.bottom to target.bottom
// so arrow remains visibly between/under the nodes (not behind them).
const x1 = a.x + NODE_W * 0.5;
const y1 = a.y + a.h;
const x2 = b.x + NODE_W * 0.5;
const y2 = b.y + b.h + TIP;
const dropMax = 36;
const cy = Math.max(y1, y2) + dropMax;
const d = `M ${x1} ${y1} C ${x1} ${cy}, ${x2} ${cy}, ${x2} ${y2}`;
return {
d,
midX: (x1 + x2) / 2,
midY: cy,
label: e.label,
dashed: e.dashed,
};
}
// TB direction.
if (!isBack) {
const x1 = a.x + NODE_W / 2;
const y1 = a.y + a.h;
const x2 = b.x + NODE_W / 2;
const y2 = b.y - TIP;
const cy = y1 + (y2 - y1) * 0.5;
const d = `M ${x1} ${y1} C ${x1} ${cy}, ${x2} ${cy}, ${x2} ${y2}`;
return {
d,
midX: (x1 + x2) / 2,
midY: (y1 + y2) / 2,
label: e.label,
dashed: e.dashed,
};
}
// TB back-edge — arc to the right.
const x1 = a.x + NODE_W;
const y1 = a.y + a.h / 2;
const x2 = b.x + NODE_W + TIP;
const y2 = b.y + b.h / 2;
const dx = 36;
const cx = Math.max(x1, x2) + dx;
const d = `M ${x1} ${y1} C ${cx} ${y1}, ${cx} ${y2}, ${x2} ${y2}`;
return {
d,
midX: cx,
midY: (y1 + y2) / 2,
label: e.label,
dashed: e.dashed,
};
});
const edgeShapes = buildEdges();
---
<figure class="alc-dag not-content" data-nosnippet>
<svg
class="alc-dag__svg"
viewBox={`0 0 ${W} ${H}`}
role="img"
aria-label={caption ?? "Dependency graph"}
>
<defs>
<marker
id="alc-dag-arrow"
viewBox="0 0 10 10"
refX="8"
refY="5"
markerWidth="6"
markerHeight="6"
orient="auto-start-reverse"
>
<path d="M 0 0 L 10 5 L 0 10 z" fill="var(--alc-accent)" />
</marker>
</defs>
{/* Edges first so they sit beneath nodes. */}
{edgeShapes.map((e) => (
<g class="alc-dag__edge">
<path
d={e.d}
fill="none"
stroke="var(--alc-accent-60)"
stroke-width="1.5"
stroke-dasharray={e.dashed ? "4 4" : undefined}
marker-end="url(#alc-dag-arrow)"
/>
{e.label && (
<text
x={e.midX}
y={e.midY - 6}
class="alc-dag__edge-label"
text-anchor="middle"
>
{e.label}
</text>
)}
</g>
))}
{/* Nodes. */}
{nodes.map((n) => {
const p = positions.get(n.id)!;
const tone = n.tone ?? "default";
if (n.kind) {
return (
<g transform={`translate(${p.x}, ${p.y})`}>
<DomainNode
kind={n.kind}
width={NODE_W}
height={p.h}
label={n.label ?? n.id}
type={n.type}
/>
</g>
);
}
return (
<g class={`alc-dag__node alc-dag__node--${tone}`} transform={`translate(${p.x}, ${p.y})`}>
<rect
width={NODE_W}
height={p.h}
rx="8"
ry="8"
class="alc-dag__node-bg"
/>
<text
x={NODE_W / 2}
y={n.type ? p.h / 2 - 4 : p.h / 2 + 1}
class="alc-dag__node-label"
text-anchor="middle"
dominant-baseline="middle"
>
{n.label ?? n.id}
</text>
{n.type && (
<text
x={NODE_W / 2}
y={p.h / 2 + 14}
class="alc-dag__node-type"
text-anchor="middle"
dominant-baseline="middle"
>
{n.type}
</text>
)}
</g>
);
})}
</svg>
{
kindsShown.length > 0 && (
<div class="alc-dag__legend">
{kindsShown.map((k) => (
<span class="alc-dag__key">
<DomainIcon kind={k} />
{KINDS[k].name}
</span>
))}
</div>
)
}
{caption && <figcaption class="alc-dag__caption">{caption}</figcaption>}
</figure>
<style>
.alc-dag {
margin: 1.5rem 0;
background: var(--alc-bg-elev-1);
border: 1px solid var(--alc-hairline-2);
border-radius: var(--alc-radius);
padding: 0.75rem;
overflow-x: auto;
}
.alc-dag__svg {
display: block;
width: 100%;
height: auto;
max-width: 100%;
}
.alc-dag__node-bg {
fill: var(--alc-bg-elev-2);
stroke: var(--alc-accent-40);
stroke-width: 1.5;
transition: stroke 200ms ease, fill 200ms ease;
}
.alc-dag__node--accent .alc-dag__node-bg {
stroke: var(--alc-accent);
fill: color-mix(in srgb, var(--alc-accent-soft) 60%, var(--alc-bg-elev-2));
}
.alc-dag__node--warn .alc-dag__node-bg {
stroke: var(--alc-warn);
fill: color-mix(in srgb, var(--alc-warn) 12%, var(--alc-bg-elev-2));
}
.alc-dag__node--danger .alc-dag__node-bg {
stroke: var(--alc-danger);
fill: color-mix(in srgb, var(--alc-danger) 10%, var(--alc-bg-elev-2));
}
.alc-dag__legend {
display: flex;
flex-wrap: wrap;
justify-content: center;
gap: 0.35rem 1rem;
margin-top: 0.5rem;
font-family: var(--alc-font-mono);
font-size: 11.5px;
color: var(--alc-fg-3);
}
.alc-dag__key {
display: inline-flex;
align-items: center;
gap: 0.4rem;
}
.alc-dag__node-label {
font-family: var(--alc-font-mono);
font-size: 13px;
font-weight: 600;
fill: var(--alc-fg-1);
}
.alc-dag__node-type {
font-family: var(--alc-font-mono);
font-size: 10.5px;
fill: var(--alc-fg-3);
}
.alc-dag__edge-label {
font-family: var(--alc-font-mono);
font-size: 10.5px;
fill: var(--alc-fg-3);
}
.alc-dag__caption {
margin-top: 0.5rem;
font-family: var(--alc-font-sans);
font-size: 13px;
color: var(--alc-fg-3);
text-align: center;
}
</style>