@fundar/data-chart-telling 0.0.64 → 1.1.0

package/docs/tooltip-and-hover.md

@@ -0,0 +1,128 @@
+# Tooltip and hover
+
+A plot becomes interactive when it is given a `tooltip`, a `{ type: 'hover' }` marker, or both. Hover is shared by every plot in a figure, so it can drive the other panels of a [facet](facets.md) or [composer](composer.md).
+
+## Tooltip
+
+<!-- example: examples/Tooltip.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!--
+	`tooltip` turns the floating box on (`true` for the defaults, or an object
+	to tune it); a `hover` marker draws the in-plot crosshair, dot and label.
+-->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	tooltip={{ strategy: 'x', format: (row) => `${row.region}: ${row.value}` }}
+	markers={[{ type: 'hover' }]}
+/>
+```
+
+<!-- /example -->
+
+![A tooltip and a hover highlight on the hovered point](images/tooltip.png)
+
+`tooltip` is `true` for the defaults, or an options object:
+
+| Option               | Meaning                                                                                                                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strategy`           | How related points are found: `'x'`, `'y'`, `'punctual'` (the exact point) or `'series'` (all points of the hovered series). Defaults per plot kind                                                                                    |
+| `sync`               | Show the highlight in every synced plot too (default `false`)                                                                                                                                                                          |
+| `format`             | `(row) => string` - the tooltip text for the hovered row (`\n` breaks lines). With several rows, they read from the highest value to the lowest (a stacked row by its own value)                                                       |
+| `content`            | A snippet `{#snippet content({ rows })}` replacing the text with custom markup. It gets the rows as the hover matched them, unsorted, and is drawn in a plain card, so the markup brings its own order, background, colors and spacing |
+| `series`             | Only these series appear in the tooltip                                                                                                                                                                                                |
+| `anchorX`, `anchorY` | Preferred side of the cursor: `'left' \| 'middle' \| 'right'` (default `'right'`) and `'top' \| 'middle' \| 'bottom'` (default `'bottom'`). It moves to the other side when it would overflow                                          |
+
+<!-- example: examples/CustomTooltip.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot, getConfiguration, paletteColor } from '@fundar/data-chart-telling';
+	import TooltipCard from './TooltipCard.svelte';
+	import { REGION_VALUES, type RegionRow } from './data';
+
+	const { palette } = getConfiguration();
+	const regions = [...new Set(REGION_VALUES.map((row) => row.region))];
+</script>
+
+<!--
+	`content` replaces the tooltip text with your own markup, drawn in a plain
+	card: TooltipCard brings its own background, colors and spacing. It is given
+	every row the hover matched, in no particular order, so it sorts them itself;
+	series colors come from the configuration's palette.
+-->
+{#snippet content({ rows }: { rows: RegionRow[] })}
+	<TooltipCard
+		heading={rows[0].date.toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric',
+			timeZone: 'UTC'
+		})}
+		footer="Monthly inflation (%)"
+		entries={[...rows]
+			.sort((a, b) => b.value - a.value)
+			.map((row) => ({
+				label: row.region,
+				color: paletteColor(regions.indexOf(row.region), palette),
+				value: row.value,
+				display: String(row.value)
+			}))}
+	/>
+{/snippet}
+
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	tooltip={{ strategy: 'x', content }}
+	markers={[{ type: 'hover' }]}
+/>
+```
+
+<!-- /example -->
+
+![A tooltip with custom markup](images/custom-tooltip.png)
+
+This is [examples/CustomTooltip.svelte](../examples/CustomTooltip.svelte); the card is [examples/TooltipCard.svelte](../examples/TooltipCard.svelte).
+
+The default strategy follows the plot's axes: it matches along the category (or index) axis - points sharing the hovered `x` when the value axis is vertical, sharing `y` when it is horizontal - and `punctual` (the exact point) on heatmaps and scatter plots.
+
+## In-plot hover
+
+`markers={[{ type: 'hover' }]}` draws a dashed rule, a dot and a value label at the hovered point, inside the SVG. Its look comes from `hover` in the [configuration](theming.md) and can be overridden per marker (`rule`, `dot`, `text`, `area`). On band scales `areaX` / `areaY` highlight the whole band instead of a thin rule.
+
+Use both together for the usual result:
+
+```svelte
+<LinePlot ... tooltip markers={[{ type: 'hover' }]} />
+```
+
+## Bars
+
+On a `BarPlot` a hover candidate is the bar's whole band (or its series' slice, when grouped), so the tooltip triggers anywhere along the column.
+
+## Syncing across plots
+
+- In a [facet](facets.md) or a [`PlotComposer`](composer.md), `tooltip.sync: true` (or `hover.sync` on the composer) shows the hovered point's highlight, and the tooltip, in every panel. That replication is the feature: the same x is highlighted across panels.
+- A composer's `hover={{ strategy, sync }}` sets the strategy and sync for all its panels.
+
+## Maps
+
+`GeoPlot` takes `tooltip` too (the row is the hovered feature) and the `{ type: 'geo-hover' }` marker, which restyles the hovered feature. See [Maps](geo.md).
+
+## Reading hover from code
+
+`useFigure().hover` and `usePlot().hover` expose `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` and, for a plot, `points`, `activePoint` and `tooltip`. See [Reading plot state](state.md).

package/docs/transforms-and-statistics.md

@@ -0,0 +1,118 @@
+# Transforms and statistics
+
+Both derive rows from the data before drawing. A **transform** reshapes the rows themselves (stack, bin, smooth, sort, filter). A **statistic** computes a summary of the data (regression, moving average, density) and draws it as an extra mark.
+
+## Transforms
+
+`transforms` is an array of flat objects: `type` picks the transform and the other fields are its channels and options, named as in [svelteplot's transforms](https://svelteplot.dev). It exists on a plot (it then runs once over all the plot's series) and on each [marker](markers.md) (over the marker's rows).
+
+<!-- example: examples/StackedBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { SEX_SHARES } from './data';
+</script>
+
+<!-- Each sex's share of the population per census, stacked with `stackY` so a bar adds up to 100%. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={SEX_SHARES}
+	x="year"
+	y="share"
+	color="sex"
+	transforms={[{ type: 'stackY' }]}
+/>
+```
+
+<!-- /example -->
+
+![Stacked bars](images/stacked-bars.png)
+
+<!-- example: examples/MovingAverage.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A 6-month moving average, run on the plot's rows. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	transforms={[{ type: 'windowY', k: 6, reduce: 'mean' }]}
+/>
+```
+
+<!-- /example -->
+
+![Lines smoothed by a moving average](images/moving-average.png)
+
+| Family    | `type`                                                                                        | Does                                                                                                                                                                                                                             |
+| --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Stack     | `stackX`, `stackY`, `stackMosaicX`, `stackMosaicY`                                            | Cumulative stacking. Options: `offset` (`'none'`, `'wiggle'`, `'center'`, `'normalize'`, `'diverging'`), `order`, `reverse`                                                                                                      |
+| Bin       | `binX`, `binY`, `bin`                                                                         | Count or reduce rows into bins. Options: `thresholds` (a count, a list, or `'auto'`, `'scott'`, `'sturges'`, `'freedman-diaconis'`), `interval`, `domain`, `cumulative`; reducers by channel (`y: 'count'`, `fill: 'mean'`, ...) |
+| Group     | `groupX`, `groupY`, `groupZ`, `group`                                                         | Reduce rows per category with named reducers (`count`, `sum`, `mean`, `p25`, ...) or functions                                                                                                                                   |
+| Window    | `windowX`, `windowY`                                                                          | Sliding window: `k` (size), `reduce` (`'mean'`, `'median'`, `'sum'`, `'max'`, ...), `anchor`, `strict`                                                                                                                           |
+| Bollinger | `bollingerX`, `bollingerY`                                                                    | Moving average and band: `n`, `k`                                                                                                                                                                                                |
+| Normalize | `normalizeX`, `normalizeY`, `normalizeParallelX`, `normalizeParallelY`                        | Rebase to a reference: `basis` (`'first'`, `'last'`, `'min'`, `'max'`, `'mean'`, `'median'`, `'sum'`, `'deviation'`)                                                                                                             |
+| Map       | `mapX`, `mapY`                                                                                | `map`: `'cumsum'`, `'rank'`, `'quantile'` or a function                                                                                                                                                                          |
+| Interval  | `intervalX`, `intervalY`                                                                      | Turn a value into an `[x1, x2]` interval of a given size                                                                                                                                                                         |
+| Jitter    | `jitterX`, `jitterY`                                                                          | Random offset: `width`, `std`, `distribution` (`'uniform'`, `'normal'`), `seed`                                                                                                                                                  |
+| Shift     | `shiftX`, `shiftY`                                                                            | Move by `by` (a number, or a string offset)                                                                                                                                                                                      |
+| Density   | `densityX`, `densityY`                                                                        | Kernel density estimate: `kernel`, `bandwidth`                                                                                                                                                                                   |
+| Sort      | `sort`, `shuffle`, `reverse`                                                                  | Reorder rows (matters for the path a line takes and which dot lands on top)                                                                                                                                                      |
+| Filter    | `filter`                                                                                      | Keep rows a test holds for                                                                                                                                                                                                       |
+| Select    | `select`, `selectFirst`, `selectLast`, `selectMinX`, `selectMaxX`, `selectMinY`, `selectMaxY` | Keep one row per group, such as each series' last point or peak                                                                                                                                                                  |
+
+Bar stacking is always `stackY`, also for horizontal bars. A transform on a `HistogramPlot` is merged over the plot's default binning, so `{ type: 'binX', thresholds: 20 }` changes the bins and the rest stays.
+
+## Statistics
+
+`statistics` is an array of derived summaries drawn as extra marks. On a plot it computes one per series by default; on a marker it applies to that marker's own rows.
+
+<!-- example: examples/Regression.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ScatterPlot } from '@fundar/data-chart-telling';
+	import { COUNTRIES } from './data';
+</script>
+
+<!-- A linear regression with its 95% confidence band. -->
+<ScatterPlot
+	width={720}
+	height={400}
+	data={COUNTRIES}
+	x="gdp"
+	y="life"
+	statistics={[{ type: 'regression', regressionType: 'linear', confidence: 0.95 }]}
+/>
+```
+
+<!-- /example -->
+
+![A scatter plot with a regression line and confidence band](images/regression.png)
+
+| `type`          | Draws                                                | Options                                                                                                                                                           |
+| --------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `regression`    | A fitted curve with a confidence band                | `regressionType` (`'linear'`, `'quad'`, `'poly'`, `'exp'`, `'log'`, `'pow'`, `'loess'`), `order`, `base`, `span`, `confidence` (`false` omits the band), `styles` |
+| `movingAverage` | A smoothed line                                      | `k` (required), `reduce`, `styles`                                                                                                                                |
+| `bollinger`     | Moving average and a band of `k` standard deviations | `n`, `k`, `styles`                                                                                                                                                |
+| `density`       | A 1D density curve over `x`                          | `kernel`, `bandwidth`, `styles`                                                                                                                                   |
+| `density2d`     | 2D density contour bands                             | `bandwidth`, `thresholds`, `styles`                                                                                                                               |
+| `box`           | A box plot per category                              | the options of the [`box` marker](markers.md)                                                                                                                     |
+
+Which series a statistic runs over:
+
+- omitted: one statistic per series;
+- `series: ['a', 'b']`: only the named series;
+- `pooled: true`: one statistic over all series combined.
+
+The same summaries are available as markers (`regression`, `bollinger`, `density`, `box`, ...) when more control over the mark is needed.

package/examples/BarValues.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES, MONTHS } from './data';
+</script>
+
+<!-- Categories on x, values on y. Swap `x` and `y` for horizontal bars. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={REGION_VALUES.filter((row) => row.date === MONTHS.at(-1))}
+	x="region"
+	y="value"
+	styles={{ values: { show: true, anchor: 'outside' } }}
+/>

package/examples/Box.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+	import { BoxPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './data';
+</script>
+
+<!-- One box per group: quartiles, median, whiskers and outliers of each height distribution. -->
+<BoxPlot width={720} height={400} data={HEIGHTS} x="group" y="height" color="group" />

package/examples/Chrome.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A plot carries its own chrome: title, subtitle, legend and caption. -->
+<LinePlot
+	width={720}
+	height={440}
+	title="Commodity prices"
+	subtitle="Price index, January 2021 = 100"
+	caption="Source: IMF, Primary Commodity Prices"
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+/>

package/examples/ChromeOrder.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- `order` places the chrome blocks; `divider` draws a rule between them. -->
+<LinePlot
+	width={720}
+	height={460}
+	title="Commodity prices"
+	subtitle="Price index"
+	caption="Source: IMF, Primary Commodity Prices"
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	order={['title', 'subtitle', 'divider', 'legend', 'plot', 'divider', 'caption']}
+/>

package/examples/Composer.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import { PlotComposer, LinePlot, BarPlot, ScatterPlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES, PROVINCE_VALUES, COUNTRIES } from './data';
+</script>
+
+<!-- Several plots in one figure, placed on named areas of a grid. -->
+<PlotComposer
+	width={900}
+	height={560}
+	title="Three views, one figure"
+	legend={false}
+	tags="A"
+	layout={{ areas: ['a a b', 'a a c'] }}
+>
+	<LinePlot area="a" data={REGION_VALUES} x="date" y="value" color="region" tooltip />
+	<BarPlot
+		area="b"
+		data={PROVINCE_VALUES.filter((row) => row.sex === 'female').slice(0, 3)}
+		x="province"
+		y="value"
+	/>
+	<ScatterPlot area="c" data={COUNTRIES} x="gdp" y="life" />
+</PlotComposer>

package/examples/CustomTooltip.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import { LinePlot, getConfiguration, paletteColor } from '@fundar/data-chart-telling';
+	import TooltipCard from './TooltipCard.svelte';
+	import { REGION_VALUES, type RegionRow } from './data';
+
+	const { palette } = getConfiguration();
+	const regions = [...new Set(REGION_VALUES.map((row) => row.region))];
+</script>
+
+<!--
+	`content` replaces the tooltip text with your own markup, drawn in a plain
+	card: TooltipCard brings its own background, colors and spacing. It is given
+	every row the hover matched, in no particular order, so it sorts them itself;
+	series colors come from the configuration's palette.
+-->
+{#snippet content({ rows }: { rows: RegionRow[] })}
+	<TooltipCard
+		heading={rows[0].date.toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric',
+			timeZone: 'UTC'
+		})}
+		footer="Monthly inflation (%)"
+		entries={[...rows]
+			.sort((a, b) => b.value - a.value)
+			.map((row) => ({
+				label: row.region,
+				color: paletteColor(regions.indexOf(row.region), palette),
+				value: row.value,
+				display: String(row.value)
+			}))}
+	/>
+{/snippet}
+
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	tooltip={{ strategy: 'x', content }}
+	markers={[{ type: 'hover' }]}
+/>

package/examples/Facets.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- One panel per region, three columns, sharing scales. A tooltip with `sync` shows in every panel on purpose. -->
+<LinePlot
+	width={900}
+	height={360}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 3, gap: 12, scales: 'shared' }}
+	tooltip={{ sync: true }}
+/>

package/examples/FacetsCarousel.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- A carousel shows `visible` panels at a time, with navigation below. -->
+<LinePlot
+	width={720}
+	height={340}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 3, mode: 'carousel', visible: 2, navLayout: 'below' }}
+/>

package/examples/FacetsRowsCols.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	// Each region's value split into two sectors.
+	const SECTORS = [
+		{ sector: 'Goods', share: 0.8 },
+		{ sector: 'Services', share: 1.4 }
+	];
+	const rows = REGION_VALUES.flatMap((row) =>
+		SECTORS.map(({ sector, share }) => ({ ...row, sector, value: row.value * share }))
+	);
+</script>
+
+<!-- One panel per region and sector; `scales: 'free'` fits each panel to its own data. -->
+<LinePlot
+	width={720}
+	height={420}
+	data={rows}
+	x="date"
+	y="value"
+	facet={{ rows: 'region', cols: 'sector', scales: 'free' }}
+/>

package/examples/FirstPlot.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- The smallest useful plot: rows, the fields to map and a pixel size. -->
+<LinePlot width={720} height={400} data={REGION_VALUES} x="date" y="value" color="region" />

package/examples/Gaps.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE_GAPS } from './data';
+</script>
+
+<!-- Missing values bridged: dashed in the middle, faded at the start, extended to the 2025 projection at the end. -->
+<LinePlot
+	width={720}
+	height={400}
+	series={[{ name: 'female', x: 'year', y: 'value', data: LIFE_GAPS }]}
+	scales={{ x: { edgeTicks: true }, y: { domain: [55, 85] } }}
+	styles={{
+		gaps: {
+			default: {
+				middle: { interpolate: 'linear', style: { stroke: { strokeDasharray: '4 4' } } },
+				start: { x: 1940, style: { stroke: { strokeOpacity: 0.4 } } },
+				end: { x: 2025, y: 81.1 }
+			}
+		}
+	}}
+/>

package/examples/GroupedBars.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './data';
+</script>
+
+<!-- Vertical bars, grouped by `color`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="province"
+	y="value"
+	color="sex"
+	scales={{ y: { domain: [70, 85] } }}
+/>

package/examples/Heatmap.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+	import { HeatmapPlot } from '@fundar/data-chart-telling';
+	import { HOUSEHOLDS } from './data';
+</script>
+
+<!-- One cell per number of rooms and of people, colored by the share of households. -->
+<HeatmapPlot width={560} height={360} data={HOUSEHOLDS} x="rooms" y="people" color="share" />

package/examples/HeatmapSegments.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	import { HeatmapPlot } from '@fundar/data-chart-telling';
+	import { HOUSEHOLDS } from './data';
+</script>
+
+<!-- Segments on a heatmap: an outlined column and a filled block of overcrowded households. -->
+<HeatmapPlot
+	width={560}
+	height={360}
+	data={HOUSEHOLDS}
+	x="rooms"
+	y="people"
+	color="share"
+	segments={{
+		default: [
+			{
+				areas: [{ x: { from: '1', to: '1' } }],
+				styles: { stroke: '#f59e0b', strokeWidth: 2 }
+			},
+			{
+				areas: [{ x: { from: '1', to: '2' }, y: { from: '4', to: '5+' } }],
+				styles: { fill: '#ef4444', fillOpacity: 0.8 }
+			}
+		]
+	}}
+/>

package/examples/Histogram.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import { HistogramPlot } from '@fundar/data-chart-telling';
+	import { HEIGHTS } from './data';
+</script>
+
+<!-- Two overlapping distributions, one per `grouping` value. -->
+<HistogramPlot
+	width={720}
+	height={400}
+	data={HEIGHTS}
+	x="height"
+	grouping="group"
+	segments={{ default: [{ styles: { fillOpacity: 0.7 } }] }}
+/>

package/examples/HorizontalBars.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './data';
+</script>
+
+<!-- Horizontal bars: the categories go on `y`, the values on `x`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+/>

package/examples/LegendReader.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import { useFigure } from '@fundar/data-chart-telling';
+
+	// Call during component init, below a plot or a PlotComposer.
+	const { legend } = useFigure();
+</script>
+
+<p>Hidden series: {legend?.off.join(', ') || 'none'}</p>

package/examples/LegendSections.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- An explicit legend: a discrete section of toggles and a continuous ramp. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	legend={[
+		{
+			type: 'discrete',
+			title: 'Region',
+			interactive: { enabled: true },
+			items: [
+				{ name: 'GBA', color: '#4f46e5', symbol: 'line' },
+				{ name: 'Cuyo', color: '#e6580d', symbol: 'line' },
+				{ name: 'Northwest', color: '#16a34a', symbol: 'line' }
+			]
+		},
+		{ type: 'continuous', title: 'Share', min: 0, max: 100, scheme: 'blues' }
+	]}
+/>

package/examples/LegendToggle.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+	import LegendReader from './LegendReader.svelte';
+</script>
+
+<!--
+	The automatic legend can toggle series. `mode: 'omit'` drops a hidden series
+	and refits the axes to what is left; 'dim' and 'hide' keep the axes.
+	Anything inside the figure (here, the footer) reads the toggles through
+	`useFigure().legend` - see LegendReader.
+-->
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	legend={{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }}
+>
+	{#snippet footer()}
+		<LegendReader />
+	{/snippet}
+</LinePlot>

package/examples/LineByRegion.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!-- One line per region, with a title, the automatic legend, end-of-line values and a tooltip. -->
+<LinePlot
+	width={720}
+	height={400}
+	title="Monthly inflation by region (%)"
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	tooltip
+	scales={{ x: { label: false } }}
+	styles={{ values: { show: true } }}
+/>

package/examples/LineDates.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- A line per commodity over a date axis, with end-of-line labels. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+/>