@fundar/data-chart-telling 1.16.0 → 1.18.0

package/dist/utils/grouping.js

@@ -1,4 +1,35 @@
 import { resolveAccessor } from './accessors';
+/**
+ * A plot's `grouping`, read into its levels. A dotted name is a field of the rows when they have one by that
+ * name, and the fields of its levels otherwise. Rows grouped by several levels make one key of them, dotted
+ * too (`'Tertiary.Finance'`), which is how `segments` names them.
+ */
+export class Grouping {
+    /** The separator between the levels of a grouping, and of the key they make together. */
+    static SEPARATOR = '.';
+    /** The levels `grouping` names, outermost first: none when it is unset. */
+    static levels(grouping, rows = []) {
+        if (grouping === undefined)
+            return [];
+        if (typeof grouping !== 'string' || !grouping.includes(Grouping.SEPARATOR))
+            return [grouping];
+        if (rows.some((row) => grouping in row))
+            return [grouping];
+        return grouping.split(Grouping.SEPARATOR);
+    }
+    /**
+     * The key rows split into series by: a single level as it is - a field stays its name - and several as
+     * the key their values make together. `nested` takes the outermost level alone, for a plot that draws
+     * the inner ones itself (a treemap).
+     */
+    static key(grouping, rows = [], nested = false) {
+        const levels = Grouping.levels(grouping, rows);
+        if (levels.length <= 1 || nested)
+            return levels[0];
+        const reads = levels.map((level) => resolveAccessor(level));
+        return (row) => reads.map((read) => String(read(row))).join(Grouping.SEPARATOR);
+    }
+}
 /**
  * Splits rows into ordered groups keyed by the stringified accessor value.
  * Insertion order of first appearance is preserved, which keeps colours stable

package/docs/concepts.md

@@ -39,13 +39,14 @@ A **channel** maps a field of each row to a visual property. Each channel takes
 | ---------- | ----------------------------------------------------------- | ---------------------- |
 | `x`, `y`   | Position on the horizontal and vertical axis                | `scales.x`, `scales.y` |
 | `color`    | A color: categorical (one per value) or continuous (a ramp) | `scales.color`         |
-| `grouping` | Which series the row belongs to                             | `scales.grouping`      |
+| `grouping` | Which series the row belongs to (`'a.b'`: several levels)   | `scales.grouping`      |
 | `opacity`  | A fill or stroke opacity                                    | `scales.opacity`       |
 | `symbol`   | A marker shape (categorical)                                | `scales.symbol`        |
 | `r`        | A dot radius, scaled so that area follows the value         | `scales.r`             |
 | `length`   | A vector or spike length                                    | `scales.length`        |
+| `value`    | What a row amounts to as a part of a whole (a treemap tile) | -                      |
 
-`grouping` splits `data` into series. When it is unset, `color` groups too, so one accessor both separates and colors the series - the usual case. Pass both to group by one field and color by another:
+`grouping` splits `data` into series. Fields joined by dots are one grouping of several levels, outermost first: a plot that nests its rows ([TreemapPlot](plots/part-of-a-whole/treemap.md)) nests them by those levels, and any other splits them by the combination of the levels (`'region.sex'` is one series per region and sex, named `'CABA.F'`, which is how `segments` keys it). A dotted name is a field when the rows have one by that name; a function is a single level. When it is unset, `color` groups too, so one accessor both separates and colors the series - the usual case. Pass both to group by one field and color by another:
 
 ```svelte
 <ScatterPlot data={rows} x="gdp" y="life" grouping="country" color="temperature" {width} {height} />

package/docs/legend.md

@@ -71,11 +71,14 @@ Items become clickable with `interactive` on the series section. `disabled` says
 
 ![Legend items as toggles](images/legend-toggle.png)
 
-| `disabled.mode`   | A hidden series...                                                                    |
-| ----------------- | ------------------------------------------------------------------------------------- |
-| `'dim'` (default) | stays, faded (`style` sets how: opacity, fill, ...; default `legend.disabledOpacity`) |
-| `'hide'`          | becomes transparent, the axes keep its range                                          |
-| `'omit'`          | is removed and the axes refit to the rest                                             |
+| `disabled.mode`   | A hidden series...                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `'dim'` (default) | stays, faded (`style` sets how: opacity, fill, ...; default `legend.disabledOpacity`)  |
+| `'hide'`          | becomes transparent, the axes keep its range                                           |
+| `'omit'`          | is removed and the axes refit to the rest; a part of a whole keeps its share and place |
+| `'rescale'`       | is removed, and the parts left make the whole again (see below)                        |
+
+A plot uses one mode for all its series. `'omit'` and `'rescale'` differ on a plot of parts of a whole. With `'omit'` the other parts keep their values: a stack closes over the hidden series and its top drops, and a [treemap](plots/part-of-a-whole/treemap.md)'s tiles keep their place and their share of the whole economy, leaving the room empty. With `'rescale'` the parts left are the new 100%: each category of a stack (`stackY`/`stackX`) is scaled back up to the total it had, and a treemap's tiles fill the plot again, each share of what is left. On any other plot, `'rescale'` is an `'omit'`.
 
 `interactive.legendStyle` is `'badge'` (default: pills filled with the series color and an eye toggle) or `'basic'` (swatches). `showIcon` toggles the symbol in a badge.
 

package/docs/markers.md

@@ -68,32 +68,33 @@ 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)          |
+| `band`                                                   | The band of a category across the whole other axis: `axis: 'x' \| 'y'`, `value` (a list, or a function with `data`), `slice`, `styles` (`AreaStyle`). Only on a band scale                          |
+| `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
 
@@ -101,7 +102,7 @@ On a plot with a [`facet`](facets.md#markers-and-segments-in-some-panels), every
 
 ## Several positions at once
 
-A `rule` takes a list as its `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
+A `rule` and a `band` take a list as their `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
 
 ```ts
 markers={[
@@ -123,9 +124,90 @@ A delta's `stroke`, `text` and `dot` can be functions of the position, to style
 
 Every other marker draws from `data` rows, one mark per row, so it already takes many positions.
 
+## Bands
+
+`{ type: 'band', axis: 'x', value: 'Salta' }` fills the band of a category on a band scale, across the whole of the other axis: a column behind a bar plot's bars, a row across a horizontal one. With `data`, `value` is a field key or a function of the row, and the rows that name the same category draw one band. `slice` fills part of the band, as the fractions of its width left out at its start and its end (`{ start: 0.5, end: 0 }` is its second half), or a function of the row for each one's; a band several rows share fills what all of their slices do. `styles` take `AreaStyle`, each field a value or a function of the row, over `band` in the [configuration](theming.md). A band takes the pointer only with a handler of its own (`onclick`...), so one behind a plot's shapes leaves them their hover. On an axis that is not a band scale it draws nothing.
+
+```ts
+markers={[
+	// The two provinces of the story, behind their bars.
+	{ type: 'band', axis: 'x', value: ['Salta', 'Jujuy'], styles: { fill: '#fde68a', fillOpacity: 0.5 } }
+]}
+```
+
 ## Hover highlight
 
-`{ 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).
+`{ type: 'hover' }` draws the plot's own hover: a crosshair, a dot and a label at the hovered point on most plots, the hovered category's band on a bar plot. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `series`, `scope`; `back` and `front`, the markers it draws behind the plot's shapes and in front of them, over the hovered points (they replace the plot's); `active` and `others`, which restyle the hovered shapes and the rest; and `format` and the number fields `decimals`, `prefix`, `suffix` and `signDisplay`, which write each point's label. See [Tooltip and hover](tooltip-and-hover.md#in-plot-hover).
+
+```ts
+// A crosshair only at the hovered point, and its value in bold, without a dot.
+{ type: 'hover', back: [{ type: 'rule', axis: 'x', points: 'active' }], front: [{ type: 'text', styles: { fontWeight: 'bold' } }] }
+```
+
+Every marker takes `hover`, which links it to the plot's hover:
+
+- `'trigger'` makes it a hit area: the pointer over one of its shapes hovers that shape's row.
+- `'style'` has its shapes take the hover marker's `active` and `others`.
+- `true` does both.
+
+```ts
+markers={[
+	{ type: 'hover', active: { stroke: 'black', strokeWidth: 2 }, others: { fillOpacity: 0.3 } },
+	{ type: 'rect', data: eras, x1: 'from', x2: 'to', y1: 0, y2: 100, hover: true }
+]}
+```
+
+A plot's own shapes are linked already where its kind does it: the tiles, cells, bars, bins and dots of `TreemapPlot`, `HeatmapPlot`, `BarPlot`, `BulletPlot`, `PyramidPlot`, `HistogramPlot`, `ScatterPlot` and the Cleveland family. The `Layout/Hover` stories show every feature of the hover on every plot kind.
+
+## 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
 

package/docs/plots/evolution/line.md

@@ -20,7 +20,7 @@ One line per series. Rows with a missing value (`null`, `undefined`, `NaN`) brea
 	x="date"
 	y="index"
 	color="commodity"
-	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+	styles={{ values: { show: true, format: (v, _number, context) => `${context.series}: ${v}` } }}
 />
 ```
 

package/docs/plots/evolution/slope.md

@@ -32,7 +32,7 @@ A line per series between two positions of a category axis, a dot on each end, t
 
 - `x` is always a category axis (a point scale, so the first and last positions reach the plot's edges), even for numbers or dates: each distinct value is a position, in the order the data gives them (`scales.x.domain` sets it).
 - `grouping` (or `color`) names the series; the legend toggles them like any other.
-- `styles.values` writes each series' first and last value (`select` picks others: `'first'`, `'last'`, `'min'`, `'max'`). Each label sits out in the margin on a lane, joined to its dot by a connector. The text is `format` of the value and series name.
+- `styles.values` writes each series' first and last value (`select` picks others: `'first'`, `'last'`, `'min'`, `'max'`). Each label sits out in the margin on a lane, joined to its dot by a connector. The text is `format` of the value, `number` and the row's context, with its `series`.
 - The value axis is hidden, since the labels carry the values; `scales.y.axisDisplay: 'visible'` brings it back. It fits the values without reaching for zero; pin `scales.y.domain` to start it there.
 - The stroke width, dot radius and padding come from `slope` in the [configuration](../../theming.md); `padding` leaves room outside the first and last position. The positions sit at the plot's edges, and the margins grow to fit the labels.
 - `segments` restyle chosen series (`styles: { stroke: { strokeWidth: 4 } }`), as in a line plot.

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

@@ -0,0 +1,103 @@
+# 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, number, context)` writes the tile's whole text instead (`value` is the share, in percent; `number` writes it as the display fields ask; `context` holds the tile's `series`, `name`, `path` and `share`), 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), its `name`, `path`, summed `value` and `share` of the whole, from 0 to 100 (see [Row context](../../state.md#row-context)). 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.
+
+A `hover` marker draws no crosshair, dot or label over a treemap, since a tile has no axes and writes its own label: it outlines the hovered tile, in the configuration's `hover.active`. The tiles are linked to the hover, so its `active` and `others` restyle them: the hovered tile lightened and outlined, the rest faded, each label still on its tile and written in the color that reads best on its new one. A tile the legend dims stays hoverable and keeps its dimmed fill; one it hides, omits or rescales away is never hovered. See [Tooltip and hover](../../tooltip-and-hover.md#restyling-the-hovered-shapes).
+
+<!-- example: examples/TreemapHover.svelte -->
+
+```svelte
+<script lang="ts">
+	import { TreemapPlot } from '@fundar/data-chart-telling';
+	import { ACTIVITY_BRANCHES } from './datasets';
+</script>
+
+<!--
+	The hover marker restyles the tiles themselves: the hovered one at full strength and outlined, every other
+	faded. Each label is still written on its tile, in the color that reads best on it.
+-->
+<TreemapPlot
+	width={760}
+	height={440}
+	data={ACTIVITY_BRANCHES}
+	value="value"
+	grouping="sector.branch"
+	styles={{ area: { fillOpacity: 0.85 } }}
+	tooltip
+	markers={[
+		{
+			type: 'hover',
+			active: { fillOpacity: 1, stroke: '#111827', strokeWidth: 2 },
+			others: { fillOpacity: 0.35 }
+		}
+	]}
+/>
+```
+
+<!-- /example -->

package/docs/plots/ranking/bar.md

@@ -55,5 +55,6 @@ 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.
+- A `hover` marker draws the hovered category's band behind its bars (its series' slice, when grouped and the bar alone is hovered), and with `active` and `others` restyles the hovered bars and the rest. See [Tooltip and hover](../../tooltip-and-hover.md#in-plot-hover).

package/docs/plots/ranking/cleveland.md

@@ -33,7 +33,7 @@ The general form of the family: per category, one dot for each series that has a
 - The connector spans the lowest and the highest dot of each category, so a series the legend omits leaves the range.
 - The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
 - Its defaults come from `cleveland` in the [configuration](../../theming.md): the connector is a neutral gray, 5 px thick.
-- `styles.values` writes each value: past the highest dot and the lowest of its category, and beside those between them. `select` (`'first'`, `'last'`, `'min'`, `'max'`, or a list) labels only those dots of each category, `series` only those series, and `color: 'series'` writes each label in its dot's series color. `format(value, seriesName, row)` also gets the row, so a label can name its category (see [Styles and segments](../../styles-and-segments.md#value-labels)).
+- `styles.values` writes each value: past the highest dot and the lowest of its category, and beside those between them. `select` (`'first'`, `'last'`, `'min'`, `'max'`, or a list) labels only those dots of each category, `series` only those series, and `color: 'series'` writes each label in its dot's series color. `format(value, number, context)` also gets the row in `context.row`, so a label can name its category (see [Styles and segments](../../styles-and-segments.md#value-labels)).
 - `segments` restyle the dots of chosen categories, as in [`DumbbellPlot`](dumbbell.md).
 - The tooltip reads one category at a time, listing every series.
 

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:
@@ -42,6 +42,7 @@ Works inside a plot - in a [`component` marker](markers.md#custom-components), w
 
 - `hover.points`, `hover.activePoint`, `hover.tooltip` (`visible`, `position`, `rows`) for this plot;
 - `margins`, `scales`, `axes`, `data`, `width`, `height`;
+- `contextOf(row)` - what the plot knows of one of its rows (see [Row context](#row-context));
 - `svelteplot` - svelteplot's own `usePlot()` state for this plot.
 
 ```svelte
@@ -66,6 +67,38 @@ Works inside a plot - in a [`component` marker](markers.md#custom-components), w
 />
 ```
 
+## Row context
+
+A plot works out a context for every row it draws, once, as it reads its data: the `series` the row is drawn in, its `x` and `y` (its own values, not a stack's running total, or where the plot's transforms put it), the `value` it shows on the value axis, the `row` itself, and whatever the plot kind works out for it. Everything that writes about a row reads the same context, so a value the plot computes - a tile's share, a density's estimate, a bin's count - is there to read without working it out again:
+
+- `tooltip.format(row, number, context)`;
+- `styles.values.format(value, number, context)`;
+- the `hover` marker's points (`point.context`), in its `format` and in its `back` and `front` markers;
+- `usePlot().contextOf(row)` in a `component` marker, and `RowContext.of(row)` anywhere, from a row the plot drew or a copy of it (the one a mark's accessor gets).
+
+What each plot kind adds:
+
+| Plot                    | `value`                               | Also                                                                            |
+| ----------------------- | ------------------------------------- | ------------------------------------------------------------------------------- |
+| Most plots              | the row's own value                   | -                                                                               |
+| `DensityPlot`           | the estimated density                 | `x` (or `y` when horizontal) is the point it is estimated at                    |
+| `HistogramPlot`         | the bin's count                       | `count`, `from`, `to` (the bin's edges)                                         |
+| `BoxPlot`, `ViolinPlot` | the value (a hovered box: its median) | the box's `category`, `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers` |
+| `TreemapPlot`           | the tile's summed value               | `name`, `path`, `share` (0 to 100); no `x` or `y`                               |
+| `HeatmapPlot`           | the cell's color value                | -                                                                               |
+
+```svelte
+<HistogramPlot
+	data={ages}
+	x="age"
+	tooltip={{
+		format: (_row, number, context) => `${context.from}-${context.to}: ${number(context.count)}`
+	}}
+/>
+```
+
+The types are `PlotRowContext`, and per kind `TreemapRowContext`, `HistogramRowContext` and `BoxRowContext`.
+
 ## When to use them
 
 Reach for these instead of re-implementing a legend, a timeline control or a hover readout beside the plot: the figure already holds that state, and a widget reading it stays in step with the plot. [examples/LegendReader.svelte](../examples/LegendReader.svelte) is a runnable reader, and the Storybook group _Configuration / State_ has both patterns.