compasso 0.3.0 → 0.4.1

package/README.md

@@ -3,12 +3,37 @@
 Standards-faithful technical diagrams as **pure SVG strings**. Deterministic, zero
 runtime dependencies, server-safe (no DOM, no canvas, no clock, no randomness).
 
-**Six diagrams shipped:** the **genogram** (McGoldrick family-systems notation), the
+**Seven diagrams shipped:** the **genogram** (McGoldrick family-systems notation), the
 **ecomap** (radial person↔environment ties), the **fault tree** (NUREG-0492 / IEC 61025
 distinctive-shape notation), the **fishbone** (Ishikawa cause-and-effect), the
-**pedigree** (Bennett 2008 standardized clinical-genetics nomenclature) and the
-**phylogenetic tree** (cladogram + phylogram). The architecture is built for more —
-see the roadmap.
+**pedigree** (Bennett 2008 standardized clinical-genetics nomenclature), the
+**phylogenetic tree** (cladogram + phylogram) and the **org chart** (top-down reporting
+hierarchy). The architecture is built for more — see the roadmap.
+
+## Gallery
+
+Every image below is a committed SVG in [`examples/svg/`](examples/svg) — rendered by the
+current code and pinned byte-for-byte by `test/snapshots/gallery.test.ts`, so the pictures
+can never drift from what compasso emits. Reproduce them all with `pnpm build && node
+examples/demo.mjs`.
+
+<table>
+  <tr>
+    <td align="center" width="50%"><strong>Genogram</strong><br><img src="examples/svg/genogram.svg" alt="genogram example" width="370"></td>
+    <td align="center" width="50%"><strong>Ecomap</strong><br><img src="examples/svg/ecomap.svg" alt="ecomap example" width="330"></td>
+  </tr>
+  <tr>
+    <td align="center"><strong>Fault tree</strong><br><img src="examples/svg/fault-tree.svg" alt="fault tree example" width="440"></td>
+    <td align="center"><strong>Fishbone</strong><br><img src="examples/svg/fishbone.svg" alt="fishbone example" width="440"></td>
+  </tr>
+  <tr>
+    <td align="center"><strong>Pedigree</strong><br><img src="examples/svg/pedigree.svg" alt="pedigree example" width="270"></td>
+    <td align="center"><strong>Phylogenetic tree</strong><br><img src="examples/svg/phylo.svg" alt="phylogenetic tree example" width="400"></td>
+  </tr>
+  <tr>
+    <td align="center" colspan="2"><strong>Org chart</strong><br><img src="examples/svg/org-chart.svg" alt="org chart example" width="470"></td>
+  </tr>
+</table>
 
 ## Principles
 
@@ -196,6 +221,67 @@ Newick-importable. Branch lengths are never lost — a `null`/zero length is val
 node sits at its parent's depth), and the verbatim length always rides the branch
 `<title>`.
 
+## Org chart
+
+```ts
+import { orgChartSvg } from "compasso/org-chart";
+
+const { svg } = orgChartSvg({
+  positions: [
+    { id: 1, name: "Alex Mercer", title: "CEO", subtitle: null, vacancy: "filled" },
+    { id: 2, name: "Priya Nair", title: "Executive Assistant", subtitle: null, vacancy: "filled" },
+    { id: 3, name: "Dana Brooks", title: "VP, Engineering", subtitle: null, vacancy: "filled" },
+    { id: 4, name: "", title: "Staff Engineer", subtitle: null, vacancy: "vacant" },
+  ],
+  reports: [
+    { id: 1, managerId: 1, reportId: 2, kind: "assistant" },
+    { id: 2, managerId: 1, reportId: 3, kind: "line" },
+    { id: 3, managerId: 3, reportId: 4, kind: "line" },
+  ],
+});
+```
+
+A top-down reporting hierarchy with a deterministic, overlap-proof tidy-tree layout (fully
+orthogonal — no diagonals). Three reporting kinds: `line` (the solid primary report that
+defines the spine), `assistant` (a staff/EA role on a side-stem), and `dotted` (a secondary
+/ matrix line, routed clear of every box). A `vacant` position draws a dashed open-seat box.
+The hierarchy is **read from the declared reports** — there is no depth or order field, and
+multiple roots (a forest) are drawn exactly as declared. An org chart is authoritative, so
+structurally invalid input is **refused with coded issues** (`OrgChartValidationError`:
+`cycle`, `multiple-managers`, `unknown-manager`, …), never silently repaired.
+
+Lower-level entry points: `computeOrgChartLayout` (pure layout) and `orgChartLayoutSvg`
+(layout → string).
+
+## Annotations
+
+Any element you declare can be flagged `annotated: true` to draw a discreet, neutral marker —
+a small dot on a node, a short tick on an edge — plus a matching legend row. compasso never
+decides what an annotation *means*; you supply the legend wording, so it reads however your
+domain needs (`"edited"`, `"under review"`, `"verified"`, …).
+
+```ts
+import { genogramSvg } from "compasso/genogram";
+
+const { svg } = genogramSvg(
+  {
+    people: [
+      { id: 1, label: "Ana", sex: "female", deceased: false, generation: 0, annotated: true },
+      { id: 2, label: "Bea", sex: "female", deceased: false, generation: 0 },
+    ],
+    unions: [],
+    parentLinks: [],
+    relationships: [],
+  },
+  { annotationLabel: "edited" }, // legend row appears only when something is annotated
+);
+```
+
+Supported on `genogram` (people, unions, parent links, relationships), `ecomap` (ties) and
+`org-chart` (positions, reports). The marker is **presence-only** — drawn as literal SVG
+inside the element's `<g>`, it never affects layout — and the legend row appears only when you
+pass `annotationLabel` **and** at least one element is annotated.
+
 ## Localization
 
 ```ts
@@ -222,16 +308,15 @@ with a negation list. PRs for new locales are welcome.
 
 The goal is a family of standards-faithful technical diagrams sharing this core
 (text metrics, stroke vocabulary, escaping, legend machinery). Shipped: genogram,
-ecomap, fault tree, fishbone, pedigree, phylogenetic tree. Next: org charts, flow/
-layered diagrams (PRISMA, UML), and symbol-library diagrams (P&ID, single-line, ladder
-logic) — each built from its public standard. AST-first; text DSLs may come later.
+ecomap, fault tree, fishbone, pedigree, phylogenetic tree, org chart. Next: flow/layered
+diagrams (PRISMA, UML), and symbol-library diagrams (P&ID, single-line, ladder logic) —
+each built from its public standard. AST-first; text DSLs may come later.
 
 ## Contributing
 
-`AGENTS.md` is the contract for changing compasso (the house conventions: pure
+`AGENTS.md` is the contract for changing compasso — the house conventions (pure
 input→SVG, determinism, the honesty rule, the overlap harness, validation doctrine,
-module anatomy). `docs/architecture.md` covers the internal structure and `docs/design/`
-the per-module design rationale.
+module anatomy). `docs/architecture.md` covers the internal structure.
 
 ## Provenance & license
 

package/dist/{chunk-RWPGGWO5.js → chunk-FYBABYC7.js}

@@ -1,4 +1,4 @@
-import { normalizeText, wrapLabelBalanced, clampLabel, estimateTextWidth, qualityLineStyle, xmlEscape, FONT_FAMILY, LEGEND_SWATCH_W, EDGE_STROKE, legendBlock } from './chunk-O3BT2O42.js';
+import { normalizeText, wrapLabelBalanced, clampLabel, estimateTextWidth, qualityLineStyle, xmlEscape, annotationDot, FONT_FAMILY, LEGEND_SWATCH_W, EDGE_STROKE, annotationSwatch, legendBlock, annotationTick } from './chunk-SD4NTRBM.js';
 
 // src/genogram/types.ts
 var UNION_STATUSES = [
@@ -175,7 +175,8 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
     parentId: l.parentId,
     childId: l.childId,
     quality: l.quality,
-    edgeId: PARENT_REL_ID_BASE + l.id
+    edgeId: PARENT_REL_ID_BASE + l.id,
+    annotated: l.annotated ?? false
   }));
   const declaredPairs = new Set(validLinks.map((l) => pairKey(l.parentId, l.childId)));
   const promotedByPair = /* @__PURE__ */ new Map();
@@ -194,7 +195,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
       [parentId, childId] = fromIsChild ? [r.toPersonId, r.fromPersonId] : [r.fromPersonId, r.toPersonId];
     }
     if (parentId === childId) continue;
-    promotedByPair.set(key, { parentId, childId, quality: r.quality, edgeId: PROMOTED_REL_ID_BASE + r.id });
+    promotedByPair.set(key, { parentId, childId, quality: r.quality, edgeId: PROMOTED_REL_ID_BASE + r.id, annotated: r.annotated ?? false });
   }
   const allLinks = [...realLinks, ...promotedByPair.values()].sort((a, b) => a.edgeId - b.edgeId);
   const coupleByPair = /* @__PURE__ */ new Map();
@@ -527,6 +528,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
         toPersonId: u.personBId,
         titles: [unionTitle(u)],
         lineStyle: "plain",
+        annotated: u.annotated ?? false,
         build: () => {
           const cy = geo.cy(rowOfPerson.get(leftId));
           if (dipLevel === 0) {
@@ -561,6 +563,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
         toPersonId: u.personBId,
         titles: [unionTitle(u)],
         lineStyle: "plain",
+        annotated: u.annotated ?? false,
         build
       });
     }
@@ -617,6 +620,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
       };
       gutterReqs.push(spineReq);
       const aId = (c) => linkOf.get(`${u.personAId}>${c}`).edgeId;
+      const aLinkAnnotated = (c) => linkOf.get(`${u.personAId}>${c}`).annotated ?? false;
       const childDrop = (c, parentId) => {
         const link = linkOf.get(`${parentId}>${c}`);
         const edgeId = link.edgeId;
@@ -629,6 +633,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
           toPersonId: c,
           titles: [linkTitle(link)],
           lineStyle: "plain",
+          annotated: link.annotated,
           build: () => {
             const y = geo.corridorLaneY(sibReq);
             const x = geo.cx(colOrThrow(c)) + arrivalOffset(arr.slot, arrivalCount.get(c) ?? 1);
@@ -649,6 +654,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
           toPersonId: null,
           titles: [linkTitle(linkOf.get(`${u.personAId}>${c}`))],
           lineStyle: "plain",
+          annotated: aLinkAnnotated(c),
           build: () => {
             const sy = geo.corridorLaneY(sibReq);
             const sx = geo.gutterCenterX(interGutter);
@@ -674,6 +680,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
           // declared quality word is dropped from the drawn element (FIX C-2 / SPEC inv #4).
           titles: [aLinkTitle(groupKids[0]), ...groupKids.slice(2).map(aLinkTitle)],
           lineStyle: "plain",
+          annotated: [groupKids[0], ...groupKids.slice(2)].some(aLinkAnnotated),
           build: () => {
             const y = geo.corridorLaneY(sibReq);
             const xs = sibSpan();
@@ -692,6 +699,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
           titles: [aLinkTitle(groupKids[1])],
           // the A-side link this spine carries, verbatim
           lineStyle: "plain",
+          annotated: aLinkAnnotated(groupKids[1]),
           build: () => {
             const sy = geo.corridorLaneY(sibReq);
             const x = geo.gutterCenterX(interGutter);
@@ -719,6 +727,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
       titles: [linkTitle(l)],
       lineStyle: "plain",
       dotted: true,
+      annotated: l.annotated,
       build
     });
   }
@@ -731,10 +740,11 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
     const title = r.quality !== null ? `${r.type} \xB7 ${r.quality}` : r.type;
     const g = bondGroups.get(key);
     if (g === void 0) {
-      bondGroups.set(key, { relIds: [r.id], titles: [title], style, aId: r.fromPersonId, bId: r.toPersonId });
+      bondGroups.set(key, { relIds: [r.id], titles: [title], style, aId: r.fromPersonId, bId: r.toPersonId, annotated: r.annotated ?? false });
     } else {
       g.relIds.push(r.id);
       g.titles.push(title);
+      if (r.annotated) g.annotated = true;
     }
   }
   const bondList = [...bondGroups.values()].sort((a, b) => Math.max(...a.relIds) - Math.max(...b.relIds));
@@ -753,6 +763,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
       toPersonId: g.bId,
       titles: g.titles,
       lineStyle: g.style,
+      annotated: g.annotated,
       build
     });
   }
@@ -849,6 +860,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
       label: p.label,
       shape: shapeForSex(p.sex),
       deceased: p.deceased,
+      annotated: p.annotated ?? false,
       cx: colCenterX[c],
       cy: rowCenterY[r],
       size: NODE_SIZE,
@@ -865,6 +877,7 @@ function computeGenogramLayout(people, unions, parentLinks, relationships, opts
     points: pl.build(),
     titles: pl.titles,
     lineStyle: pl.lineStyle,
+    annotated: pl.annotated,
     ...pl.unionStyle !== void 0 ? { unionStyle: pl.unionStyle } : {},
     ...pl.dotted ? { dotted: true } : {}
   }));
@@ -969,6 +982,7 @@ function elementSvg(el, override) {
     }
     return `<path d="${pathData(pts)}" fill="none" stroke="${EDGE_INK}" stroke-width="${width}" stroke-opacity="${opacity}"${dashAttr}/>`;
   };
+  const tick = el.annotated ? annotationTick(el.points) : "";
   if (el.kind === "union-bar" || el.kind === "union-elbow") {
     const style = resolveUnionStyle(el, override);
     const body = [drawLine(style.dash ?? null, STRUCT_WIDTH, STRUCT_OPACITY)];
@@ -977,15 +991,15 @@ function elementSvg(el, override) {
       const [a, b] = pts.length === 2 ? [pts[0], pts[1]] : longestHSegment(pts);
       body.push(slashMarks(a, b, slashes, STRUCT_WIDTH));
     }
-    return `<g data-edge-id="${el.edgeId}">${title}${body.join("")}</g>`;
+    return `<g data-edge-id="${el.edgeId}">${title}${body.join("")}${tick}</g>`;
   }
   if (el.kind === "descent" || el.kind === "sibling-bar") {
     const dash = el.dotted ? DOTTED_DASH : null;
     const opacity = el.dotted ? DOTTED_OPACITY : STRUCT_OPACITY;
-    return `<g data-edge-id="${el.edgeId}">${title}${drawLine(dash, STRUCT_WIDTH, opacity)}</g>`;
+    return `<g data-edge-id="${el.edgeId}">${title}${drawLine(dash, STRUCT_WIDTH, opacity)}${tick}</g>`;
   }
   const ink = EDGE_STROKE[el.lineStyle];
-  return `<g data-edge-id="${el.edgeId}">${title}${drawLine(ink.dash, ink.width, ink.opacity)}</g>`;
+  return `<g data-edge-id="${el.edgeId}">${title}${drawLine(ink.dash, ink.width, ink.opacity)}${tick}</g>`;
 }
 function genogramLayoutSvg(layout, opts = {}) {
   const override = opts.unionStyleByRelId ?? /* @__PURE__ */ new Map();
@@ -1003,6 +1017,9 @@ function genogramLayoutSvg(layout, opts = {}) {
         `<line x1="${node.cx - half}" y1="${node.cy - half}" x2="${node.cx + half}" y2="${node.cy + half}" stroke="${GLYPH_STROKE}" stroke-width="2"/>`
       );
     }
+    if (node.annotated) {
+      pieces.push(annotationDot(node.cx + 0.7 * half, node.cy - 0.7 * half));
+    }
     const tspans = node.labelLines.map(
       (line, i) => `<tspan x="${node.cx}" y="${node.labelTop + 10 + i * LABEL_LINE_H}">${xmlEscape(line)}</tspan>`
     ).join("");
@@ -1045,6 +1062,12 @@ function genogramLayoutSvg(layout, opts = {}) {
         label: labels.isolated
       });
     }
+    if (opts.annotationLabel !== void 0 && (layout.nodes.some((n) => n.annotated) || layout.elements.some((e) => e.annotated))) {
+      entries.push({
+        swatch: (x, y) => annotationSwatch(x, y),
+        label: opts.annotationLabel
+      });
+    }
     const block = legendBlock(entries, layout.height);
     if (block.svg !== "") {
       parts.push(block.svg);
@@ -1096,11 +1119,12 @@ function genogramSvg(input, opts = {}) {
   const svg = genogramLayoutSvg(layout, {
     unionStyleByRelId,
     ...opts.legend === false ? { legend: false } : {},
-    ...opts.svgLabels !== void 0 ? { labels: opts.svgLabels } : {}
+    ...opts.svgLabels !== void 0 ? { labels: opts.svgLabels } : {},
+    ...opts.annotationLabel !== void 0 ? { annotationLabel: opts.annotationLabel } : {}
   });
   return { svg, layout };
 }
 
 export { EDGE_FONT, GENOGRAM_SVG_LABELS_EN, GENOGRAM_TITLE_LABELS_EN, KINSHIP_EN, LABEL_FONT, LABEL_LINE_H, NODE_SIZE, PARENT_REL_ID_BASE, PROMOTED_REL_ID_BASE, UNION_NOTATION, UNION_REL_ID_BASE, UNION_STATUSES, classifyRelationshipType, computeGenogramLayout, genogramLayoutSvg, genogramSvg, latestUnionPerPair, relationshipTypeTokens };
-//# sourceMappingURL=chunk-RWPGGWO5.js.map
-//# sourceMappingURL=chunk-RWPGGWO5.js.map
+//# sourceMappingURL=chunk-FYBABYC7.js.map
+//# sourceMappingURL=chunk-FYBABYC7.js.map