@mstone6969/graph 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Malcolmston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,480 @@
-# Temporary Holding Version
+# @mstone6969/graph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A class-based chart library for React. Every chart is a TypeScript class with a matching React component: 2D charts draw to SVG with d3, and 3D charts draw to WebGL with three.js.
+
+[Live site](https://malcolmston.github.io/graph/)
+
+**628 chart classes (519 d3/SVG, 109 three.js/WebGL) expand to 42,154 variant combinations (35,114 2D, 7,040 3D).** A type is one class with one combination of its variant axes, for example `bar.horizontal.stacked`. Every type passes a test proving its geometry differs from its siblings, so this counts configurations, not 42,154 separately designed forms.
+
+The count comes from `yarn vitest run src/catalog.test.ts`, which prints it. A class such as `BarChart` is one piece of code; its declared variant axes (orientation, stacking, padding) multiply into chart types, so hand-written classes are far fewer than types.
+
+## Install
+
+```sh
+yarn add @mstone6969/graph react react-dom
+```
+
+Everything comes from one import, and bundlers keep only what you use: `Bar` adds about 323 KB minified, `BarChart` about 190 KB, and `GraphType` about 20 KB, measured in a Vite app build with React external. `react` must be installed even if you only use the classes.
+
+## Four ways to use it
+
+**Component.** The usual choice. Every chart has one, and its props are typed for that chart. Sample data is drawn until you pass `data`.
+
+```tsx
+import { Bar, Orientation, StackMode } from '@mstone6969/graph'
+
+<Bar data={rows} orientation={Orientation.Horizontal} stack={StackMode.Stacked} />
+```
+
+A component is named after its class without `Chart`, `Plot`, `Map`, `Graph` or `Diagram`, so `BarChart` gives `Bar` and `ChoroplethMap` gives `Choropleth`. If that name is taken, by a class or a browser global, it ends in `Graph` instead: `BackToBackHistogram` gives `BackToBackHistogramGraph`, and each chart page on the site shows the name.
+
+**GraphType.** For a chart chosen at runtime. `GraphType` has one member per class, and variants are props. `Graph` loads the whole catalog the first time it needs one, so prefer a component when you know the chart.
+
+```tsx
+import { Graph, GraphType, Orientation } from '@mstone6969/graph'
+
+<Graph type={GraphType.BarChart} data={rows} orientation={Orientation.Horizontal} />
+```
+
+**Class.** `<Graph>` creates the chart for you. Changing a prop updates the chart in place, so its marks animate to the new state.
+
+```tsx
+import { BarChart, Graph, Orientation, StackMode } from '@mstone6969/graph'
+
+<Graph of={BarChart} data={rows} orientation={Orientation.Horizontal} stack={StackMode.Stacked} />
+```
+
+**Instance.** You own the object and can call its methods. Use this outside React too, with `chart.mount(element)`.
+
+```tsx
+import { BarChart, Graph, Orientation } from '@mstone6969/graph'
+
+const chart = new BarChart({ data: rows, orientation: Orientation.Horizontal, title: 'Revenue by region' })
+
+<Graph chart={chart} />
+chart.update({ orientation: Orientation.Vertical })
+chart.table() // { columns, rows }, for accessibility or export
+```
+
+Option fields name your data columns, and their defaults match the sample data, so `<Bar data={sales} x="region" y="revenue" series="year" />` is all a custom dataset needs.
+
+`<Graph>` keeps `type`, `of`, `chart`, `className`, `style`, `id` and `role` for itself. A few classes, such as `BoxPlot`, have a variant axis called `style`: reach those through an instance. Components keep only `className`, `style`, `id` and `role`, so a chart option called `type` works on them.
+
+Every chart also takes the shared `ChartOptions`: `width`, `height`, `title`, `subtitle`, `theme`, `animate`, `legend`, `tooltip`, `margin`, `ariaLabel`, `onSelect` and `keyboard`. Without a fixed size it takes its parent's width, follows resizes and is 400px tall.
+
+Every x/y chart also takes `xTicks`, `yTicks`, `xFormat`, `yFormat`, `xDomain` and `yDomain`. The domains fix the ends of a continuous axis, `null` keeps the chart's own value for one end, and marks past them are clipped to the plot. Band axes, and charts whose marks do not follow an axis, ignore them.
+
+Every x/y chart also takes `referenceLines`, `referenceBands` and `annotations`, positioned by data value through the chart's own scales, so categories, dates and log axes all work. `axis` names the axis the value sits on, so `AnnotationAxis.Y` (the default) draws a horizontal line. Values off the domain are skipped, bands are trimmed to it, and a label with no free spot in the plot is dropped. Bands sit behind the marks, so charts that fill the whole plot hide them.
+
+```tsx
+<Graph of={LineChart} data={rows}
+  referenceLines={[{ value: 100, label: 'Target' }, { axis: AnnotationAxis.X, value: launch, label: 'Launch' }]}
+  referenceBands={[{ from: 20, to: 40, label: 'Safe range' }]}
+  annotations={[{ x: launch, y: 92, text: 'Price cut' }]} />
+```
+
+## Live data
+
+`append` adds rows as they arrive instead of replacing the data. However fast rows come, the chart repaints at most once per animation frame.
+
+```ts
+const chart = new LineChart({ data: [] }).mount(el)
+socket.onmessage = (event) => chart.append(JSON.parse(event.data), { window: 60_000 })
+
+chart.append(rows, { keep: 500 })   // latest 500 rows, per series on charts with a series or group column
+chart.append(rows, { window: 5000 }) // rows within 5s of the newest x; x units, so ms for dates
+chart.pause()                        // freezes the picture; rows keep arriving and aging out
+chart.resume()                       // catches up in one paint
+```
+
+`window` and `keep` can be combined and stick for later calls. With neither, rows accumulate without limit. `window` reads the chart's `x` column; pass `{ x: 'column' }` if it has none. `update({ data })` replaces the live buffer. After `destroy()`, late rows are ignored, so a socket that outlives its chart is harmless. Series keep their colour and stack order as rows age out, so `chart.data` may list a series' oldest row early, and a series that returns after leaving the window comes last in the stack.
+
+In React, `useLiveChart` gives you stable handlers:
+
+```tsx
+import { Graph, useLiveChart } from '@mstone6969/graph'
+
+const live = useLiveChart(() => new LineChart({ data: [] }), { window: 60_000 })
+useEffect(() => socket.subscribe(live.append), [live.append])
+return <Graph chart={live.chart} />
+```
+
+**Supported:** flat rows and long-form series rows (`{ date, series, value }`) on 2D charts with `DataShape.Table`, which is 379 catalog classes, row-fed massive charts included. Columnar massive data and anything else throws a clear error from `append` and `pause`: 3D charts, and hierarchy, graph, matrix, grid, volume, geo, function, text and genome data.
+
+**Motion:** cartesian charts whose x and y are both continuous slide. Each paint draws final geometry, then the marks, ticks and grid decay smoothly from where they last appeared, so a spike rescales instead of jumping, and marks are clipped to the plot only while they move. Charts with a band or point axis, a zoom or brush, their own `draw`, or no axes morph each mark with its usual transition instead. Massive charts draw on a canvas, so they and their axes repaint in one step. `animate: false` and reduced motion paint straight through.
+
+## Zoom, pan and brush
+
+Every x/y chart takes `zoom` and `brush`. Both are off by default, and then nothing about the chart changes.
+
+```tsx
+import { ZoomAxis, type BrushRange } from '@mstone6969/graph'
+
+<Graph of={LineChart} data={rows} zoom />                 // wheel, drag, double click and buttons along x
+<Graph of={ScatterPlot} data={rows} zoom={ZoomAxis.XY} /> // both axes
+<Graph of={LineChart} data={rows} brush onBrush={(range: BrushRange | null, settled: boolean) => settled && setRange(range)} />
+```
+
+Zooming redraws through the real scales, so ticks are recomputed and marks stay sharp and at their drawn size. Nothing animates during a gesture. `chart.viewport` does the same from code: `zoomIn`, `zoomOut`, `reset`, `fit({ x: [a, b] })`, `brush({ x: [a, b] })`, `clearBrush`, and `domain` for what is on screen.
+
+`onBrush` reports data, not pixels: `{ x: [low, high] }` in numbers or dates, or the list of bands covered on a band axis, and `null` when cleared. It fires while dragging with `settled` false, then once with `settled` true. A click on the plot or the × button clears it. The selection stays on its data while the chart zooms. With `zoom` on too, drag brushes, the wheel zooms and shift-drag pans. `brush: true` runs along the same axes as `zoom`. On touch, a finger brushes from anywhere on the plot; with `zoom` on too, a second finger does not pinch.
+
+| Axis | Zoom | Brush reports |
+| --- | --- | --- |
+| Linear, power, sqrt, symlog, log | Domain narrows; log zooms in log space | `[number, number]` |
+| Time | Domain narrows, ticks follow the span | `[Date, Date]` |
+| Band, point | Bands widen; ticks outside the plot are dropped | Band names |
+
+`zoom: true` follows the categories when y is the band axis, so a horizontal bar chart widens its bars instead of cutting their length. Asking for a value axis on a bar chart (`ZoomAxis.XY`) does cut bars at the plot edge, since their baseline leaves the view.
+
+Not supported: a chart that cannot follow a scale says so with one `console.warn`, has `chart.viewport.supported === false`, and draws as if the option were off. That covers custom axes with no inverse or a fixed domain (`DetectionErrorCurve`'s probit and log scales; the y axes of `ManhattanPlot` and of a mel `SpectrogramChart`, which still zoom along x). `TileMapDensity` has no interactive zoom: its `zoom` option is the tile level, a non-number there is refused, and `brush` still works. Charts with a second value scale (`DualAxisChart`, `ParetoChart`, `TimeDomainDiffChart`, `FilterResponseChart`) and `ECGChart`'s fixed amplitude grid zoom along their first axis only, because the rest would otherwise drift from its marks. The y axis does not rescale to fit the visible x window. Hand-picked ticks stay while at least three are in view, then the scale ticks itself; a chart's own tick text gives way to d3's when zoom makes neighbouring labels equal. Layers in the margin, such as a second axis or end labels, stay out of the clip on that side.
+
+## Export
+
+Every chart saves itself as an image, a PDF, a spreadsheet or plain data. `chart.exportFormats` says what is available.
+
+```ts
+import { ExportFormat, PdfOrientation, PdfPageSize } from '@mstone6969/graph'
+
+chart.toSVG()                     // string, 2D only
+chart.toPNG({ scale: 3 })         // Promise<Blob>, scale defaults to 2
+chart.toCSV()                     // string, from chart.table()
+chart.toPDF({ pageSize: PdfPageSize.Letter, orientation: PdfOrientation.Landscape, title: 'Revenue', table: true }) // Promise<Blob>
+chart.toExcel({ image: true })    // Promise<Blob>, an .xlsx from chart.table()
+chart.download(ExportFormat.PNG, { filename: 'revenue.png' })
+```
+
+A `ref` on `<Graph>` gives the same methods, plus the live `chart`:
+
+```tsx
+const graph = useRef<GraphHandle>(null)
+
+<Graph ref={graph} of={BarChart} data={rows} />
+<button onClick={() => graph.current?.download(ExportFormat.SVG)}>Save</button>
+```
+
+Charts export finished: marks caught mid-animation are saved at their end state, rows appended but not yet painted are included, and the dimming of a hovered chart is left out. A smooth map zoom still in flight is saved where it has reached. `toStandaloneSVG`, `toPNG` and `download` wait for shapes a map loads on demand; `toSVG()` is synchronous and draws what is loaded now, so await one of those for a `geography` that may still be loading. A chart that is not mounted is drawn off-screen for the export, at its `width` and `height` or 640×400. Failures throw `ChartExportError`, whose `code` is an `ExportErrorCode`; an export never falls back to a blank file.
+
+- **SVG** carries computed styles, the theme surface as a real rectangle, and the map's current zoom as plain transforms. On-screen zoom buttons are left out. It is unavailable for 3D charts, which render to WebGL: `toSVG()` throws and `exportFormats` omits it.
+- **3D PNG** comes from the chart's renderer at the current camera, with any entry animation finished, and labels, title and legend drawn on top. A `scale` beyond the GPU's limit throws.
+- **CSV** needs rows in `table()`, and throws otherwise. Dates are ISO 8601. Text that a spreadsheet would run as a formula is prefixed with `'`. `download` adds the byte order mark Excel needs; `toCSV()` does not.
+- **Fonts.** `toSVG()` is synchronous and names the theme's font stack. `chart.toStandaloneSVG()`, `toPNG` and `download` also embed any `@font-face` the page declares for that font, when its stylesheet is readable. A font that cannot be fetched stays linked and the text draws in the fallback fonts.
+- **PDF is a picture.** `toPDF` places the chart on the page as a PNG, on 2D and 3D charts alike, so its text cannot be selected and it pixelates when zoomed far in. `scale` defaults to 3. `table: true` adds `table()` as real text on pages after it. Built-in PDF fonts are Western European only, so other scripts are drawn as small pictures. Tables stop at 25,000 rows, and a cell wider than a column ends in an ellipsis.
+- **Excel needs rows.** `toExcel` writes `table()` to a real .xlsx with numbers as numbers, dates as dates in local time, and text as text. Cells starting with `=`, `+`, `-` or `@` are stored as text and never run. A chart without rows rejects with `ExportErrorCode.NoData`, and a chart with more rows than a worksheet holds does not list it. `image: true` adds a sheet holding the chart.
+- **PDF and Excel load on use.** Their code, and `pdf-lib` and `fflate`, are dynamic imports, so a chart that never calls them keeps them out of your main bundle. If the load fails, the call rejects with `ExportErrorCode.Unavailable`.
+- **Web map tiles.** `toSVG()` keeps tiles as links, so that file needs the network. `toStandaloneSVG()`, `toPNG` and `download` fetch every tile and embed it. The tile server must send `Access-Control-Allow-Origin`: if any tile cannot be read within 20 seconds, they reject with `ExportErrorCode.Tainted` and name the tile, rather than save a map with holes. Without `tiles`, a slippy map has nothing to fetch and always exports.
+
+## Keyboard
+
+2D charts take `keyboard` to reach their data marks without a mouse. It is off by default. On, the chart is one tab stop however many marks it has.
+
+| Key | Action |
+| --- | --- |
+| Arrows | Move between marks. Left and Right stay in a series, Up and Down change series. A Line has one mark per x, so there Down also moves along x. Without series, or in a free layout such as a map or scatter, arrows go the way they point. |
+| Shift and an arrow | Step through the series in data order, so every mark is reachable, including marks stacked on the same spot |
+| Home, End, Page Up, Page Down | First, last, or a tenth of the way through the series |
+| Enter, Space | Select the mark, as a click does, so `onSelect` fires and a drill map drills |
+| Escape | Leave the marks. The next arrow picks up where you were |
+
+The current mark gets a ring, the hover tooltip and an `aria-live` reading of that tooltip. `tooltip: false` removes the box and keeps the ring and the reading, because the reading is the only way a screen reader user gets the value. Marks reached are the ones given to `ctx.hover`, and on a zoomed chart only those inside the plot. A chart with no such marks, as with the signal and massive charts, the recurrence plot, crossfilter histograms or empty data, stays `role="img"` with no tab stop. Exports leave all of this out. 3D charts ignore the option.
+
+With marks to reach, the svg becomes `role="application"`. `img` hides its children and is not a keyboard target, and a screen reader in browse mode would otherwise use the arrow keys itself. DOM focus stays on the svg and the cursor moves over the marks, so a redraw cannot lose focus and the marks are never written to.
+
+## Large data
+
+SVG slows down past about 10,000 marks, so `src/charts/massive` draws to a canvas under a transparent SVG. Axes, legend, title, zoom, brush and annotations work as on any x/y chart. All three stayed interactive at 1,000,000 points in WebKit.
+
+```tsx
+import { Graph, MassiveDecimation, MassiveLineChart, MassiveScatterChart, ZoomAxis } from '@mstone6969/graph'
+
+<Graph of={MassiveScatterChart} data={rows} zoom={ZoomAxis.XY} />
+<Graph of={MassiveLineChart} data={{ x: times, y: values, time: true }} decimation={MassiveDecimation.Lttb} zoom />
+```
+
+- `MassiveScatterChart` draws dots while they read and a density raster once they overplot; zooming in brings the dots back. `display` forces either.
+- `MassiveLineChart` keeps every peak with `MassiveDecimation.MinMax`, the default. `Lttb` keeps the shape with fewer points. `None` draws every point, and is not responsive at 1M.
+- `MassiveDensityChart` is always the raster, with `bin` and `densityScale`.
+
+Columnar data (`{ x, y, series, names, time }` with typed arrays) is the cheapest input. Rows work too and can be appended; columnar data cannot. With no SVG marks, `keyboard` has nothing to reach.
+
+## Styling
+
+`chartStyle` styles any chart from the shared layer. Unset keys leave the chart as drawn. Colours take any CSS colour, or a theme token name such as `good`.
+
+```tsx
+import { Bar, Line, ScaleKind, StrokeDash } from '@mstone6969/graph'
+
+<Line data={rows} chartStyle={{ seriesColors: { Paid: '#0072b2' }, strokeWidth: 1.5, strokeDash: StrokeDash.Dashed, opacity: 0.8 }} />
+<Bar data={rows} yScaleType={ScaleKind.Sqrt} aspectRatio={2} chartStyle={{ colors: ['#7a5230', '#3f7c85'], fontSize: 1.2 }} />
+```
+
+- Colour: `colors`, `seriesColors`, `sequential`, `diverging`.
+- Marks: `strokeWidth`, `strokeDash`, `strokeCap`, `strokeJoin`, `opacity`, `markSize`, `edges`. SVG marks; `opacity` also reaches 3D materials.
+- Text: `fontSize`, `fontFamily`.
+- 3D: `wireframe`, `antialias`, `pixelRatio`.
+- Beside `chartStyle`: `aspectRatio` on every chart, `xScaleType` and `yScaleType` on SVG charts with x and y axes.
+- `chart.renderer` says what draws the marks: `RenderType.Svg`, `Canvas` or `WebGL`. Canvas charts take colour and text styling only.
+
+The playground offers each of these where it changes the chart in front of you. See the Styling page of the docs.
+
+## Specialist charts
+
+Every chart here takes the shared options, and it has a component and a `GraphType` member.
+
+**Business.** `TornadoChart` ranks drivers by how far each moves an output around the base case. `SparkBar` draws word-sized bars, one aligned row per series, including win-loss tiles.
+
+```tsx
+import { SparkBar, SparkBarForm, TornadoChart } from '@mstone6969/graph'
+
+<Graph of={TornadoChart} data={[{ driver: 'Price', low: 80, high: 130, base: 100 }, { driver: 'Volume', low: 90, high: 115, base: 100 }]} />
+<Graph of={SparkBar} data={rows} x="week" y="net" series="region" form={SparkBarForm.WinLoss} />
+```
+
+**Genomics.** `CircosPlot` draws a genome as a ring with data tracks and links, and `GenomeIdeogram` draws banded chromosomes with annotations. `GenomeSamples.cancerGenome(seed)` shows the data shape, and `bandFields`, `trackFields`, `linkFields` and `annotationFields` remap your columns.
+
+```tsx
+import { CircosPlot, GenomeIdeogram, GenomeIdeogramLayout, GenomeSamples } from '@mstone6969/graph'
+
+const genome = GenomeSamples.cancerGenome(1) // { bands, tracks, links, annotations }
+
+<Graph of={CircosPlot} data={genome} />
+<Graph of={GenomeIdeogram} data={genome} layout={GenomeIdeogramLayout.Karyogram} />
+```
+
+**Earth science.** `Hydrograph` plots discharge under rainfall and separates baseflow, in m³/s, mm and km²: pass your catchment's `area`, because the event ends and phi-index depend on it. `TernaryContour` contours a surface over three-part compositions.
+
+```tsx
+import { BaseflowMethod, Hydrograph, TernaryContour, TernarySurface } from '@mstone6969/graph'
+
+<Graph of={Hydrograph} data={rows} time="time" flow="flow" rain="rain" baseflow={BaseflowMethod.Eckhardt} area={60} />
+<Graph of={TernaryContour} data={rows} a="sand" b="clay" c="silt" value="porosity" surface={TernarySurface.ScheffeQuadratic} />
+```
+
+**Demography.** `LexisDiagram` shades rates on an isometric calendar-by-age plane, so cohorts run at 45 degrees at any size. `Nomogram` is a parallel-scale alignment chart with a live isopleth: drag a handle, use the arrow keys, or call `chart.place(rail, value)` and read `chart.solution`. Pass a `NomogramLaw` for your own equation.
+
+```tsx
+import { LexisCellKind, LexisDiagram, Nomogram, NomogramLawKind, type NomogramSolution } from '@mstone6969/graph'
+
+<Graph of={LexisDiagram} data={rows} cells={LexisCellKind.AgePeriod} />
+<Graph of={Nomogram} data={rows} law={NomogramLawKind.Fagan} onSolve={(solution: NomogramSolution) => console.log(solution)} />
+```
+
+**Structure.** `TournamentBracket` derives its pairings from seeds and scores. `DependencyMatrix` and `UmlClassDiagram` take `GraphData`. `MareyChart` plots timetables, with stations spaced by real distance; `time` and `depart` take dates or `HH:MM` clock times, including GTFS times past `24:00`.
+
+```tsx
+import { DependencyMatrix, DsmOrder, MareyChart, TournamentBracket, TournamentElimination, UmlClassDiagram, UmlDirection } from '@mstone6969/graph'
+
+<Graph of={TournamentBracket} data={results} elimination={TournamentElimination.Double} />
+<Graph of={DependencyMatrix} data={graph} order={DsmOrder.Partition} />
+<Graph of={UmlClassDiagram} data={graph} direction={UmlDirection.LeftRight} />
+<Graph of={MareyChart} data={timetable} trip="train" encounters />
+```
+
+**Market profile.** `MarketProfileChart` prints a letter for each time bracket at every price traded, with the point of control, the value area and the initial balance. It joins the financial module and reads the usual `date`, `open`, `high`, `low` and `close` columns.
+
+```tsx
+import { MarketProfileChart, TpoBracket, TpoForm } from '@mstone6969/graph'
+
+<Graph of={MarketProfileChart} data={bars} form={TpoForm.Blocks} bracket={TpoBracket.Hour} />
+```
+
+## Applied charts
+
+These take the shared options too, and each has a component and a `GraphType` member. Their built-in samples are synthetic, so `meta.sample` shows the data shape and nothing more.
+
+**Software diagrams.** `SequenceDiagram` orders messages between lifelines, with activation bars replayed from the calls, `alt`, `opt` and `loop` frames, and notes. `EntityRelationshipDiagram` takes one row per table column, as `information_schema` gives them, and derives crow's foot cardinality from nullability and keys. `ArchitectureDiagram` draws a C4 model at the context, container or component level from one data set. `NetworkTopologyDiagram` lays out routers, switches, servers, clouds and databases by tier, ring or force. `LogicGateDiagram` simulates a circuit in 0, 1 and X, and colours each wire by its state.
+
+```tsx
+import { ArchitectureDiagram, ArchitectureLevel, EntityRelationshipDiagram, ErDetail, LogicGateDiagram, LogicSymbolStyle, NetworkTopologyDiagram, SequenceDiagram, SequenceNumbering, TopologyArrangement } from '@mstone6969/graph'
+
+<Graph of={SequenceDiagram} data={[{ from: 'Web', to: 'API', label: 'POST /order', kind: 'sync' }, { from: 'API', to: 'Web', label: '201', kind: 'return' }]} numbering={SequenceNumbering.Nested} />
+<Graph of={EntityRelationshipDiagram} data={columns} table="table_name" column="column_name" detail={ErDetail.Keys} /> // rows: { table, column, type, key, references, nullable }
+<Graph of={ArchitectureDiagram} data={{ nodes, links }} level={ArchitectureLevel.Containers} /> // nodes: { id, name, kind, parent, technology, description, external }
+<Graph of={NetworkTopologyDiagram} data={{ nodes, links }} arrangement={TopologyArrangement.Radial} /> // nodes: { id, name, kind, address }
+<Graph of={LogicGateDiagram} data={{ gates, wires }} symbols={LogicSymbolStyle.Iec} /> // gates: { id, type, label, value }, wires: { from, to }
+```
+
+**Machine learning.** All six plot results you already have: none of them trains a model. `LearningCurveChart` takes long rows of `epoch`, `run`, `split` and `value`, and draws the mean per split with a spread band, the best epoch and the overfitting gap. `ElbowPlot` marks the bend by Kneedle, the L method, chord distance or second difference, and says so when a curve has none. `DecisionBoundaryChart` contours your classifier's probabilities over two features. `FeatureImportanceChart` ranks scores, with whiskers and the tail folded into Other. `PartialDependencePlot` sweeps your `predict` function over background rows, or reads precomputed curves. `AttentionHeatmap` draws weights as given, with target tokens as rows, and `chart.check()` reports rows that do not sum to 1 instead of renormalising them.
+
+```tsx
+import { AttentionHeadView, AttentionHeatmap, DecisionBoundaryChart, ElbowMethod, ElbowPlot, FeatureImportanceChart, FeatureImportanceSign, LearningCurveChart, OverfitShading, PartialDependencePlot, RunSpread, SilhouetteView } from '@mstone6969/graph'
+
+<Graph of={LearningCurveChart} data={rows} x="epoch" y="value" run="run" split="split" validationSplit="val" spread={RunSpread.Confidence95} gap={OverfitShading.AfterBest} />
+<Graph of={ElbowPlot} data={rows} x="k" y="inertia" method={ElbowMethod.Kneedle} silhouetteView={SilhouetteView.Panel} /> // rows: { k, inertia, silhouette }
+<Graph of={DecisionBoundaryChart} data={{ points, predict: (x, y) => model.proba(x, y) }} /> // predict returns { class: probability } or a label
+<Graph of={FeatureImportanceChart} data={rows} x="feature" y="gain" sign={FeatureImportanceSign.Value} top={12} />
+<Graph of={PartialDependencePlot} data={background} x="age" predict={model.predict} />
+<Graph of={AttentionHeatmap} data={{ source, target, heads: [{ name: 'Head 1', weights }] }} headView={AttentionHeadView.SmallMultiples} />
+```
+
+**Strategy and research frameworks.** `SwotMatrix` and `RaciMatrix` fit wrapped text to their cells and count what they cannot show. `RaciMatrix` audits every task for exactly one Accountable and at least one Responsible: read `chart.plan.flagged`. `VanWestendorpChart` finds the four price points from one row per respondent, and `curves` picks between the two published PMC and PME conventions. `NpsGauge` takes 0 to 10 answers. `AnsoffMatrix` places initiatives by market and product. `PerceptualMap` plots two rated attributes with fitted property vectors, or a Gabriel biplot.
+
+```tsx
+import { AnsoffDisplay, AnsoffMatrix, NpsGauge, PerceptualMap, RaciMatrix, SwotLayout, SwotMatrix, VanWestendorpChart, VanWestendorpCurves } from '@mstone6969/graph'
+
+<Graph of={SwotMatrix} data={[{ quadrant: 'S', item: 'Loyal regulars' }]} layout={SwotLayout.Rows} />
+<Graph of={RaciMatrix} data={[{ task: 'Launch', role: 'Lead', assignment: 'A/R' }]} grouping load />
+<Graph of={VanWestendorpChart} data={rows} tooCheap="q1" cheap="q2" expensive="q3" tooExpensive="q4" curves={VanWestendorpCurves.Direct} />
+<Graph of={NpsGauge} data={rows} score="score" />
+<Graph of={AnsoffMatrix} data={rows} item="initiative" display={AnsoffDisplay.Bars} risk />
+<Graph of={PerceptualMap} data={rows} name="brand" x="price" y="quality" xDomain={[1, 7]} yDomain={[1, 7]} vectors />
+```
+
+**Life science.** `MaPlot` computes M and A with median or loess normalisation and BH or Bonferroni calls, from red and green channels, precomputed values or a DESeq2-style `baseMean`. `OncoPrint` reads cBioPortal and MAF alteration terms, with a row for every profiled sample so that frequencies keep the whole cohort as the denominator. `PedigreeChart` follows standard genetics notation. Status columns are boolean-like, so map PED affection codes first: in PED, 1 means unaffected. `RamachandranPlot` judges each residue against the MolProbity Top8000 regions for its class. The regions are simplified polygons, so use MolProbity itself for formal validation.
+
+The Ramachandran regions are adapted from the Richardson Lab Top8000 data (Williams et al. 2018, Protein Science 27:293-315), used under CC BY 4.0. The chart's default subtitle carries this credit, so keep it, or credit the data yourself, if you replace the subtitle.
+
+```tsx
+import { MaNormalization, MaPlot, OncoPrint, OncoSort, PedigreeCarrierMark, PedigreeChart, RamachandranPanel, RamachandranPlot } from '@mstone6969/graph'
+
+<Graph of={MaPlot} data={rows} gene="gene" red="R" green="G" pvalue="p" normalization={MaNormalization.Loess} />
+<Graph of={OncoPrint} data={maf} sample="Tumor_Sample_Barcode" gene="Hugo_Symbol" alteration="Variant_Classification" sort={OncoSort.Memo} />
+<Graph of={PedigreeChart} data={people} carrierMark={PedigreeCarrierMark.Dot} showKey /> // rows: { id, father, mother, sex, affected, carrier, deceased, proband }
+<Graph of={RamachandranPlot} data={residues} panel={RamachandranPanel.Glycine} /> // rows: { phi, psi, residue, nextResidue, omega, label }
+```
+
+`<Graph>` and components keep `id` and `style` for themselves, so rename `PedigreeChart`'s id column, or set `HovmollerDiagram`'s `style`, through an instance.
+
+**Rotation, waves and buildings.** `RelativeStrengthRotation` joins the financial module. It tracks relative strength and its momentum through four quadrants, a method developed by Julius de Kempenaer. His exact formula is proprietary, so `RotationMethod` offers two named approximations that will not match licensed software, or you can name your own computed columns with `ratio` and `momentum`. It does not reproduce licensed RRG output. `HovmollerDiagram` joins the earth science module and maps a field against time and longitude or latitude, with stated or fitted phase-speed guides. `FloorPlanMap` joins the maps and draws rooms in plain plan units, with one colour scale across floors, door swings, asset markers and on-screen floor buttons.
+
+```tsx
+import { FloorDoorSwing, FloorPlanMap, HovmollerDiagram, HovmollerGuides, HovmollerSection, RelativeStrengthRotation, RotationMethod } from '@mstone6969/graph'
+
+<Graph of={RelativeStrengthRotation} data={prices} benchmarkSymbol="SPX" method={RotationMethod.ZScore} tail={10} /> // rows: { date, series, close }
+<Graph of={HovmollerDiagram} data={rows} section={HovmollerSection.Longitude} guides={HovmollerGuides.Fitted} /> // rows: { time, longitude, latitude, value }
+<Graph of={FloorPlanMap} data={{ rooms, doors: [{ from: 'Lab', to: 'Hall', level: 2, swing: FloorDoorSwing.Left }], assets }} level={2} zoom /> // rooms: { name, level, value, points }
+```
+
+## Maps
+
+Every 2D map takes `zoom` for drag, wheel, double click and on-screen buttons. `chart.viewport` does the same from code (`zoomIn`, `zoomOut`, `reset`, `fit`).
+
+Region maps take `geography` to load bundled shapes on demand, so a page only downloads what it draws, then `rows` and `join` to attach your values. Shapes carry `fips`, `code` (states) and `name`.
+
+```tsx
+import { GeoLayer, UsCountyMap, ChoroplethMap } from '@mstone6969/graph'
+
+<Graph of={UsCountyMap} rows={rows} /> // rows: [{ fips: '48201', value: 12 }]
+<Graph of={ChoroplethMap} geography={GeoLayer.World50m} rows={rows} join="name" zoom />
+```
+
+`GeoLayer.World110m` swaps to 1:50m outlines by itself once you zoom in. `GeoAtlas` loads the same layers directly.
+
+`DrillDownMap` opens a region into what it contains. With no setup it goes country, state, county; pass `children` for your own levels. One `rows` table can hold every level.
+
+`SlippyPointMap` and `SlippyRegionMap` are Web Mercator maps. They draw their own land and make no network requests unless you pass `tiles`:
+
+```tsx
+import { OPEN_STREET_MAP, SlippyPointMap } from '@mstone6969/graph'
+
+<Graph of={SlippyPointMap} data={places} tiles={OPEN_STREET_MAP} />
+```
+
+`TileSource` requires `attribution`, and the map prints it. The public OpenStreetMap server has a usage policy: use your own provider for production traffic.
+
+## How it fits together
+
+**Abstract classes** hold everything charts share. You only write the part that differs.
+
+```
+Chart                  options, lifecycle, sizing, theme, palette, tooltip
+├── Chart2D            SVG root, title, legend. You implement draw()
+│   ├── CartesianChart axes and grid. You implement scales() and plotMarks()
+│   └── RadialChart    centred polar frame. You implement drawRadial()
+└── Chart3D            renderer, camera, lights, orbit, picking. You implement build()
+```
+
+**Concrete classes** extend one of those. When several classes in a module share logic, the module adds its own abstract class between them.
+
+**Enums** name every option value, so `Orientation.Horizontal` is checked by the compiler and shows up in autocomplete. Shared ones (`ChartFamily`, `Dimension`, `DataShape`, `StackMode`, `CurveKind`, `ScaleKind`, `SymbolKind`, `LegendPosition`, `ThemeMode`) live in core. Modules export their own for chart-specific choices.
+
+**Interfaces** are the contracts. `ChartOptions` is what every chart accepts, each class extends it with its own options, `ChartMeta` describes a class, `ChartClass` is any constructor with that `meta`, and `ChartType` is one class plus one combination of values. Data shapes (`Row`, `TreeNode`, `GraphData`, `MatrixData`, `GridData`, `VolumeData`) are interfaces too.
+
+**The variant system** ties these together. Every class declares `static readonly meta`, and `meta.variants` maps option keys to values, with the first value as the default:
+
+```ts
+variants: {
+  orientation: [Orientation.Vertical, Orientation.Horizontal],
+  stack: [StackMode.None, StackMode.Stacked, StackMode.Normalized],
+}
+```
+
+`VariantSpace` expands that into the cartesian product, and `meta.valid(values)` prunes combinations in which an axis would have no effect. Moved axes form the id, so the type above with both axes changed is `bar.horizontal.stacked`. `ChartRegistry` holds the result as `catalog`:
+
+```ts
+import { catalog, ChartFamily, Dimension, GraphType } from '@mstone6969/graph'
+
+catalog.find({ text: 'stacked', family: ChartFamily.Comparison, dimension: Dimension.Two })
+const [type] = catalog.find({ text: 'horizontal stacked', family: ChartFamily.Comparison })
+const chart = catalog.create(type, { data: rows })
+catalog.create(GraphType.BarChart, { data: rows })
+```
+
+## Adding a chart
+
+1. Create one class in its own file under `src/charts/<module>/`, with its options interface beside it. Extend the abstract that fits.
+2. Declare `static readonly meta`: a globally unique kebab-case `id`, `name`, one-sentence `description`, `family`, `dimension`, `shape`, a `sample` built from `SampleData`, and `variants`.
+3. Draw through the context so animation, tooltips and themes work: `ctx.marks` for joins, `ctx.set` for animated attributes, `ctx.hover` on data marks, `ctx.palette` for colour.
+4. Re-export it from the module's `index.ts` and list it in `<module>Catalog`.
+
+```ts
+import { scaleBand, scaleLinear, type ScaleBand, type ScaleLinear } from 'd3'
+import { CartesianChart, ChartFamily, DataShape, Dimension, type CartesianOptions, type Context2D, type Row } from '../../core'
+import { SampleData } from '../../data'
+
+export interface DotRankOptions extends CartesianOptions<Row[]> { x?: string; y?: string; rule?: boolean }
+interface DotRankAxes { x: ScaleBand<string>; y: ScaleLinear<number, number> }
+
+/** Ranks categories with a dot, for when bars would be too heavy. */
+export class DotRankChart extends CartesianChart<DotRankOptions, DotRankAxes> {
+  static readonly meta = {
+    id: 'dot-rank', name: 'Dot rank', family: ChartFamily.Comparison, dimension: Dimension.Two, shape: DataShape.Table,
+    description: 'Ranks categories by value with a single dot per category.',
+    sample: (seed: number) => SampleData.categories(seed, 7, 1),
+    variants: { rule: [false, true] },
+  }
+
+  protected override defaults() { return { x: 'category', y: 'value', rule: false } }
+
+  protected scales(ctx: Context2D): DotRankAxes {
+    const { data, x, y } = this.options
+    const top = Math.max(0, ...data.map((row) => +row[y!]!))
+    return {
+      x: scaleBand(data.map((row) => String(row[x!])), [0, ctx.plot.width]).padding(0.3),
+      y: scaleLinear([0, top], [ctx.plot.height, 0]).nice(),
+    }
+  }
+
+  protected plotMarks(ctx: Context2D, axes: DotRankAxes): void {
+    const { data, x, y, rule } = this.options
+    const center = (row: Row) => axes.x(String(row[x!]))! + axes.x.bandwidth() / 2
+    const rules = ctx.marks('rules', 'line', rule ? data : [], (row) => String(row[x!])).attr('stroke', ctx.theme.axis).attr('stroke-width', 2)
+    ctx.set(rules, { x1: center, x2: center, y1: axes.y(0), y2: (row) => axes.y(+row[y!]!) })
+    const dots = ctx.marks('dots', 'circle', data, (row) => String(row[x!])).attr('fill', ctx.palette.color('value'))
+    ctx.set(dots, { cx: center, cy: (row) => axes.y(+row[y!]!), r: 6 }, { r: 0 }, 20)
+    ctx.hover(dots, (row) => ({ title: String(row[x!]), rows: [[y!, +row[y!]!]] }))
+  }
+}
+```
+
+The full rules are in [AUTHORING.md](AUTHORING.md). A chart is finished when `yarn vitest run src/charts/<module>` passes and `yarn sheet <module>` renders it correctly in light and dark.
+
+## Site
+
+The site is at <https://malcolmston.github.io/graph/>. It covers the 628 chart classes with a page per chart, a family page for each of the 21 families, guides and reference docs, and a playground that runs TSX in the browser. Sample data is labelled as such. `gallery/` holds its source, and `.github/workflows/pages.yml` deploys it on every push to `main`.
+
+```sh
+yarn install         # once
+yarn dev             # local site, on the port Vite prints
+yarn build:gallery   # writes dist-gallery/
+yarn generate:docs   # rebuilds gallery/docs/generated after a change to src
+yarn e2e             # checks dist-gallery in WebKit, screenshots in .cache/gallery/
+yarn e2e:site        # every docs page, family and chart link in WebKit, screenshots in .cache/site/
+yarn e2e:animated    # every 2D class settles on its static render
+yarn e2e:maps        # map input in WebKit, including tiles
+yarn e2e:live        # streaming soak and fidelity sweep
+yarn e2e:keyboard    # real key presses
+yarn e2e:zoom        # real wheel, drag and keyboard
+yarn e2e:export      # real exports in WebKit, files in .cache/export/
+yarn e2e:massive     # draw times at 100k and 1M points, report as JSON
+```