@fundar/data-chart-telling 0.0.63 → 1.0.0

package/docs/plots.md

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

package/docs/scales.md

@@ -0,0 +1,78 @@
+# Scales
+
+`scales` configures how data values become positions and visual properties. It has one entry per channel.
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="date"
+	y="index"
+	color="division"
+	scales={{
+		x: { label: 'Month' },
+		y: { label: 'Index (Jan 2021 = 100)', domain: [90, 280], grid: true },
+		color: {
+			scheme: { Food: '#1b9e77', Transport: '#d95f02', Housing: '#7570b3', Health: '#e7298a' }
+		}
+	}}
+/>
+```
+
+![A line plot with a labelled axis, gridlines and custom colors](images/scales.png)
+
+## Axes: `x` and `y`
+
+Each axis takes an `AxisScale`.
+
+| Field                                                                        | Meaning                                                                                                                                                                                                                       |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                                                                       | `'auto'` (default), `'linear'`, `'pow'`, `'sqrt'`, `'log'`, `'symlog'`, `'time'`, `'utc'`, `'band'`, `'point'`, `'ordinal'`, `'categorical'` and the color-oriented types (`'sequential'`, `'diverging'`, `'threshold'`, ...) |
+| `domain`, `range`                                                            | Explicit input and output extent                                                                                                                                                                                              |
+| `reverse`, `nice`, `zero`, `clamp`, `round`, `percent`                       | Direction, rounding and baseline behaviour                                                                                                                                                                                    |
+| `label`, `labelAnchor`, `labelOrientation`, `labelPosition`, `titleFontSize` | The axis title (`label: false` hides it)                                                                                                                                                                                      |
+| `ticks`, `tickSpacing`, `tickSize`, `tickPadding`, `tickRotate`              | Tick placement and size                                                                                                                                                                                                       |
+| `tickFormat`                                                                 | `false`, an `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object, or `(d, index, ticks) => string`                                                                                                                |
+| `grid`                                                                       | `true` or a stroke style for gridlines                                                                                                                                                                                        |
+| `axisDisplay`                                                                | `'visible'` (default), `'hidden'` (keeps the space, so aligned panels stay aligned) or `'none'`                                                                                                                               |
+| `padding`, `paddingInner`, `paddingOuter`, `align`                           | Band and point spacing                                                                                                                                                                                                        |
+| `insetLeft`, `insetRight`, `insetTop`, `insetBottom`                         | Pixels kept free at each end                                                                                                                                                                                                  |
+| `interval`, `base`, `constant`, `sort`                                       | Time/discrete intervals, log base, symlog constant, category order                                                                                                                                                            |
+
+Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in the [configuration](theming.md#locale).
+
+## Color
+
+`scales.color` configures the `color` channel (and a choropleth on a map).
+
+| Field     | Meaning                                                                                                                                                                                        |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `domain`  | `[min, max]` for a continuous value, or the list of categories                                                                                                                                 |
+| `scheme`  | A named [d3-scale-chromatic](https://d3js.org/d3-scale-chromatic) ramp (`'turbo'`, `'blues'`, `'rdylbu'`, case-insensitive), two or more colors to interpolate, or a `Record<category, color>` |
+| `pivot`   | Splits an array `scheme` into two halves meeting at this value (a diverging ramp)                                                                                                              |
+| `unknown` | Color of a value outside the mapping (default `#ccc`)                                                                                                                                          |
+
+A continuous ramp is set with `scheme: [colorA, colorB]`. Categorical colors come from the configuration's `palette` unless `scheme` is a category-to-color record.
+
+A marker can carry its own `scales.color`, independent of the plot's, so two ramps can coexist in one plot.
+
+## Grouping
+
+`scales.grouping.reverse` flips which group sorts first, such as which side of a [pyramid](plots.md#pyramidplot) a series sits on.
+
+## Opacity
+
+`scales.opacity` maps a value to an opacity: `domain` (`[min, max]` or categories), `range` (`[minOpacity, maxOpacity]` or a category-to-opacity record), `unknown`.
+
+## Symbol
+
+`scales.symbol` maps categories to shapes: `domain`, `range` (a list of `SymbolType` cycled in order, or a record), `unknown`. The default shape cycle is `symbols` in the configuration.
+
+## Radius and length
+
+`scales.r` (dot radius) and `scales.length` (vector length) take `domain: [min, max]` and `range: [minPx, maxPx]`. The radius scale is a square-root scale, so a dot's area follows its value; hand it raw values, not pre-scaled radii.
+
+## Shared and free scales
+
+[Facets](facets.md) and [timelines](timeline.md) share scales across panels or steps by default so panels stay comparable; each has an option to refit per panel or step.

package/docs/state.md

@@ -0,0 +1,71 @@
+# Reading plot state
+
+A plot's state - its hover, legend, timeline, margins, scales, rows and size - can be read from anything drawn with it, to build custom UI. Both hooks are read-only, except for the legend (series can be turned on and off) and the timeline (it can be played and moved). Call them while a component initializes; outside a plot or a figure they throw.
+
+## `useFigure()`
+
+Works anywhere inside a figure, including the `header`, `footer` and `content` snippets of a plot or composer. It returns:
+
+- `hover` - `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` (the id of the plot owning the hover).
+- `legend` (or `null`) - `entries`, `range`, `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes.
+- `timeline` (or `null`) - `enabled`, `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, `controls`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`.
+
+A footer that toggles series through the legend:
+
+```svelte
+<!-- FigureReadout.svelte -->
+<script lang="ts">
+	import { useFigure } from '@fundar/data-chart-telling';
+
+	const figure = useFigure();
+	const series = $derived(
+		(figure.legend?.entries ?? []).flatMap((e) => (e.type === 'series' ? [e] : []))
+	);
+</script>
+
+{#each series as entry (entry.name)}
+	<button onclick={() => figure.legend?.toggle(entry.name, { mode: 'omit' })}>
+		{figure.legend?.isOff(entry.name) ? 'Show' : 'Hide'}
+		{entry.name}
+	</button>
+{/each}
+```
+
+```svelte
+{#snippet footer()}<FigureReadout />{/snippet}
+<LinePlot data={rows} x="year" y="value" color="sex" tooltip {footer} />
+```
+
+## `usePlot()`
+
+Works inside a plot - in a [`component` marker](markers.md#custom-components), which is mounted in the plot's SVG. It returns everything `useFigure()` does, plus:
+
+- `hover.points`, `hover.activePoint`, `hover.tooltip` (`visible`, `position`, `rows`) for this plot;
+- `margins`, `scales`, `axes`, `data`, `width`, `height`;
+- `svelteplot` - svelteplot's own `usePlot()` state for this plot.
+
+```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 }]}
+/>
+```
+
+## When to use them
+
+Reach for these instead of re-implementing a legend, a timeline control or a hover readout beside the plot: the figure already holds that state, and a widget reading it stays in step with the plot. [examples/LegendReader.svelte](../examples/LegendReader.svelte) is a runnable reader, and the Storybook group _Configuration / State_ has both patterns.

package/docs/styles-and-segments.md

@@ -0,0 +1,215 @@
+# 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
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={rows}
+	x="date"
+	y="index"
+	color="division"
+	styles={{
+		values: {
+			show: true,
+			format: (value, seriesName) => `${seriesName}: ${value.toFixed(0)}`,
+			fontStyle: { fontSize: 13 }
+		}
+	}}
+/>
+```
+
+![End-of-line value labels](images/styles-values.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).
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	series={[{ name: 'female', x: 'year', y: 'value', data: rowsWithHoles }]}
+	styles={{
+		gaps: {
+			default: {
+				middle: { interpolate: 'linear', style: { stroke: { strokeDasharray: '4 4' } } },
+				start: { x: 2007, style: { stroke: { strokeOpacity: 0.4 } } },
+				end: { x: 2023, y: 85 }
+			}
+		}
+	}}
+/>
+```
+
+![A line bridged across missing values with dashed segments](images/styles-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:
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	series={[{ name: 'gdp', x: 'year', y: 'value', data: gdp }]}
+	segments={{
+		gdp: [
+			{ styles: { stroke: { stroke: '#94a3b8', strokeWidth: 1 } } },
+			{
+				areas: [{ x: { from: 2008, to: 2010 } }],
+				styles: { stroke: { stroke: '#ef4444', strokeWidth: 3 } }
+			}
+		]
+	}}
+/>
+```
+
+![A grey line with a highlighted red range](images/segments-highlight.png)
+
+Per-series colors, plus dots over a range shared by every series:
+
+```svelte
+<LinePlot
+	{width}
+	{height}
+	data={lifeExpectancy}
+	x="year"
+	y="value"
+	color="sex"
+	segments={{
+		female: [{ styles: { stroke: { stroke: 'steelblue' } } }],
+		male: [{ styles: { stroke: { stroke: 'tomato' } } }],
+		default: [
+			{
+				areas: [{ x: { from: 2010, to: 2012 } }],
+				styles: { dots: { dotRadius: 5, dotSymbol: 'circle' } }
+			}
+		]
+	}}
+/>
+```
+
+![Two series colored individually, with dots on a shared range](images/segments-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:
+
+```svelte
+<HeatmapPlot
+	{width}
+	{height}
+	{data}
+	x="quarter"
+	y="product"
+	color="sales"
+	segments={{
+		default: [
+			{
+				areas: [{ x: { from: 'Q1', to: 'Q1' } }, { x: { from: 'Q3', to: 'Q3' } }],
+				styles: { stroke: '#f59e0b', strokeWidth: 2 }
+			},
+			{
+				areas: [{ x: { from: 'Q2', to: 'Q2' }, y: { from: 'Alpha', to: 'Beta' } }],
+				styles: { fill: '#ef4444', fillOpacity: 0.8 }
+			}
+		]
+	}}
+/>
+```
+
+![A heatmap with highlighted columns and cells](images/segments-heatmap.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.