Status: Implemented
Visualize is a server-side visualization library for Elixir: D3-shaped scales, shapes, layouts and geographic projections that produce SVG (or Canvas command streams) for Phoenix LiveView. This directory is the complete specification of the library — the contract every module in lib/ is held to, and the record of why it is shaped the way it is.
1. Source of truth
This directory is normative. Where the code under lib/ and a document here disagree, the code is wrong: the disagreement is a bug to be fixed in the code, or a proposal to change the specification — never a silent drift of one away from the other.
Drift is detected mechanically. API_SURFACE.md is a generated golden listing every public function the specification declares (each `Module.function/arity` in the first cell of a table row) against every public function lib/ defines. It is regenerated by mix vis.surface --write, checked by mix vis.surface --check, and gated in CI (see 12-testing-and-conformance). A function that exists in lib/ without a row here is unspecified; a row here without a function is unimplemented; either fails the gate.
2. Requirement language
The key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in RFC 2119. Prose without these words is descriptive; a table's Contract column is normative.
3. Status vocabulary
Every document carries a **Status:** line immediately after its title.
- Draft — being written; may be incomplete or internally inconsistent; not a contract yet.
- Agreed — the design is settled and changes need a proposal, but the code does not exist or does not yet conform.
- Implemented — code exists and conforms; any divergence is a defect.
4. Reading order
| # | Document | What it settles | Status |
|---|---|---|---|
| 00 | Prior art | The D3.js lineage, what was deliberately not ported, the LiveView constraints, Elixir neighbours | Implemented |
| 01 | Goals and scope | What Visualize is for, what it will not do, optional dependencies, compatibility | Implemented |
| 02 | Architecture | The data → scale → shape → IR → backend → render pipeline; the IR; the backend behaviour; the SVG element layer | Implemented |
| 03 | Scales | Every scale type, its domain/range semantics, ticks, nice, invert, colour schemes | Implemented |
| 04 | Shapes and curves | Line, area, arc, pie, stack, symbol generators and every curve type | Implemented |
| 05 | Axes and formatting | Axis generation, tick placement, number and time formatting | Implemented |
| 06 | Layouts | Hierarchy, tree, cluster, pack, partition, treemap, chord, sankey, force simulation | Implemented |
| 07 | Geo | Projections and their families, GeoJSON paths, Delaunay, Voronoi | Implemented |
| 08 | Utilities | Data, colour, interpolate, ease, random, polygon, contour, themes | Implemented |
| 09 | Rendering backends | SVG and Canvas backends, binary encoding, hybrid and incremental rendering | Implemented |
| 10 | LiveView integration | Components, hooks, HEEx-safe elements, the JS hook contract | Implemented |
| 11 | Public API | The facade module, what is public, naming and error conventions | Implemented |
| 12 | Testing and conformance | Goldens, the API surface gate, heading checks, CI stages, the ExTLA model | Agreed |
| 13 | Decisions | The architecture decision record log | Implemented |
| 14 | Declarative chart | The design map: schema with facets, style grammar, frame, marks, variables, version, validation, JSON; application, composition and compilation; the builder | Agreed |
Documents are numbered in reading order; the README keeps its name so the directory index renders it. New documents take the next free number.
5. Changing the specification
- Edit the document. Keep headings decimal-numbered and gap-free (
## 1.,### 1.1,#### 1.1.1), one#title per file, and a**Status:**line on line 3. - If a function table changed, run
mix vis.surface --writeto regenerateAPI_SURFACE.md. - Run
mix vis.headingsto check the numbering, thenmix vis.surface --check. - Commit the regenerated
API_SURFACE.mdin the same change as the document edit, so the golden and the specification never disagree in history.
A change that alters the intended behaviour of implemented code MUST be recorded as a decision in 13-decisions and MUST go through a proposal before the code changes.