@fundar/data-chart-telling 0.0.63 → 1.0.0

package/docs/facets.md

@@ -0,0 +1,69 @@
+# Facets
+
+`facet` splits a plot's rows into small multiples: one panel per value of a field, each drawn with the same plot configuration.
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="year"
+	y="value"
+	facet={{ by: 'region', columns: 3, gap: 12 }}
+/>
+```
+
+![One panel per region](images/facets-grid.png)
+
+The data phases (grouping, transforms, statistics, shared scales) run once for all panels; each panel then lays itself out in its own box. Panels share legend toggles and hover, so one legend controls them all.
+
+## One facet per value
+
+`{ by }` makes one panel per distinct value of the `by` field.
+
+| Option                   | Meaning                                                                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `by`                     | Field (or function) to split by                                                                                                                 |
+| `values`                 | The facet values to show, in order. Default: every value, in data order                                                                         |
+| `columns`                | Panels per row: a number, or `{ desktop, mobile }`                                                                                              |
+| `mode`                   | `'grid'` (all at once, default), `'carousel'` (a few at a time with prev/next) or `'paginated'` (pages). Also `{ desktop, mobile }`             |
+| `visible`                | Carousel: how many panels show at once                                                                                                          |
+| `pageSize`               | Paginated: panels per page                                                                                                                      |
+| `navLayout`              | `'overlay'` or `'below'` the navigation buttons                                                                                                 |
+| `formatIndicator`        | `(current, total) => string` for the position badge                                                                                             |
+| `indicator`, `navButton` | Snippets replacing the badge and the buttons                                                                                                    |
+| `gap`                    | Pixels between panels                                                                                                                           |
+| `scales`                 | `'shared'` (default), `'free'`, `'free-x'`, `'free-y'`                                                                                          |
+| `axes`                   | `'all'` (default) draws every panel's axes; `'outer'` draws only the left column's y and the bottom row's x, with panels resized to equal boxes |
+
+```svelte
+<BarPlot ... facet={{ by: 'group', columns: 3, mode: 'carousel', visible: 2 }} />
+```
+
+![A carousel showing two panels at a time](images/facets-carousel.png)
+
+## Rows by columns
+
+`{ rows, cols }` makes one panel per combination of a row field and a column field, with each value labelled. Combinations without data stay empty. `rowValues` and `colValues` choose and order the values. A free `x` scale is shared down each column and a free `y` along each row.
+
+```svelte
+<LinePlot ... facet={{ rows: 'region', cols: 'sector', scales: 'free' }} />
+```
+
+![Panels for each combination of region and sector](images/facets-rows-cols.png)
+
+## Alignment
+
+Panels line up: each plot reports the margins it settled on, and once all have, every column and row pins its widest ones, so the plot areas align whatever their tick labels need.
+
+## Hover and tooltips
+
+`tooltip={{ sync: true }}` shows the hovered point in every panel, a feature for comparing the same x across panels. See [Tooltip and hover](tooltip-and-hover.md).
+
+## Facets with a timeline
+
+`facet` and [`timeline`](timeline.md) combine: each step shows its rows split into panels.
+
+## Maps
+
+`GeoPlot` takes `facet` and reads the field from each feature's `properties` (and from each marker row); features without the field are drawn in every panel.

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).