@fundar/data-chart-telling 1.1.0 → 1.2.0

package/docs/plots/ranking/cleveland.md

@@ -0,0 +1,54 @@
+# ClevelandPlot
+
+Part of [Plots](../../plots.md).
+
+The general form of the family: per category, one dot for each series that has a value there, joined by a connector from the lowest to the highest. A [`LollipopPlot`](lollipop.md) is its one-series case and a [`DumbbellPlot`](dumbbell.md) its two-series case, which check their series and point here when they need more. Categories on `x` stand the rows upright; on `y` they lie sideways.
+
+<!-- example: examples/Cleveland.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ClevelandPlot } from '@fundar/data-chart-telling';
+	import { AGE_SHARES } from './datasets';
+</script>
+
+<!-- One dot per census year in each age group, joined from the lowest share to the highest. The years follow one another, so they take a sequential blues ramp. -->
+<ClevelandPlot
+	width={720}
+	height={400}
+	data={AGE_SHARES}
+	x="share"
+	y="ageGroup"
+	grouping="year"
+	scales={{ color: { scheme: 'blues', schemeRange: [0.3, 1] } }}
+/>
+```
+
+<!-- /example -->
+
+![Cleveland dot plot of age group shares across census years](../../images/cleveland.png)
+
+- `grouping` (or `color`) gives one dot per group in each category. Numeric fields need `grouping` to split into series; `color` on a number draws a continuous ramp instead.
+- `scales.color.scheme: 'blues'` colors the series on a sequential ramp, which reads better than the default palette when the series follow one another, such as years; `schemeRange: [0.3, 1]` skips the ramp's near-white start.
+- The connector spans the lowest and the highest dot of each category, so a series the legend omits leaves the range.
+- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
+- Its defaults come from `cleveland` in the [configuration](../../theming.md): the connector is a neutral gray, 5 px thick.
+- `styles.values` writes each value: past the highest dot and the lowest of its category, and beside those between them. `select` (`'first'`, `'last'`, `'min'`, `'max'`, or a list) labels only those dots of each category, `series` only those series, and `color: 'series'` writes each label in its dot's series color. `format(value, seriesName, row)` also gets the row, so a label can name its category (see [Styles and segments](../../styles-and-segments.md#value-labels)).
+- `segments` restyle the dots of chosen categories, as in [`DumbbellPlot`](dumbbell.md).
+- The tooltip reads one category at a time, listing every series.
+
+## Connectors
+
+`styles.connector` styles the line each category draws between its dots, on `DumbbellPlot`, `ClevelandPlot` and `LollipopPlot`:
+
+| Field        | Meaning                                                                                                                                                                                                                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `from`, `to` | Where a difference runs between: `to` minus `from`. Each is a series name, `'first'` or `'last'` (the defaults), or `'min'` or `'max'` for the category's lowest and highest dot - `from: 'min', to: 'max'` makes the whole connector the stretch. On a lollipop, the value minus the baseline |
+| `width`      | Thickness in px, `'dots'` for a band as thick as the dots are wide, or a function of the connector                                                                                                                                                                                             |
+| `color`      | One color; `{ by: 'sign', positive, negative, zero }`; `{ by: 'difference' \| 'length', scheme, pivot, ... }` (a color scale, diverging around `pivot: 0` by default for a difference); or a function                                                                                          |
+| `opacity`    | 0-1, or a function of the connector                                                                                                                                                                                                                                                            |
+| `arrow`      | `true`, or `{ headLength, headAngle }`: draws the `from`-`to` stretch as an arrow pointing at the `to` dot, the way the value moved, instead of a line. It is as thick as `width` says, else `connector.arrow.width` in the configuration (2 px)                                               |
+| `outside`    | How the part of a connector outside the `from`-`to` stretch looks, where the dots of the other series lie: a color, or `{ color, opacity }`. Default: the neutral connector color, faded                                                                                                       |
+| `label`      | `true`, or `{ text, format, anchor, fontStyle }`: `text` is the `'difference'` (signed, the default), the `'length'`, or a function; `anchor` is `'outside'` (beside the connector) or `'middle'` (on it, for a thick one)                                                                     |
+
+With more than two series, the connector spans the lowest and the highest dot, but only the stretch between the `from` and `to` dots takes `color`, `opacity` and the label (centered on it); the rest is `outside`. A function gets the connector: `{ category, from, to, length, difference, span, series }`, `span` being that stretch. A lone dot's stem keeps its series' color unless `color` is set, and a segment's own `stroke` wins over both.

package/docs/plots/ranking/dumbbell.md

@@ -0,0 +1,39 @@
+# DumbbellPlot
+
+Part of [Plots](../../plots.md).
+
+Two dots per category, one for each of two series, joined by a connector: the gap between them is what the eye reads, such as a before and an after, or two groups. Categories on `x` stand the rows upright; on `y` they lie sideways. A plot with any other number of series warns and points to [`LollipopPlot`](lollipop.md) (one) or [`ClevelandPlot`](cleveland.md) (any number).
+
+<!-- example: examples/Dumbbell.svelte -->
+
+```svelte
+<script lang="ts">
+	import { DumbbellPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+</script>
+
+<!-- Two dots per province, one per sex, joined by a connector: the gap in life expectancy at birth. -->
+<DumbbellPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Dumbbell plot of life expectancy by province and sex](../../images/dumbbell.png)
+
+- `grouping` (or `color`) names the two series; the legend toggles them like any other.
+- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
+- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them, and `scales.x.sort` orders them by what they hold: `{ by: 'range' }` by the gap between their dots, `{ by: 'value', series }` by one series' value (see [Scales](../../scales.md)).
+- `r` sizes the dots by a field (`r="population"`; area follows the value, and the legend gets a size section) or fixes their radius in pixels (`r={8}`).
+- The connector is a neutral gray as thick as the dots are wide (`stemWidth: 'dots'`), a band; its default color and width, the dot radius and the padding come from `dumbbell` in the [configuration](../../theming.md). `styles.connector` restyles it per category (see [Connectors](cleveland.md#connectors)). `styles.connector.arrow` draws it as an arrow from one series to the other, pointing the way the value moved.
+- `styles.values` writes each value past its dot, away from the other one. A label past the lowest dot can reach the axis labels when that dot sits at the edge of the axis; pin `scales.y.domain` (or `x`) wide enough to leave it room.
+- `segments` restyle the dots of chosen categories (`styles: { dots: { dotRadius: 9 } }`, `areas: [{ x: { from: 'Salta', to: 'Salta' } }]`).
+- The tooltip reads one category at a time, listing its two values.

package/docs/plots/ranking/forest.md

@@ -0,0 +1,40 @@
+# ForestPlot
+
+Part of [Plots](../../plots.md).
+
+Per row, a dot - an estimate - on a stem that spans its interval: a mean with its range, a coefficient with its confidence interval. Each row gives its interval as `lower` and `upper` fields, or as an `error` that reaches that far either side of its value. Categories on `y` lie sideways, the usual way of a forest plot; on `x` they stand upright. It is a mode of [`ClevelandPlot`](cleveland.md): one row per category, and a plot with several warns and points to [`facet`](../../concepts.md) or `ClevelandPlot`.
+
+<!-- example: examples/Forest.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ForestPlot } from '@fundar/data-chart-telling';
+	import { INFLATION_RANGES } from './datasets';
+</script>
+
+<!-- One row per region and year: the mean monthly inflation as a dot, on a stem from its lowest to its highest month. -->
+<ForestPlot
+	width={720}
+	height={480}
+	data={INFLATION_RANGES}
+	x="mean"
+	y="period"
+	lower="min"
+	upper="max"
+	color="region"
+	scales={{ x: { label: 'Monthly inflation (%)' } }}
+/>
+```
+
+<!-- /example -->
+
+![Forest plot of monthly inflation by region and year](../../images/forest.png)
+
+- `lower` and `upper` name the fields of the interval's ends, `error` the half-width of an interval centered on the value. When both are given, `lower` and `upper` win; a row without an interval draws its dot alone, and an interval is widened to hold its value.
+- The value axis fits the intervals, not the estimates alone, without reaching for zero; pin `scales.x.domain` (or `y`) to start it at zero.
+- Rows keep the order the data gives them; `scales.y.sort` orders them: `{ by: 'value' }` by their estimate, `{ by: 'range' }` by the width of their interval, each across all rows or, with `grouped: true`, within each region (see [Scales](../../scales.md)).
+- The stem and its caps - a short tick across each end, on by default - come from `forest` and `connector` in the [configuration](../../theming.md). `styles.connector` restyles them (see [Connectors](cleveland.md#connectors)); `styles.connector.caps` is `false` to leave the stems open, or `{ length }` in pixels.
+- A reference line, such as the line of no effect, is a `rule` marker: `markers={[{ type: 'rule', axis: 'x', value: 0 }]}`.
+- `styles.values` writes each estimate beside its dot.
+- `segments` restyle the stems and dots of chosen rows.
+- The tooltip reads the hovered row.

package/docs/plots/ranking/lollipop.md

@@ -0,0 +1,39 @@
+# LollipopPlot
+
+Part of [Plots](../../plots.md).
+
+One value per category, drawn as a dot on a thin stem that rises from the baseline: a lighter alternative to bars when there are many categories. String values on `x` stand the lollipops upright; on `y` they lie sideways.
+
+<!-- example: examples/Lollipop.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LollipopPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+
+	const female = PROVINCE_VALUES.filter((row) => row.sex === 'female');
+</script>
+
+<!-- One dot on a stem per province: female life expectancy at birth, with its value beside it. -->
+<LollipopPlot
+	width={720}
+	height={400}
+	data={female}
+	x="value"
+	y="province"
+	scales={{ x: { domain: [70, 85] } }}
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Lollipop plot of life expectancy by province](../../images/lollipop.png)
+
+- `grouping` (or `color`) draws one set of lollipops per group, as long as each category has a value in only one of them - coloring by the category field itself is the usual case. A category with values in several groups warns: that is a [`DumbbellPlot`](dumbbell.md) (two) or a [`ClevelandPlot`](cleveland.md) (any number).
+- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them, and `scales.x.sort` orders them by what they hold: `{ by: 'range' }` by the gap between their dots, `{ by: 'value', series }` by one series' value (see [Scales](../../scales.md)).
+- The value axis reaches zero, where the stems start; pinning `scales.y.domain` moves the baseline to the nearest end of it, and a negative value hangs below zero.
+- `scales.x.paddingInner` / `paddingOuter` set the room around each lollipop; the defaults, with the dot radius and the stem width (a thin 2 px line), come from `lollipop` in the [configuration](../../theming.md).
+- `styles.values` writes each value just past its dot.
+- `segments` restyle whole categories: `styles: { stroke: {...}, dots: {...} }` restyle their stems and dots (`areas: [{ x: { from: 'Salta', to: 'Salta' } }]`).
+- The tooltip reads one lollipop at a time, along the category axis.

package/docs/plots.md

@@ -1,284 +1,26 @@
 # Plots
 
-Nine 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`                                      |
-| [`BoxPlot`](#boxplot)             | The distribution of values per category | a category channel and a value channel          |
-| [`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))                     |
+Every plot kind shares one set of props (see [Concepts](concepts.md)). They differ in what they draw, which channels they need and how they hover.
+
+| Category     | Plot                                             | Draws                                                          | Needs                                                   |
+| ------------ | ------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------- |
+| Distribution | [DensityPlot](plots/distribution/density.md)     | A smoothed distribution of a numeric field                     | `x` or `y`                                              |
+| Distribution | [HistogramPlot](plots/distribution/histogram.md) | Counts of a numeric field in bins                              | `x` or `y`                                              |
+| Distribution | [BoxPlot](plots/distribution/box.md)             | The distribution of values per category                        | a category channel and a value channel                  |
+| Distribution | [ViolinPlot](plots/distribution/violin.md)       | The mirrored density of values per category, with a box inside | a category channel and a value channel                  |
+| Distribution | [PyramidPlot](plots/distribution/pyramid.md)     | Two series mirrored around zero                                | a category channel, a value channel, two series         |
+| Correlation  | [HeatmapPlot](plots/correlation/heatmap.md)      | A grid of colored cells                                        | `x`, `y`, `color`                                       |
+| Correlation  | [ScatterPlot](plots/correlation/scatter.md)      | A point per row                                                | `x`, `y`                                                |
+| Ranking      | [BarPlot](plots/ranking/bar.md)                  | Bars, grouped, stacked or horizontal                           | a category channel and a value channel                  |
+| Ranking      | [BulletPlot](plots/ranking/bullet.md)            | A bar against a target, over graded ranges                     | a category channel, a value channel, `target`, `ranges` |
+| Ranking      | [LollipopPlot](plots/ranking/lollipop.md)        | One dot on a stem per category                                 | a category channel and a value channel                  |
+| Ranking      | [DumbbellPlot](plots/ranking/dumbbell.md)        | Two dots per category, joined                                  | a category channel, a value channel, two series         |
+| Ranking      | [ClevelandPlot](plots/ranking/cleveland.md)      | Any number of dots per category, joined                        | a category channel, a value channel, a series per dot   |
+| Ranking      | [ForestPlot](plots/ranking/forest.md)            | One dot on an interval per row                                 | a category channel, a value channel, `lower`/`upper`    |
+| Evolution    | [LinePlot](plots/evolution/line.md)              | A line per series                                              | `x`, `y`                                                |
+| Evolution    | [AreaPlot](plots/evolution/area.md)              | A filled area per series                                       | `x`, `y`                                                |
+| Evolution    | [SparklinePlot](plots/evolution/sparkline.md)    | A small line with its last value, no axes                      | `x`, `y`                                                |
+| Evolution    | [SlopePlot](plots/evolution/slope.md)            | A line per series between two positions                        | a category channel with two values, a value channel     |
+| Map          | [GeoPlot](geo.md)                                | 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).
-
-<!-- example: examples/LineDates.svelte -->
-
-```svelte
-<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}` } }}
-/>
-```
-
-<!-- /example -->
-
-![A line plot with end-of-line labels](images/line-dates.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.
-
-<!-- example: examples/StackedArea.svelte -->
-
-```svelte
-<script lang="ts">
-	import { AreaPlot } from '@fundar/data-chart-telling';
-	import { AGE_SHARES } from './data';
-</script>
-
-<!-- Each age group's share of the population, stacked with `stackY` so the bands add up to 100%. -->
-<AreaPlot
-	width={720}
-	height={400}
-	data={AGE_SHARES}
-	x="year"
-	y="share"
-	color="ageGroup"
-	scales={{ x: { ticks: [1991, 2001, 2010, 2022] } }}
-	transforms={[{ type: 'stackY' }]}
-/>
-```
-
-<!-- /example -->
-
-![A stacked area plot](images/stacked-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.
-
-<!-- example: examples/GroupedBars.svelte -->
-
-```svelte
-<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] } }}
-/>
-```
-
-<!-- /example -->
-
-![Vertical grouped bars](images/grouped-bars.png)
-
-<!-- example: examples/HorizontalBars.svelte -->
-
-```svelte
-<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] } }}
-/>
-```
-
-<!-- /example -->
-
-![Horizontal grouped bars](images/horizontal-bars.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.
-
-<!-- example: examples/Histogram.svelte -->
-
-```svelte
-<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 } }] }}
-/>
-```
-
-<!-- /example -->
-
-![Two overlapping histograms](images/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.
-
-## BoxPlot
-
-Summarizes the values of each series per category as a box: it spans the middle half of the values (25th to 75th percentile), the line across it is the median, the whiskers reach the farthest values within 1.5 times the box's height, and dots mark the values past them. String values on `x` stand the boxes upright; on `y` they lie sideways.
-
-<!-- example: examples/Box.svelte -->
-
-```svelte
-<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" />
-```
-
-<!-- /example -->
-
-![Box plots of two height distributions](images/box.png)
-
-- `grouping` (or `color`) draws one box per group and category. Groups that share categories draw their boxes on top of each other, so split them with `facet` instead, or color by the category field itself.
-- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them.
-- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
-- `scales.x.paddingInner` / `paddingOuter` set how wide the boxes are; the defaults come from `box` in the [configuration](theming.md).
-- The tooltip reads one box at a time, not every value inside it: the hovered row carries `category`, `min`, `p25`, `median`, `p75`, `max`, `count` and `outliers`.
-- `segments` restyle whole categories (`areas: [{ x: { from: 'Bus', to: 'Bus' } }]`). A segment that splits one category's values draws two boxes.
-
-## HeatmapPlot
-
-A grid of cells, `x` and `y` being the categories of the columns and rows and `color` the value that colors each cell.
-
-<!-- example: examples/Heatmap.svelte -->
-
-```svelte
-<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" />
-```
-
-<!-- /example -->
-
-![A heatmap with value labels](images/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.
-
-<!-- example: examples/Pyramid.svelte -->
-
-```svelte
-<script lang="ts">
-	import { PyramidPlot } from '@fundar/data-chart-telling';
-	import { AGES } from './data';
-</script>
-
-<!-- A population pyramid: one side per `color` value. -->
-<PyramidPlot width={720} height={400} data={AGES} x="share" y="ageGroup" color="sex" />
-```
-
-<!-- /example -->
-
-![A population pyramid](images/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.
-
-<!-- example: examples/Scatter.svelte -->
-
-```svelte
-<script lang="ts">
-	import { ScatterPlot } from '@fundar/data-chart-telling';
-	import { COUNTRIES } from './data';
-</script>
-
-<!-- Points sized by `r`, colored by `color` and shaped by `symbol`. -->
-<ScatterPlot
-	width={720}
-	height={420}
-	data={COUNTRIES}
-	x="gdp"
-	y="life"
-	r="population"
-	color="continent"
-	symbol="income"
-/>
-```
-
-<!-- /example -->
-
-![A scatter plot sized, colored and shaped by channels](images/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

@@ -7,7 +7,7 @@
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { PRICES } from './data';
+	import { PRICES } from './datasets';
 </script>
 
 <!-- Axis labels, a fixed domain with gridlines and a color per series. -->
@@ -41,21 +41,26 @@
 
 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                                                                                                                                                                                                                                                                                                                                                      |
-| `niceTolerance`                                                              | How far past a tick, as a share of the step, a domain the plot nices itself still ends on it (default `0.05`), so parts adding up to `100.2` stay at `100`. Applies to stacked and ranged axes, axes grown to cover markers or a transform's output, a bar plot's value axis and shared facet/timeline domains; `0` rounds like d3                                                              |
-| `edgeTicks`                                                                  | Ticks at the data's first and last values beside the nice ones. `false` turns them off, `true` on, `{ collision: 'drop-nice' \| 'drop-edge' \| 'extend' }` picks what happens when one crowds a nice tick. Defaults to `axis.edgeTicks.x` / `.y` in the [configuration](theming.md#edge-ticks) (on for x, off for y); ignored when the axis sets `ticks`, `tickSpacing`, `interval` or `domain` |
-| `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                                                                                                                                                                                                                                                                                                                              |
+| 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`, `zero`, `clamp`, `round`, `percent`                               | Direction, rounding and baseline behaviour                                                                                                                                                                                                                                                                                                                                                                                           |
+| `nice`                                                                       | `true` or `false` to round the domain out to round numbers or not, or `{ tolerance }`: how far past a tick, as a share of the step, a domain the plot nices itself still ends on it (default `0.05`), so parts adding up to `100.2` stay at `100`. Applies to stacked and ranged axes, axes grown to cover markers or a transform's output, a bar plot's value axis and shared facet/timeline domains; `tolerance: 0` rounds like d3 |
+| `edgeTicks`                                                                  | Ticks at the data's first and last values beside the nice ones. `false` turns them off, `true` on, `{ collision: 'drop-nice' \| 'drop-edge' \| 'extend' }` picks what happens when one crowds a nice tick. Defaults to `axis.edgeTicks.x` / `.y` in the [configuration](theming.md#edge-ticks) (on for x, off for y); ignored when the axis sets `ticks`, `tickSpacing`, `interval` or `domain`                                      |
+| `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`                                               | Time/discrete intervals, log base, symlog constant                                                                                                                                                                                                                                                                                                                                                                                   |
+| `sort`                                                                       | Category order: a comparator of two rows, or by what the categories hold (below)                                                                                                                                                                                                                                                                                                                                                     |
+
+A category axis whose labels do not fit side by side turns them by itself: to 45 degrees, else to 90, and when even that is not enough it writes only every few labels (and a vertical category axis, such as the one of horizontal bars, does the same). The margin grows to fit the turned labels. An axis with a `tickRotate` of its own - 0 included, which keeps the labels flat - is left as the author set it, and `axis.autoRotate: false` in the [configuration](theming.md) turns this off for every plot.
+
+A category axis can be ordered by what its categories hold, without writing a comparator: `sort: { by: 'value', series?, order? }` orders them by their value in one `series` (or, without it, by the sum of their values) and `sort: { by: 'range', order? }` by the spread between their lowest and their highest value; `order` is `'ascending'` (default) or `'descending'`. `grouped: true` orders within each series instead of across all of them: the series stay together, in the order they first appear. On a plot with intervals (`lower`/`upper`) the range counts the interval's ends. A category with nothing to order by goes last. An explicit `domain` wins. With [facets](facets.md) the order is read off every panel's rows, so the panels share it.
 
 Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in the [configuration](theming.md#locale).
 
@@ -63,20 +68,21 @@ Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in
 
 `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`)                                                                                                                                          |
+| 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>` |
+| `schemeRange` | The part of a named `scheme` to use, as `[from, to]` fractions of it (default `[0, 1]`): `[0.3, 1]` skips the near-white start of a ramp like `'blues'`                                        |
+| `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 continuous ramp is set with `scheme: [colorA, colorB]`. Categorical colors come from the configuration's `palette` unless `scheme` is a category-to-color record. Series that follow one another (years, say) read better on a named sequential ramp, which is sampled across the series in order: `scheme: 'blues', schemeRange: [0.3, 1]`.
 
 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.
+`scales.grouping.reverse` flips which group sorts first, such as which side of a [pyramid](plots/distribution/pyramid.md) a series sits on.
 
 ## Opacity