@fundar/data-chart-telling 1.1.0 → 1.3.0

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
 

package/docs/styles-and-segments.md

@@ -21,7 +21,7 @@
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { PRICES } from './data';
+	import { PRICES } from './datasets';
 </script>
 
 <!-- End-of-line value labels with a custom format and font size. -->
@@ -46,14 +46,17 @@
 
 ![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                                                                          |
+| 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                                                                                                                                              |
+| `select`       | Which row of each group is labelled: `'first'`, `'last'`, `'min'`, `'max'`, or a list of them. A group is a series on a line or area plot (default `'last'`), a category on the plots that join dots (default: every dot) |
+| `series`       | Labels only these series, by name                                                                                                                                                                                         |
+| `color`        | `'series'` writes each label in its series' color; any other CSS color writes them all in it (`fontStyle.fill` wins)                                                                                                      |
+| `format`       | `(value, seriesName, row) => string`; `row` is the labelled row, for its other fields                                                                                                                                     |
+| `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).
 
@@ -70,14 +73,14 @@ A row whose value is `null`, `undefined` or `NaN` breaks a line. `styles.gaps` b
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { LIFE_GAPS } from './data';
+	import { FEMALE_LIFE_GAPS } from './datasets';
 </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 }]}
+	series={[{ name: 'female', x: 'year', y: 'value', data: FEMALE_LIFE_GAPS }]}
 	scales={{ x: { edgeTicks: true }, y: { domain: [55, 85] } }}
 	styles={{
 		gaps: {
@@ -116,6 +119,7 @@ type Range = { from?: AxisValue; to?: AxisValue }; // inclusive on both ends
 - 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).
+- `facet` limits the segment to the [facet panels](facets.md#markers-and-segments-in-some-panels) it names - a `by` value or a list of them. Without it the segment applies to every panel.
 
 The style shape depends on the plot:
 
@@ -137,7 +141,7 @@ A baseline color with a highlighted range:
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 
 	const gba = REGION_VALUES.filter((row) => row.region === 'GBA');
 </script>
@@ -170,7 +174,7 @@ Per-series colors, plus dots over a range shared by every series:
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { LIFE } from './data';
+	import { LIFE } from './datasets';
 </script>
 
 <!-- Segments per series name, plus `default` for rules shared by every series. -->
@@ -218,25 +222,25 @@ Heatmap columns and cells:
 ```svelte
 <script lang="ts">
 	import { HeatmapPlot } from '@fundar/data-chart-telling';
-	import { HOUSEHOLDS } from './data';
+	import { PENGUIN_COUNTS } from './datasets';
 </script>
 
-<!-- Segments on a heatmap: an outlined column and a filled block of overcrowded households. -->
+<!-- Segments on a heatmap: an outlined column and a filled block of cells. -->
 <HeatmapPlot
 	width={560}
 	height={360}
-	data={HOUSEHOLDS}
-	x="rooms"
-	y="people"
-	color="share"
+	data={PENGUIN_COUNTS}
+	x="island"
+	y="species"
+	color="count"
 	segments={{
 		default: [
 			{
-				areas: [{ x: { from: '1', to: '1' } }],
+				areas: [{ x: { from: 'Biscoe', to: 'Biscoe' } }],
 				styles: { stroke: '#f59e0b', strokeWidth: 2 }
 			},
 			{
-				areas: [{ x: { from: '1', to: '2' }, y: { from: '4', to: '5+' } }],
+				areas: [{ x: { from: 'Dream', to: 'Torgersen' }, y: { from: 'Chinstrap', to: 'Gentoo' } }],
 				styles: { fill: '#ef4444', fillOpacity: 0.8 }
 			}
 		]

package/docs/theming.md

@@ -31,26 +31,27 @@ resetConfiguration(); // back to the shipped defaults
 
 ## 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                                                                                                                                                                                                                                            |
+| Key                                                                                                                                                                 | Controls                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `font`, `color`, `background`                                                                                                                                       | Base text of every figure                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `palette`                                                                                                                                                           | Categorical series colors, in order: a list of colors, or the name of a [d3-scale-chromatic](https://d3js.org/d3-scale-chromatic) scheme - a color list (`'dark2'`, `'tableau10'`) or a ramp (`'viridis'`, `'blues'`) - or `{ scheme, count, schemeRange }` for a ramp with its own number of colors (8 by default) and part of the ramp (`[0.3, 1]` skips the near-white start of `'blues'`). A name is turned into the list of colors when it is set |
+| `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, the series `icon` (`rounded`, and the shape each mark draws as in `marks`), `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`, `density`, `violin`, `box`, `lollipop`, `dumbbell`, `cleveland`, `forest`, `bullet`, `slope`, `sparkline`, `scatter` | Per-kind defaults: line curve (`'auto'`, straight segments), stroke width, dot radius, series padding, gap fills, fill opacity, inset, density stroke width, violin padding and box width, box, lollipop, dumbbell, Cleveland and forest padding, stem width, forest caps, bullet bar thickness, ranges and target tick, slope stroke width, dot radius and padding, sparkline stroke width and dot radius                                             |
+| `text`                                                                                                                                                              | `declutter` geometry of value labels and connectors                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `connector`                                                                                                                                                         | What `styles.connector` falls back to on lollipop, dumbbell, Cleveland and forest plots: `sign` (`positive`, `negative`, `zero` colors), `lengthScheme` and `differenceScheme` (color ramps), `arrow` (`width`, `headLength`, `headAngle` of a connector drawn as an arrow), `outsideOpacity` (the part of a connector outside its `from`-`to` stretch), `capLength` (px, of a forest plot's end caps), `labelFontSize` and `labelGap`                 |
+| `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
 
@@ -70,6 +71,8 @@ setConfiguration({ axis: { locale: 'en-US', compactDisplay: 'long' } });
 setConfiguration({ axis: { edgeTicks: { x: { enabled: true, collision: 'extend' } } } });
 ```
 
+`axis.autoRotate` (default `true`) lets a category axis whose labels do not fit turn them to 45 or 90 degrees, and leave some out when that is not enough; an axis with its own `scales.x.tickRotate` is never touched, and `autoRotate: false` turns it off for every plot. It is read when a plot mounts.
+
 A plot overrides it with `scales.x.edgeTicks` or `scales.y.edgeTicks` (see [Scales](scales.md)).
 
 ## CSS variables