@fundar/data-chart-telling 0.0.64 → 1.1.0

package/docs/styles-and-segments.md

@@ -0,0 +1,269 @@
+# Styles and segments
+
+`styles` sets plot-wide options; `segments` restyles ranges of the data.
+
+## Styles
+
+`styles` is typed per plot kind, with these fields on the axis-based plots:
+
+| Field    | Plots                                | Purpose                       |
+| -------- | ------------------------------------ | ----------------------------- |
+| `values` | all axis-based plots                 | Value labels on the marks     |
+| `frame`  | all plots                            | A border around the plot area |
+| `gaps`   | `LinePlot`, `BarPlot`, `PyramidPlot` | Bridges over missing values   |
+
+`GeoPlot` has its own `styles` (base fill and stroke, tile layer, click handler) - see [Maps](geo.md).
+
+### Value labels
+
+<!-- example: examples/ValueLabels.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { PRICES } from './data';
+</script>
+
+<!-- End-of-line value labels with a custom format and font size. -->
+<LinePlot
+	width={720}
+	height={400}
+	data={PRICES}
+	x="date"
+	y="index"
+	color="commodity"
+	styles={{
+		values: {
+			show: true,
+			format: (value, seriesName) => `${seriesName}: ${value.toFixed(0)}`,
+			fontStyle: { fontSize: 13 }
+		}
+	}}
+/>
+```
+
+<!-- /example -->
+
+![End-of-line value labels](images/value-labels.png)
+
+| Field          | Meaning                                                                                                                                        |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `show`         | Draws the labels. Off by default, except on a heatmap                                                                                          |
+| `anchor`       | `'outside'`, `'start'`, `'middle'`, `'end'` - where a label sits on its mark                                                                   |
+| `format`       | `(value, seriesName) => string`                                                                                                                |
+| `hoverIsolate` | Hovering a label dims every other series                                                                                                       |
+| `fontStyle`    | Text style: `fontSize`, `fill`, `dx`, `dy`, `textAnchor`, `lineAnchor`, `rotate`, `class`, ... Overrides the anchor's placement field by field |
+| `strokeStyle`  | Style of the connector lines drawn from labels that had to move apart                                                                          |
+
+Where the labels go depends on the plot: the end of each series on a line or area plot, one per bar on a bar, pyramid or histogram, one per point on a scatter, one per cell on a heatmap. On lines, overlapping labels spread apart, share one column and are joined to their points by elbow connectors; the right margin grows to fit them when it is `'auto'`. The spread is tuned by `text.declutter` in the [configuration](theming.md).
+
+### Frame
+
+`styles={{ frame: true }}` draws a border around the plot area; an object restyles it (`stroke`, `fill`, `inset`, `insetTop`, ...).
+
+### Gaps
+
+A row whose value is `null`, `undefined` or `NaN` breaks a line. `styles.gaps` bridges the break with a distinct, interpolated stretch. It is keyed by series name, or `'default'` for the series with no entry of their own, and has three zones: `start` (before the first real point), `middle` and `end` (after the last).
+
+<!-- example: examples/Gaps.svelte -->
+
+```svelte
+<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 }
+			}
+		}
+	}}
+/>
+```
+
+<!-- /example -->
+
+![A line bridged across missing values with dashed segments](images/gaps.png)
+
+- `middle` bridges holes between real points, `interpolate` is an easing name (default `'linear'`).
+- `start` and `end` reach out to the given `x` (required to fill the zone), landing on `y` there (default: the nearest real value).
+- On bar plots only the presence of `x` matters.
+- Unset styles fall back to `line.gap`, `bar.gap` and `pyramid.gap` in the [configuration](theming.md).
+
+## Segments
+
+`segments` separates data ranges from their styling. It is an object: each key is a series name (a feature id for `GeoPlot`), or `'default'`, mapped to a list of segments.
+
+```ts
+type SegmentsConfig<TStyle> = Record<string, Segment<TStyle>[]>;
+type Segment<TStyle> = { areas?: Area[]; styles?: TStyle; scales?: ...; legend?: MarkLegend };
+type Area = { x?: Range; y?: Range };
+type Range = { from?: AxisValue; to?: AxisValue }; // inclusive on both ends
+```
+
+- A segment applies to a data point (or heatmap cell) inside **any** of its `areas`.
+- An `Area` limits by `x`, `y` or both; leaving one out leaves that axis open.
+- A segment without `areas` is a **catch-all**: it matches every point, is evaluated last, and is overridden by any area-specific segment. A catch-all placed first is a baseline that highlighted ranges override.
+- `'default'` applies to every series; a named key applies to that series only, and wins over `'default'` where both match.
+- `legend` names the segment on the automatic [legend](legend.md).
+
+The style shape depends on the plot:
+
+| Plot                        | Style type                         | Fields                                         |
+| --------------------------- | ---------------------------------- | ---------------------------------------------- |
+| `LinePlot`                  | `LineSegmentStyle`                 | `stroke` (line style), `dots` (dot style)      |
+| `AreaPlot`, `HistogramPlot` | `AreaStyle`                        | `fill`, `fillOpacity`, `stroke`, ...           |
+| `BarPlot`, `PyramidPlot`    | `BarSegmentStyle` (`AreaStyle`)    | `fill`, `fillOpacity`, `stroke`, ...           |
+| `HeatmapPlot`               | `CellSegmentStyle` (`AreaStyle`)   | `fill`, `fillOpacity`, `stroke`, `strokeWidth` |
+| `ScatterPlot`               | `ScatterSegmentStyle` (`DotStyle`) | dot fill, stroke, radius, symbol               |
+| `GeoPlot`                   | `GeoSegmentStyle`                  | `fill`, `fillOpacity`, `stroke`, `strokeWidth` |
+
+### Examples
+
+A baseline color with a highlighted range:
+
+<!-- example: examples/SegmentHighlight.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	const gba = REGION_VALUES.filter((row) => row.region === 'GBA');
+</script>
+
+<!-- A grey line with the 2023-2024 surge drawn in red. -->
+<LinePlot
+	width={720}
+	height={380}
+	series={[{ name: 'GBA', x: 'date', y: 'value', data: gba }]}
+	segments={{
+		GBA: [
+			{ styles: { stroke: { stroke: '#94a3b8', strokeWidth: 1 } } },
+			{
+				areas: [{ x: { from: new Date('2023-07-01'), to: new Date('2024-03-01') } }],
+				styles: { stroke: { stroke: '#ef4444', strokeWidth: 3 } }
+			}
+		]
+	}}
+/>
+```
+
+<!-- /example -->
+
+![A grey line with a highlighted red range](images/segment-highlight.png)
+
+Per-series colors, plus dots over a range shared by every series:
+
+<!-- example: examples/SegmentsBySeries.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { LIFE } from './data';
+</script>
+
+<!-- Segments per series name, plus `default` for rules shared by every series. -->
+<LinePlot
+	width={720}
+	height={380}
+	data={LIFE}
+	x="year"
+	y="value"
+	color="sex"
+	scales={{ x: { edgeTicks: true } }}
+	segments={{
+		female: [{ styles: { stroke: { stroke: 'steelblue' } } }],
+		male: [{ styles: { stroke: { stroke: 'tomato' } } }],
+		default: [
+			{
+				areas: [{ x: { from: 1965, to: 1980 } }],
+				styles: { dots: { dotRadius: 5, dotSymbol: 'circle' } }
+			}
+		]
+	}}
+/>
+```
+
+<!-- /example -->
+
+![Two series colored individually, with dots on a shared range](images/segments-by-series.png)
+
+Two areas in one segment, the second with a `y` limit:
+
+```ts
+{
+	areas: [
+		{ x: { from: 2010, to: 2012 } },
+		{ x: { from: 2015, to: 2020 }, y: { from: 83.5, to: 84 } }
+	],
+	styles: { stroke: { strokeDasharray: '6 4' } }
+}
+```
+
+Heatmap columns and cells:
+
+<!-- example: examples/HeatmapSegments.svelte -->
+
+```svelte
+<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 }
+			}
+		]
+	}}
+/>
+```
+
+<!-- /example -->
+
+![A heatmap with highlighted columns and cells](images/heatmap-segments.png)
+
+Map features, keyed by feature id:
+
+```svelte
+<GeoPlot
+	{width}
+	{height}
+	data={provinces}
+	featureId={(f) => String(f.properties?.nombre)}
+	segments={{
+		default: [{ styles: { fillOpacity: 0.7, stroke: '#94a3b8' } }],
+		Mendoza: [{ styles: { fill: '#3b82f6', fillOpacity: 0.9 } }],
+		Salta: [{ styles: { fill: '#ef4444', fillOpacity: 0.9 } }]
+	}}
+/>
+```
+
+![A map with two highlighted provinces](images/segments-geo.png)
+
+A segment typed with `satisfies SegmentsConfig<LineSegmentStyle>` gets completion for its style fields.

package/docs/theming.md

@@ -0,0 +1,226 @@
+# Theming
+
+The whole package reads its styling - fonts, colors, spacing, the legend, tooltip, axes, plot geometry - from one global, reactive configuration. Changing it re-themes every plot on screen; nothing is passed prop by prop.
+
+```ts
+import {
+	setConfiguration,
+	getConfiguration,
+	resetConfiguration,
+	THEMES
+} from '@fundar/data-chart-telling';
+
+setConfiguration(THEMES.Editorial); // a ready-made theme
+
+setConfiguration({
+	font: '"Inter", sans-serif',
+	palette: ['#4f46e5', '#e6580d', '#16a34a'],
+	legend: { continuous: { label: { size: '0.8125rem', weight: 400 } } }
+});
+
+getConfiguration(); // the live, merged configuration
+resetConfiguration(); // back to the shipped defaults
+```
+
+- `setConfiguration` takes a deep-partial patch and deep-merges it into the current configuration: name only the leaves to change. It is reactive, so mounted plots update.
+- Call it once at startup, or when the theme switches. It is global, not per plot; a plot's own props (`styles`, `scales`, a legend section's `format`, ...) always win over it.
+- The configuration is cloned when stored, so it holds data only: numbers, strings, arrays, objects. Functions belong in plot props such as `format` and `tickFormat`.
+- When `setConfiguration` runs inside an `$effect`, wrap the call in `untrack` so the effect does not re-trigger itself.
+- `THEMES` holds `Default`, `Editorial`, `Dark` and `Compact`; each is a patch for `setConfiguration`.
+- The complete shape is the type `PlotStylesConfig` (patches: `PlotStylesConfigInput`); the shipped values are `DEFAULT_CONFIG`.
+
+## Sections
+
+| Key                                                             | Controls                                                                                                                                                                                                                                                                                  |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `font`, `color`, `background`                                   | Base text of every figure                                                                                                                                                                                                                                                                 |
+| `palette`                                                       | Categorical series colors, in order                                                                                                                                                                                                                                                       |
+| `symbols`                                                       | Shape cycle for the `symbol` channel                                                                                                                                                                                                                                                      |
+| `continuous`                                                    | Default ramp endpoints, label color and opacity range for continuous color and opacity                                                                                                                                                                                                    |
+| `spacing`, `chrome`                                             | Padding around header, legend and caption; the chrome `order` and `rowGap`                                                                                                                                                                                                                |
+| `title`, `subtitle`, `caption`                                  | Text blocks: `font`, `size`, `weight`, `color`, `leading`, `spacing`                                                                                                                                                                                                                      |
+| `divider`                                                       | The line a `'divider'` in the chrome `order` draws                                                                                                                                                                                                                                        |
+| `legend`                                                        | Text, gaps, swatches, `disabledOpacity`, paginated nav buttons, the continuous bar, its handles, ticks and labels, and the `seriesTitle` and `sizeScale` options                                                                                                                          |
+| `axis`                                                          | Axis color, font and tick sizes, `grid`, and the number locale (below)                                                                                                                                                                                                                    |
+| `tooltip`                                                       | Tooltip background, color, font size, padding, radius, border                                                                                                                                                                                                                             |
+| `margins`                                                       | Default margin per side (`'auto'` or a number)                                                                                                                                                                                                                                            |
+| `line`, `area`, `bar`, `pyramid`, `histogram`, `box`, `scatter` | Per-kind defaults: stroke width, dot radius, series padding, gap fills, fill opacity, inset, box padding                                                                                                                                                                                  |
+| `text`                                                          | `declutter` geometry of value labels and connectors                                                                                                                                                                                                                                       |
+| `hover`                                                         | Look of the hover marker: `rule`, `dot`, `font`, `area`                                                                                                                                                                                                                                   |
+| `delta`                                                         | The `delta` marker's label, per axis the delta is taken on: `text.x` (beside a vertical delta: `dx: 12`, `textAnchor: 'start'`) and `text.y` (above a horizontal one: `dy: -10`, `textAnchor: 'middle'`). `lineAnchor` picks where along the delta the label sits and how it aligns there |
+| `timeline`                                                      | The rule (`rule`) and the player bar (`player`: controls, speeds, `stepDuration`, button, track, thumb, toggle)                                                                                                                                                                           |
+| `facet`                                                         | The position badge and prev/next buttons                                                                                                                                                                                                                                                  |
+| `frameClip`                                                     | Tolerance for clipping marks to the plot frame                                                                                                                                                                                                                                            |
+
+## Locale
+
+`axis.locale` (default `'es-AR'`) and `axis.compactDisplay` (`'short'` or `'long'`, default `'short'`) set how the automatic tick formatter writes numbers - the one used by any axis without its own `scales.x`/`scales.y.tickFormat`. A legend's size section writes its values the same way. Whether an axis abbreviates at all stays svelteplot's call, based on its value range; these two choose the wording once it does.
+
+```ts
+setConfiguration({ axis: { locale: 'en-US', compactDisplay: 'long' } });
+```
+
+`axis.locale` updates plots already on screen. `axis.compactDisplay` is read when a plot mounts, so a later change shows on the next mount.
+
+## Edge ticks
+
+`axis.edgeTicks.x` and `axis.edgeTicks.y` (`{ enabled, collision }`, on for x and off for y, both `'drop-nice'`) add a tick at the data's first and last values beside the nice ones, on a continuous axis whose other axis is continuous too, so a reader sees where the data starts and ends. When one lands too close to a nice tick for both labels, `collision` picks what gives way: `'drop-nice'` keeps the data's tick, `'drop-edge'` keeps the nice one, `'extend'` widens the axis to the next nice tick past the data.
+
+```ts
+setConfiguration({ axis: { edgeTicks: { x: { enabled: true, collision: 'extend' } } } });
+```
+
+A plot overrides it with `scales.x.edgeTicks` or `scales.y.edgeTicks` (see [Scales](scales.md)).
+
+## CSS variables
+
+Some fields reach the DOM as CSS custom properties, which every figure sets on its root element and the components read with a fallback. Those can also be overridden with plain CSS on a wrapping element for a one-off, non-reactive tweak:
+
+```css
+.my-dashboard {
+	--dct-tooltip-bg: #0b3d2e;
+	--dct-title-size: 2rem;
+}
+```
+
+The remaining fields are plain values read by plot code (palette, tick sizes, margins, per-kind geometry, hover look); `setConfiguration` is the way to change those.
+
+The text blocks map `title`, `subtitle` and `caption` to `--dct-{block}-{font|size|weight|color|leading|spacing}`. Every other variable and the configuration path it comes from:
+
+### base
+
+| CSS variable | Config path  |
+| ------------ | ------------ |
+| `--dct-font` | `font`       |
+| `--dct-fg`   | `color`      |
+| `--dct-bg`   | `background` |
+
+### spacing
+
+| CSS variable        | Config path              |
+| ------------------- | ------------------------ |
+| `--dct-header-pad`  | `spacing.headerPadding`  |
+| `--dct-legend-pad`  | `spacing.legendPadding`  |
+| `--dct-caption-pad` | `spacing.captionPadding` |
+| `--dct-bleed`       | `spacing.bleed`          |
+
+### divider
+
+| CSS variable           | Config path      |
+| ---------------------- | ---------------- |
+| `--dct-divider-color`  | `divider.color`  |
+| `--dct-divider-width`  | `divider.width`  |
+| `--dct-divider-style`  | `divider.style`  |
+| `--dct-divider-margin` | `divider.margin` |
+
+### chrome
+
+| CSS variable    | Config path     |
+| --------------- | --------------- |
+| `--dct-row-gap` | `chrome.rowGap` |
+
+### legend
+
+| CSS variable                            | Config path                              |
+| --------------------------------------- | ---------------------------------------- |
+| `--dct-legend-font`                     | `legend.font`                            |
+| `--dct-legend-size`                     | `legend.size`                            |
+| `--dct-legend-weight`                   | `legend.weight`                          |
+| `--dct-legend-color`                    | `legend.color`                           |
+| `--dct-legend-title-size`               | `legend.titleSize`                       |
+| `--dct-legend-title-weight`             | `legend.titleWeight`                     |
+| `--dct-legend-gap`                      | `legend.gap`                             |
+| `--dct-legend-swatch`                   | `legend.swatchSize`                      |
+| `--dct-legend-size-gap`                 | `legend.sizeScale.gap`                   |
+| `--dct-legend-nav-bg`                   | `legend.navButton.background`            |
+| `--dct-legend-nav-color`                | `legend.navButton.color`                 |
+| `--dct-legend-nav-size`                 | `legend.navButton.size`                  |
+| `--dct-legend-nav-font-size`            | `legend.navButton.fontSize`              |
+| `--dct-legend-nav-disabled-opacity`     | `legend.navButton.disabledOpacity`       |
+| `--dct-continuous-handle-width`         | `legend.continuous.handle.width`         |
+| `--dct-continuous-handle-height`        | `legend.continuous.handle.height`        |
+| `--dct-continuous-handle-radius`        | `legend.continuous.handle.radius`        |
+| `--dct-continuous-handle-fill`          | `legend.continuous.handle.fill`          |
+| `--dct-continuous-handle-stroke`        | `legend.continuous.handle.stroke`        |
+| `--dct-continuous-handle-stroke-width`  | `legend.continuous.handle.strokeWidth`   |
+| `--dct-continuous-tick-color`           | `legend.continuous.tick.color`           |
+| `--dct-continuous-tick-width`           | `legend.continuous.tick.width`           |
+| `--dct-continuous-tick-length`          | `legend.continuous.tick.length`          |
+| `--dct-continuous-label-rotate`         | `legend.continuous.label.rotate`         |
+| `--dct-continuous-label-size`           | `legend.continuous.label.size`           |
+| `--dct-continuous-label-weight`         | `legend.continuous.label.weight`         |
+| `--dct-continuous-label-overlap-rotate` | `legend.continuous.label.overlap.rotate` |
+
+### axis
+
+| CSS variable       | Config path  |
+| ------------------ | ------------ |
+| `--dct-axis-color` | `axis.color` |
+
+### tooltip
+
+| CSS variable           | Config path          |
+| ---------------------- | -------------------- |
+| `--dct-tooltip-bg`     | `tooltip.background` |
+| `--dct-tooltip-color`  | `tooltip.color`      |
+| `--dct-tooltip-size`   | `tooltip.fontSize`   |
+| `--dct-tooltip-pad`    | `tooltip.padding`    |
+| `--dct-tooltip-radius` | `tooltip.radius`     |
+| `--dct-tooltip-border` | `tooltip.border`     |
+
+### timeline
+
+| CSS variable                       | Config path                               |
+| ---------------------------------- | ----------------------------------------- |
+| `--dct-timeline-axis`              | `timeline.axisColor`                      |
+| `--dct-timeline-active`            | `timeline.activeColor`                    |
+| `--dct-timeline-gap`               | `timeline.gap`                            |
+| `--dct-player-bg`                  | `timeline.player.background`              |
+| `--dct-player-color`               | `timeline.player.color`                   |
+| `--dct-player-radius`              | `timeline.player.radius`                  |
+| `--dct-player-pad`                 | `timeline.player.padding`                 |
+| `--dct-player-gap`                 | `timeline.player.gap`                     |
+| `--dct-player-size`                | `timeline.player.fontSize`                |
+| `--dct-player-weight`              | `timeline.player.fontWeight`              |
+| `--dct-player-value-width`         | `timeline.player.valueWidth`              |
+| `--dct-player-button-size`         | `timeline.player.button.size`             |
+| `--dct-player-button-bg`           | `timeline.player.button.background`       |
+| `--dct-player-button-color`        | `timeline.player.button.color`            |
+| `--dct-player-button-hover-bg`     | `timeline.player.button.hoverBackground`  |
+| `--dct-player-button-radius`       | `timeline.player.button.radius`           |
+| `--dct-player-track-height`        | `timeline.player.track.height`            |
+| `--dct-player-track-color`         | `timeline.player.track.color`             |
+| `--dct-player-track-fill`          | `timeline.player.track.fillColor`         |
+| `--dct-player-track-radius`        | `timeline.player.track.radius`            |
+| `--dct-player-thumb-size`          | `timeline.player.thumb.size`              |
+| `--dct-player-thumb-color`         | `timeline.player.thumb.color`             |
+| `--dct-player-toggle-bg`           | `timeline.player.toggle.background`       |
+| `--dct-player-toggle-color`        | `timeline.player.toggle.color`            |
+| `--dct-player-toggle-active-bg`    | `timeline.player.toggle.activeBackground` |
+| `--dct-player-toggle-active-color` | `timeline.player.toggle.activeColor`      |
+| `--dct-player-toggle-radius`       | `timeline.player.toggle.radius`           |
+| `--dct-player-toggle-size`         | `timeline.player.toggle.fontSize`         |
+| `--dct-player-toggle-pad`          | `timeline.player.toggle.padding`          |
+
+### heatmap ramp
+
+| CSS variable      | Config path             |
+| ----------------- | ----------------------- |
+| `--dct-heat-min`  | `continuous.min`        |
+| `--dct-heat-max`  | `continuous.max`        |
+| `--dct-heat-text` | `continuous.labelColor` |
+
+### facet
+
+| CSS variable                       | Config path                       |
+| ---------------------------------- | --------------------------------- |
+| `--dct-facet-indicator-bg`         | `facet.indicator.background`      |
+| `--dct-facet-indicator-color`      | `facet.indicator.color`           |
+| `--dct-facet-indicator-size`       | `facet.indicator.fontSize`        |
+| `--dct-facet-indicator-pad`        | `facet.indicator.padding`         |
+| `--dct-facet-indicator-radius`     | `facet.indicator.radius`          |
+| `--dct-facet-nav-bg`               | `facet.navButton.background`      |
+| `--dct-facet-nav-color`            | `facet.navButton.color`           |
+| `--dct-facet-nav-btn-size`         | `facet.navButton.size`            |
+| `--dct-facet-nav-font-size`        | `facet.navButton.fontSize`        |
+| `--dct-facet-nav-disabled-opacity` | `facet.navButton.disabledOpacity` |

package/docs/timeline.md

@@ -0,0 +1,128 @@
+# Timeline
+
+`timeline` steps a plot through its data by a field - usually a year or a date. Each step shows the rows of one value of that field. It draws as a **player** by default - a control bar with play, pause and a slider - or as a **rule**, a guide beside the plot that the page drives (`type: 'rule'`).
+
+<!-- example: examples/TimelinePlayer.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+</script>
+
+<!--
+	`timeline` slices the rows by `accessor`. A timeline is a player by default:
+	play/pause, the current step and a slider in the chrome. `progress` sets where
+	it starts. `type: 'rule'` draws a guide beside the plot with no controls
+	instead (see TimelineRule). To build your own widget, read
+	`useFigure().timeline` (seek, play, pause, next, ...).
+-->
+<BarPlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="region"
+	y="value"
+	scales={{ y: { domain: [0, 30] } }}
+	timeline={{ accessor: 'date', progress: 0.25, player: { autoplay: false, loop: true } }}
+/>
+```
+
+<!-- /example -->
+
+![A bar plot with a player bar](images/timeline-player.png)
+
+## Options
+
+| Option                             | Meaning                                                                                                                                                                                                                                                                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `accessor`                         | Field (or function) giving each row's step - required. A number (a year, a count), a `Date`, or a date string: ISO (`'2023'`, `'2023-05'`, `'2023-05-17'`, with or without a time), or any other read through `dateFormat`. A row whose value reads as none shows at every step |
+| `dateFormat`                       | How a date string that is not ISO reads: the tokens `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, anything else literal (`'DD/MM/YYYY'`, `'MM-YYYY'`). A part it leaves out is the first: January, the 1st, midnight                                                                    |
+| `type`                             | `'player'` (default) draws a control bar in the chrome; `'rule'` draws a guide with the steps written along it                                                                                                                                                                  |
+| `progress`                         | The position, `0`-`1`. A player keeps its own position from there on, until `progress` changes                                                                                                                                                                                  |
+| `values`                           | The steps, when not every distinct value of `accessor` - read like `accessor`'s values                                                                                                                                                                                          |
+| `filterMode`                       | `'exact'` shows the rows of the current step; `'upTo'` shows every row up to it (a cumulative reveal). `LinePlot` defaults to `'upTo'`                                                                                                                                          |
+| `interpolate`                      | Tween values between steps so a scrub is smooth: `true`, or `{ key, value, create, progressEasing, segmentEasing }`. Line and bar plots default to interpolating their value channel                                                                                            |
+| `scales`                           | `'shared'` (default): axes span every step, so they hold still while scrubbing; `'free'` refits them to each step                                                                                                                                                               |
+| `onprogress`, `onvalue`            | Called with the new position (`0`-`1`) and with the step it lands on - a `Date` on a timeline of dates, else the number                                                                                                                                                         |
+| `orientation`, `show`, `thickness` | A rule's direction (`'vertical'` default, beside the plot; `'horizontal'`), visibility and size                                                                                                                                                                                 |
+
+## Player
+
+The player is a bar in the chrome, below the plot by default, placed like any other [chrome block](chrome.md) through `order` (`'timeline'`, or a row such as `'(plot, timeline)'`).
+
+```svelte
+<LinePlot
+	...
+	timeline={{
+		accessor: 'year',
+		player: {
+			controls: ['play', 'value', 'slider', 'speed', 'loop'],
+			autoplay: true,
+			loop: true,
+			speed: 1,
+			speeds: [0.5, 1, 2],
+			stepDuration: 800,
+			format: (year) => `Year ${year}`
+		}
+	}}
+/>
+```
+
+| `player` option               | Meaning                                                                                                                                                                                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `controls`                    | The controls drawn, in this order: `'play'`, `'value'`, `'slider'`, `'speed'`, `'loop'`                                                                                                                                                                    |
+| `autoplay`                    | Start playing as soon as there are steps                                                                                                                                                                                                                   |
+| `loop`, `speed`               | Where the player starts; it keeps them from there and tells `onloop` / `onspeed` on change                                                                                                                                                                 |
+| `speeds`                      | Speeds the speed control cycles through                                                                                                                                                                                                                    |
+| `stepDuration`                | Milliseconds per step at speed `1`                                                                                                                                                                                                                         |
+| `format`                      | How a step reads, in the `'value'` control and along a rule. It gets a `Date` on a timeline of dates, else the number. Defaults to the step itself; dates read as dates, as precise as the steps need (`2023`, `ene 2023`, `17 ene 2023`) in `axis.locale` |
+| `onplay`, `onspeed`, `onloop` | Change callbacks                                                                                                                                                                                                                                           |
+
+Defaults for `controls`, `speeds` and `stepDuration` come from `timeline.player` in the [configuration](theming.md), together with the bar's colors and sizes.
+
+## Rule
+
+`type: 'rule'` draws a line with its steps written along it, beside the plot. `progress` picks the step, and the page supplies the control (a slider, a button, scroll position):
+
+<!-- example: examples/TimelineRule.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './data';
+
+	// A rule has no controls of its own: the page moves it through `progress` (0 to 1).
+	// One step per year; a line plot shows every row up to the current step.
+	let progress = $state(0.5);
+</script>
+
+<input type="range" min="0" max="1" step="0.001" bind:value={progress} />
+<LinePlot
+	width={720}
+	height={400}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	color="region"
+	timeline={{ accessor: (row) => row.date.getUTCFullYear(), type: 'rule', progress }}
+/>
+```
+
+<!-- /example -->
+
+![A line plot revealed up to the current step, with a timeline rule](images/timeline-rule.png)
+
+A rule's look comes from `timeline.rule` in the [configuration](theming.md) (`fontSize`, `activeFontSize`, `axisWidth`, ...) and `--dct-timeline-*` variables.
+
+## Custom controls
+
+`useFigure().timeline` exposes the timeline's state and actions, to build a widget of your own in place of the player: `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. On a timeline of dates, `steps` and `value` are `Date`s and `seekValue` takes a `Date` or a date string. See [Reading plot state](state.md).
+
+## One timeline for several plots
+
+A [`PlotComposer`](composer.md) with its own `timeline` drives every panel from one control; plots inside it with a `timeline` follow its `progress`.
+
+## Maps
+
+`GeoPlot` slices both its features (reading a field from each feature's `properties`) and its markers' rows; features or rows without the field are drawn in every step.