@mstone6969/graph 0.0.0-stage → 0.1.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,383 @@
-# 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 gallery](https://malcolmston.github.io/graph/)
+
+**642 chart classes (521 d3/SVG, 121 three.js/WebGL) expand to 42,928 chart types (35,606 2D, 7,322 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,928 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 550 KB before gzip, `BarChart` about 370 KB, and `GraphType` about 20 KB. `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: `Histogram` gives `HistogramGraph`, and each gallery page 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 fills its parent and follows resizes.
+
+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 387 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) and charts that lay out their own marks (`MarimekkoBar`). `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`, `ParetoBar`, `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 or as data. `chart.exportFormats` says what is available.
+
+```ts
+import { ExportFormat } 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.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.
+- **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. 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 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.
+
+## 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} />
+```
+
+## 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.
+
+## Gallery
+
+`gallery/` is a browsable catalog of every type: search, filters, a live chart per type, a control for each variant axis, a copyable snippet and the data table.
+
+```sh
+yarn dev             # local gallery
+yarn build:gallery   # writes dist-gallery/
+yarn e2e             # checks dist-gallery in WebKit, screenshots in .cache/gallery/
+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
+```