@misoto22/design 0.6.0 → 0.7.0

package/dist/diagrams/lib/geometry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The arithmetic every figure shares: boxes, text extents, and the frame that
+ * ends up around them.
+ *
+ * Everything here is a pure function of numbers already in the specification.
+ * That is not a stylistic preference — it is what lets these figures render on
+ * a server. A layout that measured real text would need a DOM, a layout that
+ * relaxed a force graph would need to settle, and neither can produce the same
+ * markup twice. Both would hydrate into a different picture than the one that
+ * was sent, which for a diagram is worse than not rendering at all.
+ */
+/** A rectangle in the figure's user-unit space. */
+interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+declare const centerOf: (box: Box) => [number, number];
+/** Grows a rectangle by `pad` on every side. */
+declare function inflate(box: Box, pad: number): Box;
+/** The smallest rectangle containing all of them. Returns null for an empty list. */
+declare function union(boxes: Box[]): Box | null;
+/**
+ * How wide a run of text is, without measuring it.
+ *
+ * A real measurement needs a DOM and the loaded face, and this module has
+ * neither by design — so this is an estimate, and the honest thing is to say
+ * what kind. Latin glyphs in the system's sans average close to 0.52em of
+ * advance across ordinary label text; digits and capitals run wider; a CJK
+ * ideograph is a full em by definition, as is a fullwidth punctuation mark.
+ *
+ * The estimate is used for two things and neither needs to be exact: choosing a
+ * box wide enough that a label is not clipped, and deciding where a line's
+ * label mask sits. Both fail gracefully — a box a few units too wide is
+ * invisible, and a mask a few units too wide hides a little more of a line than
+ * it had to.
+ *
+ * It is deliberately NOT used to justify, wrap mid-word, or letter-space
+ * anything. Those need the real face.
+ */
+declare function textWidth(text: string, fontSize: number): number;
+/**
+ * A label broken to fit a width, with a hard cap on how many lines it may take.
+ *
+ * Breaks on spaces for Latin and between characters for CJK, which has no
+ * spaces to break on. A word longer than the whole line is left to overflow
+ * rather than hyphenated: an identifier — `TenantMainMiddleware` — split across
+ * two lines is harder to read than one that runs slightly wide, and the caller
+ * sized the box from `textWidth` anyway.
+ *
+ * The last line is ellipsised when the text does not fit in `maxLines`, because
+ * silently dropping the tail is how a diagram comes to say something it does
+ * not mean.
+ */
+declare function wrapText(text: string, fontSize: number, maxWidth: number, maxLines?: number): string[];
+/**
+ * The type scale inside a figure, in user units.
+ *
+ * Fixed numbers rather than tokens, because these are SVG geometry: a `<text>`
+ * sized in `rem` inside a scaled `viewBox` changes size when the figure is
+ * zoomed, which means a diagram at 200% is a different diagram. The figure
+ * scales as one picture, so its type scales with it.
+ */
+declare const TYPE: {
+    /** A node's name. */
+    readonly label: 13;
+    /** The line under it. */
+    readonly sub: 10.5;
+    /** A mono chip: a tag, a classification, a step number. */
+    readonly chip: 9.5;
+    /** A relationship's own wording. */
+    readonly edge: 10.5;
+    /** A band, lane or stage heading. */
+    readonly band: 10.5;
+};
+/** Default box sizes per diagram type, in user units. */
+declare const BOX: {
+    readonly node: {
+        readonly w: 168;
+        readonly h: 62;
+    };
+    readonly wide: {
+        readonly w: 200;
+        readonly h: 62;
+    };
+    readonly participant: {
+        readonly w: 128;
+        readonly h: 46;
+    };
+};
+/**
+ * How tall a box has to be to hold what it was given.
+ *
+ * A declared height is a FLOOR, not a ceiling. When a specification asks for a
+ * 64-unit box and then puts two lines of label, a sublabel and a tag chip in
+ * it, honouring the 64 prints the tag over the sublabel — which reads as a
+ * rendering fault rather than as a box that was asked to hold too much. Growing
+ * the box is visible and correct; clipping is invisible and wrong.
+ */
+declare function nodeHeight(labelLines: number, hasSub: boolean, hasTag?: boolean, base?: number): number;
+/** `viewBox` as the attribute wants it. */
+declare function viewBoxOf(box: Box): string;
+/**
+ * Coordinates rounded to a tenth.
+ *
+ * SVG happily accepts eighteen decimal places and puts every one of them in the
+ * markup, which on a figure with two hundred line segments is a measurable
+ * share of the document. A tenth of a user unit is well under a device pixel at
+ * any zoom a reader will use.
+ */
+declare function round(value: number): number;
+
+export { BOX, type Box, TYPE, centerOf, inflate, nodeHeight, round, textWidth, union, viewBoxOf, wrapText };

package/dist/diagrams/lib/geometry.js

@@ -0,0 +1,113 @@
+const centerOf = (box) => [box.x + box.w / 2, box.y + box.h / 2];
+function inflate(box, pad) {
+  return { x: box.x - pad, y: box.y - pad, w: box.w + pad * 2, h: box.h + pad * 2 };
+}
+function union(boxes) {
+  if (boxes.length === 0) return null;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const box of boxes) {
+    if (box.x < minX) minX = box.x;
+    if (box.y < minY) minY = box.y;
+    if (box.x + box.w > maxX) maxX = box.x + box.w;
+    if (box.y + box.h > maxY) maxY = box.y + box.h;
+  }
+  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}
+function textWidth(text, fontSize) {
+  let em = 0;
+  for (const character of text) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code > 11903) {
+      em += 1;
+    } else if (character === " ") {
+      em += 0.26;
+    } else if (/[.,:;'`!|iljtIf()[\]{}]/.test(character)) {
+      em += 0.31;
+    } else if (/[A-Z0-9@#%&WM]/.test(character)) {
+      em += 0.62;
+    } else {
+      em += 0.52;
+    }
+  }
+  return em * fontSize;
+}
+function wrapText(text, fontSize, maxWidth, maxLines = 2) {
+  if (textWidth(text, fontSize) <= maxWidth) return [text];
+  const lines = [];
+  let current = "";
+  const tokens = text.match(/[⺀-鿿豈-﫿＀-￯]|[^\s⺀-鿿]+|\s+/g) ?? [text];
+  for (const token of tokens) {
+    const candidate = current + token;
+    if (current !== "" && textWidth(candidate.trimEnd(), fontSize) > maxWidth) {
+      lines.push(current.trimEnd());
+      current = token.trimStart();
+      if (lines.length === maxLines) break;
+    } else {
+      current = candidate;
+    }
+  }
+  if (lines.length < maxLines && current.trim() !== "") lines.push(current.trimEnd());
+  if (lines.length === maxLines) {
+    const placed = lines.join("").replace(/\s+/g, "");
+    const whole = text.replace(/\s+/g, "");
+    if (placed.length < whole.length) {
+      const last = lines[maxLines - 1] ?? "";
+      lines[maxLines - 1] = `${clampToWidth(last, fontSize, maxWidth - textWidth("\u2026", fontSize))}\u2026`;
+    }
+  }
+  return lines;
+}
+function clampToWidth(text, fontSize, maxWidth) {
+  let width = 0;
+  let out = "";
+  for (const character of text) {
+    const next = textWidth(character, fontSize);
+    if (width + next > maxWidth) break;
+    width += next;
+    out += character;
+  }
+  return out.trimEnd();
+}
+const TYPE = {
+  /** A node's name. */
+  label: 13,
+  /** The line under it. */
+  sub: 10.5,
+  /** A mono chip: a tag, a classification, a step number. */
+  chip: 9.5,
+  /** A relationship's own wording. */
+  edge: 10.5,
+  /** A band, lane or stage heading. */
+  band: 10.5
+};
+const BOX = {
+  node: { w: 168, h: 62 },
+  wide: { w: 200, h: 62 },
+  participant: { w: 128, h: 46 }
+};
+function nodeHeight(labelLines, hasSub, hasTag = false, base = BOX.node.h) {
+  const content = 20 + labelLines * (TYPE.label * 1.25) + (hasSub ? TYPE.sub * 1.5 : 0) + (hasTag ? 20 : 0);
+  return Math.max(base, Math.ceil(content));
+}
+function viewBoxOf(box) {
+  return `${round(box.x)} ${round(box.y)} ${round(box.w)} ${round(box.h)}`;
+}
+function round(value) {
+  return Math.round(value * 10) / 10;
+}
+export {
+  BOX,
+  TYPE,
+  centerOf,
+  inflate,
+  nodeHeight,
+  round,
+  textWidth,
+  union,
+  viewBoxOf,
+  wrapText
+};
+//# sourceMappingURL=geometry.js.map

package/dist/diagrams/lib/geometry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/diagrams/lib/geometry.ts"],"sourcesContent":["/**\n * The arithmetic every figure shares: boxes, text extents, and the frame that\n * ends up around them.\n *\n * Everything here is a pure function of numbers already in the specification.\n * That is not a stylistic preference — it is what lets these figures render on\n * a server. A layout that measured real text would need a DOM, a layout that\n * relaxed a force graph would need to settle, and neither can produce the same\n * markup twice. Both would hydrate into a different picture than the one that\n * was sent, which for a diagram is worse than not rendering at all.\n */\n\n/** A rectangle in the figure's user-unit space. */\nexport interface Box {\n  x: number\n  y: number\n  w: number\n  h: number\n}\n\nexport const centerOf = (box: Box): [number, number] => [box.x + box.w / 2, box.y + box.h / 2]\n\n/** Grows a rectangle by `pad` on every side. */\nexport function inflate(box: Box, pad: number): Box {\n  return { x: box.x - pad, y: box.y - pad, w: box.w + pad * 2, h: box.h + pad * 2 }\n}\n\n/** The smallest rectangle containing all of them. Returns null for an empty list. */\nexport function union(boxes: Box[]): Box | null {\n  if (boxes.length === 0) return null\n  let minX = Infinity\n  let minY = Infinity\n  let maxX = -Infinity\n  let maxY = -Infinity\n  for (const box of boxes) {\n    if (box.x < minX) minX = box.x\n    if (box.y < minY) minY = box.y\n    if (box.x + box.w > maxX) maxX = box.x + box.w\n    if (box.y + box.h > maxY) maxY = box.y + box.h\n  }\n  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY }\n}\n\n/**\n * How wide a run of text is, without measuring it.\n *\n * A real measurement needs a DOM and the loaded face, and this module has\n * neither by design — so this is an estimate, and the honest thing is to say\n * what kind. Latin glyphs in the system's sans average close to 0.52em of\n * advance across ordinary label text; digits and capitals run wider; a CJK\n * ideograph is a full em by definition, as is a fullwidth punctuation mark.\n *\n * The estimate is used for two things and neither needs to be exact: choosing a\n * box wide enough that a label is not clipped, and deciding where a line's\n * label mask sits. Both fail gracefully — a box a few units too wide is\n * invisible, and a mask a few units too wide hides a little more of a line than\n * it had to.\n *\n * It is deliberately NOT used to justify, wrap mid-word, or letter-space\n * anything. Those need the real face.\n */\nexport function textWidth(text: string, fontSize: number): number {\n  let em = 0\n  for (const character of text) {\n    const code = character.codePointAt(0) ?? 0\n    if (code > 0x2e7f) {\n      // CJK, kana, hangul, fullwidth forms — one em each.\n      em += 1\n    } else if (character === ' ') {\n      em += 0.26\n    } else if (/[.,:;'`!|iljtIf()[\\]{}]/.test(character)) {\n      em += 0.31\n    } else if (/[A-Z0-9@#%&WM]/.test(character)) {\n      em += 0.62\n    } else {\n      em += 0.52\n    }\n  }\n  return em * fontSize\n}\n\n/**\n * A label broken to fit a width, with a hard cap on how many lines it may take.\n *\n * Breaks on spaces for Latin and between characters for CJK, which has no\n * spaces to break on. A word longer than the whole line is left to overflow\n * rather than hyphenated: an identifier — `TenantMainMiddleware` — split across\n * two lines is harder to read than one that runs slightly wide, and the caller\n * sized the box from `textWidth` anyway.\n *\n * The last line is ellipsised when the text does not fit in `maxLines`, because\n * silently dropping the tail is how a diagram comes to say something it does\n * not mean.\n */\nexport function wrapText(\n  text: string,\n  fontSize: number,\n  maxWidth: number,\n  maxLines = 2,\n): string[] {\n  if (textWidth(text, fontSize) <= maxWidth) return [text]\n\n  const lines: string[] = []\n  let current = ''\n\n  // Latin words stay whole; a CJK run is a sequence of individual break\n  // opportunities, so each ideograph becomes its own token.\n  const tokens = text.match(/[⺀-鿿豈-﫿＀-￯]|[^\\s⺀-鿿]+|\\s+/g) ?? [text]\n\n  for (const token of tokens) {\n    const candidate = current + token\n    if (current !== '' && textWidth(candidate.trimEnd(), fontSize) > maxWidth) {\n      lines.push(current.trimEnd())\n      current = token.trimStart()\n      if (lines.length === maxLines) break\n    } else {\n      current = candidate\n    }\n  }\n\n  if (lines.length < maxLines && current.trim() !== '') lines.push(current.trimEnd())\n\n  if (lines.length === maxLines) {\n    // Anything still unplaced belongs to the last line, which must therefore\n    // admit that it is truncated.\n    const placed = lines.join('').replace(/\\s+/g, '')\n    const whole = text.replace(/\\s+/g, '')\n    if (placed.length < whole.length) {\n      const last = lines[maxLines - 1] ?? ''\n      lines[maxLines - 1] = `${clampToWidth(last, fontSize, maxWidth - textWidth('…', fontSize))}…`\n    }\n  }\n\n  return lines\n}\n\n/** The longest prefix of `text` that fits, character by character. */\nfunction clampToWidth(text: string, fontSize: number, maxWidth: number): string {\n  let width = 0\n  let out = ''\n  for (const character of text) {\n    const next = textWidth(character, fontSize)\n    if (width + next > maxWidth) break\n    width += next\n    out += character\n  }\n  return out.trimEnd()\n}\n\n/**\n * The type scale inside a figure, in user units.\n *\n * Fixed numbers rather than tokens, because these are SVG geometry: a `<text>`\n * sized in `rem` inside a scaled `viewBox` changes size when the figure is\n * zoomed, which means a diagram at 200% is a different diagram. The figure\n * scales as one picture, so its type scales with it.\n */\nexport const TYPE = {\n  /** A node's name. */\n  label: 13,\n  /** The line under it. */\n  sub: 10.5,\n  /** A mono chip: a tag, a classification, a step number. */\n  chip: 9.5,\n  /** A relationship's own wording. */\n  edge: 10.5,\n  /** A band, lane or stage heading. */\n  band: 10.5,\n} as const\n\n/** Default box sizes per diagram type, in user units. */\nexport const BOX = {\n  node: { w: 168, h: 62 },\n  wide: { w: 200, h: 62 },\n  participant: { w: 128, h: 46 },\n} as const\n\n/**\n * How tall a box has to be to hold what it was given.\n *\n * A declared height is a FLOOR, not a ceiling. When a specification asks for a\n * 64-unit box and then puts two lines of label, a sublabel and a tag chip in\n * it, honouring the 64 prints the tag over the sublabel — which reads as a\n * rendering fault rather than as a box that was asked to hold too much. Growing\n * the box is visible and correct; clipping is invisible and wrong.\n */\nexport function nodeHeight(\n  labelLines: number,\n  hasSub: boolean,\n  hasTag = false,\n  base: number = BOX.node.h,\n): number {\n  const content =\n    20 + labelLines * (TYPE.label * 1.25) + (hasSub ? TYPE.sub * 1.5 : 0) + (hasTag ? 20 : 0)\n  return Math.max(base, Math.ceil(content))\n}\n\n/** `viewBox` as the attribute wants it. */\nexport function viewBoxOf(box: Box): string {\n  return `${round(box.x)} ${round(box.y)} ${round(box.w)} ${round(box.h)}`\n}\n\n/**\n * Coordinates rounded to a tenth.\n *\n * SVG happily accepts eighteen decimal places and puts every one of them in the\n * markup, which on a figure with two hundred line segments is a measurable\n * share of the document. A tenth of a user unit is well under a device pixel at\n * any zoom a reader will use.\n */\nexport function round(value: number): number {\n  return Math.round(value * 10) / 10\n}\n"],"mappings":"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","names":[]}

package/dist/diagrams/lib/legend.d.ts

@@ -0,0 +1,32 @@
+import { NodeKind, LegendMode, LifecycleStateKind, Variant } from '../spec.js';
+
+type LegendEntry = {
+    key: string;
+    label: string;
+    sample: React.ReactNode;
+};
+/**
+ * Which entries the key shows.
+ *
+ * `auto` — the default and the truthful one — lists only the kinds the figure
+ * actually drew. A key that names seven kinds beside a figure using three is
+ * not more informative; it is four claims the picture does not support.
+ */
+declare function resolveLegend<T extends string>(used: T[], mode?: LegendMode, all?: T[], overrides?: Record<string, {
+    label?: string;
+    visible?: boolean;
+}>): T[];
+/** A key entry for each node kind, drawn with the same sigil the figure uses. */
+declare function kindLegend(kinds: NodeKind[], overrides?: Record<string, {
+    label?: string;
+}>): LegendEntry[];
+/** A key entry for each relationship variant, drawn as the line itself. */
+declare function variantLegend(variants: (Variant | 'return')[], overrides?: Record<string, {
+    label?: string;
+}>): LegendEntry[];
+/** A key entry for each lifecycle state kind, drawn as its plate. */
+declare function stateLegend(kinds: LifecycleStateKind[], overrides?: Record<string, {
+    label?: string;
+}>): LegendEntry[];
+
+export { type LegendEntry, kindLegend, resolveLegend, stateLegend, variantLegend };

package/dist/diagrams/lib/legend.js

@@ -0,0 +1,84 @@
+import { jsx } from "react/jsx-runtime";
+import { KIND_WORD, Sigil } from "./marks.js";
+const VARIANT_LABEL = {
+  default: "Call",
+  emphasis: "Primary path",
+  security: "Crosses a trust boundary",
+  dashed: "Asynchronous",
+  return: "Return"
+};
+const STATE_LABEL = {
+  start: "Entry",
+  active: "Working",
+  waiting: "Waiting",
+  decision: "Decision",
+  success: "Succeeded",
+  failure: "Failed",
+  neutral: "Idle",
+  external: "External"
+};
+function resolveLegend(used, mode = "auto", all = [], overrides) {
+  if (mode === "hidden") return [];
+  const base = mode === "all" ? all : [...new Set(used)];
+  return base.filter((key) => overrides?.[key]?.visible !== false);
+}
+function kindLegend(kinds, overrides) {
+  return kinds.map((kind) => ({
+    key: kind,
+    // The key names a kind with the SAME word the plate's eyebrow prints. They
+    // were two vocabularies for one fact — a plate reading SERVICE beside a key
+    // reading "Datastore" — which is the one thing a key must never do.
+    label: overrides?.[kind]?.label ?? KIND_WORD[kind],
+    sample: /* @__PURE__ */ jsx("g", { transform: "translate(1, 1)", children: /* @__PURE__ */ jsx(Sigil, { kind, x: 0, y: 0 }) })
+  }));
+}
+function variantLegend(variants, overrides) {
+  return variants.map((variant) => ({
+    key: variant,
+    label: overrides?.[variant]?.label ?? VARIANT_LABEL[variant],
+    sample: /* @__PURE__ */ jsx(
+      "path",
+      {
+        d: "M 0.5 7 H 13.5",
+        fill: "none",
+        className: variant === "emphasis" ? "stroke-(--diagram-line-strong) [stroke-width:2.4]" : variant === "security" ? "stroke-(--diagram-line) [stroke-width:1.6] [stroke-dasharray:4_2]" : variant === "dashed" || variant === "return" ? "stroke-(--diagram-line-soft) [stroke-width:1.6] [stroke-dasharray:3_2.5]" : "stroke-(--diagram-line) [stroke-width:1.6]"
+      }
+    )
+  }));
+}
+function stateLegend(kinds, overrides) {
+  return kinds.map((kind) => ({
+    key: kind,
+    label: overrides?.[kind]?.label ?? STATE_LABEL[kind],
+    sample: kind === "decision" ? /* @__PURE__ */ jsx(
+      "path",
+      {
+        d: "M 7 1 L 13 7 L 7 13 L 1 7 Z",
+        className: "fill-(--diagram-node) stroke-(--diagram-rule-hard) [stroke-width:1.2]"
+      }
+    ) : kind === "external" ? /* @__PURE__ */ jsx(
+      "path",
+      {
+        d: "M 1 2 H 9.5 L 13 5.5 V 12 H 1 Z",
+        className: "fill-(--diagram-node-2) stroke-(--diagram-rule) [stroke-width:1.2]"
+      }
+    ) : /* @__PURE__ */ jsx(
+      "rect",
+      {
+        x: "1",
+        y: "3",
+        width: "12",
+        height: "8",
+        rx: kind === "start" ? 4 : 2,
+        className: kind === "start" ? "fill-(--diagram-plate) stroke-(--diagram-plate) [stroke-width:1.2]" : kind === "success" ? "fill-(--success-wash) stroke-(--success) [stroke-width:1.2]" : kind === "failure" ? "fill-(--danger-wash) stroke-(--danger) [stroke-width:1.2]" : kind === "waiting" ? "fill-(--diagram-node) stroke-(--diagram-rule) [stroke-width:1.2] [stroke-dasharray:3_2]" : kind === "neutral" ? "fill-(--diagram-node-2) stroke-(--diagram-rule) [stroke-width:1.2]" : "fill-(--diagram-node) stroke-(--diagram-rule-hard) [stroke-width:1.2]"
+      }
+    )
+  }));
+}
+export {
+  kindLegend,
+  resolveLegend,
+  stateLegend,
+  variantLegend
+};
+//# sourceMappingURL=legend.js.map

package/dist/diagrams/lib/legend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/diagrams/lib/legend.tsx"],"sourcesContent":["import type { LegendMode, LifecycleStateKind, NodeKind, Variant } from '../spec'\nimport { KIND_WORD, Sigil } from './marks'\n\nconst VARIANT_LABEL: Record<Variant | 'return', string> = {\n  default: 'Call',\n  emphasis: 'Primary path',\n  security: 'Crosses a trust boundary',\n  dashed: 'Asynchronous',\n  return: 'Return',\n}\n\nconst STATE_LABEL: Record<LifecycleStateKind, string> = {\n  start: 'Entry',\n  active: 'Working',\n  waiting: 'Waiting',\n  decision: 'Decision',\n  success: 'Succeeded',\n  failure: 'Failed',\n  neutral: 'Idle',\n  external: 'External',\n}\n\nexport type LegendEntry = { key: string; label: string; sample: React.ReactNode }\n\n/**\n * Which entries the key shows.\n *\n * `auto` — the default and the truthful one — lists only the kinds the figure\n * actually drew. A key that names seven kinds beside a figure using three is\n * not more informative; it is four claims the picture does not support.\n */\nexport function resolveLegend<T extends string>(\n  used: T[],\n  mode: LegendMode = 'auto',\n  all: T[] = [],\n  overrides?: Record<string, { label?: string; visible?: boolean }>,\n): T[] {\n  if (mode === 'hidden') return []\n  const base = mode === 'all' ? all : [...new Set(used)]\n  return base.filter((key) => overrides?.[key]?.visible !== false)\n}\n\n/** A key entry for each node kind, drawn with the same sigil the figure uses. */\nexport function kindLegend(\n  kinds: NodeKind[],\n  overrides?: Record<string, { label?: string }>,\n): LegendEntry[] {\n  return kinds.map((kind) => ({\n    key: kind,\n    // The key names a kind with the SAME word the plate's eyebrow prints. They\n    // were two vocabularies for one fact — a plate reading SERVICE beside a key\n    // reading \"Datastore\" — which is the one thing a key must never do.\n    label: overrides?.[kind]?.label ?? KIND_WORD[kind],\n    sample: (\n      <g transform=\"translate(1, 1)\">\n        <Sigil kind={kind} x={0} y={0} />\n      </g>\n    ),\n  }))\n}\n\n/** A key entry for each relationship variant, drawn as the line itself. */\nexport function variantLegend(\n  variants: (Variant | 'return')[],\n  overrides?: Record<string, { label?: string }>,\n): LegendEntry[] {\n  return variants.map((variant) => ({\n    key: variant,\n    label: overrides?.[variant]?.label ?? VARIANT_LABEL[variant],\n    sample: (\n      <path\n        d=\"M 0.5 7 H 13.5\"\n        fill=\"none\"\n        className={\n          variant === 'emphasis'\n            ? 'stroke-(--diagram-line-strong) [stroke-width:2.4]'\n            : variant === 'security'\n              ? 'stroke-(--diagram-line) [stroke-width:1.6] [stroke-dasharray:4_2]'\n              : variant === 'dashed' || variant === 'return'\n                ? 'stroke-(--diagram-line-soft) [stroke-width:1.6] [stroke-dasharray:3_2.5]'\n                : 'stroke-(--diagram-line) [stroke-width:1.6]'\n        }\n      />\n    ),\n  }))\n}\n\n/** A key entry for each lifecycle state kind, drawn as its plate. */\nexport function stateLegend(\n  kinds: LifecycleStateKind[],\n  overrides?: Record<string, { label?: string }>,\n): LegendEntry[] {\n  return kinds.map((kind) => ({\n    key: kind,\n    label: overrides?.[kind]?.label ?? STATE_LABEL[kind],\n    sample:\n      kind === 'decision' ? (\n        <path\n          d=\"M 7 1 L 13 7 L 7 13 L 1 7 Z\"\n          className=\"fill-(--diagram-node) stroke-(--diagram-rule-hard) [stroke-width:1.2]\"\n        />\n      ) : kind === 'external' ? (\n        <path\n          d=\"M 1 2 H 9.5 L 13 5.5 V 12 H 1 Z\"\n          className=\"fill-(--diagram-node-2) stroke-(--diagram-rule) [stroke-width:1.2]\"\n        />\n      ) : (\n        <rect\n          x=\"1\"\n          y=\"3\"\n          width=\"12\"\n          height=\"8\"\n          rx={kind === 'start' ? 4 : 2}\n          className={\n            kind === 'start'\n              ? 'fill-(--diagram-plate) stroke-(--diagram-plate) [stroke-width:1.2]'\n              : kind === 'success'\n                ? 'fill-(--success-wash) stroke-(--success) [stroke-width:1.2]'\n                : kind === 'failure'\n                  ? 'fill-(--danger-wash) stroke-(--danger) [stroke-width:1.2]'\n                  : kind === 'waiting'\n                    ? 'fill-(--diagram-node) stroke-(--diagram-rule) [stroke-width:1.2] [stroke-dasharray:3_2]'\n                    : kind === 'neutral'\n                      ? 'fill-(--diagram-node-2) stroke-(--diagram-rule) [stroke-width:1.2]'\n                      : 'fill-(--diagram-node) stroke-(--diagram-rule-hard) [stroke-width:1.2]'\n          }\n        />\n      ),\n  }))\n}\n"],"mappings":"AAuDQ;AAtDR,SAAS,WAAW,aAAa;AAEjC,MAAM,gBAAoD;AAAA,EACxD,SAAS;AAAA,EACT,UAAU;AAAA,EACV,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,QAAQ;AACV;AAEA,MAAM,cAAkD;AAAA,EACtD,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,UAAU;AAAA,EACV,SAAS;AAAA,EACT,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AACZ;AAWO,SAAS,cACd,MACA,OAAmB,QACnB,MAAW,CAAC,GACZ,WACK;AACL,MAAI,SAAS,SAAU,QAAO,CAAC;AAC/B,QAAM,OAAO,SAAS,QAAQ,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC;AACrD,SAAO,KAAK,OAAO,CAAC,QAAQ,YAAY,GAAG,GAAG,YAAY,KAAK;AACjE;AAGO,SAAS,WACd,OACA,WACe;AACf,SAAO,MAAM,IAAI,CAAC,UAAU;AAAA,IAC1B,KAAK;AAAA;AAAA;AAAA;AAAA,IAIL,OAAO,YAAY,IAAI,GAAG,SAAS,UAAU,IAAI;AAAA,IACjD,QACE,oBAAC,OAAE,WAAU,mBACX,8BAAC,SAAM,MAAY,GAAG,GAAG,GAAG,GAAG,GACjC;AAAA,EAEJ,EAAE;AACJ;AAGO,SAAS,cACd,UACA,WACe;AACf,SAAO,SAAS,IAAI,CAAC,aAAa;AAAA,IAChC,KAAK;AAAA,IACL,OAAO,YAAY,OAAO,GAAG,SAAS,cAAc,OAAO;AAAA,IAC3D,QACE;AAAA,MAAC;AAAA;AAAA,QACC,GAAE;AAAA,QACF,MAAK;AAAA,QACL,WACE,YAAY,aACR,sDACA,YAAY,aACV,sEACA,YAAY,YAAY,YAAY,WAClC,6EACA;AAAA;AAAA,IAEZ;AAAA,EAEJ,EAAE;AACJ;AAGO,SAAS,YACd,OACA,WACe;AACf,SAAO,MAAM,IAAI,CAAC,UAAU;AAAA,IAC1B,KAAK;AAAA,IACL,OAAO,YAAY,IAAI,GAAG,SAAS,YAAY,IAAI;AAAA,IACnD,QACE,SAAS,aACP;AAAA,MAAC;AAAA;AAAA,QACC,GAAE;AAAA,QACF,WAAU;AAAA;AAAA,IACZ,IACE,SAAS,aACX;AAAA,MAAC;AAAA;AAAA,QACC,GAAE;AAAA,QACF,WAAU;AAAA;AAAA,IACZ,IAEA;AAAA,MAAC;AAAA;AAAA,QACC,GAAE;AAAA,QACF,GAAE;AAAA,QACF,OAAM;AAAA,QACN,QAAO;AAAA,QACP,IAAI,SAAS,UAAU,IAAI;AAAA,QAC3B,WACE,SAAS,UACL,uEACA,SAAS,YACP,gEACA,SAAS,YACP,8DACA,SAAS,YACP,4FACA,SAAS,YACP,uEACA;AAAA;AAAA,IAEhB;AAAA,EAEN,EAAE;AACJ;","names":[]}

package/dist/diagrams/lib/marks.d.ts

@@ -0,0 +1,207 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { NodeKind, Variant, LifecycleStateKind } from '../spec.js';
+import { Box } from './geometry.js';
+
+/** What each kind is called on a plate's eyebrow. Short, because it is a kicker. */
+declare const KIND_WORD: Record<NodeKind, string>;
+/**
+ * The marker definitions every figure needs.
+ *
+ * Rendered once per figure. The ids are namespaced by the figure's own id
+ * because two diagrams on one page would otherwise share one `<defs>`, and the
+ * second figure's arrowheads would silently take the first figure's paint —
+ * SVG ids are document-global, and a duplicate is resolved to whichever came
+ * first rather than to the nearest one.
+ */
+declare function DiagramDefs({ uid }: {
+    uid: string;
+}): react.JSX.Element;
+/**
+ * The 14×14 mark that says what kind of thing a node is.
+ *
+ * Drawn on a 14-unit grid at a 1.35 stroke. Both numbers went up from the first
+ * pass and both had to: at 12 units and a 1.2 stroke the seven forms were a few
+ * grey pixels apart at reading size, which is not a distinction — it is a
+ * smudge. Every path is closed geometry rather than an icon font, because a
+ * figure has to serialise into a standalone file and a font the exported
+ * document cannot fetch renders as a box.
+ */
+declare function Sigil({ kind, x, y, reversed, }: {
+    kind: NodeKind;
+    x: number;
+    y: number;
+    reversed?: boolean;
+}): react.JSX.Element;
+/**
+ * A plate's internal vertical rhythm, in user units from its top edge.
+ *
+ * Written out as one object rather than computed inline in three renderers,
+ * because these numbers ARE the plate: change one and the card stops looking
+ * like a card. The eyebrow sits high and tight, the name is the only thing set
+ * at reading size, and the sublabel hangs under it in the meta voice.
+ */
+declare const PLATE: {
+    readonly padX: 15;
+    readonly eyebrow: 19;
+    readonly label: 39;
+    readonly sub: 53;
+    readonly lineStep: 17;
+    /** Where the eyebrow lands when there is none — the label moves up into it. */
+    readonly riseWithoutEyebrow: 16;
+};
+/**
+ * How tall a plate has to be to hold what it was given.
+ *
+ * A declared height is a FLOOR, not a ceiling. When a specification asks for a
+ * 60-unit box and then puts two lines of name and a qualifier in it, honouring
+ * the 60 prints the qualifier through the bottom rule — which reads as a
+ * rendering fault rather than as a box asked to hold too much. Growing is
+ * visible and correct; clipping is invisible and wrong.
+ */
+declare function plateHeight(labelLines: number, hasSub: boolean, hasEyebrow: boolean, floor?: number): number;
+interface NodePlateProps {
+    box: Box;
+    label: string;
+    sublabel?: string;
+    tag?: string;
+    kind?: NodeKind;
+    variant?: Variant;
+    /** Printed in the trailing corner in mono — a step number. */
+    step?: string;
+    /** Paints the plate on the recessed ground rather than on paper. */
+    muted?: boolean;
+    /** Lit by a guided chapter or a reader's focus. */
+    active?: boolean;
+    /** Dimmed because something else is lit. */
+    dimmed?: boolean;
+    onSelect?: () => void;
+    /** A stable hook the viewer chrome and the tests both address nodes by. */
+    nodeId?: string;
+}
+/**
+ * One box, with everything that can be printed inside it.
+ *
+ * Three registers, top to bottom, and each is a different voice on purpose: a
+ * mono kicker naming the KIND, the name at reading size in the interface face,
+ * and the qualifier back in mono. That is the same ladder a record on a page
+ * uses — the diagram is not inventing a second typography for itself.
+ *
+ * WHAT IT IS NOT is a button, and that is deliberate. The `<svg>` around it
+ * carries `role="img"`, which makes everything inside it presentational to
+ * assistive technology — so a `role="button"` here would announce a control a
+ * screen reader can never reach. The keyboard route to the same selection is
+ * the figure's own summary list, which is a real `<ul>` of real `<button>`s
+ * sitting beside the picture. `onSelect` here is the POINTER path to that same
+ * action, and nothing else.
+ */
+declare function NodePlate({ box, label, sublabel, tag, kind, variant, step, muted, active, dimmed, onSelect, nodeId, }: NodePlateProps): react.JSX.Element;
+/**
+ * A mono chip: a version, a region, a protocol, a data classification.
+ *
+ * A rule and a word, with no fill under it. The filled chip this replaced put a
+ * third ground inside a plate that already sat on a figure that sat on the
+ * page, and three grounds deep is where a diagram stops reading as structure
+ * and starts reading as packaging.
+ */
+declare function Chip({ x, y, text, align, reversed, }: {
+    x: number;
+    y: number;
+    text: string;
+    align?: 'start' | 'middle' | 'end';
+    reversed?: boolean;
+}): react.JSX.Element;
+/**
+ * How a line is painted: the colour as a class, the geometry as attributes.
+ *
+ * THE SPLIT IS NOT ARBITRARY, and getting it wrong cost an afternoon. Tailwind
+ * generates a rule only for a class name it can find as a LITERAL in the
+ * source. A width built at runtime — `` `[stroke-width:${weight}]` `` — is a
+ * class that never gets a rule, so the browser falls back to SVG's default
+ * 1px, silently, on exactly the lines a figure most needs to be heavier. The
+ * main path came out the same weight as a side branch and nothing said so.
+ *
+ * Colour still goes through a class, because a paint has to resolve a custom
+ * property and `stroke="var(--x)"` is not valid as an attribute. Width and dash
+ * pattern are plain numbers, so they go through presentation attributes where
+ * no build step has to have predicted them — and `getComputedStyle` reports an
+ * attribute exactly as it reports a rule, so the export still picks them up.
+ */
+declare function edgeClasses(variant?: Variant | 'return'): string;
+/** A line's width and dash pattern, as presentation attributes. */
+declare function edgeStroke(variant?: Variant | 'return', weight?: number): {
+    strokeWidth: number;
+    strokeDasharray?: string;
+};
+/** Which arrowhead a line ends in. */
+declare function edgeMarker(variant?: Variant | 'return'): 'arrow' | 'arrow-strong' | 'arrow-open';
+interface EdgeLabelProps {
+    x: number;
+    y: number;
+    axis: 'x' | 'y';
+    text: string;
+    /** A mono chip printed under the wording — a data classification. */
+    chip?: string;
+    /** A second, quieter line — a condition, a timeout, a retry count. */
+    note?: string;
+}
+/**
+ * A relationship's wording, on a mask that punches the line out from under it.
+ *
+ * The mask is not decoration. A label drawn straight onto a line is unreadable
+ * at every size, and the two repairs a renderer can make are moving the label
+ * or hiding the line behind it. Moving it changes which segment the wording
+ * belongs to, which is a semantic change; masking is the one that leaves the
+ * meaning alone.
+ *
+ * Set in mono rather than in the interface face. The wording on a line is an
+ * ANNOTATION on the picture, not a second rank of content — and at the sans
+ * face it competed with the names on the plates, which is the one comparison it
+ * must lose.
+ */
+declare function EdgeLabel({ x, y, axis, text, chip, note }: EdgeLabelProps): react.JSX.Element;
+/**
+ * A labelled frame around a set of boxes: a region, a security group, a phase,
+ * a process group.
+ *
+ * A FRAME IS A RULE AND NOT A GROUND. Archify washes its regions with a tint,
+ * which this system cannot copy for two reasons: a second ground inside a paper
+ * figure reads as packaging rather than as structure — the same argument the
+ * containment `Diagram` primitive makes about nested boxes — and every
+ * relationship label crossing the wash would then need to know which of two
+ * grounds its mask is punching through, which is a question a label cannot
+ * answer. `muted` therefore washes only where a band IS the ground it labels: a
+ * workflow's exception lane, which nothing routes across.
+ *
+ * The label sits ABOVE the top rule rather than inside the frame or on it.
+ * Inside, it costs a line of vertical space in every frame whether or not the
+ * frame had one to spare. ON the rule — which is where it started — it has to
+ * punch a mask through the frame, and that mask then competes for the same few
+ * units of clear ground as any relationship label routed along the frame's own
+ * edge: two captions, two white plates, one on top of the other. Above the
+ * rule it needs no mask, leaves the frame unbroken, and reads as a caption for
+ * the frame rather than as its first child.
+ */
+declare function BandFrame({ box, label, dashed, muted, }: {
+    box: Box;
+    label?: string;
+    dashed?: boolean;
+    muted?: boolean;
+}): react.JSX.Element;
+/**
+ * The plate shape for a lifecycle state.
+ *
+ * This is the one place the system spends colour, and it spends exactly the two
+ * tokens it reserves for state: `--success` on a terminal success, `--danger`
+ * on a terminal failure. Every other kind is carried by shape — a filled cap
+ * for a start, a diamond for a decision, a dashed frame for a wait, a cut
+ * corner for something outside the system — so a greyscale print loses the two
+ * outcomes' hue and keeps all six other distinctions.
+ */
+declare function StatePlate({ box, kind, children, }: {
+    box: Box;
+    kind: LifecycleStateKind;
+    children?: ReactNode;
+}): react.JSX.Element;
+
+export { BandFrame, Chip, DiagramDefs, EdgeLabel, type EdgeLabelProps, KIND_WORD, NodePlate, type NodePlateProps, PLATE, Sigil, StatePlate, edgeClasses, edgeMarker, edgeStroke, plateHeight };