@brunosouzas/design-system 0.3.1 → 0.4.0

package/dist/src/pieces/cover.js

@@ -1,5 +1,6 @@
 // Cover specs (spec cover-cli; design §6): validation of the JSON a cover is
-// written in, and the 800x420 frame that draws it from the pieces.
+// written in, and the frames that draw it from the pieces: the 800x420 cover,
+// the banner, the body diagram and the icon (change designer-formats).
 //
 // Why here and not in scripts/: the validation and the frame are pure, so the
 // tests and a future site build can use them without the command line.
@@ -9,12 +10,16 @@
 // attributes, because the cover is published as SVG.
 import { tokens } from "../../tokens/generated/tokens.js";
 import { PIECE_NAMES, PIECES, rings } from "./library.js";
-import { el, g } from "./node.js";
+import { EIP_ICON_HEIGHT, EIP_ICON_WIDTH, EIP_ICONS } from "./eip-icons.js";
+import { LINK_ICON_SIZE } from "./link-icons.js";
+import { el, g, r2 } from "./node.js";
+import { UI_ICON_SIZE } from "./ui-icons.js";
 import { COLOUR_TOKENS, CURRENT_COLOUR, checkParams, isColourLiteral, MAX_SIZE, PATH_DATA } from "./params.js";
 export const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const TOP_LEVEL = ["id", "title", "description", "format", "background", "rings", "pieces", "custom"];
-/** Cover (800x420, the default) or banner (1200x420, rounded corners): spec cover-cli, "Banner output". */
-export const FORMATS = ["cover", "banner"];
+const TOP_LEVEL = ["id", "title", "description", "format", "background", "rings", "pieces", "custom", "customAt", "height", "text"];
+/** Cover (800x420, the default), banner (1200x420, rounded corners), body diagram (560 laid out, 800 shown) or icon:
+ * spec cover-cli, "Banner output", "Diagram output", "Icon output". */
+export const FORMATS = ["cover", "banner", "diagram", "icon"];
 const CUSTOM_TAGS = ["g", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text"];
 // Attributes a free-form object may use (design §6): geometry, paint, text and transform.
 const CUSTOM_ATTRS = new Set([
@@ -134,118 +139,278 @@ export const comparePaths = (a, b) => {
     }
     return left.length - right.length;
 };
-/** Every problem of a parsed spec, sorted by path; empty when the spec is valid. */
-export const validateCoverSpec = (spec) => {
-    if (!isPlainObject(spec))
-        return [{ path: "(root)", message: `a cover spec must be a JSON object, found ${Array.isArray(spec) ? "an array" : describe(spec)}` }];
+// ---------- text tables (spec cover-cli "Text tables", "Text references", "Language choice"; design §3) ----------
+/** A language of a text table and of `--lang`: `pt`, `en`, `pt-br`. */
+export const LANGUAGE = /^[a-z]{2}(-[a-z]{2})?$/;
+const TEXT_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const REFERENCE = /^@([A-Za-z][A-Za-z0-9_-]*)$/;
+const isTextValue = (value) => (typeof value === "string" && value !== "") ||
+    (Array.isArray(value) && value.length > 0 && Array.from({ length: value.length }, (_, i) => value[i]).every((item) => typeof item === "string" && item !== ""));
+/** The table `lang` picks, or the problems of the tables and of the language choice. */
+const pickTable = (spec, lang) => {
+    if (spec.text === undefined)
+        return { problems: lang === undefined ? [] : [{ path: "text", message: "--lang needs text tables" }] };
+    const text = spec.text;
+    if (!isPlainObject(text) || Object.keys(text).length === 0)
+        return { problems: [{ path: "text", message: "expected an object of languages (such as en, pt), each a table of text keys" }] };
+    const problems = [];
+    const tables = new Map();
+    for (const [code, table] of Object.entries(text)) {
+        if (!LANGUAGE.test(code))
+            problems.push({ path: `text.${code}`, message: "expected a language code such as pt or en" });
+        else if (!isPlainObject(table))
+            problems.push({ path: `text.${code}`, message: "expected an object of text keys" });
+        else
+            tables.set(code, table);
+    }
+    const keys = new Set();
+    for (const [code, table] of tables) {
+        for (const [key, value] of Object.entries(table)) {
+            keys.add(key);
+            if (!TEXT_KEY.test(key))
+                problems.push({ path: `text.${code}.${key}`, message: "expected a text key (a letter, then letters, digits, _ or -)" });
+            else if (!isTextValue(value))
+                problems.push({ path: `text.${code}.${key}`, message: "expected a non-empty string or a non-empty array of non-empty strings" });
+        }
+    }
+    for (const [code, table] of tables) {
+        for (const key of keys)
+            if (!Object.hasOwn(table, key))
+                problems.push({ path: `text.${code}.${key}`, message: "missing: another language defines it" });
+    }
+    if (problems.length > 0)
+        return { problems };
+    const codes = [...tables.keys()].sort().join(", ");
+    if (lang === undefined)
+        return { problems: [{ path: "text", message: `choose a language with --lang (${codes})` }] };
+    if (!tables.has(lang))
+        return { problems: [{ path: "text", message: `no table for ${lang} (${codes})` }] };
+    return { table: tables.get(lang), problems: [] };
+};
+/** The spec with every `@key` outside `text` replaced once by the table's value; unknown keys by path. */
+const resolveText = (spec, table) => {
+    const unknown = [];
+    const visit = (value, path) => {
+        if (typeof value === "string") {
+            const match = REFERENCE.exec(value);
+            if (!match)
+                return value;
+            if (!Object.hasOwn(table, match[1])) {
+                unknown.push({ path, message: `unknown text key ${match[1]}` });
+                return value;
+            }
+            const found = table[match[1]];
+            return Array.isArray(found) ? [...found] : found;
+        }
+        if (Array.isArray(value))
+            return Array.from({ length: value.length }, (_, i) => visit(value[i], `${path}[${i}]`));
+        if (isPlainObject(value))
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, visit(child, path ? `${path}.${key}` : key)]));
+        return value;
+    };
+    const { text, ...rest } = spec;
+    return { spec: { ...visit(rest, ""), text }, unknown };
+};
+/** The spec the frame draws: resolved for `lang`, with the language in its id (decision 4). */
+const forLanguage = (spec, lang) => {
+    if (spec.text === undefined || lang === undefined)
+        return spec;
+    const resolved = resolveText(spec, spec.text[lang]).spec;
+    // The id may be a reference too: the language goes on the resolved id.
+    return { ...resolved, id: `${resolved.id}-${lang}` };
+};
+// ---------- validation ----------
+/** Icon pieces and the box each draws in (spec cover-cli, "Icon output"). */
+const ICON_PIECES = ["eipIcon", "uiIcon", "linkIcon"];
+const iconBox = (entry) => {
+    if (entry.piece === "eipIcon") {
+        const scale = entry.scale ?? 1;
+        return [EIP_ICON_WIDTH * scale, EIP_ICON_HEIGHT * scale];
+    }
+    const side = entry.size ?? (entry.piece === "uiIcon" ? UI_ICON_SIZE : LINK_ICON_SIZE);
+    return [side, side];
+};
+/** Problems of one `pieces` entry against its piece's parameters (spec cover-cli, "Piece parameters checked"). */
+const checkEntry = (piece, params, at, out) => {
+    const definition = PIECES[piece];
+    const own = checkParams(definition.schema, params, at);
+    // Every output is a standalone image: currentColor (accepted by uiIcon for inline page icons) is refused.
+    for (const [name, spec] of Object.entries(definition.schema)) {
+        if (spec.kind === "color" && spec.currentColor && params[name] === CURRENT_COLOUR) {
+            own.push({ path: `${at}.${name}`, message: "currentColor is for icons inline in a page; a cover uses a token path" });
+        }
+    }
+    out.push(...own);
+    // Limits between parameters are reported with the schema's problems, except on a parameter
+    // already reported; a relation that cannot read a broken parameter reports nothing.
+    let related = [];
+    if (definition.relations) {
+        try {
+            // A relation that reads a broken parameter may return anything: keep only real problems.
+            const found = definition.relations(params);
+            related = Array.isArray(found) ? found.filter((p) => isPlainObject(p) && typeof p.path === "string" && typeof p.message === "string") : [];
+        }
+        catch {
+            related = [];
+        }
+        const reported = new Set(own.map((problem) => problem.path));
+        out.push(...related.map((problem) => ({ path: `${at}.${problem.path}`, message: problem.message })).filter((problem) => !reported.has(problem.path)));
+    }
+    // A valid entry is drawn once: an overflow is a spec problem at the entry, not a crash.
+    if (own.length === 0 && related.length === 0) {
+        try {
+            PIECES[piece](params);
+        }
+        catch (error) {
+            if (error instanceof RangeError && error.message.endsWith(": the drawing overflows"))
+                out.push({ path: at, message: "the drawing overflows" });
+        }
+    }
+};
+const checkRings = (spec, out) => {
+    if (!isPlainObject(spec.rings))
+        return void out.push({ path: "rings", message: "missing or not an object (expected cx, cy and an optional radius)" });
+    const ringProblems = checkParams(rings.schema, spec.rings, "rings").filter((problem) => problem.path !== "rings.color" && problem.path !== "rings.count");
+    out.push(...ringProblems);
+    // The piece takes any finite centre; a spec keeps 0.1.0's ±10000, which bounds a banner's and a diagram's ring count.
+    for (const axis of ["cx", "cy"]) {
+        const value = spec.rings[axis];
+        if (ringProblems.some((p) => p.path === `rings.${axis}`) || typeof value !== "number")
+            continue;
+        if (value < -MAX_SIZE)
+            out.push({ path: `rings.${axis}`, message: `expected a number at least -${MAX_SIZE}, found ${value}` });
+        else if (value > MAX_SIZE)
+            out.push({ path: `rings.${axis}`, message: `expected a number at most ${MAX_SIZE}, found ${value}` });
+    }
+    if (Object.hasOwn(spec.rings, "color"))
+        out.push({ path: "rings.color", message: "unknown parameter: the ring colour comes from the background" });
+    if (Object.hasOwn(spec.rings, "count"))
+        out.push({ path: "rings.count", message: "unknown parameter: the ring count comes from the format" });
+};
+const NOT_FOR_ICONS = "not used by the icon format";
+const EIP_TEXT = "comes from the EIP icon, with its CC BY 4.0 credit";
+/** Every problem of a resolved spec (no text references left to resolve). */
+const validateResolved = (spec) => {
     const out = [];
+    const blocked = [];
     colourLiterals(spec, "", out);
     for (const key of Object.keys(spec)) {
         if (!TOP_LEVEL.includes(key))
             out.push({ path: key, message: `unknown key (expected ${TOP_LEVEL.join(", ")})` });
     }
+    if (spec.format !== undefined && (typeof spec.format !== "string" || !FORMATS.includes(spec.format))) {
+        out.push({ path: "format", message: `expected one of ${FORMATS.join(", ")}` });
+    }
+    // An unknown format is checked as a cover, as before this change.
+    const format = FORMATS.includes(spec.format) ? spec.format : "cover";
     if (typeof spec.id !== "string" || !SAFE_ID.test(spec.id))
         out.push({ path: "id", message: `expected a safe slug (lowercase letters, digits, single hyphens), found ${describe(spec.id)}` });
+    const pieces = spec.pieces;
+    const eipIconSpec = format === "icon" && Array.isArray(pieces) && pieces.length === 1 && isPlainObject(pieces[0]) && pieces[0].piece === "eipIcon";
     for (const key of ["title", "description"]) {
-        if (typeof spec[key] !== "string" || spec[key].trim() === "")
+        if (eipIconSpec) {
+            if (spec[key] !== undefined)
+                out.push({ path: key, message: EIP_TEXT });
+        }
+        else if (typeof spec[key] !== "string" || spec[key].trim() === "")
             out.push({ path: key, message: "expected a non-empty string" });
     }
-    if (typeof spec.background !== "string" || !backgroundNames().includes(spec.background)) {
-        out.push({ path: "background", message: `expected one of ${backgroundNames().join(", ")}, found ${describe(spec.background)}` });
+    if (format === "icon") {
+        for (const key of ["background", "rings", "custom", "customAt", "height"])
+            if (spec[key] !== undefined)
+                out.push({ path: key, message: NOT_FOR_ICONS });
+        for (const key of ["background", "rings", "custom"])
+            if (spec[key] !== undefined)
+                blocked.push(key);
     }
-    if (!isPlainObject(spec.rings))
-        out.push({ path: "rings", message: "missing or not an object (expected cx, cy and an optional radius)" });
     else {
-        const ringProblems = checkParams(rings.schema, spec.rings, "rings").filter((problem) => problem.path !== "rings.color" && problem.path !== "rings.count");
-        out.push(...ringProblems);
-        // The piece takes any finite centre; a cover spec keeps 0.1.0's ±10000, which bounds a banner's ring count.
-        for (const axis of ["cx", "cy"]) {
-            const value = spec.rings[axis];
-            if (ringProblems.some((p) => p.path === `rings.${axis}`) || typeof value !== "number")
-                continue;
-            if (value < -MAX_SIZE)
-                out.push({ path: `rings.${axis}`, message: `expected a number at least -${MAX_SIZE}, found ${value}` });
-            else if (value > MAX_SIZE)
-                out.push({ path: `rings.${axis}`, message: `expected a number at most ${MAX_SIZE}, found ${value}` });
+        if (format === "diagram") {
+            if (spec.background !== undefined)
+                out.push({ path: "background", message: "a diagram is drawn on color.panel; background is for covers and banners" });
+            const height = spec.height;
+            if (typeof height !== "number" || !Number.isFinite(height) || height < 1 || height > MAX_SIZE)
+                out.push({ path: "height", message: `expected a number from 1 to ${MAX_SIZE}` });
+        }
+        else {
+            if (typeof spec.background !== "string" || !backgroundNames().includes(spec.background)) {
+                out.push({ path: "background", message: `expected one of ${backgroundNames().join(", ")}, found ${describe(spec.background)}` });
+            }
+            if (spec.height !== undefined)
+                out.push({ path: "height", message: "only a diagram takes a height" });
+        }
+        checkRings(spec, out);
+        if (!isPlainObject(spec.rings) && spec.rings !== undefined)
+            blocked.push("rings");
+        if (spec.custom !== undefined) {
+            if (Array.isArray(spec.custom)) {
+                out.push({ path: "custom", message: "one free-form object per cover; a repeated object must be a piece" });
+                blocked.push("custom");
+            }
+            else
+                checkCustom(spec.custom, "custom", out);
+        }
+        if (spec.customAt !== undefined) {
+            const at = spec.customAt;
+            if (spec.custom === undefined)
+                out.push({ path: "customAt", message: "needs custom" });
+            else if (Array.isArray(pieces)) {
+                if (typeof at !== "number" || !Number.isInteger(at) || at < 0 || at > pieces.length)
+                    out.push({ path: "customAt", message: `expected an integer from 0 to ${pieces.length}` });
+            }
+            else if (typeof at !== "number" || !Number.isInteger(at) || at < 0) {
+                // Without a pieces array the count is unknown: the type is still checked.
+                out.push({ path: "customAt", message: "expected an integer from 0 to the number of pieces" });
+            }
         }
     }
-    if (isPlainObject(spec.rings) && Object.hasOwn(spec.rings, "color"))
-        out.push({ path: "rings.color", message: "unknown parameter: the ring colour comes from the background" });
-    if (isPlainObject(spec.rings) && Object.hasOwn(spec.rings, "count"))
-        out.push({ path: "rings.count", message: "unknown parameter: the ring count comes from the format" });
-    if (spec.format !== undefined && (typeof spec.format !== "string" || !FORMATS.includes(spec.format))) {
-        out.push({ path: "format", message: `expected one of ${FORMATS.join(", ")}` });
-    }
-    if (!Array.isArray(spec.pieces))
+    if (!Array.isArray(pieces)) {
         out.push({ path: "pieces", message: "missing or not an array" });
-    else
-        spec.pieces.forEach((entry, index) => {
+        if (pieces !== undefined)
+            blocked.push("pieces");
+    }
+    else if (format === "icon") {
+        const entry = pieces[0];
+        if (pieces.length !== 1 || !isPlainObject(entry) || !ICON_PIECES.includes(entry.piece)) {
+            out.push({ path: "pieces", message: "an icon spec holds exactly one piece: eipIcon, uiIcon or linkIcon" });
+            blocked.push("pieces");
+        }
+        else {
+            const { piece, ...params } = entry;
+            for (const axis of ["x", "y"])
+                if (params[axis] !== undefined && params[axis] !== 0)
+                    out.push({ path: `pieces[0].${axis}`, message: "an icon is drawn at 0, 0" });
+            checkEntry(piece, { ...params, x: 0, y: 0 }, "pieces[0]", out);
+        }
+    }
+    else {
+        for (let index = 0; index < pieces.length; index++) {
+            const entry = pieces[index];
             const at = `pieces[${index}]`;
-            if (!isPlainObject(entry))
-                return void out.push({ path: at, message: "expected an object with piece and its parameters" });
+            if (!isPlainObject(entry)) {
+                out.push({ path: at, message: "expected an object with piece and its parameters" });
+                blocked.push(at);
+                continue;
+            }
             const { piece, ...params } = entry;
             if (typeof piece !== "string" || !PIECE_NAMES.includes(piece)) {
-                return void out.push({ path: `${at}.piece`, message: `unknown piece ${describe(piece)} (expected one of ${PIECE_NAMES.join(", ")})` });
-            }
-            if (piece === "rings")
-                return void out.push({ path: `${at}.piece`, message: "rings belong to the cover's rings field" });
-            const definition = PIECES[piece];
-            const own = checkParams(definition.schema, params, at);
-            // A cover is a standalone image: currentColor (accepted by uiIcon for inline page icons) is refused.
-            for (const [name, spec] of Object.entries(definition.schema)) {
-                if (spec.kind === "color" && spec.currentColor && params[name] === CURRENT_COLOUR) {
-                    own.push({ path: `${at}.${name}`, message: "currentColor is for icons inline in a page; a cover uses a token path" });
-                }
-            }
-            out.push(...own);
-            // Limits between parameters are reported with the schema's problems, except on a parameter
-            // already reported; a relation that cannot read a broken parameter reports nothing.
-            if (definition.relations) {
-                let related = [];
-                try {
-                    related = definition.relations(params);
-                }
-                catch {
-                    related = [];
-                }
-                const reported = new Set(own.map((problem) => problem.path));
-                out.push(...related.map((problem) => ({ path: `${at}.${problem.path}`, message: problem.message })).filter((problem) => !reported.has(problem.path)));
+                out.push({ path: `${at}.piece`, message: `unknown piece ${describe(piece)} (expected one of ${PIECE_NAMES.join(", ")})` });
+                blocked.push(at);
+                continue;
             }
-            // A valid entry is drawn once: an overflow is a spec problem at the entry, not a crash.
-            if (own.length === 0 && !(definition.relations?.(params) ?? []).length) {
-                try {
-                    PIECES[piece](params);
-                }
-                catch (error) {
-                    if (error instanceof RangeError && error.message.endsWith(": the drawing overflows"))
-                        out.push({ path: at, message: "the drawing overflows" });
-                }
+            if (piece === "rings") {
+                out.push({ path: `${at}.piece`, message: "rings belong to the cover's rings field" });
+                blocked.push(at);
+                continue;
             }
-        });
-    if (spec.custom !== undefined) {
-        if (Array.isArray(spec.custom))
-            out.push({ path: "custom", message: "one free-form object per cover; a repeated object must be a piece" });
-        else
-            checkCustom(spec.custom, "custom", out);
-    }
-    // A colour literal is reported once, by the literal check, not again as a bad token path.
-    // A container with the wrong shape is one problem: nothing inside it is reported.
-    const blocked = [];
-    if (!Array.isArray(spec.pieces) && spec.pieces !== undefined)
-        blocked.push("pieces");
-    if (Array.isArray(spec.pieces)) {
-        spec.pieces.forEach((entry, index) => {
-            const known = isPlainObject(entry) && typeof entry.piece === "string" && PIECE_NAMES.includes(entry.piece) && entry.piece !== "rings";
-            if (!known)
-                blocked.push(`pieces[${index}]`);
-        });
+            checkEntry(piece, params, at, out);
+        }
     }
-    if (Array.isArray(spec.custom))
-        blocked.push("custom");
-    if (!isPlainObject(spec.rings) && spec.rings !== undefined)
-        blocked.push("rings");
-    const insideBlocked = (path) => blocked.some((b) => (path.startsWith(`${b}.`) || path.startsWith(`${b}[`)) && path !== `${b}.piece`);
-    out.splice(0, out.length, ...out.filter((p) => !insideBlocked(p.path)));
+    return { problems: out, blocked };
+};
+/** Under a path (the path itself included): `a` covers `a`, `a.b` and `a[0]`. */
+const under = (path, base) => path === base || path.startsWith(`${base}.`) || path.startsWith(`${base}[`);
+/** Sorted, one per path and message; a colour literal replaces any other problem at its path. */
+const finish = (out) => {
     const literalPaths = new Set(out.filter((p) => p.message.startsWith("colour literals")).map((p) => p.path));
     const seen = new Set();
     const unique = out.filter((p) => {
@@ -257,6 +422,26 @@ export const validateCoverSpec = (spec) => {
     });
     return unique.sort((a, b) => comparePaths(a.path, b.path) || compareCodePoints(a.message, b.message));
 };
+/** Every problem of a parsed spec, sorted by path; empty when the spec is valid. `lang` picks a text table. */
+export const validateCoverSpec = (spec, options = {}) => {
+    if (!isPlainObject(spec))
+        return [{ path: "(root)", message: `a cover spec must be a JSON object, found ${Array.isArray(spec) ? "an array" : describe(spec)}` }];
+    // Text problems stop the check: references cannot be resolved, so the rest would report false problems.
+    const { table, problems: textProblems } = pickTable(spec, options.lang);
+    if (textProblems.length > 0)
+        return finish(textProblems);
+    const { spec: resolved, unknown } = table ? resolveText(spec, table) : { spec, unknown: [] };
+    const { problems, blocked } = validateResolved(resolved);
+    // A container with the wrong shape is one problem: nothing inside it is reported (its `piece` problem stays).
+    // An unknown text key replaces every other problem at its path.
+    const insideBlocked = (path) => blocked.some((b) => under(path, b) && path !== b && path !== `${b}.piece`);
+    // Unknown references inside a wrong container are not reported either: the container is one problem.
+    // A reference in an entry's `piece` names the piece: it is reported even when its container is refused.
+    const unknownKept = unknown.filter((u) => !insideBlocked(u.path) || /^pieces\[\d+\]\.piece$/.test(u.path));
+    const kept = problems.filter((p) => !insideBlocked(p.path) && !unknownKept.some((u) => under(p.path, u.path)));
+    return finish([...kept, ...unknownKept]);
+};
+// ---------- drawing ----------
 const resolveCustom = (node) => {
     const attrs = {};
     for (const [name, value] of Object.entries(node.attrs ?? {})) {
@@ -273,28 +458,62 @@ export const bannerRingCount = (cx, cy, radius = tokens.cover.ringRadius) => {
     const far = Math.max(...[[0, 0], [width, 0], [0, height], [width, height]].map(([x, y]) => Math.hypot(x - cx, y - cy)));
     return Math.max(1, Math.ceil((far - radius) / tokens.cover.ringStep) + 1);
 };
-/** The cover's (or banner's) node tree. The spec must be valid (validateCoverSpec returned no problem). */
-export const coverTree = (spec) => {
+/** Layout units per shown pixel of a body diagram (560 / 800). */
+const LAYOUT_SCALE = tokens.bodyDiagram.layoutWidth / tokens.bodyDiagram.width;
+/** Rings of a diagram (spec cover-cli, "Diagram rings at the shown scale"): the cover's step and width at the shown scale. */
+export const diagramRings = (cx, cy, height, radius = tokens.bodyDiagram.ringRadius * LAYOUT_SCALE) => {
+    const width = tokens.bodyDiagram.layoutWidth;
+    const step = tokens.cover.ringStep * LAYOUT_SCALE;
+    const far = Math.max(...[[0, 0], [width, 0], [0, height], [width, height]].map(([x, y]) => Math.hypot(x - cx, y - cy)));
+    return { count: Math.max(1, Math.ceil((far - radius) / step) + 1), step, width: tokens.cover.ringWidth * LAYOUT_SCALE, radius };
+};
+const draw = (entry) => {
+    const { piece, ...params } = entry;
+    return PIECES[piece](params);
+};
+/** The outlined group's children: every body in paint order, `custom` before `pieces[customAt]` (default: last). */
+const bodies = (spec, drawnPieces) => {
+    const custom = spec.custom ? resolveCustom(spec.custom) : null;
+    const at = spec.customAt ?? drawnPieces.length;
+    return [...drawnPieces.slice(0, at).flatMap((d) => d.body), custom, ...drawnPieces.slice(at).flatMap((d) => d.body)];
+};
+const root = (id, width, height, viewBox, ...children) => el("svg", { xmlns: "http://www.w3.org/2000/svg", width, height, viewBox, role: "img", "aria-labelledby": `${id}-title ${id}-desc`, "font-family": tokens.font.sans }, ...children);
+/** An icon (spec cover-cli, "Icon output"): the piece at 0,0 in a box of its own size. */
+const iconTree = (spec) => {
+    const entry = spec.pieces[0];
+    const [width, height] = iconBox(entry);
+    const eip = entry.piece === "eipIcon" ? EIP_ICONS.find((icon) => icon.name === entry.name) : undefined;
+    return root(spec.id, width, height, `0 0 ${width} ${height}`, el("title", { id: `${spec.id}-title` }, eip?.title ?? spec.title), el("desc", { id: `${spec.id}-desc` }, eip?.description ?? spec.description), ...draw({ ...entry, x: 0, y: 0 }).body);
+};
+/** A body diagram (spec cover-cli, "Diagram output"): laid out 560 wide, shown 800 wide, on the panel. */
+const diagramTree = (spec) => {
+    const width = tokens.bodyDiagram.layoutWidth;
+    const height = spec.height;
+    const rx = r2(tokens.bodyDiagram.radius * LAYOUT_SCALE);
+    const frame = `url(#${spec.id}-frame)`;
+    const ring = diagramRings(spec.rings.cx, spec.rings.cy, height, spec.rings.radius);
+    const drawnPieces = spec.pieces.map(draw);
+    return root(spec.id, tokens.bodyDiagram.width, r2(height / LAYOUT_SCALE), `0 0 ${width} ${height}`, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height, rx }))), el("rect", { width, height, rx, fill: tokens.color.panel }), g({ "clip-path": frame }, g({ fill: "none", stroke: tokens.color.ring, "stroke-width": r2(ring.width) }, ...Array.from({ length: ring.count }, (_, i) => el("circle", { cx: spec.rings.cx, cy: spec.rings.cy, r: r2(ring.radius + i * ring.step) })))), g({ "clip-path": frame }, g({ stroke: tokens.color.ink, "stroke-width": tokens.map.outline, "stroke-linejoin": "round" }, ...bodies(spec, drawnPieces)), g({ "font-size": tokens.map.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text))));
+};
+/** The cover's (banner's, diagram's, icon's) node tree. The spec must be valid for `lang` (validateCoverSpec returned no problem). */
+export const coverTree = (input, options = {}) => {
+    const spec = forLanguage(input, options.lang);
+    if (spec.format === "icon")
+        return iconTree(spec);
+    if (spec.format === "diagram")
+        return diagramTree(spec);
     const banner = spec.format === "banner";
     const { width, height } = banner ? tokens.banner : tokens.cover;
     // A banner's corners are rounded; a cover keeps today's square frame, attribute for attribute.
     const corner = banner ? { rx: tokens.banner.radius } : {};
     const pair = tokens.coverBackground[spec.background];
-    const drawnPieces = spec.pieces.map(({ piece, ...params }) => PIECES[piece](params));
+    const drawnPieces = spec.pieces.map(draw);
     const ringPath = `coverBackground.${spec.background}.ring`;
     const ringCount = banner ? { count: bannerRingCount(spec.rings.cx, spec.rings.cy, spec.rings.radius) } : {};
     const frame = `url(#${spec.id}-frame)`;
-    const outlined = g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...drawnPieces.flatMap((d) => d.body), spec.custom ? resolveCustom(spec.custom) : null);
+    const outlined = g({ stroke: tokens.color.ink, "stroke-width": tokens.outline.block, "stroke-linejoin": "round" }, ...bodies(spec, drawnPieces));
     const labels = g({ "font-size": tokens.cover.labelSize, "font-weight": tokens.cover.labelWeight, fill: tokens.color.ink, "text-anchor": "middle" }, ...drawnPieces.flatMap((d) => d.text));
-    return el("svg", {
-        xmlns: "http://www.w3.org/2000/svg",
-        width,
-        height,
-        viewBox: `0 0 ${width} ${height}`,
-        role: "img",
-        "aria-labelledby": `${spec.id}-title ${spec.id}-desc`,
-        "font-family": tokens.font.sans,
-    }, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height, ...corner }))), el("rect", { width, height, ...corner, fill: pair.fill }), g({ "clip-path": frame }, ...rings({ ...spec.rings, color: ringPath, ...ringCount }).body), 
+    return root(spec.id, width, height, `0 0 ${width} ${height}`, el("title", { id: `${spec.id}-title` }, spec.title), el("desc", { id: `${spec.id}-desc` }, spec.description), el("defs", {}, el("clipPath", { id: `${spec.id}-frame` }, el("rect", { width, height, ...corner }))), el("rect", { width, height, ...corner, fill: pair.fill }), g({ "clip-path": frame }, ...rings({ ...spec.rings, color: ringPath, ...ringCount }).body), 
     // On a banner, pieces and labels are clipped too, so nothing pokes past a rounded corner.
     ...(banner ? [g({ "clip-path": frame }, outlined, labels)] : [outlined, labels]));
 };

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

@@ -0,0 +1,137 @@
+import { type Ink, type SurfaceName } from "./ink.ts";
+export type ShapeParams = Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height?: number;
+    text: string[];
+    subtitle?: string;
+    fill?: string;
+    textSize?: number;
+};
+export type DiagramBoxParams = ShapeParams & {
+    radius?: number;
+    shape?: "box" | "pill";
+};
+/** A box or a pill with a fill and centred lines: a body diagram's step, system or note. */
+export declare const diagramBox: import("./piece.ts").Piece<DiagramBoxParams>;
+/** A decision: a diamond in its bounds. */
+export declare const decisionNode: import("./piece.ts").Piece<Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height?: number;
+    text: string[];
+    subtitle?: string;
+    fill?: string;
+    textSize?: number;
+} & {
+    height: number;
+}>;
+export type StoreNodeParams = ShapeParams & {
+    height: number;
+    ry?: number;
+};
+/** A store: a cylinder in its bounds, with the front of its lid. */
+export declare const storeNode: import("./piece.ts").Piece<StoreNodeParams>;
+/** A queue: a box with a rail 10 in from each side. */
+export declare const queueNode: import("./piece.ts").Piece<ShapeParams>;
+/** An exchange: a hexagon with its points 0.26 × height in, as the motion shape (src/brand/flow-shapes.ts). */
+export declare const exchangeNode: import("./piece.ts").Piece<ShapeParams>;
+export type TaggedContainerParams = Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    tag: string;
+    tagWidth?: number;
+    tagFill?: string;
+    fill?: string;
+};
+/** A container (a platform, a broker) with its name on a tab centred on the top edge. */
+export declare const taggedContainer: import("./piece.ts").Piece<TaggedContainerParams>;
+export type LifelineParams = {
+    x: number;
+    y1: number;
+    y2: number;
+    state?: "active" | "inactive";
+    width?: number;
+    surface?: SurfaceName;
+};
+/** A participant's lifeline: dashed while active, sparse dots once nothing calls it. */
+export declare const lifeline: import("./piece.ts").Piece<LifelineParams>;
+export type PhaseBandParams = Ink & {
+    x: number;
+    y: number;
+    width: number;
+    height?: number;
+    text: string;
+    fill: string;
+    textSize?: number;
+};
+/** A phase of a sequence: a pill across the diagram in its state's colour. */
+export declare const phaseBand: import("./piece.ts").Piece<PhaseBandParams>;
+type Head = {
+    tag: string;
+    condition?: string;
+    tagWidth?: number;
+    conditionWidth?: number;
+};
+export type AltFrameParams = Head & {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    sections?: (Head & {
+        y: number;
+    })[];
+    surface?: SurfaceName;
+};
+/** An alt/else frame: the frame, a dashed divider per section, and a tag (with its condition) per part. */
+export declare const altFrame: import("./piece.ts").Piece<AltFrameParams>;
+export type EdgeLabelParams = {
+    x: number;
+    y: number;
+    lines: string[];
+    anchor?: "start" | "middle" | "end";
+    backdrop?: boolean;
+    width?: number;
+    textSize?: number;
+    surface?: SurfaceName;
+};
+/** Words next to an arrow: lines down from the baseline (x, y), optionally on a backdrop that hides what is behind. */
+export declare const edgeLabel: import("./piece.ts").Piece<EdgeLabelParams>;
+export type StateStartParams = {
+    cx: number;
+    cy: number;
+    r?: number;
+    surface?: SurfaceName;
+};
+/** 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 declare const stateStart: import("./piece.ts").Piece<StateStartParams>;
+/** The body diagram pieces, in catalogue order (design §3). */
+export declare const DIAGRAM_PIECES: {
+    readonly diagramBox: import("./piece.ts").Piece<DiagramBoxParams>;
+    readonly decisionNode: import("./piece.ts").Piece<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<StoreNodeParams>;
+    readonly queueNode: import("./piece.ts").Piece<ShapeParams>;
+    readonly exchangeNode: import("./piece.ts").Piece<ShapeParams>;
+    readonly taggedContainer: import("./piece.ts").Piece<TaggedContainerParams>;
+    readonly lifeline: import("./piece.ts").Piece<LifelineParams>;
+    readonly phaseBand: import("./piece.ts").Piece<PhaseBandParams>;
+    readonly altFrame: import("./piece.ts").Piece<AltFrameParams>;
+    readonly edgeLabel: import("./piece.ts").Piece<EdgeLabelParams>;
+};
+export {};