compasso 0.3.0 → 0.4.0

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,38 @@ 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).
+
 ## Localization
 
 ```ts
@@ -222,16 +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, 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