@fundar/data-chart-telling 0.0.64 → 1.0.0

package/docs/geo.md

@@ -0,0 +1,151 @@
+# Maps
+
+`GeoPlot` draws GeoJSON or TopoJSON as a map. It shares chrome, `tooltip`, `legend`, `segments`, `markers`, `timeline`, `facet` and `margins` with the other plots; instead of `x`/`y` axes it has a projection (`coordinates`).
+
+```svelte
+<GeoPlot
+	{width}
+	{height}
+	data={provinces}
+	featureId={(f) => String(f.properties?.nombre)}
+	color={(f) => Number(f.properties?.population)}
+	scales={{ color: { scheme: 'blues' } }}
+	coordinates={{ projection: { type: argentinaBicontinental } }}
+	tooltip={{ format: (f) => String(f.properties?.nombre) }}
+/>
+```
+
+![A choropleth map](images/plots-geo.png)
+
+## Data
+
+| Prop           | Meaning                                                                                                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `data`         | A GeoJSON `FeatureCollection`, an array of `Feature`s, or a TopoJSON `Topology`                                                                                                                              |
+| `object`       | Required for a `Topology`: the key under `topology.objects` to draw. Needs the optional `topojson-client` package                                                                                            |
+| `featureId`    | Accessor for each feature's stable id. Default: `feature.id ?? properties.id ?? properties.name`. It is the key of `segments`, and identifies features in hover and click                                    |
+| `color`        | `(feature) => number \| undefined` - the value of a choropleth. Features without one use `styles.fill` or their `segments`                                                                                   |
+| `excludeParts` | `(part, feature) => boolean`, where `part` is `{ centroid, geometry }` - drops geometry parts from drawing and hover (a distant territory drawn in an inset instead). `segments` still apply to what remains |
+
+## Styles
+
+`styles` for a map:
+
+| Field                   | Meaning                                                                                                                            |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `fill`, `fillOpacity`   | Base fill of features with no choropleth value or segment                                                                          |
+| `stroke`, `strokeWidth` | Base outline                                                                                                                       |
+| `tileLayer`             | A raster basemap under the features: `{ url, attribution, opacity, minZoom, maxZoom, tileSize }`. Mercator-family projections only |
+| `onFeatureClick`        | `(feature, event) => void`                                                                                                         |
+| `frame`                 | A border around the map                                                                                                            |
+
+## Scales
+
+`scales.color` configures the choropleth (domain, scheme, pivot, unknown - see [Scales](scales.md#color)); `scales.length` configures `vector` markers. A map has no `x`/`y`.
+
+## Segments
+
+Per-feature styling, keyed by feature id, with `'default'` as the baseline for every feature:
+
+```svelte
+<GeoPlot
+	...
+	segments={{
+		default: [{ styles: { fillOpacity: 0.7 } }],
+		argentina: [{ styles: { fill: '#3b82f6' } }]
+	}}
+/>
+```
+
+Style fields: `fill`, `fillOpacity`, `stroke`, `strokeWidth`.
+
+## Coordinates
+
+`coordinates` bundles the projection and the gestures.
+
+| Field        | Meaning                                                                                                                                                                                                                                                                                                                       |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `projection` | A name - `'equal-earth'` (default), `'mercator'`, `'orthographic'`, `'albers'`, `'albers-usa'`, `'azimuthal-equal-area'`, `'conic-conformal'`, `'equirectangular'`, `'stereographic'`, `'transverse-mercator'` and the other svelteplot projections - or an object `{ type, rotate, center, parallels, inset, clip, domain }` |
+| `zoom`       | `true` or `{ min, max, initial }`: wheel and pinch zoom                                                                                                                                                                                                                                                                       |
+| `pan`        | `true`: drag to pan a flat projection                                                                                                                                                                                                                                                                                         |
+| `rotate`     | `true`: drag to spin an `'orthographic'` globe                                                                                                                                                                                                                                                                                |
+| `camera`     | A declarative viewpoint (below)                                                                                                                                                                                                                                                                                               |
+
+`projection.type` can also be a custom factory. The package ships `argentinaBicontinental`, a projection fitted to Argentina's full territory (the mainland, the Antarctic sector and the islands):
+
+```svelte
+<GeoPlot ... coordinates={{ projection: { type: argentinaBicontinental } }} />
+```
+
+`projection.domain` fits the projection to a GeoJSON object (`'data'` fits to the plot's own `data`); it is also what sizes `'identity'` projections.
+
+### Camera
+
+`coordinates.camera` frames a target and animates to a new one when it changes:
+
+```svelte
+<GeoPlot
+	...
+	coordinates={{
+		projection: 'mercator',
+		camera: {
+			target: { features: ['Neuquén', 'Río Negro', 'Chubut'] },
+			zoom: 1,
+			anchor: 'middle-middle',
+			padding: 24,
+			transition: { duration: 750, easing: 'cubicOut' }
+		}
+	}}
+/>
+```
+
+![The camera framing three provinces](images/geo-camera.png)
+
+- `target`: `{ features: [ids] }`, `{ center: [lon, lat] }` or `{ bounds: geoJsonObject }`.
+- `zoom`: multiplier on the tight fit (for `center`, the pixel scale itself).
+- `anchor` and `padding`: where the framed target lands in the plot, as for insets.
+- `transition`: `duration` (ms), `easing`, a live `progress` (`0`-`1`) to drive it yourself, and `direction` (`'shortest'` or `'longest'` rotation, orthographic only).
+
+## Markers
+
+Map markers go in `markers`, like on other plots. `dot` and `text` work as on any plot; the map-specific ones:
+
+| `type`          | Draws                                                                                                                                                           |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `graticule`     | Longitude and latitude gridlines: `step`, `stepX`, `stepY`, `behind`                                                                                            |
+| `sphere`        | The globe outline (for `'orthographic'`): `styles`, `behind`                                                                                                    |
+| `vector`        | Arrows or spikes at points: `data`, `x`, `y`, `length`, `rotate`, `shape` (`'arrow'`, `'spike'`, `'arrow-filled'`), `anchor`                                    |
+| `link`          | Lines between point pairs: `data`, `x1`, `y1`, `x2`, `y2`, `curve` (`'auto'` traces great-circle arcs, `'linear'`)                                              |
+| `contour`       | Contour lines of a scalar field: `data` with `x`, `y`, `value`, or a sampler function; `thresholds`, `fill`, `stroke`, `clip` (`'land'` or `'ocean'`), `behind` |
+| `inset`         | A small, separately projected map anchored to an edge of the plot (see below)                                                                                   |
+| `geo-hover`     | Restyles the hovered feature: `styles` (an area style)                                                                                                          |
+| `geo-component` | Your own Svelte component                                                                                                                                       |
+
+### Insets
+
+An `inset` draws part of the map (or other data) in its own small panel, such as an island or a distant territory:
+
+```svelte
+<GeoPlot
+	...
+	excludeParts={(part) => part.centroid[0] > 100}
+	markers={[
+		{
+			type: 'inset',
+			location: 'bottom-right',
+			features: ['hawaii'],
+			projection: 'mercator',
+			width: 0.25,
+			height: 0.25,
+			margin: 8,
+			tooltip: { format: (f) => String(f.properties.name) }
+		}
+	]}
+/>
+```
+
+`location` is one of the 17 anchors (`'top-left'`, `'bottom-right'`, `'middle-left'`, ...); `features` filters by id from the plot's `data` (or give the inset its own `data`); `featurePartsFilter` narrows to geometry parts; `width` and `height` are fractions of the plot; an inset always fits its own content.
+
+## Tooltip and hover
+
+`tooltip` works as on other plots with the hovered feature as the row (`format: (feature) => string`, or a `content` snippet). Add `{ type: 'geo-hover' }` for an in-map highlight. Hover matches the browser's own SVG hit-testing, so a feature is hovered where it is drawn.

package/docs/getting-started.md

@@ -0,0 +1,79 @@
+# Getting started
+
+## Install
+
+```bash
+pnpm add @fundar/data-chart-telling svelte svelteplot
+```
+
+- `svelte` ^5 and `svelteplot` ^0.14 are peer dependencies.
+- `topojson-client` is an optional peer, needed only to feed [GeoPlot](geo.md) a TopoJSON `Topology`.
+- The package ships `.svelte` files, so the app builds with `@sveltejs/vite-plugin-svelte` or SvelteKit.
+- Import everything from the package root: `import { LinePlot } from '@fundar/data-chart-telling'`.
+
+## A first plot
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+
+	const rows = [
+		{ year: 2020, region: 'North', value: 3.1 },
+		{ year: 2021, region: 'North', value: 3.8 },
+		{ year: 2020, region: 'South', value: 2.2 },
+		{ year: 2021, region: 'South', value: 2.9 }
+	];
+</script>
+
+<LinePlot width={720} height={400} data={rows} x="year" y="value" color="region" />
+```
+
+![A line plot with one line per region](images/first-plot.png)
+
+- `data` is an array of flat rows; `x` and `y` name the fields that position each row.
+- `color="region"` splits the rows into one series per region and gives each its own color.
+- `width` and `height` are pixels.
+
+Everything else is an optional prop: `title`, `subtitle`, `caption`, `legend`, `tooltip`, `scales`, `styles`, `markers`, `timeline`, `facet`. See [Concepts](concepts.md) for the full picture.
+
+## Sizing a plot to its container
+
+A plot draws at the pixel size it is given. To fill a container or the window, bind the container's size and render the plot once both are known:
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+
+	let { rows } = $props();
+	let width = $state(0);
+	let height = $state(0);
+</script>
+
+<div style="width: 100%; height: 100vh" bind:clientWidth={width} bind:clientHeight={height}>
+	{#if width > 0 && height > 0}
+		<LinePlot {width} {height} data={rows} x="year" y="value" color="region" />
+	{/if}
+</div>
+```
+
+The runnable version is [examples/ResponsiveLine.svelte](../examples/ResponsiveLine.svelte). Inside a [composer](composer.md) cell, a plot takes the cell's size and needs no `width` or `height`.
+
+## Getting data in
+
+A plot reads plain JavaScript values. Load a CSV or JSON with whatever the app already uses, convert dates to `Date` objects (UTC midnight avoids timezone shifts) and numbers to `number`, then pass the rows:
+
+```ts
+const rows = parsed.map((r) => ({
+	date: new Date(Date.UTC(r.year, r.month - 1, 1)),
+	division: r.division,
+	index: Number(r.index)
+}));
+```
+
+Sort rows by their x field when a line should connect them in order, or add a `sort` [transform](transforms-and-statistics.md).
+
+## Next steps
+
+- [Concepts](concepts.md) - how rows, series and channels fit together.
+- [Plots](plots.md) - pick the plot kind.
+- [examples/](../examples/) - small runnable components for the common cases.

package/docs/legend.md

@@ -0,0 +1,106 @@
+# Legend
+
+A plot builds its legend from what it draws: its series, the scales its channels use, and the segments and markers that name themselves. Nothing needs configuring for the common case.
+
+## The automatic legend
+
+`legend` is unset or `true` for the automatic legend, `false` for none. The automatic legend can have these sections:
+
+| Section            | Appears when                    | Content                                    |
+| ------------------ | ------------------------------- | ------------------------------------------ |
+| series (discrete)  | the plot has several series     | one item per series, in its color and mark |
+| color (continuous) | `color` is a continuous value   | a ramp with its min and max                |
+| opacity            | `opacity` is a continuous value | a ramp fading across the opacity range     |
+| size               | `r` is mapped                   | a few dots at representative values        |
+| symbol             | `symbol` is mapped              | each category next to its shape            |
+
+Segments and markers join the series section when they carry a `legend` label:
+
+```svelte
+<LinePlot
+	...
+	segments={{
+		default: [
+			{
+				areas: [{ x: { from: 2020 } }],
+				styles: { stroke: { strokeDasharray: '4 4' } },
+				legend: 'Projection'
+			}
+		]
+	}}
+/>
+```
+
+`legend` on a segment or marker is a string, or `{ label, color, symbol, lineStyle, filled, opacity }` to override how the item looks.
+
+## Toggling series
+
+Items become clickable with `interactive` on the series section. `disabled` says what a hidden series becomes:
+
+```svelte
+<LinePlot ... legend={{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }} />
+```
+
+![Legend items as toggles](images/legend-interactive.png)
+
+| `disabled.mode`   | A hidden series...                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `'dim'` (default) | stays, faded (`style` sets how: opacity, fill, ...; default `legend.disabledOpacity`) |
+| `'hide'`          | becomes transparent, the axes keep its range                                          |
+| `'omit'`          | is removed and the axes refit to the rest                                             |
+
+`interactive.legendStyle` is `'badge'` (default: pills filled with the series color and an eye toggle) or `'basic'` (swatches). `showIcon` toggles the symbol in a badge.
+
+A continuous section narrows with `interactive: { enabled: true, mode: 'filter' | 'rescale' }`: drag handles trim the range, `'filter'` hides what lies outside, `'rescale'` refits the ramp.
+
+Series can be toggled from code too: `useFigure().legend` has `off`, `isOff(name)`, `toggle`, `turnOff`, `turnOn` (see [Reading plot state](state.md)).
+
+## Adjusting the automatic legend
+
+An object adjusts the automatic legend while keeping what the plots read:
+
+```ts
+legend={{
+	items: [{ name: 'Target', color: '#000', symbol: 'line' }], // appended to the series section
+	sections: [/* extra sections after the automatic ones */],
+	series: { title: 'Division', layout: { type: 'flex' } },
+	color: { title: 'Temperature', interactive: { enabled: true } },
+	opacity: { title: 'Confidence' },
+	size: { title: 'Population' },
+	symbol: { title: 'Income group' }
+}}
+```
+
+Each channel key adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
+
+## Explicit sections
+
+A list replaces the automatic legend with exactly those sections:
+
+```ts
+legend={[
+	{
+		type: 'discrete',
+		title: 'Indicator',
+		interactive: { enabled: true },
+		items: [
+			{ name: 'GDP', color: '#4f46e5', symbol: 'line' },
+			{ name: 'Employment', color: '#e6580d', symbol: 'line' }
+		]
+	},
+	{ type: 'continuous', title: 'Share', min: 0, max: 100, scheme: 'blues' }
+]}
+```
+
+![A legend of explicit sections: discrete items and a continuous ramp](images/legend-sections.png)
+
+Section types:
+
+- `discrete` - `items` (`name`, `label`, `color`, `symbol`, `filled`, `opacity`, `lineStyle`), `columns`, `layout` (`{ type: 'vertical' }`, `{ type: 'horizontal', maxRows }` paginated, `{ type: 'flex' }`), `interactive`, `navButton`.
+- `continuous` - `min`, `max`, `colorMin`, `colorMax`, `scheme`, `pivot`, `opacity`, `ticks`, `width`, `format`, `interactive`.
+- `size` - `domain`, `range`, `values`, `color`, `filled`, `symbol`, `format`.
+- `symbol` - `items` of `{ name, symbol }`, `color`, `filled`, `layout`.
+
+## Placement and look
+
+The legend is a chrome block: `order` places it (`'legend'`, or in a row with the plot). Its fonts, gaps, swatch size and the continuous bar's geometry are `legend.*` in the [configuration](theming.md). A paginated section's prev/next arrows are replaceable with a `navButton` snippet.

package/docs/markers.md

@@ -0,0 +1,106 @@
+# Markers
+
+`markers` adds marks to a plot beyond the ones its kind draws: annotations, regions, derived shapes, hover highlights, or any Svelte component. It is an array of objects; `type` picks the marker and the other fields configure it.
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={lifeExpectancy}
+	x="year"
+	y="value"
+	color="sex"
+	markers={[
+		{ type: 'hover' },
+		{ type: 'rule', axis: 'x', value: 2020, styles: { stroke: '#999', strokeDasharray: '4 4' } },
+		{
+			type: 'delta',
+			axis: 'x',
+			at: 2018,
+			from: { type: 'series', series: 'female' },
+			to: { type: 'series', series: 'male' },
+			formatDiff: (d) => d.toFixed(1)
+		}
+	]}
+/>
+```
+
+![A line plot with a reference rule and a delta between two series](images/markers.png)
+
+Markers draw in array order. Type a markers array with `satisfies AxisBasedMarkersConfig[]` (or `GeoMarkersConfig[]`) to get completion.
+
+## Fields every marker shares
+
+| Field                      | Meaning                                                                                                                                                                                         |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`                     | The marker's own rows. Unset, it draws the plot's rows                                                                                                                                          |
+| `x`, `y`, `grouping`       | Accessors, when the marker reads other fields than the plot                                                                                                                                     |
+| `series`                   | Draw over one series only (by name)                                                                                                                                                             |
+| `scope`                    | With `series`: `'series'` (default) draws once over the whole series; `'segment'` draws once per [segment](styles-and-segments.md), in its color - a `selectMaxY` marks each segment's own peak |
+| `scales`                   | The marker's own `color`/`opacity`/`symbol` scales, independent of the plot's                                                                                                                   |
+| `transforms`, `statistics` | Derive rows for this marker ([Transforms](transforms-and-statistics.md))                                                                                                                        |
+| `clip`                     | Clip to the plot's frame                                                                                                                                                                        |
+| `legend`                   | Name the marker on the automatic [legend](legend.md)                                                                                                                                            |
+
+Many markers also take channel fields (`color`, `fill`, `opacity`, `r`, `symbol`, `weight`, `x1`/`x2`/`y1`/`y2`) and a `styles` object (`StrokeStyle`, `AreaStyle`, `DotStyle` or `FontStyle` depending on the mark).
+
+## Catalog for axis-based plots
+
+| `type`                                                   | Draws                                                                                                        |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                               |
+| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins` |
+| `line`                                                   | A line through the rows                                                                                      |
+| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (or a function with `data`), `styles`                          |
+| `tick`                                                   | A short tick per row along one axis                                                                          |
+| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                          |
+| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges                                   |
+| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                               |
+| `difference`                                             | The area between two series, colored by which one is on top                                                  |
+| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`                                          |
+| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                   |
+| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position, as a line and a label         |
+| `hull`                                                   | The convex hull around a cluster of points                                                                   |
+| `density`                                                | 2D density contour bands                                                                                     |
+| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`                        |
+| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                        |
+| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                               |
+| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                     |
+| `image`                                                  | An image per row; `src`, `width`, `height`                                                                   |
+| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                          |
+| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                      |
+| `hover`                                                  | The in-plot hover highlight (see below)                                                                      |
+| `component`                                              | Your own Svelte component (see below)                                                                        |
+
+## Hover highlight
+
+`{ type: 'hover' }` draws a crosshair, a dot and a label at the hovered point. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `ruleX`, `ruleY`, `areaX`, `areaY` (a band highlight on band scales), `showLabels`, `format`, and the styles `rule`, `area`, `dot`, `text`. See [Tooltip and hover](tooltip-and-hover.md).
+
+## Custom components
+
+`{ type: 'component', component: MyMark, props: { ... } }` mounts a Svelte component inside the plot's SVG. It can read the plot it is in with [`usePlot()`](state.md), so it can draw from the plot's scales, margins, hover and rows.
+
+```svelte
+<!-- HoverReadout.svelte -->
+<script lang="ts">
+	import { usePlot } from '@fundar/data-chart-telling';
+	const plot = usePlot();
+	const point = $derived(plot.hover.activePoint);
+</script>
+
+<text x={plot.margins.left + 8} y={plot.margins.top + 16}>
+	{point ? `${point.series} at ${point.x}: ${point.label}` : 'Hover the plot'}
+</text>
+```
+
+```svelte
+<LinePlot
+	...
+	tooltip
+	markers={[{ type: 'hover' }, { type: 'component', component: HoverReadout }]}
+/>
+```
+
+## Markers on maps
+
+`GeoPlot` accepts `dot` and `text` plus map-specific markers: `graticule`, `sphere`, `vector`, `link`, `contour`, `inset`, `geo-hover` and `geo-component`. They are described in [Maps](geo.md#markers).

package/docs/plots.md

@@ -0,0 +1,158 @@
+# Plots
+
+Eight plot kinds share one set of props (see [Concepts](concepts.md)). They differ in what they draw, which channels they need and how they hover.
+
+| Plot                              | Draws                                | Needs                                           |
+| --------------------------------- | ------------------------------------ | ----------------------------------------------- |
+| [`LinePlot`](#lineplot)           | A line per series                    | `x`, `y`                                        |
+| [`AreaPlot`](#areaplot)           | A filled area per series             | `x`, `y`                                        |
+| [`BarPlot`](#barplot)             | Bars, grouped, stacked or horizontal | a category channel and a value channel          |
+| [`HistogramPlot`](#histogramplot) | Counts of a numeric field in bins    | `x` or `y`                                      |
+| [`HeatmapPlot`](#heatmapplot)     | A grid of colored cells              | `x`, `y`, `color`                               |
+| [`PyramidPlot`](#pyramidplot)     | Two series mirrored around zero      | a category channel, a value channel, two series |
+| [`ScatterPlot`](#scatterplot)     | A point per row                      | `x`, `y`                                        |
+| [`GeoPlot`](#geoplot)             | A map from GeoJSON or TopoJSON       | `data` (see [Maps](geo.md))                     |
+
+All of them accept `data` with `grouping`/`color`, or pre-built `series`.
+
+## LinePlot
+
+One line per series. Rows with a missing value (`null`, `undefined`, `NaN`) break the line; `styles.gaps` can [bridge the break](styles-and-segments.md#gaps).
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="date"
+	y="index"
+	color="division"
+	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+/>
+```
+
+![A line plot with end-of-line labels](images/plots-line.png)
+
+- `styles.values.show` writes a label at the end of each series, with the series name and value. Overlapping labels spread apart automatically and the margin grows to fit them.
+- Hover finds the points sharing the hovered `x`.
+- With a [`timeline`](timeline.md), the line reveals itself up to the current step and interpolates `y` between steps.
+- `segments` style ranges of a line; `markers` add `delta`, `rule`, `text` and the rest (see [Markers](markers.md)).
+
+## AreaPlot
+
+One filled area per series, under the line from `y` to the baseline. Default fill opacity comes from `area.fillOpacity` in the configuration.
+
+```svelte
+<AreaPlot
+	{width}
+	{height}
+	data={rows}
+	x="year"
+	y="value"
+	color="region"
+	transforms={[{ type: 'stackY' }]}
+/>
+```
+
+![A stacked area plot](images/plots-area.png)
+
+`transforms={[{ type: 'stackY' }]}` stacks the series.
+
+## BarPlot
+
+Bars where one axis holds the categories and the other the values. Categories on `x` give vertical bars; categories on `y` give horizontal bars.
+
+```svelte
+<!-- vertical -->
+<BarPlot {width} {height} data={rows} x="province" y="value" color="sex" />
+<!-- horizontal -->
+<BarPlot {width} {height} data={rows} x="value" y="province" color="sex" />
+```
+
+![Vertical grouped bars](images/plots-bar.png)
+
+![Horizontal grouped bars](images/plots-bar-horizontal.png)
+
+- Several series sharing a category sit side by side, each in its slice of the category band. The gap between them is `bar.seriesPadding` in the configuration.
+- `transforms={[{ type: 'stackY' }]}` stacks the series instead. Stacking is always `stackY`, also for horizontal bars, because the value channel is the one stacked.
+- `scales.x.paddingInner` / `paddingOuter` set the spacing between category bands.
+- `styles.values.show` labels each bar; `styles.values.anchor` places the label (`'outside'`, `'start'`, `'middle'`, `'end'`).
+- The tooltip triggers anywhere over a bar's whole band, not just over the visible bar.
+
+## HistogramPlot
+
+Bins the rows of each series along one axis and draws the count per bin. Give `x` alone for vertical bars or `y` alone for horizontal bars.
+
+```svelte
+<HistogramPlot
+	{width}
+	{height}
+	data={rows}
+	x="weight"
+	grouping="group"
+	segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}
+/>
+```
+
+![Two overlapping histograms](images/plots-histogram.png)
+
+- `grouping` (or `color`) draws one histogram per group.
+- Override the default binning with a `binX` (or `binY`) transform: `transforms={[{ type: 'binX', thresholds: 20 }]}`. A transform given here is merged over the default one.
+- `transforms={[{ type: 'stackY' }]}` stacks groups in each bin.
+- `segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}` makes overlapping groups translucent.
+
+## HeatmapPlot
+
+A grid of cells, `x` and `y` being the categories of the columns and rows and `color` the value that colors each cell.
+
+```svelte
+<HeatmapPlot {width} {height} data={cells} x="quarter" y="product" color="sales" />
+```
+
+![A heatmap with value labels](images/plots-heatmap.png)
+
+- The color domain spans the whole dataset, so it stays comparable across [facets](facets.md).
+- Cell value labels are on by default (`styles.values.show` turns them off).
+- `segments` restyle chosen columns, rows or single cells (see [Styles and segments](styles-and-segments.md)).
+- Hover matches one cell at a time.
+
+## PyramidPlot
+
+Two series mirrored around a shared zero baseline, such as a population pyramid. Categories on `y` give horizontal bars; categories on `x` give vertical ones.
+
+```svelte
+<PyramidPlot {width} {height} data={ages} x="share" y="ageGroup" color="sex" />
+```
+
+![A population pyramid](images/plots-pyramid.png)
+
+- `scales.grouping.reverse` swaps which series sits on which side.
+- Hover finds the points sharing the hovered category.
+
+## ScatterPlot
+
+A dot per row.
+
+```svelte
+<ScatterPlot
+	{width}
+	{height}
+	data={countries}
+	x="gdp"
+	y="life"
+	r="population"
+	color="continent"
+	symbol="income"
+/>
+```
+
+![A scatter plot sized, colored and shaped by channels](images/plots-scatter.png)
+
+- `r` sizes the dots (area follows the value; configure with `scales.r`). The legend gets a size section.
+- `symbol` varies the dot shape by category (`scales.symbol`), `opacity` varies transparency, `color` colors by category or by a continuous ramp.
+- A literal number for `r` is a fixed radius in pixels.
+- `dotRadius` defaults come from `scatter.dotRadius` in the configuration.
+
+## GeoPlot
+
+Draws GeoJSON or TopoJSON as a map: base features, a choropleth through `color`, per-feature `segments`, projections, camera and map-specific markers. It has its own page: [Maps](geo.md).