@fundar/data-chart-telling 1.15.0 → 1.17.0

package/docs/markers.md

@@ -68,32 +68,32 @@ Many markers also take channel fields (`color`, `fill`, `opacity`, `r`, `symbol`
 
 ## Catalog for axis-based plots
 
-| `type`                                                   | Draws                                                                                                                                                                                                            |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                                                                                                                                   |
-| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins`                                                                                                     |
-| `line`                                                   | A line through the rows                                                                                                                                                                                          |
-| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (a list draws a line at each, or a function with `data`), `styles`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
-| `tick`                                                   | A short tick per row along one axis                                                                                                                                                                              |
-| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                                                                                                                              |
-| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges                                                                                                                                       |
-| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                                                                                                                                   |
-| `difference`                                             | The area between two series, colored by which one is on top                                                                                                                                                      |
-| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row                                              |
-| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                                                                                                                       |
-| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position - or at each of a list of them, `at: [1980, 2000]` - as a line and a label                                                         |
-| `hull`                                                   | The convex hull around a cluster of points                                                                                                                                                                       |
-| `density`                                                | 2D density contour bands                                                                                                                                                                                         |
-| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band                                                          |
-| `violin`                                                 | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside                                 |
-| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                                                                                                                            |
-| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                                                                                                                                   |
-| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                                                                                                                         |
-| `image`                                                  | An image per row; `src`, `width`, `height`                                                                                                                                                                       |
-| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                                                                                                                              |
-| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                                                                                                                          |
-| `hover`                                                  | The in-plot hover highlight (see below)                                                                                                                                                                          |
-| `component`                                              | Your own Svelte component (see below)                                                                                                                                                                            |
+| `type`                                                   | Draws                                                                                                                                                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dot`                                                    | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`)                                                                                                                                      |
+| `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins`, `fit`                                                                                 |
+| `line`                                                   | A line through the rows                                                                                                                                                                             |
+| `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (a list draws a line at each, or a function with `data`), `styles` (`StrokeStyle`, and `inset`, `insetTop`, ... to pull it in from its ends)          |
+| `tick`                                                   | A short tick per row along one axis                                                                                                                                                                 |
+| `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                                                                                                                 |
+| `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges; `styles` (`AreaStyle`, and `inset`, `insetLeft`, ...); `label`, a text in each (`cell`, `bar` and `waffle` take it too) |
+| `area`                                                   | A filled area under a curve, or between `y1` and `y2`; `curve`                                                                                                                                      |
+| `difference`                                             | The area between two series, colored by which one is on top                                                                                                                                         |
+| `arrow`                                                  | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`, `styles` (`StrokeStyle`, and `inset`, `insetStart`, `insetEnd`)                                                                |
+| `trail`                                                  | A variable-width ribbon along a path, its width set by `r`                                                                                                                                          |
+| `delta`                                                  | The distance between two series (or a series and a fixed value) at a position - or at each of a list of them, `at: [1980, 2000]` - as a line and a label                                            |
+| `hull`                                                   | The convex hull around a cluster of points                                                                                                                                                          |
+| `density`                                                | 2D density contour bands                                                                                                                                                                            |
+| `box`                                                    | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band                                             |
+| `violin`                                                 | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside                    |
+| `regression`, `bollinger`                                | A fitted curve, a moving-average band                                                                                                                                                               |
+| `waffle`                                                 | The value as a grid of unit squares; `unit`, `multiple`, `gap`                                                                                                                                      |
+| `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation                                                                                                                                                            |
+| `image`                                                  | An image per row; `src`, `width`, `height`                                                                                                                                                          |
+| `raster`                                                 | A field sampled over a rectangle, drawn to a canvas                                                                                                                                                 |
+| `brush`                                                  | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend`                                                                                                                             |
+| `hover`                                                  | The in-plot hover highlight (see below)                                                                                                                                                             |
+| `component`                                              | Your own Svelte component (see below)                                                                                                                                                               |
 
 ## Markers in some facets
 
@@ -127,6 +127,56 @@ Every other marker draws from `data` rows, one mark per row, so it already takes
 
 `{ type: 'hover' }` draws a crosshair, a dot and a label at the hovered point. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `ruleX`, `ruleY`, `areaX`, `areaY` (a band highlight on band scales), `showLabels`, `format`, the number fields `decimals`, `prefix`, `suffix` and `signDisplay` (they write the label's value; `format` gets a `number` function that does the same), and the styles `rule`, `area`, `dot`, `text`. See [Tooltip and hover](tooltip-and-hover.md).
 
+## Styles that depend on the row
+
+Everything a marker is drawn with goes in its `styles` - its colors, strokes and insets - and none of it sits beside `type`, `data` and the channels.
+
+On the markers that draw a shape for each row - `rect`, `bar`, `cell`, `waffle`, `dot`, `tick`, `rule`, `arrow`, `voronoi` and `delaunayLink` - any field of `styles` can be a function of the row in place of a value, so each shape gets its own (`rect`, `cell`, `rule` and `arrow` take the insets that way too; `bar`'s are fractions of its band, the same for all):
+
+```ts
+{ type: 'rect', data: eras, x1: 'from', x2: 'to', y1: 0, y2: 100,
+  styles: { fill: 'steelblue', fillOpacity: (era) => (era.name === locked ? 0.55 : 0.12) } }
+```
+
+A color or an opacity the function returns is drawn as it is, not mapped through a scale. Where the function would only read a field, name the field: a number (`strokeWidth`, `fillOpacity`, an inset...) given as a string is the field of the rows, and so is a color when the rows have a field of that name - `fill: 'tint'` reads `row.tint`, but `fill: 'tomato'` is the color unless some row has a `tomato` field. A `text` marker does the same with `fill`, `fillOpacity`, `stroke`, `strokeWidth`, `fontWeight` and `fontStyle`; the other fields place and measure the labels, so they are one value for all. The markers that draw one shape for many rows (`line`, `area`, `density`, `hull`, a mesh) take plain values.
+
+## A label in each shape
+
+A `rect`, `cell`, `bar` or `waffle` marker takes a `label`: a text written in the middle of each shape, with every option of a `text` marker but `type`, `data`, `x` and `y`, which the shape sets. It never takes the pointer from the shape under it, so `onclick` and the hover go on as they were.
+
+```ts
+{ type: 'rect', data: tiles, x1: 'x1', x2: 'x2', y1: 'y1', y2: 'y2',
+  label: { text: 'name', styles: { fill: 'white' }, fit: { fallback: 'value' } } }
+```
+
+`anchor` puts the label against an edge (`'top'`, `'bottom'`, `'left'`, `'right'`) or in a corner (`'top-left'`...) instead of the middle, and `outside` puts one anchored to an edge beyond it; `gap` is its distance from the edge. A label outside is not fitted, and `fitMargins: true` grows the plot's margins to hold it where it would run past them. A label with a handler of its own (`onpointerenter`...) listens for the pointer; the others leave it to the shape. Its styles take functions of the row, to dim the label of a series, say. A label inside its shape with no `fill` of its own is written in the color that reads best on the shape's own - white on a dark one, near black on a light one - picked per row from the configuration's `text.label.contrast` (`['#ffffff', '#111827']`), or white or black where neither reaches the WCAG AA ratio of 4.5:1. The shape is read as it is seen: a `fillOpacity` under 1 blends it with the plot's `background`. One outside keeps its plot's color.
+
+The label is fitted to its shape unless `fit` is `false`. One too big is written smaller, down to `minFontSize`; at that size it breaks into the lines the shape holds and the last one is cut short with an ellipsis; when fewer than `minLetters` letters would show, `fallback` - a value, a field or a function of the row - is written instead; and when not even that fits, nothing is. `padding` is the room kept free inside each edge. The defaults of `gap`, `padding`, `minFontSize` (8) and `minLetters` (3) are the configuration's `text.label`: `setConfiguration({ text: { label: { gap: 6 } } })`. A `text` marker of your own takes the same `fit` with a box of its own (`x1`, `x2`, `y1`, `y2`), which is rarely what you want.
+
+## Events
+
+Every marker takes handlers for the pointer:
+
+```svelte
+<LinePlot
+	...
+	markers={[
+		{
+			type: 'rect',
+			data: eras,
+			x1: 'from',
+			x2: 'to',
+			y1: 0,
+			y2: 100,
+			onclick: (event, era) => select(era)
+		}
+	]}
+/>
+```
+
+- `onclick`, `ondblclick`, `oncontextmenu`, `onpointerdown`, `onpointerup`, `onpointerenter`, `onpointerleave`, `onpointermove`, `onmouseenter` and `onmouseleave` are called with the event, the row the shape draws and its index.
+- Every marker that draws a svelteplot shape takes them (`brush`, `hover`, `inset`, `delta` and the map's `features` and `geo-hover` have events of their own). svelteplot documents them on all its marks, but its code wires them up on some only today: `rect`, `bar`, `cell`, `area`, `arrow`, `dot`, `trail`, `vector`, `link`, `line`, `delaunayLink` and `voronoi`. On the others they do nothing yet.
+
 ## Custom components
 
 `{ type: 'component', component: MyMark, props: { ... } }` mounts a Svelte component inside the plot's SVG. It can read the plot it is in with [`usePlot()`](state.md), so it can draw from the plot's scales, margins, hover and rows.

package/docs/plots/part-of-a-whole/treemap.md

@@ -0,0 +1,69 @@
+# TreemapPlot
+
+Part of [Plots](../../plots.md).
+
+A part-to-whole made of rectangles: each row is a tile whose **area** is its `value`, and the tiles are nested by `grouping`, so a group's tiles sit together. `value` is the field (or function) giving a tile's size; the last level of `grouping` names it. The plot is the [`treemap` transform](../../transforms-and-statistics.md) drawn as `rect` markers, each with a `label`.
+
+<!-- example: examples/Treemap.svelte -->
+
+```svelte
+<script lang="ts">
+	import { TreemapPlot } from '@fundar/data-chart-telling';
+	import { ACTIVITY_BRANCHES } from './datasets';
+</script>
+
+<!-- One tile per branch, sized by its value and colored by its sector. -->
+<TreemapPlot
+	width={760}
+	height={440}
+	data={ACTIVITY_BRANCHES}
+	value="value"
+	grouping="sector.branch"
+/>
+```
+
+<!-- /example -->
+
+![A treemap of branches of activity, sized by value and colored by sector](../../images/treemap.png)
+
+- A row without a positive `value` has no tile.
+- `grouping` is the **whole path** of a tile, its fields joined by dots, outermost first: `grouping="sector.kind.branch"` nests the tiles by sector, then by kind, and names each one after its branch. A function is a single level. Rows with the same path are one tile, their values added up, so `grouping="sector"` alone makes three big tiles. The outermost level colors the tiles and is what the [legend](../../legend.md) lists; `scales.color` sets the colors, as in any plot. Without `grouping`, `color` groups the tiles, as it groups the series of any plot. `scales.color.depth` colors deeper levels as tones of their sector's color: `2` a tone per kind, `3` per branch (see [Scales](../../scales.md#color)).
+- How a rectangle is split among its tiles is an option of the plot's own `treemap` transform: `transforms={[{ type: 'treemap', tile: 'binary' }]}` sets it over the one the plot builds from `value` and `grouping`. `tile` is `'squarify'` (the default, which keeps them close to squares), `'binary'`, `'slice'`, `'dice'` or `'sliceDice'`.
+- Tiles have no axes.
+
+## Labels
+
+Each tile is labelled with its name and its **share of the whole**, in percent, as `styles.values` asks (`decimals`, `prefix`, `suffix`, `signDisplay`; one decimal and a `%` suffix unless you set otherwise, or `numbers.decimals` says). A label is fitted to the tile it is written on:
+
+1. The name over the value, in as many lines as the tile has room for - at a smaller font size first, when that writes the whole name.
+2. The name cut short with an ellipsis on its last line, when it still does not fit.
+3. The value alone, when almost none of the name would show.
+4. Nothing, when not even the value fits.
+
+`styles.values.format(value, group, row, number)` writes the tile's whole text instead (`value` is the share, in percent; `number` writes it as the display fields ask), and `styles.values.show: false` leaves the tiles bare. The label's `fontStyle` sets `fontSize` (the biggest it takes), `fontWeight` and `fill`; `treemap` in the [configuration](../../theming.md) sets the lines between tiles, the label color and the room kept around it.
+
+## Style
+
+`styles.area` styles every tile - `fillOpacity`, `stroke`, `strokeWidth`, `strokeDasharray`, `borderRadius` - over the color of its group (a `fill` there wins over it). A group turned off in the [legend](../../legend.md) dims its tiles and their labels. With `disabled: { mode: 'omit' }` its tiles are gone and the rest keep their place and share, and with `{ mode: 'rescale' }` the rest fill the plot as the new whole, each share of what is left.
+
+## Segments
+
+`segments` are keyed by series - the outermost `grouping` level - or `default` for every one, and style a group's tiles together: a highlighted sector against the rest faded, an outlined one, a recolored one. A key can also be the **path** of a tile, its levels joined by dots - `'Tertiary.Finance'`, `'Tertiary.Finance.Insurance'` - and the most specific one wins. A segment sets no `areas`, as a tile has no position on an axis. A named key wins over `default`, and both over `styles.area` (see [Styles and segments](../../styles-and-segments.md)).
+
+```svelte
+<!-- Tertiary at some strength, its Finance tiles at full strength and outlined, every other sector faded. -->
+<TreemapPlot
+	{data}
+	value="value"
+	grouping="sector.kind.branch"
+	segments={{
+		default: [{ styles: { fillOpacity: 0.25 } }],
+		Tertiary: [{ styles: { fillOpacity: 0.6 } }],
+		'Tertiary.Finance': [{ styles: { fillOpacity: 1, stroke: 'gold' } }]
+	}}
+/>
+```
+
+## Hover and tooltip
+
+Hovering a tile matches it alone - an invisible `rect` over each tile drives the plot's hover - and `tooltip` shows its name and share. `tooltip.format(row, number, context)` writes it by hand: `row` is the tile's row, with the fields of every level and its summed `value`, and `context` what the library works out about it - its `series` (the outermost level) and its `share` of the whole, from 0 to 100. The share is worked out from the values, in whatever unit they are, so a dataset whose `value` is a percentage already reads the same.

package/docs/plots/ranking/bar.md

@@ -55,5 +55,5 @@ Bars where one axis holds the categories and the other the values. Categories on
 - 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'`).
+- `styles.values.show` labels each bar; `styles.values.anchor` places the label (`'outside'`, `'middle'`, `'top'`, `'bottom'`, `'left'`, `'right'`, a corner such as `'top-left'`, or `'tip'` and `'base'`, the ends of the bar away from zero and on it).
 - The tooltip triggers anywhere over a bar's whole band, not just over the visible bar.

package/docs/plots.md

@@ -2,25 +2,26 @@
 
 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))                             |
+| 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     |
+| Part of a whole | [TreemapPlot](plots/part-of-a-whole/treemap.md)  | A tile per row, its area its value, nested by `grouping`       | `value`, `grouping`                                     |
+| 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`.

package/docs/scales.md

@@ -80,9 +80,12 @@ A numeric axis takes `prefix`, `suffix`, `decimals` and `signDisplay` to write i
 | `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`)                                                                                                                                          |
+| `depth`       | With a `grouping` of several levels, the level the colors reach (default `1`, a color per outermost value); deeper, each value down to it takes a tone of its outermost value's color          |
 
 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]`.
 
+With `grouping: 'sector.kind.branch'`, `depth: 2` keeps each sector's color and gives every kind under it a tone of it; `depth: 3` gives every branch its own tone, those of one kind next to each other. A plot that splits its series by every level (a line per `'continent.country'`) colors them the same way, and a [treemap](plots/part-of-a-whole/treemap.md), which nests them, colors its tiles. The tones are `ColorTones` (`colorTones(color, count)` and `hierarchicalColors(paths, depth, colorOf)` in the package), for any page of your own that colors a hierarchy.
+
 A marker can carry its own `scales.color`, independent of the plot's, so two ramps can coexist in one plot.
 
 ## Grouping

package/docs/state.md

@@ -7,7 +7,7 @@ A plot's state - its hover, legend, timeline, margins, scales, rows and size - c
 Works anywhere inside a figure, including the `header`, `footer` and `content` snippets of a plot or composer. It returns:
 
 - `hover` - `activeX`, `activeY`, `activeSeries`, `strategy`, `sync`, `source` (the id of the plot owning the hover).
-- `legend` (or `null`) - `entries`, `range`, `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes.
+- `legend` (or `null`) - `entries`, `range`, `off` (names of hidden series), `isOff(name)`, `turnOff(name, action)`, `turnOn(name)`, `toggle(name, action)`. `action` is `{ mode: 'dim' | 'hide' | 'omit' | 'rescale' }`; `'omit'` removes the series and refits the axes, and `'rescale'` also makes the parts left of a whole (a stack, a treemap) the new 100%.
 - `timeline` (or `null`) - `enabled`, `steps`, `value`, `index`, `progress`, `playing`, `loop`, `speed`, `speeds`, `controls`, and `seek`, `seekIndex`, `seekValue`, `next`, `previous`, `play`, `pause`, `toggle`, `setLoop`, `setSpeed`, `cycleSpeed`. On a timeline of dates, `steps` and `value` are `Date`s and `seekValue` takes a `Date` or a date string.
 
 A footer that toggles series through the legend:

package/docs/styles-and-segments.md

@@ -46,18 +46,18 @@
 
 ![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. On a bar, `'outside'` is beyond its tip (on either side of zero), `'start'` / `'end'` its left / right end (top / bottom on a vertical bar), inside, and `'middle'` its centre |
-| `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)                                                                                                                                         |
-| `decimals`, `prefix`, `suffix`, `signDisplay` | How the value reads, over `numbers.decimals` ([Number format](theming.md#number-format)); `format` replaces them                                                                                                                                             |
-| `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                                                                                                                                                                                        |
+| Field                                         | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `show`                                        | Draws the labels. Off by default, except on a heatmap                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `anchor`                                      | Where a label sits on its mark. On a line, area, slope or scatter plot: `'outside'`, `'start'`, `'middle'`, `'end'`, the side of its point the text is written on. On a bar, bullet, pyramid, histogram or heatmap - plots that label a shape - the label is in the shape: `'middle'`, an edge as the page draws it (`'top'`, `'bottom'`, `'left'`, `'right'`), a corner (`'top-left'`...), the end of the bar away from zero (`'tip'`) or the one on zero (`'base'`), whichever side of zero the value is; or beyond the tip, outside it: `'outside'` (the default). The labels are those of the shapes' own `label` - see [Markers](markers.md#a-label-in-each-shape) |
+| `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)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `decimals`, `prefix`, `suffix`, `signDisplay` | How the value reads, over `numbers.decimals` ([Number format](theming.md#number-format)); `format` replaces them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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).
 
@@ -121,12 +121,12 @@ A row whose value is `null`, `undefined` or `NaN` breaks a line. `styles.gaps` b
 
 - A plot uses the ones its own marks are made of and ignores the rest, so one `styles` can be shared between plots:
 
-  | Plot                                                                                                                       | Uses                                                           |
-  | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-  | `LinePlot`, `SlopePlot`, `SparklinePlot`                                                                                   | `stroke` (the line), `dot` (a dot on every point; unset, none) |
-  | `AreaPlot`, `BarPlot`, `BulletPlot`, `PyramidPlot`, `HistogramPlot`, `BoxPlot`, `DensityPlot`, `ViolinPlot`, `HeatmapPlot` | `area`                                                         |
-  | `ScatterPlot`                                                                                                              | `dot`                                                          |
-  | `LollipopPlot`, `DumbbellPlot`, `ClevelandPlot`, `ForestPlot`                                                              | `stroke` (the stems and connectors), `dot`                     |
+  | Plot                                                                                                                                      | Uses                                                           |
+  | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+  | `LinePlot`, `SlopePlot`, `SparklinePlot`                                                                                                  | `stroke` (the line), `dot` (a dot on every point; unset, none) |
+  | `AreaPlot`, `BarPlot`, `BulletPlot`, `PyramidPlot`, `HistogramPlot`, `BoxPlot`, `DensityPlot`, `ViolinPlot`, `HeatmapPlot`, `TreemapPlot` | `area`                                                         |
+  | `ScatterPlot`                                                                                                                             | `dot`                                                          |
+  | `LollipopPlot`, `DumbbellPlot`, `ClevelandPlot`, `ForestPlot`                                                                             | `stroke` (the stems and connectors), `dot`                     |
 
   `GeoPlot` has styles of its own and uses none of them.
 
@@ -161,6 +161,7 @@ The style shape depends on the plot:
 | `AreaPlot`, `HistogramPlot` | `AreaStyle`                        | `fill`, `fillOpacity`, `stroke`, ...           |
 | `BarPlot`, `PyramidPlot`    | `BarSegmentStyle` (`AreaStyle`)    | `fill`, `fillOpacity`, `stroke`, ...           |
 | `HeatmapPlot`               | `CellSegmentStyle` (`AreaStyle`)   | `fill`, `fillOpacity`, `stroke`, `strokeWidth` |
+| `TreemapPlot`               | `BarSegmentStyle` (`AreaStyle`)    | `fill`, `fillOpacity`, `stroke`, ...           |
 | `ScatterPlot`               | `ScatterSegmentStyle` (`DotStyle`) | dot fill, stroke, radius, symbol               |
 | `GeoPlot`                   | `GeoSegmentStyle`                  | `fill`, `fillOpacity`, `stroke`, `strokeWidth` |
 

package/docs/theming.md

@@ -36,7 +36,7 @@ resetConfiguration(); // back to the shipped defaults
 | `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                                                                                                                                                                                                                                                                                                                                                                 |
+| `continuous`                                                                                                                                                        | Default ramp endpoints 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                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -45,11 +45,12 @@ resetConfiguration(); // back to the shipped defaults
 | `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                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `text`                                                                                                                                                              | `label` defaults (`gap`, `padding`, `minFontSize`, `minLetters`, and `contrast`, the colors a label inside its shape picks from) of the label a shape writes in itself, and `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)                                                                                                                                                                                                                                                                                                                                        |
+| `treemap`                                                                                                                                                           | The tiles of a `TreemapPlot`: `stroke` (the line between tiles, white by default) and `strokeWidth`, `fontSize`, `padding` (the room kept around a label) and `lineHeight`                                                                                                                                                                                                                                                                             |
+| `timeline`                                                                                                                                                          | The rule (`rule`) and the player bar (`player`: controls, speeds, `stepDuration`, button, track, thumb, toggle); `snap` is how close to its last step (a fraction of the span, `1e-4` by default) a tweened timeline counts as being at it                                                                                                                                                                                                             |
 | `facet`                                                                                                                                                             | The position badge and prev/next buttons                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `frameClip`                                                                                                                                                         | Tolerance for clipping marks to the plot frame                                                                                                                                                                                                                                                                                                                                                                                                         |
 
@@ -98,7 +99,7 @@ A plot overrides it with `scales.x.edgeTicks` or `scales.y.edgeTicks` (see [Scal
 
 ## CSS variables
 
-Some fields reach the DOM as CSS custom properties, which every figure sets on its root element and the components read with a fallback. Those can also be overridden with plain CSS on a wrapping element for a one-off, non-reactive tweak:
+Some fields reach the DOM as CSS custom properties, which the components read with a fallback. The configuration sets them once on the document root, as a rule with no specificity (`:where(:root)`), so plain CSS of your own overrides them - on a wrapping element, for one dashboard, or anywhere else:
 
 ```css
 .my-dashboard {
@@ -225,14 +226,6 @@ The text blocks map `title`, `subtitle` and `caption` to `--dct-{block}-{font|si
 | `--dct-player-toggle-size`         | `timeline.player.toggle.fontSize`         |
 | `--dct-player-toggle-pad`          | `timeline.player.toggle.padding`          |
 
-### heatmap ramp
-
-| CSS variable      | Config path             |
-| ----------------- | ----------------------- |
-| `--dct-heat-min`  | `continuous.min`        |
-| `--dct-heat-max`  | `continuous.max`        |
-| `--dct-heat-text` | `continuous.labelColor` |
-
 ### facet
 
 | CSS variable                       | Config path                       |

package/docs/tooltip-and-hover.md

@@ -43,7 +43,7 @@ A plot becomes interactive when it is given a `tooltip`, a `{ type: 'hover' }` m
 | `series`             | Only these series appear in the tooltip                                                                                                                                                                                                                                                                                                                            |
 | `anchorX`, `anchorY` | Preferred side of the cursor: `'left' \| 'middle' \| 'right'` (default `'right'`) and `'top' \| 'middle' \| 'bottom'` (default `'bottom'`). It moves to the other side when it would overflow                                                                                                                                                                      |
 
-`decimals`, `prefix`, `suffix` and `signDisplay` ([Number format](theming.md#number-format)) write the value the default text shows - the one on the value axis, the `x` of horizontal bars - and a heatmap's color value. A custom `format` gets a second argument, `number`, that writes a number the same way: `format: (row, number) => `${row.region}: ${number(row.value)}``.
+`decimals`, `prefix`, `suffix` and `signDisplay` ([Number format](theming.md#number-format)) write the value the default text shows - the one on the value axis, the `x` of horizontal bars - and a heatmap's color value. A custom `format` gets a second argument, `number`, that writes a number the same way: `format: (row, number) => `${row.region}: ${number(row.value)}``. Its third, `context`, is what the plot knows of the row beyond its fields: the `series`it is drawn in, and what its kind works out (a [treemap](plots/part-of-a-whole/treemap.md)'s`share`).
 
 <!-- example: examples/CustomTooltip.svelte -->
 

package/docs/transforms-and-statistics.md

@@ -54,22 +54,23 @@ Both derive rows from the data before drawing. A **transform** reshapes the rows
 
 ![Lines smoothed by a moving average](images/moving-average.png)
 
-| Family    | `type`                                                                                        | Does                                                                                                                                                                                                                             |
-| --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Stack     | `stackX`, `stackY`, `stackMosaicX`, `stackMosaicY`                                            | Cumulative stacking. Options: `offset` (`'none'`, `'wiggle'`, `'center'`, `'normalize'`, `'diverging'`), `order`, `reverse`                                                                                                      |
-| Bin       | `binX`, `binY`, `bin`                                                                         | Count or reduce rows into bins. Options: `thresholds` (a count, a list, or `'auto'`, `'scott'`, `'sturges'`, `'freedman-diaconis'`), `interval`, `domain`, `cumulative`; reducers by channel (`y: 'count'`, `fill: 'mean'`, ...) |
-| Group     | `groupX`, `groupY`, `groupZ`, `group`                                                         | Reduce rows per category with named reducers (`count`, `sum`, `mean`, `p25`, ...) or functions                                                                                                                                   |
-| Window    | `windowX`, `windowY`                                                                          | Sliding window: `k` (size), `reduce` (`'mean'`, `'median'`, `'sum'`, `'max'`, ...), `anchor`, `strict`                                                                                                                           |
-| Bollinger | `bollingerX`, `bollingerY`                                                                    | Moving average and band: `n`, `k`                                                                                                                                                                                                |
-| Normalize | `normalizeX`, `normalizeY`, `normalizeParallelX`, `normalizeParallelY`                        | Rebase to a reference: `basis` (`'first'`, `'last'`, `'min'`, `'max'`, `'mean'`, `'median'`, `'sum'`, `'deviation'`)                                                                                                             |
-| Map       | `mapX`, `mapY`                                                                                | `map`: `'cumsum'`, `'rank'`, `'quantile'` or a function                                                                                                                                                                          |
-| Interval  | `intervalX`, `intervalY`                                                                      | Turn a value into an `[x1, x2]` interval of a given size                                                                                                                                                                         |
-| Jitter    | `jitterX`, `jitterY`                                                                          | Random offset: `width`, `std`, `distribution` (`'uniform'`, `'normal'`), `seed`                                                                                                                                                  |
-| Shift     | `shiftX`, `shiftY`                                                                            | Move by `by` (a number, or a string offset)                                                                                                                                                                                      |
-| Density   | `densityX`, `densityY`                                                                        | Kernel density estimate: `kernel`, `bandwidth`                                                                                                                                                                                   |
-| Sort      | `sort`, `shuffle`, `reverse`                                                                  | Reorder rows (matters for the path a line takes and which dot lands on top)                                                                                                                                                      |
-| Filter    | `filter`                                                                                      | Keep rows a test holds for                                                                                                                                                                                                       |
-| Select    | `select`, `selectFirst`, `selectLast`, `selectMinX`, `selectMaxX`, `selectMinY`, `selectMaxY` | Keep one row per group, such as each series' last point or peak                                                                                                                                                                  |
+| Family    | `type`                                                                                        | Does                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Stack     | `stackX`, `stackY`, `stackMosaicX`, `stackMosaicY`                                            | Cumulative stacking. Options: `offset` (`'none'`, `'wiggle'`, `'center'`, `'normalize'`, `'diverging'`), `order`, `reverse`                                                                                                                                                                                                                                                                                                                                                    |
+| Bin       | `binX`, `binY`, `bin`                                                                         | Count or reduce rows into bins. Options: `thresholds` (a count, a list, or `'auto'`, `'scott'`, `'sturges'`, `'freedman-diaconis'`), `interval`, `domain`, `cumulative`; reducers by channel (`y: 'count'`, `fill: 'mean'`, ...)                                                                                                                                                                                                                                               |
+| Group     | `groupX`, `groupY`, `groupZ`, `group`                                                         | Reduce rows per category with named reducers (`count`, `sum`, `mean`, `p25`, ...) or functions                                                                                                                                                                                                                                                                                                                                                                                 |
+| Treemap   | `treemap`                                                                                     | Lay rows out as tiles in the unit square, with d3-hierarchy. `value` (the area), `levels` (what the tiles nest by, outermost first; rows with the same path are one tile and their values add up), `tile` (`'squarify'`, `'binary'`, `'slice'`, `'dice'`, `'sliceDice'`), `aspect` (width over height of the box). Produces `x1`/`x2`/`y1`/`y2` for a `rect` marker and `x`/`y` at each tile's centre for a `text`; the tile's name, path, value and share are left on its row |
+| Window    | `windowX`, `windowY`                                                                          | Sliding window: `k` (size), `reduce` (`'mean'`, `'median'`, `'sum'`, `'max'`, ...), `anchor`, `strict`                                                                                                                                                                                                                                                                                                                                                                         |
+| Bollinger | `bollingerX`, `bollingerY`                                                                    | Moving average and band: `n`, `k`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Normalize | `normalizeX`, `normalizeY`, `normalizeParallelX`, `normalizeParallelY`                        | Rebase to a reference: `basis` (`'first'`, `'last'`, `'min'`, `'max'`, `'mean'`, `'median'`, `'sum'`, `'deviation'`)                                                                                                                                                                                                                                                                                                                                                           |
+| Map       | `mapX`, `mapY`                                                                                | `map`: `'cumsum'`, `'rank'`, `'quantile'` or a function                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Interval  | `intervalX`, `intervalY`                                                                      | Turn a value into an `[x1, x2]` interval of a given size                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Jitter    | `jitterX`, `jitterY`                                                                          | Random offset: `width`, `std`, `distribution` (`'uniform'`, `'normal'`), `seed`                                                                                                                                                                                                                                                                                                                                                                                                |
+| Shift     | `shiftX`, `shiftY`                                                                            | Move by `by` (a number, or a string offset)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Density   | `densityX`, `densityY`                                                                        | Kernel density estimate: `kernel`, `bandwidth`                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Sort      | `sort`, `shuffle`, `reverse`                                                                  | Reorder rows (matters for the path a line takes and which dot lands on top)                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Filter    | `filter`                                                                                      | Keep rows a test holds for                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Select    | `select`, `selectFirst`, `selectLast`, `selectMinX`, `selectMaxX`, `selectMinY`, `selectMaxY` | Keep one row per group, such as each series' last point or peak                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 Bar stacking is always `stackY`, also for horizontal bars. A transform on a `HistogramPlot` is merged over the plot's default binning, so `{ type: 'binX', thresholds: 20 }` changes the bins and the rest stays.
 

package/examples/Treemap.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+	import { TreemapPlot } from '@fundar/data-chart-telling';
+	import { ACTIVITY_BRANCHES } from './datasets';
+</script>
+
+<!-- One tile per branch, sized by its value and colored by its sector. -->
+<TreemapPlot
+	width={760}
+	height={440}
+	data={ACTIVITY_BRANCHES}
+	value="value"
+	grouping="sector.branch"
+/>