compasso 0.2.0 → 0.4.0

package/README.md

@@ -3,10 +3,37 @@
 Standards-faithful technical diagrams as **pure SVG strings**. Deterministic, zero
 runtime dependencies, server-safe (no DOM, no canvas, no clock, no randomness).
 
-**Four 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) and the **fishbone** (Ishikawa cause-and-effect). The
-architecture is built for more — see the roadmap.
+distinctive-shape notation), the **fishbone** (Ishikawa cause-and-effect), the
+**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
 
@@ -139,6 +166,93 @@ effect at every level (suppressible via `arrowheads: false`). **Declared order i
 honored** — significance-near-the-head is the analyst's call, never re-sorted. Label
 spacing is driven by measured text widths, so labels never collide.
 
+## Pedigree
+
+```ts
+import { pedigreeSvg } from "compasso/pedigree";
+
+const { svg } = pedigreeSvg({
+  conditions: [{ id: 1, label: "Cystic fibrosis" }],
+  individuals: [
+    { id: 1, label: "I-1", sex: "male", generation: 1, deceased: true, carrier: true, role: null, lifeStatus: "alive", affectedBy: [] },
+    { id: 2, label: "I-2", sex: "female", generation: 1, deceased: false, carrier: true, role: null, lifeStatus: "alive", affectedBy: [] },
+    { id: 3, label: "II-1", sex: "female", generation: 2, deceased: false, carrier: false, role: "proband", lifeStatus: "alive", affectedBy: [1] },
+  ],
+  matings: [{ id: 1, partnerAId: 1, partnerBId: 2, consanguineous: false }],
+  sibships: [{ id: 1, matingId: 1, childIds: [3], twinGroups: [] }],
+});
+```
+
+Standardized clinical-genetics notation (Bennett et al. 2008): square/circle/diamond by
+sex, **filled glyph = affected** (multiple conditions shown as up to four vertical
+partitions), carrier center dot, deceased slash, **proband filled arrow / consultand
+open arrow**, **consanguineous matings as a double line**, MZ/DZ/unknown-zygosity twins,
+Roman-numeral generations with within-generation "II-3" addresses. A pedigree is a
+clinical record, so structurally invalid input is **refused with coded issues**
+(`PedigreeValidationError`), never silently repaired. The layout is deterministic and
+overlap-proof — including remarriages and multi-spouse hubs.
+
+## Phylogenetic tree
+
+```ts
+import { phyloSvg } from "compasso/phylo";
+
+const { svg } = phyloSvg({
+  rootId: 1,
+  nodes: [
+    { id: 1, label: "root" },
+    { id: 2, label: "Clade A", support: 98 },
+    { id: 3, label: "Homo sapiens" },
+    { id: 4, label: "Pan troglodytes" },
+  ],
+  edges: [
+    { id: 1, parentId: 1, childId: 2, length: 0.4 },
+    { id: 2, parentId: 2, childId: 3, length: 0.6 },
+    { id: 3, parentId: 2, childId: 4, length: 0.55 },
+  ],
+}, { mode: "phylogram", showSupport: true });
+```
+
+Rectangular cladogram or phylogram. In `phylogram` mode each node's x is its cumulative
+branch length from the root (fit to width); in `cladogram` mode tips right-align with
+optional dotted extensions. Optional bootstrap/posterior `support` values at clades and a
+distance scale bar (phylogram only). The flat `{rootId, nodes, edges}` AST is
+Newick-importable. Branch lengths are never lost — a `null`/zero length is valid (the
+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).
+
 ## Localization
 
 ```ts
@@ -165,10 +279,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. Next: more tree-based diagrams (phylogenetic, 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
+input→SVG, determinism, the honesty rule, the overlap harness, validation doctrine,
+module anatomy). `docs/architecture.md` covers the internal structure.
 
 ## Provenance & license