@brunosouzas/design-system 0.3.1 → 0.4.0

package/dist/src/pieces/diagram.js

@@ -0,0 +1,205 @@
+// Body diagram pieces (spec illustration-pieces, change body-diagram-pieces,
+// design §3 and §4): the shapes, lines and labels of the blog's body diagrams
+// that the metro and diagram pieces lack. Like those, they paint what the caller
+// lays out; positions, text measurement and truncation stay with the caller.
+//
+// What can go wrong: every parameter is checked by its schema first; the limits
+// between parameters are checked in the order of design §3 and the first one is
+// thrown as a RangeError naming the parameter.
+import { tokens } from "../../tokens/generated/tokens.js";
+import { inkOf, inkSchema, limits, roomFor, sticker, surfaceParam } from "./ink.js";
+import { drawn, el, r2 } from "./node.js";
+import { col, colour, label, MAX_SIZE, pos, size } from "./params.js";
+import { definePiece } from "./piece.js";
+const ink = tokens.color.ink;
+const font = tokens.font.sans;
+const bold = tokens.font.weightBold;
+const M = tokens.map;
+const lines = (max) => ({ kind: "array", required: true, minItems: 1, maxItems: max, of: label() });
+const textSize = { kind: "number", min: 6, max: 48 };
+// ---------- words ----------
+/** Characters of a word for a width estimate: backticks do not count. */
+const characters = (value) => Array.from(value.replace(/`/g, "")).length;
+/** Backticks mark code (design §4): with an even number of them, each part between backticks becomes a tspan in
+ * the monospace stack; empty parts are dropped. With an odd number, the string is drawn as is. */
+const spans = (value) => {
+    const parts = value.split("`");
+    if (parts.length % 2 === 0)
+        return [value];
+    return parts.flatMap((part, i) => (part === "" ? [] : i % 2 === 1 ? [el("tspan", { "font-family": tokens.font.mono }, part)] : [part]));
+};
+// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
+const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, ...spans(value));
+/** No fill: the surface's panel with its text; a fill: that token with ink words (ADR 0003). */
+const coloursOf = (fill, params) => {
+    const { s } = inkOf(params);
+    return fill === undefined ? { face: s.panel, text: s.text, sub: s.muted } : { face: colour(fill, "fill"), text: ink, sub: ink };
+};
+/** Centred lines (bold) and an optional subtitle (11, regular), centred on (cx, cy). */
+const centred = (cx, cy, text, subtitle, c, size_ = M.labelSize) => {
+    const step = size_ * 1.25;
+    const block = (text.length - 1) * step + (subtitle === undefined ? 0 : 15);
+    const first = cy + (4.5 * size_) / 13 - block / 2;
+    return [
+        ...text.map((line, i) => words(cx, first + i * step, line, { fill: c.text, "font-size": size_, "font-weight": bold, "text-anchor": "middle" })),
+        ...(subtitle === undefined ? [] : [words(cx, first + (text.length - 1) * step + 15, subtitle, { fill: c.sub, "font-size": 11, "font-weight": 400, "text-anchor": "middle" })]),
+    ];
+};
+/** Room on the smaller of width and height, naming the smaller one. */
+const roomOn = (width, height, params) => width < height ? roomFor("width", width, params) : roomFor("height", height, params);
+const polygon = (points) => (dx, dy, attrs) => el("polygon", { points: points.map(([px, py]) => `${r2(px + dx)},${r2(py + dy)}`).join(" "), ...attrs });
+const rect = (x, y, w, h, rx) => (dx, dy, attrs) => el("rect", { x: r2(x + dx), y: r2(y + dy), width: r2(w), height: r2(h), rx: r2(rx), ...attrs });
+const shapeSchema = (heightRequired) => ({
+    x: pos(),
+    y: pos(),
+    width: size(true),
+    height: size(heightRequired),
+    text: lines(3),
+    subtitle: label(false),
+    fill: col(),
+    textSize,
+    ...inkSchema,
+});
+/** A box or a pill with a fill and centred lines: a body diagram's step, system or note. */
+export const diagramBox = definePiece("diagramBox", { ...shapeSchema(false), radius: { kind: "number", min: 0, max: MAX_SIZE }, shape: { kind: "enum", values: ["box", "pill"] } }, (params) => {
+    const { x, y, width, height = M.nodeHeight, text, subtitle, fill, shape = "box" } = params;
+    const radius = shape === "pill" ? height / 2 : (params.radius ?? Math.min(M.nodeRadius, height / 2));
+    const c = coloursOf(fill, params);
+    return drawn(sticker(rect(x, y, width, height, radius), c.face, params), centred(x + width / 2, y + height / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const height = params.height ?? M.nodeHeight;
+    return limits(roomOn(params.width, height, params), params.shape === "pill" && params.radius !== undefined && { path: "radius", message: "cannot be combined with shape pill" }, params.radius !== undefined && params.radius > height / 2 && { path: "radius", message: `must be at most half the height (${r2(height / 2)}), found ${r2(params.radius)}` });
+});
+/** A decision: a diamond in its bounds. */
+export const decisionNode = definePiece("decisionNode", shapeSchema(true), (params) => {
+    const { x, y, width: w, height: h, text, subtitle, fill } = params;
+    const c = coloursOf(fill, params);
+    const shape = polygon([[x + w / 2, y], [x + w, y + h / 2], [x + w / 2, y + h], [x, y + h / 2]]);
+    return drawn(sticker(shape, c.face, params), centred(x + w / 2, y + h / 2, text, subtitle, c, params.textSize));
+}, (params) => limits(roomOn(params.width, params.height, params)));
+/** A store: a cylinder in its bounds, with the front of its lid. */
+export const storeNode = definePiece("storeNode", { ...shapeSchema(true), ry: size() }, (params) => {
+    const { x, y, width: w, height: h, text, subtitle, fill, ry = 8 } = params;
+    const c = coloursOf(fill, params);
+    const { outline } = inkOf(params);
+    const rx = r2(w / 2);
+    const body = (dx, dy, attrs) => el("path", { d: `M${r2(x + dx)},${r2(y + ry + dy)} A${rx},${ry} 0 0 1 ${r2(x + w + dx)},${r2(y + ry + dy)} V${r2(y + h - ry + dy)} A${rx},${ry} 0 0 1 ${r2(x + dx)},${r2(y + h - ry + dy)} Z`, ...attrs });
+    const lid = el("path", { d: `M${r2(x)},${r2(y + ry)} A${rx},${ry} 0 0 0 ${r2(x + w)},${r2(y + ry)}`, fill: "none", stroke: ink, "stroke-width": r2(0.75 * outline) });
+    return drawn([...sticker(body, c.face, params), lid], centred(x + w / 2, y + (h + ry) / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const ry = params.ry ?? 8;
+    return limits(roomOn(params.width, params.height, params), ry > params.height / 4 && { path: "ry", message: `must be at most a quarter of the height (${r2(params.height / 4)}), found ${r2(ry)}` });
+});
+const RAIL = 10;
+/** A queue: a box with a rail 10 in from each side. */
+export const queueNode = definePiece("queueNode", shapeSchema(false), (params) => {
+    const { x, y, width: w, height: h = M.nodeHeight, text, subtitle, fill } = params;
+    const c = coloursOf(fill, params);
+    const { outline } = inkOf(params);
+    const rails = el("path", { d: `M${r2(x + RAIL)},${r2(y)} V${r2(y + h)} M${r2(x + w - RAIL)},${r2(y)} V${r2(y + h)}`, fill: "none", stroke: ink, "stroke-width": r2(0.75 * outline) });
+    return drawn([...sticker(rect(x, y, w, h, tokens.radius.small), c.face, params), rails], centred(x + w / 2, y + h / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const height = params.height ?? M.nodeHeight;
+    const least = Math.max(height, 2 * RAIL + 4 * inkOf(params).outline);
+    return limits(roomFor("height", height, params), params.width < least && { path: "width", message: `must be at least the height and leave room for the rails (${r2(least)}), found ${r2(params.width)}` });
+});
+/** An exchange: a hexagon with its points 0.26 × height in, as the motion shape (src/brand/flow-shapes.ts). */
+export const exchangeNode = definePiece("exchangeNode", shapeSchema(false), (params) => {
+    const { x, y, width: w, height: h = M.nodeHeight, text, subtitle, fill } = params;
+    const c = coloursOf(fill, params);
+    const k = 0.26 * h;
+    const shape = polygon([[x + k, y], [x + w - k, y], [x + w, y + h / 2], [x + w - k, y + h], [x + k, y + h], [x, y + h / 2]]);
+    return drawn(sticker(shape, c.face, params), centred(x + w / 2, y + h / 2, text, subtitle, c, params.textSize));
+}, (params) => {
+    const height = params.height ?? M.nodeHeight;
+    return limits(roomFor("height", height, params), params.width < height && { path: "width", message: `must be at least the height (${r2(height)}), found ${r2(params.width)}` });
+});
+// ---------- container ----------
+const TAB = 24;
+const tabWidth = (params) => params.tagWidth ?? 7.2 * characters(params.tag) + 24;
+/** A container (a platform, a broker) with its name on a tab centred on the top edge. */
+export const taggedContainer = definePiece("taggedContainer", { x: pos(), y: pos(), width: size(true), height: size(true), tag: label(), tagWidth: size(), tagFill: col(), fill: col(), ...inkSchema }, (params) => {
+    const { x, y, width, height, tag, tagFill = "color.transitional", fill } = params;
+    const tw = tabWidth(params);
+    const c = coloursOf(fill, params);
+    return drawn([...sticker(rect(x, y, width, height, M.nodeRadius), c.face, params), ...sticker(rect(x + 14, y - TAB / 2, tw, TAB, TAB / 2), colour(tagFill, "tagFill"), params)], [words(x + 14 + tw / 2, y + 4.5, tag, { fill: ink, "font-size": M.badgeTextSize, "font-weight": bold, "text-anchor": "middle" })]);
+}, (params) => {
+    const tw = tabWidth(params);
+    const need = 4 * inkOf(params).outline;
+    return limits(roomOn(params.width, params.height, params), tw < TAB && { path: "tagWidth", message: `must be at least the tab's height (${TAB}), found ${r2(tw)}` }, TAB < need && { path: "inkScale", message: `leaves no room for the tab's outline: the tab is ${TAB} high and needs ${r2(need)}` }, params.width < tw + 28 && { path: "width", message: `leaves no room for the tag: needs at least ${r2(tw + 28)}` });
+});
+/** A participant's lifeline: dashed while active, sparse dots once nothing calls it. */
+export const lifeline = definePiece("lifeline", { x: pos(), y1: pos(), y2: pos(), state: { kind: "enum", values: ["active", "inactive"] }, width: { kind: "number", min: 0, exclusiveMin: true, max: 12 }, surface: surfaceParam }, ({ x, y1, y2, state = "active", width = 1.75, surface = "light" }) => {
+    const active = state === "active";
+    // Width as given, like pipe's: a valid hairline must not round to zero.
+    return drawn([
+        el("line", { x1: r2(x), y1: r2(y1), x2: r2(x), y2: r2(y2), stroke: tokens.surface[surface].muted, "stroke-width": width, "stroke-dasharray": active ? "5 5" : "1 6", "stroke-linecap": active ? "butt" : "round" }),
+    ]);
+}, ({ y1, y2 }) => limits(y1 === y2 && { path: "y2", message: "must differ from y1" }));
+/** A phase of a sequence: a pill across the diagram in its state's colour. */
+export const phaseBand = definePiece("phaseBand", { x: pos(), y: pos(), width: size(true), height: size(), text: label(), fill: { kind: "color", required: true }, textSize, ...inkSchema }, (params) => {
+    const { x, y, width, height = 26, text, fill, textSize: size_ = M.labelSize } = params;
+    return drawn(sticker(rect(x, y, width, height, height / 2), colour(fill, "fill"), params), [
+        words(x + width / 2, y + height / 2 + (4.5 * size_) / 13, text, { fill: ink, "font-size": size_, "font-weight": bold, "text-anchor": "middle" }),
+    ]);
+}, (params) => {
+    const height = params.height ?? 26;
+    return limits(roomFor("height", height, params), params.width < height && { path: "width", message: `must be at least the height (${r2(height)}), found ${r2(params.width)}` });
+});
+/** An alt/else frame: the frame, a dashed divider per section, and a tag (with its condition) per part. */
+export const altFrame = definePiece("altFrame", {
+    x: pos(),
+    y: pos(),
+    width: size(true),
+    height: size(true),
+    tag: label(),
+    condition: label(false),
+    tagWidth: size(),
+    conditionWidth: size(),
+    sections: {
+        kind: "array",
+        maxItems: 10,
+        of: { kind: "object", fields: { y: pos(), tag: label(), condition: label(false), tagWidth: size(), conditionWidth: size() } },
+    },
+    surface: surfaceParam,
+}, ({ x, y, width, height, sections = [], surface = "light", ...first }) => {
+    const s = tokens.surface[surface];
+    const head = (top, { tag, condition, tagWidth, conditionWidth }) => {
+        const tw = tagWidth ?? 6.4 * characters(tag) + 14;
+        const body = [el("rect", { x: r2(x + 7), y: r2(top + 6), width: r2(tw), height: 17, rx: 4, fill: s.text, stroke: "none" })];
+        const text = [words(x + 7 + tw / 2, top + 18.5, tag, { fill: s.panel, "font-size": 10, "font-weight": tokens.font.weightHeavy, "text-anchor": "middle" })];
+        if (condition !== undefined) {
+            body.push(el("rect", { x: r2(x + 7 + tw + 2), y: r2(top + 7.5), width: r2(conditionWidth ?? 6.2 * characters(condition) + 8), height: 14, rx: 3, fill: s.background, stroke: "none" }));
+            text.push(words(x + 7 + tw + 6, top + 18.5, condition, { fill: s.text, "font-size": 11, "font-weight": bold, "text-anchor": "start" }));
+        }
+        return { body, text };
+    };
+    const heads = [head(y, first), ...sections.map((section) => head(section.y, section))];
+    return drawn([
+        el("rect", { x: r2(x), y: r2(y), width: r2(width), height: r2(height), rx: 7, fill: "none", stroke: s.text, "stroke-width": 1.75 }),
+        ...sections.map((section) => el("line", { x1: r2(x), y1: r2(section.y), x2: r2(x + width), y2: r2(section.y), stroke: s.text, "stroke-width": 1.4, "stroke-dasharray": "4 4" })),
+        ...heads.flatMap((part) => part.body),
+    ], heads.flatMap((part) => part.text));
+}, ({ y, height, sections = [] }) => limits(...sections.map((section, i) => (section.y <= y || section.y >= y + height) && { path: `sections[${i}].y`, message: "must lie inside the frame" })));
+/** Words next to an arrow: lines down from the baseline (x, y), optionally on a backdrop that hides what is behind. */
+export const edgeLabel = definePiece("edgeLabel", { x: pos(), y: pos(), lines: lines(4), anchor: { kind: "enum", values: ["start", "middle", "end"] }, backdrop: { kind: "boolean" }, width: size(), textSize, surface: surfaceParam }, ({ x, y, lines: rows, anchor = "middle", backdrop = false, width, textSize: size_ = 11, surface = "light" }) => {
+    const s = tokens.surface[surface];
+    const k = size_ / 11;
+    const body = backdrop
+        ? rows.map((row, i) => {
+            const w = width ?? (6.2 * characters(row) + 8) * k;
+            const left = anchor === "start" ? x - 4 * k : anchor === "end" ? x - w + 4 * k : x - w / 2;
+            return el("rect", { x: r2(left), y: r2(y + (i * 13 - 10) * k), width: r2(w), height: r2(14 * k), rx: 3, fill: s.background, stroke: "none" });
+        })
+        : [];
+    return drawn(body, rows.map((row, i) => words(x, y + i * 13 * k, row, { fill: s.text, "font-size": size_, "font-weight": bold, "text-anchor": anchor })));
+});
+/** Default start radius in layout units: the published dot (bodyDiagram.startRadius at the shown width) laid out at 560. */
+const START_RADIUS = (tokens.bodyDiagram.startRadius * tokens.bodyDiagram.layoutWidth) / tokens.bodyDiagram.width;
+/** The initial state of a state machine (change designer-formats, design §4): a filled dot in the surface's text
+ * colour, no outline (its own stroke none, so a cover's outlined group does not grow it), no shadow, no text. */
+export const stateStart = definePiece("stateStart", { cx: pos(), cy: pos(), r: size(), surface: surfaceParam }, ({ cx, cy, r = START_RADIUS, surface = "light" }) => 
+// The radius is written as given (a size, never rounded away); the centre is a position.
+drawn([el("circle", { cx: r2(cx), cy: r2(cy), r, fill: tokens.surface[surface].text, stroke: "none" })]));
+/** The body diagram pieces, in catalogue order (design §3). */
+export const DIAGRAM_PIECES = { diagramBox, decisionNode, storeNode, queueNode, exchangeNode, taggedContainer, lifeline, phaseBand, altFrame, edgeLabel };

package/dist/src/pieces/index.d.ts

@@ -5,5 +5,5 @@ export { COLOUR_TOKENS, DATA_COLOUR, MAX_ITEMS, paint, MAX_SIZE, checkParams, co
 export { definePiece, type Piece } from "./piece.ts";
 export * from "./library.ts";
 export { EIP_ICONS, EIP_ICON_NAMES, EIP_ICON_HEIGHT, EIP_ICON_WIDTH, type EipIcon } from "./eip-icons.ts";
-export { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec, type CoverFormat, type CoverPiece, type CoverSpec, type CustomNode } from "./cover.ts";
+export { FORMATS, LANGUAGE, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, diagramRings, validateCoverSpec, type CoverFormat, type CoverOptions, type CoverPiece, type CoverRings, type CoverSpec, type CustomNode } from "./cover.ts";
 export { tokens, type Tokens } from "../../tokens/generated/tokens.ts";

package/dist/src/pieces/index.js

@@ -10,5 +10,5 @@ export { COLOUR_TOKENS, DATA_COLOUR, MAX_ITEMS, paint, MAX_SIZE, checkParams, co
 export { definePiece } from "./piece.js";
 export * from "./library.js";
 export { EIP_ICONS, EIP_ICON_NAMES, EIP_ICON_HEIGHT, EIP_ICON_WIDTH } from "./eip-icons.js";
-export { FORMATS, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, validateCoverSpec } from "./cover.js";
+export { FORMATS, LANGUAGE, SAFE_ID, backgroundNames, bannerRingCount, comparePaths, coverTree, diagramRings, validateCoverSpec } from "./cover.js";
 export { tokens } from "../../tokens/generated/tokens.js";

package/dist/src/pieces/ink.d.ts

@@ -0,0 +1,48 @@
+import { type Attrs, type SvgNode } from "./node.ts";
+import type { ParamSpec, Problem, Schema } from "./params.ts";
+export type Point = [number, number];
+export declare const SURFACES: readonly ["light", "dark"];
+export type SurfaceName = (typeof SURFACES)[number];
+export type Ink = {
+    surface?: SurfaceName;
+    inkScale?: number;
+};
+export declare const surfaceParam: ParamSpec;
+export declare const inkScaleParam: ParamSpec;
+export declare const inkSchema: Schema;
+/** Collects the limits between parameters (piece.ts, `relations`). */
+export declare const limits: (...checks: (Problem | false)[]) => Problem[];
+/** The surface's colours and the ink measures at a scale. */
+export declare const inkOf: ({ surface, inkScale }: Ink) => {
+    s: {
+        readonly background: "#14215A";
+        readonly grid: "#1C2D74";
+        readonly muted: "#8F9BD0";
+        readonly panel: "#1C2D74";
+        readonly rim: "#EEF2FF";
+        readonly rimWidth: 1;
+        readonly shadow: "#4C5CB8";
+        readonly text: "#EEF2FF";
+        readonly zoneOpacity: 0.22;
+    } | {
+        readonly background: "#EEF2FF";
+        readonly grid: "#E0E7FB";
+        readonly muted: "#5B6694";
+        readonly panel: "#FFFFFF";
+        readonly rim: "#EEF2FF";
+        readonly rimWidth: 0;
+        readonly shadow: "#0A1033";
+        readonly text: "#0A1033";
+        readonly zoneOpacity: 0.12;
+    };
+    outline: number;
+    rim: number;
+    offset: number;
+};
+/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
+export declare const roomFor: (name: string, smallest: number, inkParams: Ink) => Problem | false;
+export declare const atLeast: (name: string, value: number, least: number, what: string) => Problem | false;
+export type Shape = (dx: number, dy: number, attrs: Attrs) => SvgNode;
+/** The ink sticker (metro-and-diagram-pieces design §3): shadow copy, rim on dark, then the face. */
+export declare const sticker: (shape: Shape, face: string, inkParams: Ink) => SvgNode[];
+export declare const words: (x: number, y: number, value: string, attrs: Attrs) => SvgNode;

package/dist/src/pieces/ink.js

@@ -0,0 +1,38 @@
+// Ink helpers shared by the metro, diagram and body diagram pieces (moved from
+// metro.ts unchanged; change body-diagram-pieces, design §8). Internal: the
+// package does not export this module.
+import { tokens } from "../../tokens/generated/tokens.js";
+import { el, r2 } from "./node.js";
+export const SURFACES = ["light", "dark"];
+const ink = tokens.color.ink;
+const font = tokens.font.sans;
+const M = tokens.map;
+export const surfaceParam = { kind: "enum", values: SURFACES };
+export const inkScaleParam = { kind: "number", min: 0.25, max: 8 };
+export const inkSchema = { surface: surfaceParam, inkScale: inkScaleParam };
+/** Collects the limits between parameters (piece.ts, `relations`). */
+export const limits = (...checks) => checks.filter((check) => check !== false);
+/** The surface's colours and the ink measures at a scale. */
+export const inkOf = ({ surface = "light", inkScale = 1 }) => {
+    const s = tokens.surface[surface];
+    return { s, outline: M.outline * inkScale, rim: s.rimWidth * inkScale, offset: M.shadow * inkScale };
+};
+/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
+export const roomFor = (name, smallest, inkParams) => {
+    const need = 4 * inkOf(inkParams).outline;
+    return smallest < need && { path: name, message: `leaves no room for the outline: needs at least ${r2(need)} at this ink scale` };
+};
+export const atLeast = (name, value, least, what) => value < least && { path: name, message: `must be at least ${what} (${r2(least)}), found ${r2(value)}` };
+/** The ink sticker (metro-and-diagram-pieces design §3): shadow copy, rim on dark, then the face. */
+export const sticker = (shape, face, inkParams) => {
+    const { s, outline, rim, offset } = inkOf(inkParams);
+    const wide = r2(outline + 2 * rim);
+    return [
+        // Joins are set here, so a sticker draws the same inside any group.
+        shape(offset, offset, { fill: s.shadow, stroke: s.shadow, "stroke-width": wide, "stroke-linejoin": "round" }),
+        ...(s.rimWidth > 0 ? [shape(0, 0, { fill: s.rim, stroke: s.rim, "stroke-width": wide, "stroke-linejoin": "round" })] : []),
+        shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" }),
+    ];
+};
+// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
+export const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, value);

package/dist/src/pieces/library.d.ts

@@ -1,4 +1,5 @@
 export * from "./metro.ts";
+export * from "./diagram.ts";
 export * from "./ui-icons.ts";
 export * from "./link-icons.ts";
 type Point = [number, number];
@@ -275,6 +276,27 @@ export declare const PIECES: {
     readonly suggestedHalo: import("./piece.ts").Piece<import("./metro.ts").SuggestedHaloParams>;
     readonly licenceMark: import("./piece.ts").Piece<import("./metro.ts").LicenceMarkParams>;
     readonly zone: import("./piece.ts").Piece<import("./metro.ts").ZoneParams>;
+    readonly diagramBox: import("./piece.ts").Piece<import("./diagram.ts").DiagramBoxParams>;
+    readonly decisionNode: import("./piece.ts").Piece<import("./ink.ts").Ink & {
+        x: number;
+        y: number;
+        width: number;
+        height?: number;
+        text: string[];
+        subtitle?: string;
+        fill?: string;
+        textSize?: number;
+    } & {
+        height: number;
+    }>;
+    readonly storeNode: import("./piece.ts").Piece<import("./diagram.ts").StoreNodeParams>;
+    readonly queueNode: import("./piece.ts").Piece<import("./diagram.ts").ShapeParams>;
+    readonly exchangeNode: import("./piece.ts").Piece<import("./diagram.ts").ShapeParams>;
+    readonly taggedContainer: import("./piece.ts").Piece<import("./diagram.ts").TaggedContainerParams>;
+    readonly lifeline: import("./piece.ts").Piece<import("./diagram.ts").LifelineParams>;
+    readonly phaseBand: import("./piece.ts").Piece<import("./diagram.ts").PhaseBandParams>;
+    readonly altFrame: import("./piece.ts").Piece<import("./diagram.ts").AltFrameParams>;
+    readonly edgeLabel: import("./piece.ts").Piece<import("./diagram.ts").EdgeLabelParams>;
     readonly pill: import("./piece.ts").Piece<PillParams>;
     readonly rings: import("./piece.ts").Piece<RingsParams>;
     readonly sheet: import("./piece.ts").Piece<SheetParams>;
@@ -303,6 +325,7 @@ export declare const PIECES: {
     readonly eipIcon: import("./piece.ts").Piece<EipIconParams>;
     readonly uiIcon: import("./piece.ts").Piece<import("./ui-icons.ts").UiIconParams>;
     readonly linkIcon: import("./piece.ts").Piece<import("./link-icons.ts").LinkIconParams>;
+    readonly stateStart: import("./piece.ts").Piece<import("./diagram.ts").StateStartParams>;
 };
 export type PieceName = keyof typeof PIECES;
 export declare const PIECE_NAMES: PieceName[];

package/dist/src/pieces/library.js

@@ -12,9 +12,11 @@ import { drawn, el, g, r2, shadowed } from "./node.js";
 import { col, colour, count, label, MAX_SIZE, PATH_DATA, pos, size } from "./params.js";
 import { definePiece } from "./piece.js";
 import { METRO_PIECES } from "./metro.js";
+import { DIAGRAM_PIECES, stateStart } from "./diagram.js";
 import { uiIcon } from "./ui-icons.js";
 import { linkIcon } from "./link-icons.js";
 export * from "./metro.js";
+export * from "./diagram.js";
 export * from "./ui-icons.js";
 export * from "./link-icons.js";
 const ink = tokens.color.ink;
@@ -381,5 +383,7 @@ export const PIECES = {
     ...METRO_PIECES,
     uiIcon,
     linkIcon,
+    ...DIAGRAM_PIECES,
+    stateStart,
 };
 export const PIECE_NAMES = Object.keys(PIECES);

package/dist/src/pieces/metro.d.ts

@@ -1,10 +1,5 @@
-type Point = [number, number];
-export declare const SURFACES: readonly ["light", "dark"];
-export type SurfaceName = (typeof SURFACES)[number];
-export type Ink = {
-    surface?: SurfaceName;
-    inkScale?: number;
-};
+import { type Ink, type Point, type SurfaceName } from "./ink.ts";
+export { SURFACES, type Ink, type SurfaceName } from "./ink.ts";
 export type LineBadgeParams = Ink & {
     x: number;
     y: number;
@@ -60,16 +55,20 @@ export declare const nodeBlock: import("./piece.ts").Piece<NodeBlockParams>;
 export declare const pillNode: import("./piece.ts").Piece<NodeParams>;
 /** A diagram hexagon (an agent). */
 export declare const hexNode: import("./piece.ts").Piece<NodeParams>;
+export type ArrowKind = "message" | "reply" | "failure" | "failFast";
 export type MessageArrowParams = {
     from: Point;
     to: Point;
     curve?: "bezier" | "straight";
+    controls?: [Point, Point];
     head?: boolean;
     label?: string;
     width?: number;
+    kind?: ArrowKind;
     surface?: SurfaceName;
 };
-/** An edge with a head at `to`: curved (leaves and enters horizontally) or straight, with an optional label. */
+/** An edge with a head at `to`: curved (leaves and enters horizontally), straight, or through the caller's two
+ * control points, with an optional label. `kind` paints a reply, a failure or a fail-fast path (card 141). */
 export declare const messageArrow: import("./piece.ts").Piece<MessageArrowParams>;
 export type LedgerMarkParams = {
     x: number;
@@ -129,4 +128,3 @@ export declare const METRO_PIECES: {
     readonly licenceMark: import("./piece.ts").Piece<LicenceMarkParams>;
     readonly zone: import("./piece.ts").Piece<ZoneParams>;
 };
-export {};

package/dist/src/pieces/metro.js

@@ -9,46 +9,18 @@
 // cross-parameter limits (room for the outline, width against height, arrow
 // length) are checked here and thrown as a RangeError naming the parameter.
 import { tokens } from "../../tokens/generated/tokens.js";
+import { atLeast, inkOf, inkSchema, limits, roomFor, sticker, surfaceParam, words } from "./ink.js";
 import { drawn, el, g, r2 } from "./node.js";
 import { col, colour, label, MAX_SIZE, PATH_DATA, paint, pos, size } from "./params.js";
 import { definePiece } from "./piece.js";
-export const SURFACES = ["light", "dark"];
+export { SURFACES } from "./ink.js";
 const ink = tokens.color.ink;
 const white = tokens.color.white;
 const font = tokens.font.sans;
 const bold = tokens.font.weightBold;
 const M = tokens.map;
-const surfaceParam = { kind: "enum", values: SURFACES };
-const inkScaleParam = { kind: "number", min: 0.25, max: 8 };
 const dataColour = (required = true) => ({ kind: "dataColor", required });
 const point = (required = true) => ({ kind: "point", required });
-const inkSchema = { surface: surfaceParam, inkScale: inkScaleParam };
-/** Collects the limits between parameters (piece.ts, `relations`). */
-const limits = (...checks) => checks.filter((check) => check !== false);
-/** The surface's colours and the ink measures at a scale. */
-const inkOf = ({ surface = "light", inkScale = 1 }) => {
-    const s = tokens.surface[surface];
-    return { s, outline: M.outline * inkScale, rim: s.rimWidth * inkScale, offset: M.shadow * inkScale };
-};
-/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
-const roomFor = (name, smallest, inkParams) => {
-    const need = 4 * inkOf(inkParams).outline;
-    return smallest < need && { path: name, message: `leaves no room for the outline: needs at least ${r2(need)} at this ink scale` };
-};
-const atLeast = (name, value, least, what) => value < least && { path: name, message: `must be at least ${what} (${r2(least)}), found ${r2(value)}` };
-/** The ink sticker (design §3): shadow copy, rim on dark, then the face. */
-const sticker = (shape, face, inkParams) => {
-    const { s, outline, rim, offset } = inkOf(inkParams);
-    const wide = r2(outline + 2 * rim);
-    return [
-        // Joins are set here, so a sticker draws the same inside any group.
-        shape(offset, offset, { fill: s.shadow, stroke: s.shadow, "stroke-width": wide, "stroke-linejoin": "round" }),
-        ...(s.rimWidth > 0 ? [shape(0, 0, { fill: s.rim, stroke: s.rim, "stroke-width": wide, "stroke-linejoin": "round" })] : []),
-        shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" }),
-    ];
-};
-// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
-const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, value);
 const pill = (x, y, w, h) => (dx, dy, attrs) => el("rect", { x: r2(x + dx), y: r2(y + dy), width: r2(w), height: r2(h), rx: r2(h / 2), ...attrs });
 // Without a text, the default width is the one-character width (card 167).
 const badgeWidth = ({ width, text }) => width ?? Math.max(30, 7.6 * (text === undefined ? 1 : Array.from(text).length) + 18);
@@ -167,32 +139,47 @@ export const nodeBlock = definePiece("nodeBlock", { ...nodeSchema, radius: { kin
 export const pillNode = definePiece("pillNode", nodeSchema, (p) => drawNode("pill", p), nodeLimits("pill"));
 /** A diagram hexagon (an agent). */
 export const hexNode = definePiece("hexNode", nodeSchema, (p) => drawNode("hex", p), nodeLimits("hex"));
-/** An edge with a head at `to`: curved (leaves and enters horizontally) or straight, with an optional label. */
+/** An edge with a head at `to`: curved (leaves and enters horizontally), straight, or through the caller's two
+ * control points, with an optional label. `kind` paints a reply, a failure or a fail-fast path (card 141). */
 export const messageArrow = definePiece("messageArrow", {
     from: point(),
     to: point(),
     curve: { kind: "enum", values: ["bezier", "straight"] },
+    controls: { kind: "array", minItems: 2, maxItems: 2, of: point() },
     head: { kind: "boolean" },
     label: label(false),
     width: { kind: "number", min: 1, max: 12 },
+    kind: { kind: "enum", values: ["message", "reply", "failure", "failFast"] },
     surface: surfaceParam,
-}, ({ from, to, curve = "bezier", head = true, label: text, width = M.edgeWidth, surface = "light" }) => {
+}, ({ from, to, curve = "bezier", controls, head = true, label: text, width = M.edgeWidth, kind = "message", surface = "light" }) => {
     const s = tokens.surface[surface];
+    const paint_ = kind === "failure" ? tokens.color.failure : kind === "failFast" ? tokens.color.failFast : s.text;
     const length = 5 * width;
     const distance = Math.hypot(to[0] - from[0], to[1] - from[1]);
     const dx = to[0] - from[0];
     // A curve whose ends are almost above each other has no horizontal entry: draw it straight.
-    const bent = curve === "bezier" && Math.abs(dx) > 2 * length;
-    const direction = bent ? [Math.sign(dx), 0] : [dx / distance, (to[1] - from[1]) / distance];
+    const bent = controls === undefined && curve === "bezier" && Math.abs(dx) > 2 * length;
+    // With controls, the head points from the last of c2, c1, from that differs from `to` (design §5).
+    const towards = (q) => {
+        const l = Math.hypot(to[0] - q[0], to[1] - q[1]);
+        return [(to[0] - q[0]) / l, (to[1] - q[1]) / l];
+    };
+    const tail = controls && [controls[1], controls[0], from].find((q) => q[0] !== to[0] || q[1] !== to[1]);
+    const direction = tail !== undefined ? towards(tail) : bent ? [Math.sign(dx), 0] : [dx / distance, (to[1] - from[1]) / distance];
     const end = head ? [to[0] - direction[0] * length, to[1] - direction[1] * length] : to;
     const mx = (from[0] + to[0]) / 2;
     const at = (p) => `${r2(p[0])},${r2(p[1])}`;
-    const d = bent ? `M${at(from)} C${r2(mx)},${r2(from[1])} ${r2(mx)},${r2(to[1])} ${at(end)}` : `M${at(from)} L${at(end)}`;
-    const body = [el("path", { d, fill: "none", stroke: s.text, "stroke-width": r2(width), "stroke-linecap": "round" })];
+    const d = controls
+        ? `M${at(from)} C${at(controls[0])} ${at(controls[1])} ${at(end)}`
+        : bent
+            ? `M${at(from)} C${r2(mx)},${r2(from[1])} ${r2(mx)},${r2(to[1])} ${at(end)}`
+            : `M${at(from)} L${at(end)}`;
+    const dash = kind === "message" ? {} : { "stroke-dasharray": `${r2(2.4 * width)} ${r2(3.2 * width)}` };
+    const body = [el("path", { d, fill: "none", stroke: paint_, "stroke-width": r2(width), "stroke-linecap": "round", ...dash })];
     if (head) {
         const normal = [-direction[1] * 2 * width, direction[0] * 2 * width];
         const points = [to, [end[0] + normal[0], end[1] + normal[1]], [end[0] - normal[0], end[1] - normal[1]]];
-        body.push(el("polygon", { points: points.map(at).join(" "), fill: s.text, stroke: s.text, "stroke-width": 1, "stroke-linejoin": "round" }));
+        body.push(el("polygon", { points: points.map(at).join(" "), fill: paint_, stroke: paint_, "stroke-width": 1, "stroke-linejoin": "round" }));
     }
     const words_ = [];
     if (text !== undefined) {
@@ -202,9 +189,9 @@ export const messageArrow = definePiece("messageArrow", {
         words_.push(words(middle[0], middle[1] + 4, text, { fill: s.text, "font-size": 11, "font-weight": 400, "text-anchor": "middle" }));
     }
     return drawn(body, words_);
-}, ({ from, to, head = true, width = M.edgeWidth }) => {
+}, ({ from, to, head = true, width = M.edgeWidth, controls, curve }) => {
     const distance = Math.hypot(to[0] - from[0], to[1] - from[1]);
-    return limits(distance === 0 && { path: "to", message: "must differ from from" }, distance > 0 && head && distance < 10 * width && { path: "to", message: `is too close to from for the head: needs at least ${r2(10 * width)}, found ${r2(distance)}` });
+    return limits(distance === 0 && { path: "to", message: "must differ from from" }, distance > 0 && head && distance < 10 * width && { path: "to", message: `is too close to from for the head: needs at least ${r2(10 * width)}, found ${r2(distance)}` }, controls !== undefined && curve !== undefined && { path: "controls", message: "cannot be combined with curve" });
 });
 /** stackledger's mark (favicon, header): an ink square with a bent line and two stations, 32 units scaled to `size`.
  * On a surface with a rim (dark), a light rim of 2 × rimWidth lines the square inside its 32 box (card 167). */

package/dist/src/pieces/node.d.ts

@@ -1,4 +1,4 @@
-export declare const SVG_TAGS: readonly ["svg", "g", "title", "desc", "defs", "clipPath", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text"];
+export declare const SVG_TAGS: readonly ["svg", "g", "title", "desc", "defs", "clipPath", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text", "tspan"];
 export type SvgTag = (typeof SVG_TAGS)[number];
 export type AttrValue = string | number;
 export type Attrs = Readonly<Record<string, AttrValue>>;

package/dist/src/pieces/node.js

@@ -23,6 +23,7 @@ export const SVG_TAGS = [
     "polygon",
     "path",
     "text",
+    "tspan",
 ];
 export const el = (tag, attrs = {}, ...children) => ({
     tag,

package/dist/src/pieces/params.js

@@ -89,7 +89,8 @@ const checkValue = (spec, value, path, out) => {
             return;
         case "point":
             // Any finite number: a map position has no maximum (spec illustration-pieces, "Positions of any size").
-            if (!Array.isArray(value) || value.length !== 2 || !value.every((n) => typeof n === "number" && Number.isFinite(n))) {
+            // Both indices read directly: every() skips the holes of a sparse array.
+            if (!Array.isArray(value) || value.length !== 2 || ![value[0], value[1]].every((n) => typeof n === "number" && Number.isFinite(n))) {
                 return report(`expected a point [x, y] of finite numbers, found ${describe(value)}`);
             }
             return;
@@ -100,7 +101,9 @@ const checkValue = (spec, value, path, out) => {
                 return report(`expected at least ${spec.minItems} item(s)`);
             if (value.length > (spec.maxItems ?? MAX_ITEMS))
                 return report(`expected at most ${spec.maxItems ?? MAX_ITEMS} item(s)`);
-            value.forEach((item, index) => checkValue(spec.of, item, `${path}[${index}]`, out));
+            // An index loop, not forEach: a hole in a sparse array is checked as a missing item, not skipped.
+            for (let index = 0; index < value.length; index++)
+                checkValue(spec.of, value[index], `${path}[${index}]`, out);
             return;
         case "object":
             if (!isPlainObject(value))

package/dist/src/pieces/render.js

@@ -10,7 +10,8 @@ export const toSvg = (node, depth = 0) => {
     if (node.children.length === 0)
         return `${open}/>`;
     // Text content, alone or mixed with elements, is written inline: added whitespace would change it.
-    if (node.children.some((child) => typeof child === "string")) {
+    // A text node is always written inline, so one holding only a tspan keeps its words intact (body-diagram-pieces §4).
+    if (node.tag === "text" || node.children.some((child) => typeof child === "string")) {
         return `${open}>${node.children.map((child) => toSvg(child)).join("")}</${node.tag}>`;
     }
     if (node.children.every((child) => typeof child === "string")) {

package/dist/tokens/generated/tokens.d.ts

@@ -4,6 +4,13 @@ export declare const tokens: {
         readonly radius: 20;
         readonly width: 1200;
     };
+    readonly bodyDiagram: {
+        readonly layoutWidth: 560;
+        readonly radius: 14;
+        readonly ringRadius: 70;
+        readonly startRadius: 11;
+        readonly width: 800;
+    };
     readonly color: {
         readonly backend: "#FF6B6B";
         readonly blocked: "#FF8A3D";

package/dist/tokens/generated/tokens.js

@@ -5,6 +5,13 @@ export const tokens = {
         "radius": 20,
         "width": 1200
     },
+    "bodyDiagram": {
+        "layoutWidth": 560,
+        "radius": 14,
+        "ringRadius": 70,
+        "startRadius": 11,
+        "width": 800
+    },
     "color": {
         "backend": "#FF6B6B",
         "blocked": "#FF8A3D",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosouzas/design-system",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Design tokens and illustration pieces of brunosouzas.com: tokens as CSS, JSON and TypeScript, pieces that draw SVG (and React), and a cover command.",
   "license": "Apache-2.0",
   "repository": {