@fundar/data-chart-telling 1.16.0 → 1.18.0

package/docs/styles-and-segments.md

@@ -35,7 +35,7 @@
 	styles={{
 		values: {
 			show: true,
-			format: (value, seriesName) => `${seriesName}: ${value.toFixed(0)}`,
+			format: (value, _number, context) => `${context.series}: ${value.toFixed(0)}`,
 			fontStyle: { fontSize: 13 }
 		}
 	}}
@@ -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, number, context) => string`; `number` writes a value as the fields above ask, `context` is the labelled row's [context](state.md#row-context): its `series`, the `row` itself for its other fields, and what the plot works out                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `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,10 +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`                                                                                                                                                                                                                                                                                                                                                                                                |
+| `hover`                                                                                                                                                             | The look of the markers a hover draws, under their own `styles`: `rule` (a crosshair), `dot`, `font` (a label), `area` (a band or a span), and `active`, the outline of the hovered shape on a treemap or a heatmap                                                                                                                                                                                                                                    |
+| `band`                                                                                                                                                              | The look of a `band` marker under its own `styles`: `fill` (`#94a3b8`) and `fillOpacity` (`0.25`), and any other `AreaStyle` field                                                                                                                                                                                                                                                                                                                     |
 | `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                                                                                                                                                              |
+| `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 +100,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 +227,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: the `series`it is drawn in, its`x`, `y`and`value`, and what its kind works out - a [treemap](plots/part-of-a-whole/treemap.md)'s `share`, a histogram's bin edges, a box's quartiles (see [Row context](state.md#row-context)).
 
 <!-- example: examples/CustomTooltip.svelte -->
 
@@ -104,14 +104,92 @@ The default strategy follows the plot's axes: it matches along the category (or
 
 ## In-plot hover
 
-`markers={[{ type: 'hover' }]}` draws a dashed rule, a dot and a value label at the hovered point, inside the SVG. Its look comes from `hover` in the [configuration](theming.md) and can be overridden per marker (`rule`, `dot`, `text`, `area`). On band scales `areaX` / `areaY` highlight the whole band instead of a thin rule.
+`markers={[{ type: 'hover' }]}` draws the plot's own hover inside the SVG: markers behind its shapes, markers in front of them, and a new look for the shapes the hover reaches. What each plot kind draws:
 
-Use both together for the usual result:
+| Plot                                                                       | Behind (`back`)                                                                                                     | In front (`front`)  |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `LinePlot`, `AreaPlot`, `DensityPlot`                                      | a dashed crosshair along each axis the strategy matches along: `x`, `y`, both for `'punctual'`, none for `'series'` | a dot and the value |
+| `ScatterPlot`                                                              | a crosshair along both axes, through the hovered point                                                              | the value           |
+| `SlopePlot`, `ClevelandPlot`, `DumbbellPlot`, `ForestPlot`, `LollipopPlot` | a rule along the value axis, at the hovered point                                                                   | a dot and the value |
+| `BarPlot`, `BulletPlot`, `BoxPlot`, `ViolinPlot`, `PyramidPlot`            | the hovered category's band (a series' slice, when grouped and alone)                                               | -                   |
+| `HistogramPlot`                                                            | the hovered bin's span                                                                                              | -                   |
+| `SparklinePlot`                                                            | -                                                                                                                   | a dot               |
+| `TreemapPlot`, `HeatmapPlot`                                               | - (the hovered tile or cell is outlined, in the configuration's `hover.active`)                                     | -                   |
+
+What a plot draws follows the strategy in force as it is shown: a [composer](composer.md)'s `hover={{ strategy }}` changed from one step of a story to the next changes the crosshair a line plot draws, with no new `hover` marker. `GeoPlot` has a hover of its own, the `geo-hover` marker (see [Maps](#maps)).
+
+Use it with a tooltip for the usual result:
 
 ```svelte
 <LinePlot ... tooltip markers={[{ type: 'hover' }]} />
 ```
 
+The marker's own fields are laid over the plot's:
+
+- `back` and `front` are lists of markers - any but another `hover`, a `component` too - that replace the plot's when set; `back: []` draws nothing behind.
+- `active` and `others` restyle the shapes (see [Restyling the hovered shapes](#restyling-the-hovered-shapes)), field by field over the plot's.
+- `strategy`, `sync`, `series` and `scope` say what it reaches, as for a tooltip, and the number fields `decimals`, `prefix`, `suffix` and `signDisplay` (or `format(point, number)`) write each point's label.
+
+```svelte
+<!-- A band behind the hovered category, and a dot and its value on each bar. -->
+<BarPlot
+	{data}
+	x="province"
+	y="value"
+	markers={[
+		{
+			type: 'hover',
+			back: [{ type: 'band', axis: 'x' }],
+			front: [{ type: 'dot' }, { type: 'text' }]
+		}
+	]}
+/>
+```
+
+### The markers it draws
+
+A marker in `back` or `front` draws the hovered points, unless it has `data` of its own. Each point is a row with its `x`, `y`, `label` (the value, written as the hover marker's number fields ask), `series`, `color` (its series'), `areaInset` (its series' slice of a grouped band) and `row` (the plot's row it stands for). What a marker leaves unset comes from the hover:
+
+- `x` and `y` are the point's;
+- a `rule` sits at each point along its `axis`, and a `band` around it, in its series' slice;
+- a `text` writes the point's `label`;
+- each takes the look of `hover` in the [configuration](theming.md) (`rule`, `area` for a `band` and a `rect`, `dot`, `font`), and a `dot` and a `text` the point's series color.
+
+`points` picks which of the points a marker draws: `'all'` (the default), `'active'` (the one nearest the pointer of those the hover reaches - moving the pointer up and down a category moves it from one series' point to another's - so a crosshair is drawn once, not once per series) or a function of the point that keeps some. On a pyramid, two labels each on their side of zero:
+
+```ts
+front: [
+	{ type: 'dot' },
+	{ type: 'text', points: (p) => Number(p.x) >= 0, styles: { textAnchor: 'start', dx: 10, dy: 0 } },
+	{ type: 'text', points: (p) => Number(p.x) < 0, styles: { textAnchor: 'end', dx: -10, dy: 0 } }
+];
+```
+
+On a grouped bar plot a point sits in its series' slice of the band, and each marker is drawn there - but a `band`, which takes the slice itself and covers the whole band where the hover matches every series of it.
+
+## Restyling the hovered shapes
+
+`active` and `others` on the `hover` marker restyle the shapes themselves: the ones the hover matches take `active`, every other one `others`, while the hover is on. Each takes `fill`, `fillOpacity`, `stroke`, `strokeWidth`, `strokeOpacity` and `strokeDasharray`, a value for every shape or a function of its row, and each value replaces the shape's own.
+
+```svelte
+<TreemapPlot
+	{data}
+	value="value"
+	grouping="sector.branch"
+	markers={[{ type: 'hover', active: { fillOpacity: 1 }, others: { fillOpacity: 0.3 } }]}
+/>
+```
+
+- What is hovered is what the hover already matches: its `strategy` decides. A treemap tile or a heatmap cell is one shape (`punctual`); on a `BarPlot` the bars of the hovered category (`'x'`), of the hovered series (`'series'`) or the one bar (`'punctual'`).
+- The shapes of a plot's own kind are linked to it: a `TreemapPlot`'s tiles, a `HeatmapPlot`'s cells, the bars of a `BarPlot`, a `BulletPlot` and a `PyramidPlot`, a `HistogramPlot`'s bins, a `ScatterPlot`'s dots and the dots of a `ClevelandPlot`, a `DumbbellPlot`, a `ForestPlot` and a `LollipopPlot`. On a dot, `fill`, `stroke` and the rest are its `dotFill`, `dotStroke`... A line or an area has no shape of a row to restyle: its point is the dot its hover draws in `front`. A marker of yours is linked with `hover: true` (it also hovers the row of the shape under the pointer, see [Markers](markers.md#hover-highlight)) or `hover: 'style'` (it only takes the styles).
+- The shape is restyled, nothing is drawn over it: a label inside it stays on top and, with no `fill` of its own, is written in the color that reads best on the shape's new color.
+- A `series` on the marker restyles that series' shapes only.
+
+The styles a shape is drawn with, from the weakest: the kind's defaults and the configuration, `styles` (`styles.area`), `segments`, then `others` or `active`. The [legend](legend.md) goes over all of them:
+
+- A series it dims (`mode: 'dim'`, the default, or another series isolated) stays hoverable: it is matched, shows in the tooltip and takes `active` or `others`, but keeps its dimmed `fill`, `fillOpacity` and `strokeOpacity`, so the hover never brings it back to full strength. An outline (`stroke`, `strokeWidth`, `strokeDasharray`) still applies.
+- A series it hides, omits or rescales away is out of the hover: never matched, never restyled.
+
 ## Bars
 
 On a `BarPlot` a hover candidate is the bar's whole band (or its series' slice, when grouped), so the tooltip triggers anywhere along the column.

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/LineDates.svelte

@@ -11,5 +11,5 @@
 	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/examples/ResponsiveLine.svelte

@@ -23,7 +23,9 @@
 				x: { label: 'Month' },
 				y: { label: 'Inflation (%)' }
 			}}
-			styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+			styles={{
+				values: { show: true, format: (v, _number, context) => `${context.series}: ${v}` }
+			}}
 			margins={{ right: 'auto' }}
 		/>
 	{/if}

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"
+/>

package/examples/TreemapHover.svelte

@@ -0,0 +1,25 @@
+<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 }
+		}
+	]}
+/>

package/examples/ValueLabels.svelte

@@ -14,7 +14,7 @@
 	styles={{
 		values: {
 			show: true,
-			format: (value, seriesName) => `${seriesName}: ${value.toFixed(0)}`,
+			format: (value, _number, context) => `${context.series}: ${value.toFixed(0)}`,
 			fontStyle: { fontSize: 13 }
 		}
 	}}

package/examples/datasets/economic-activity.ts

@@ -0,0 +1,40 @@
+// ── The weight of each branch of activity in a city's gross added value ──────
+// IDECBA, value added at basic prices by branch of activity, Ciudad de Buenos Aires,
+// 2024 (preliminary), in millions of pesos of 2004. A selection of the larger branches.
+
+export type ActivityRow = {
+	sector: 'Primary' | 'Secondary' | 'Tertiary';
+	kind: string;
+	branch: string;
+	/** Millions of pesos of 2004. */
+	value: number;
+};
+
+export const ACTIVITY_BRANCHES: ActivityRow[] = [
+	{ sector: 'Primary', kind: 'Extraction', branch: 'Oil, gas and coal', value: 778 },
+	{ sector: 'Primary', kind: 'Agriculture', branch: 'Agriculture and livestock', value: 193 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Chemicals', value: 2999 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Food and beverages', value: 2882 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Publishing and printing', value: 1251 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Machinery and equipment', value: 973 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Clothing', value: 814 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Textiles', value: 381 },
+	{
+		sector: 'Tertiary',
+		kind: 'Trade and transport',
+		branch: 'Wholesale and retail trade',
+		value: 15365
+	},
+	{ sector: 'Tertiary', kind: 'Trade and transport', branch: 'Transport', value: 3707 },
+	{ sector: 'Tertiary', kind: 'Trade and transport', branch: 'Communications', value: 8210 },
+	{ sector: 'Tertiary', kind: 'Finance', branch: 'Banking and finance', value: 7857 },
+	{ sector: 'Tertiary', kind: 'Finance', branch: 'Insurance', value: 3106 },
+	{ sector: 'Tertiary', kind: 'Public services', branch: 'Public administration', value: 7606 },
+	{ sector: 'Tertiary', kind: 'Public services', branch: 'Public education', value: 2374 },
+	{ sector: 'Tertiary', kind: 'Public services', branch: 'Public health', value: 1525 },
+	{ sector: 'Tertiary', kind: 'Private services', branch: 'Private health', value: 5439 },
+	{ sector: 'Tertiary', kind: 'Private services', branch: 'Private education', value: 1952 },
+	{ sector: 'Tertiary', kind: 'Private services', branch: 'Restaurants and bars', value: 2439 },
+	{ sector: 'Tertiary', kind: 'Real estate', branch: 'Housing', value: 6179 },
+	{ sector: 'Tertiary', kind: 'Real estate', branch: 'Construction', value: 3905 }
+];

package/examples/datasets/index.ts

@@ -5,6 +5,7 @@ export * from './commodity-prices';
 export * from './countries-over-time';
 export * from './daily-temperature';
 export * from './earthquakes';
+export * from './economic-activity';
 export * from './flight-routes';
 export * from './height-density';
 export * from './heights';

package/llms-full.txt

@@ -12,7 +12,7 @@ Svelte 5 plot components on top of svelteplot. This file is checked against the
 ## The mental model
 
 - A **plot** is one graph (axes + marks). Titles, subtitle, caption, legend, facets and a timeline are props of the plot itself.
-- Plots: `LinePlot AreaPlot BarPlot DensityPlot HistogramPlot BoxPlot ViolinPlot LollipopPlot DumbbellPlot ClevelandPlot ForestPlot BulletPlot SlopePlot SparklinePlot HeatmapPlot PyramidPlot ScatterPlot GeoPlot`.
+- Plots: `LinePlot AreaPlot BarPlot DensityPlot HistogramPlot BoxPlot ViolinPlot LollipopPlot DumbbellPlot ClevelandPlot ForestPlot BulletPlot SlopePlot SparklinePlot TreemapPlot HeatmapPlot PyramidPlot ScatterPlot GeoPlot`.
 - `PlotComposer` lays several plots out in one figure with shared hover, legend and timeline.
 - `width` and `height` are pixel numbers on a standalone plot. To fill a container or the window, bind its size (`examples/ResponsiveLine.svelte`) and render the plot once both are > 0.
 
@@ -43,17 +43,17 @@ Two ways to give data, one per plot:
 | `segments` | Style ranges of the data (rule 1 below). |
 | `markers` | Extra marks, an array of `{ type: '...', ... }`. |
 | `margins` | `{ top, right, bottom, left }`, each a number or `'auto'` (all `'auto'` by default). |
-| `tooltip` | `true` or `{ strategy, sync, format, content, series, anchorX, anchorY }`. The text lists matched rows highest value first; a `content` snippet gets them unsorted. |
+| `tooltip` | `true` or `{ strategy, sync, format, content, series, anchorX, anchorY }`; `format(row, number, context)`, `context` holding the row's `series`, `x`, `y`, `value`, `row` and what the kind adds (a treemap's `share`, a histogram's `from`/`to`/`count`, a box's quartiles). The text lists matched rows highest value first; a `content` snippet gets them unsorted. |
 | `timeline` | `{ accessor: 'year' }` steps through the rows by a field, drawn as a player bar (default); `type: 'rule'` draws a rule beside the plot instead. The field may hold numbers, `Date`s or date strings (ISO, or any other with `dateFormat: 'DD/MM/YYYY'`); date steps read as dates, and reach `onvalue`, `player.format` and `useFigure().timeline` (`steps`, `value`, `seekValue`) as `Date`s. Other options: `progress` (position, `0`-`1`), `values` (the steps, when not every distinct value), `filterMode` (`'exact'` shows the current step's rows, `'upTo'` every row up to it; `LinePlot` defaults to `'upTo'`), `interpolate` (tween values between steps), `scales` (`'shared'` keeps both axes still across steps, `'free'` refits both to each step, `'free-x'`/`'free-y'` refit one and keep the other still), `onprogress`, `onvalue`, and a rule's `orientation`, `show` and `thickness`. |
 | `facet` | `{ by: 'field', columns, gap, scales: 'shared'\|'free'\|'free-x'\|'free-y', mode: 'grid'\|'carousel'\|'paginated' }` or `{ rows, cols }`. |
-| `transforms` `statistics` | svelteplot transforms / derived summaries. `statistics` is `[{ type, ...options, series?, pooled? }]` (per series by default, `series: ['a']` only those, `pooled: true` all rows at once; a marker's own `.statistics` runs over its own `data`). Types: `regression` (`regressionType`: `'linear'|'quad'|'poly'|'exp'|'log'|'pow'|'loess'`, `order`, `base`, `span`, `confidence`, `styles`), `movingAverage` (`k`, `reduce`, `styles`), `bollinger` (`n`, `k`, `styles`), `density` (`kernel`, `bandwidth`, `styles`), `density2d` (`bandwidth`, `thresholds`, `styles`), `box` (the `box` marker's options), `deviation` (a rule at an estimator and a band around it, along the plot's value axis: `estimator`: `'mean'|'median'|'midrange'`, `spread`: `'stdev'|'mad'`, `k`, `rule` and `band`: styles or `false`, each with an optional `label: true | { text, styles: FontStyle }`, the band's also `edge: 'lower'|'upper'` and `position: 'inside'|'outside'`)|'upper'`). |
+| `transforms` `statistics` | svelteplot transforms / derived summaries. `treemap` is the library's own transform: `{ type: 'treemap', value: 'count', levels: ['island', 'species'], tile: 'squarify', aspect: 1 }` makes a tile per distinct path of `levels` (outermost first), its area the sum of its rows' `value`, and gives a `rect` marker `x1`/`x2`/`y1`/`y2` in the unit square (`x`/`y` at each tile's centre for a `text`). `statistics` is `[{ type, ...options, series?, pooled? }]` (per series by default, `series: ['a']` only those, `pooled: true` all rows at once; a marker's own `.statistics` runs over its own `data`). Types: `regression` (`regressionType`: `'linear'|'quad'|'poly'|'exp'|'log'|'pow'|'loess'`, `order`, `base`, `span`, `confidence`, `styles`), `movingAverage` (`k`, `reduce`, `styles`), `bollinger` (`n`, `k`, `styles`), `density` (`kernel`, `bandwidth`, `styles`), `density2d` (`bandwidth`, `thresholds`, `styles`), `box` (the `box` marker's options), `deviation` (a rule at an estimator and a band around it, along the plot's value axis: `estimator`: `'mean'|'median'|'midrange'`, `spread`: `'stdev'|'mad'`, `k`, `rule` and `band`: styles or `false`, each with an optional `label: true | { text, styles: FontStyle }`, the band's also `edge: 'lower'|'upper'` and `position: 'inside'|'outside'`)|'upper'`). |
 
-Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `PyramidPlot` mirrors two series around zero; `HeatmapPlot` colors cells by `color`; `HistogramPlot` bins one numeric field; `DensityPlot` smooths one numeric field into a kernel density curve (`styles.mark: 'line'` draws a line instead of an area; a `densityX` transform sets `kernel` and `bandwidth`); `BoxPlot` x = category, y = value, one box per category (its tooltip row is the box summary: `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers`); `ViolinPlot` x = category, y = value (swap for horizontal), the mirrored density of each category's values with a box inside (`styles`: `kernel`, `bandwidth`, `trim`, `scale: 'width'|'shared'`, `box: false | width`; its tooltip row is a box plot's); `LollipopPlot` x = category, y = value, one dot on a stem per category (stems start at zero, or at the nearest end of a pinned domain; `styles.values` labels each dot); `DumbbellPlot` x = category, y = value, `color`/`grouping` names exactly two series, joined by a connector per category (another count warns); `ClevelandPlot` is the same for any number of series, joined from the lowest to the highest (use `grouping` for a numeric series field; `styles.values.select` (`'first'|'last'|'min'|'max'` or a list), `series` and `color: 'series'` choose and color the labelled dots; `styles.connector` sets the connector's `width` (number or `'dots'` for a band), `color` (one, `{ by: 'sign' | 'difference' | 'length' }` or a function), `opacity`, `arrow` (draws the from-to stretch as an arrow), `outside` (the part past the from/to dots), `label` (centered on the from-to stretch) and the `from`/`to` series of its difference); `ForestPlot` x = value, y = category (or swapped), one dot per row on a stem spanning its interval given by `lower`/`upper` fields or an `error` either side (the value axis fits the intervals; `styles.connector.caps` toggles the end ticks, on by default); `BulletPlot` is a bar plot with a `target` (field, function or number: a tick across the band) and `ranges` (upper bounds, each a field, function or number: bands from the baseline, the smallest darkest) drawn around its thin bars (the value axis reaches them); `SlopePlot` x = category (its first and last positions are the two moments), y = value, a line with a dot on every point per series, its first and last labelled before and after it by `styles.values` (the value axis is hidden by default; `scales.y.axisDisplay: 'visible'` shows it); `SparklinePlot` is a small `LinePlot` with no axes and no legend (`legend` and `margins` bring them back), a dot on each series' last point and its value beside it (`styles.values` formats it or turns it off with `show: false`; `facet` makes one per category); `ScatterPlot` takes `r` (size) and `symbol`; `GeoPlot` takes GeoJSON/TopoJSON in `data` and `coordinates` for the projection (`docs/geo.md`).
+Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `PyramidPlot` mirrors two series around zero; `HeatmapPlot` colors cells by `color`; `HistogramPlot` bins one numeric field; `DensityPlot` smooths one numeric field into a kernel density curve (`styles.mark: 'line'` draws a line instead of an area; a `densityX` transform sets `kernel` and `bandwidth`); `BoxPlot` x = category, y = value, one box per category (its tooltip row is the box summary: `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers`); `ViolinPlot` x = category, y = value (swap for horizontal), the mirrored density of each category's values with a box inside (`styles`: `kernel`, `bandwidth`, `trim`, `scale: 'width'|'shared'`, `box: false | width`; its tooltip row is a box plot's); `LollipopPlot` x = category, y = value, one dot on a stem per category (stems start at zero, or at the nearest end of a pinned domain; `styles.values` labels each dot); `DumbbellPlot` x = category, y = value, `color`/`grouping` names exactly two series, joined by a connector per category (another count warns); `ClevelandPlot` is the same for any number of series, joined from the lowest to the highest (use `grouping` for a numeric series field; `styles.values.select` (`'first'|'last'|'min'|'max'` or a list), `series` and `color: 'series'` choose and color the labelled dots; `styles.connector` sets the connector's `width` (number or `'dots'` for a band), `color` (one, `{ by: 'sign' | 'difference' | 'length' }` or a function), `opacity`, `arrow` (draws the from-to stretch as an arrow), `outside` (the part past the from/to dots), `label` (centered on the from-to stretch) and the `from`/`to` series of its difference); `ForestPlot` x = value, y = category (or swapped), one dot per row on a stem spanning its interval given by `lower`/`upper` fields or an `error` either side (the value axis fits the intervals; `styles.connector.caps` toggles the end ticks, on by default); `BulletPlot` is a bar plot with a `target` (field, function or number: a tick across the band) and `ranges` (upper bounds, each a field, function or number: bands from the baseline, the smallest darkest) drawn around its thin bars (the value axis reaches them); `SlopePlot` x = category (its first and last positions are the two moments), y = value, a line with a dot on every point per series, its first and last labelled before and after it by `styles.values` (the value axis is hidden by default; `scales.y.axisDisplay: 'visible'` shows it); `SparklinePlot` is a small `LinePlot` with no axes and no legend (`legend` and `margins` bring them back), a dot on each series' last point and its value beside it (`styles.values` formats it or turns it off with `show: false`; `facet` makes one per category); `TreemapPlot` takes `value` (a tile's area) and `grouping` (the whole path of a tile, fields joined by dots, outermost first: `'sector.branch'` - the last level names it, rows with one path are one tile, the outermost colors the tiles and the legend); a `treemap` entry in its `transforms` sets `tile` (`'squarify'` default, `'binary'`, `'slice'`, `'dice'`, `'sliceDice'`); its tiles are labelled by `styles.values` with their name over their share of the whole, cut short or reduced to the share alone where they do not fit; its `segments` can be keyed by the path of a tile (`'Tertiary.Finance'`) and `tooltip.format(row, number, context)` gets the tile's row and a `context` with its `series`, `name`, `path`, `value` and `share` (0-100); `ScatterPlot` takes `r` (size) and `symbol`; `GeoPlot` takes GeoJSON/TopoJSON in `data` and `coordinates` for the projection (`docs/geo.md`).
 
 ## Switches
 
-- **Hover and tooltip** are enabled by `tooltip` and/or a hover marker. The usual look: `tooltip={true} markers={[{ type: 'hover' }]}`. `tooltip.strategy` is `'x' | 'y' | 'punctual' | 'series'`.
-- **Value labels**: `styles={{ values: { show: true } }}`. On a LinePlot they sit at the end of each series, spread apart automatically, and the right margin grows to fit them (keep `margins.right` at `'auto'`). Format with `values.format: (value, seriesName) => string`; style with `values.fontStyle`.
+- **Hover and tooltip** are enabled by `tooltip` and/or a hover marker. The usual look: `tooltip={true} markers={[{ type: 'hover' }]}`. `tooltip.strategy` is `'x' | 'y' | 'punctual' | 'series'`. The hover marker's `active` and `others` restyle the hovered shapes and the rest (`fill`, `fillOpacity`, `stroke`, `strokeWidth`, `strokeOpacity`, `strokeDasharray`, each a value or a function of the row): `markers={[{ type: 'hover', active: { fillOpacity: 1 }, others: { fillOpacity: 0.3 } }]}`. It works on a treemap's tiles, a bar plot's bars and a heatmap's cells as they are; a marker of yours takes it with `hover: true` (also a hit area) or `hover: 'style'`. A series the legend dims stays hoverable but keeps its dimmed fill; one it hides, omits or rescales is never hovered. The hover marker draws its plot kind's own hover - a crosshair along the strategy's axes with a dot and the value on line, area and density plots; a crosshair through the point and its value on a scatter plot; a rule along the value axis with a dot and the value on slope and Cleveland-family plots; the hovered category's `band` behind bar, bullet, box, violin and pyramid plots; the hovered bin's span behind a histogram; a dot on a sparkline; on a treemap or a heatmap, only the hovered tile or cell outlined (`hover.active` in the configuration) - following the strategy in force (a composer's can change while shown), laid out as `back` (markers behind the plot's shapes) and `front` (in front), lists of any markers but `hover` that replace the kind's when set (`back: []` draws nothing behind). They draw the hovered points (`x`, `y`, `label`, `series`, `color`, `areaInset`, `row`), and what they leave unset comes from the hover: `x`/`y`, a `rule`'s and a `band`'s `value`, a `text`'s `text`, the configuration's `hover` look and the series color. `points: 'active' | (point) => boolean` draws only the point under the pointer, or some: `{ type: 'hover', back: [{ type: 'rule', axis: 'x', points: 'active' }], front: [{ type: 'dot' }] }`.
+- **Value labels**: `styles={{ values: { show: true } }}`. On a LinePlot they sit at the end of each series, spread apart automatically, and the right margin grows to fit them (keep `margins.right` at `'auto'`). Format with `values.format: (value, number, context) => string` (`context.series`, `context.row`); style with `values.fontStyle`.
 - **Toggling series from the legend**: `interactive.enabled` on the series section.
 - **A frame** around the plot area: `styles={{ frame: true }}`.
 
@@ -76,8 +76,9 @@ Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `Pyramid
 Inside a plot's snippets (`header`, `footer`, tooltip `content`) or any child of a figure, call during component init:
 
 - `useFigure()` returns `{ hover, legend, timeline }` for the whole figure.
-- `usePlot()` returns the same plus `margins`, `scales`, `axes`, `data`, `width`, `height`, `svelteplot` (inside a plot, e.g. a `component` marker).
-- `legend.off` (names of hidden series), `legend.isOff(name)`, `legend.toggle(name, action)`, `turnOff`, `turnOn`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes, so the visible domain follows `legend.off`.
+- `usePlot()` returns the same plus `margins`, `scales`, `axes`, `data`, `width`, `height`, `svelteplot` (inside a plot, e.g. a `component` marker), and `contextOf(row)`.
+- Row context: every row a plot draws has a context worked out once - `series`, `x`, `y`, `value`, `row` and what the kind adds (`TreemapPlot`: `name`, `path`, `share`; `HistogramPlot`: `count`, `from`, `to`; `BoxPlot`/`ViolinPlot`: `category`, `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers`; `DensityPlot`'s `value` is the estimate). `tooltip.format`, `styles.values.format`, the `hover` marker's points (`point.context`) and `RowContext.of(row)` all read it.
+- `legend.off` (names of hidden series), `legend.isOff(name)`, `legend.toggle(name, action)`, `turnOff`, `turnOn`. `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%, so the visible domain follows `legend.off`.
 - `timeline.steps`, `value`, `progress`, `playing`, `seek(p)`, `seekValue(v)`, `next()`, `previous()`, `play()`, `pause()`, `toggle()`, `setSpeed()`.
 - `hover.activeX`, `activeY`, `activeSeries`, `source`.
 
@@ -86,7 +87,7 @@ The timeline is a player bar by default: `timeline={{ accessor: 'year', player:
 ## Markers
 
 Add with `markers={[{ type: '...' }]}`. For x/y plots:
-`area arrow bar bollinger box brush cell component delaunayLink delaunayMesh delta density difference dot hover hull image line raster rect regression rule text tick trail violin voronoi voronoiMesh waffle`.
+`area arrow band bar bollinger box brush cell component delaunayLink delaunayMesh delta density difference dot hover hull image line raster rect regression rule text tick trail violin voronoi voronoiMesh waffle`.
 GeoPlot: `graticule sphere dot text vector link contour inset geo-hover geo-component`.
 
 - `delta` annotates the difference between two series at a position: `{ type: 'delta', axis: 'x', at: 2020, from: { type: 'series', series: 'A' }, to: { type: 'series', series: 'B' }, formatDiff: (d) => d.toFixed(1) }`; `at` can be a list of positions, one delta at each (`at: [1991, 2001]`), and `line`, `text` and `dot` can be functions of the position (`text: (at) => at === 2022 ? { dx: -20, textAnchor: 'end' } : { dx: 20 }`).
@@ -108,6 +109,7 @@ GeoPlot: `graticule sphere dot text vector link contour inset geo-hover geo-comp
 - `LineByRegion.svelte` - one line per region with title, legend, end labels and tooltip.
 - `ResponsiveLine.svelte` - fill the window, end-of-line labels, axis labels.
 - `Tooltip.svelte` - tooltip + hover marker.
+- `TreemapHover.svelte` - a treemap whose hover lightens the hovered tile and fades the rest.
 - `Segments.svelte` - styling a range of the data.
 - `LegendToggle.svelte` + `LegendReader.svelte` - interactive legend and reading its state.
 - `TimelinePlayer.svelte` - animated bar chart with a player.

package/llms.txt

@@ -26,6 +26,7 @@ Start with the full guide: it lists the mental model, the props every plot share
   - [BulletPlot](./docs/plots/ranking/bullet.md)
   - [SlopePlot](./docs/plots/evolution/slope.md)
   - [SparklinePlot](./docs/plots/evolution/sparkline.md)
+  - [TreemapPlot](./docs/plots/part-of-a-whole/treemap.md)
   - [ClevelandPlot](./docs/plots/ranking/cleveland.md)
   - [HeatmapPlot](./docs/plots/correlation/heatmap.md)
   - [PyramidPlot](./docs/plots/distribution/pyramid.md)
@@ -40,7 +41,7 @@ Start with the full guide: it lists the mental model, the props every plot share
 - [Chrome](./docs/chrome.md): title, caption, header, footer, order, dividers
 - [Facets](./docs/facets.md): small multiples
 - [Composer](./docs/composer.md): several plots in one figure
-- [Reading plot state](./docs/state.md): `useFigure`, `usePlot`
+- [Reading plot state](./docs/state.md): `useFigure`, `usePlot`, the row context every format reads
 - [Maps](./docs/geo.md): GeoPlot, projections, camera, map markers
 - [Theming](./docs/theming.md): configuration, themes, locale, CSS variables
 
@@ -55,6 +56,8 @@ Start with the full guide: it lists the mental model, the props every plot share
 - [Timeline rule driven by a slider](./examples/TimelineRule.svelte)
 - [Facets with a synced tooltip](./examples/Facets.svelte)
 - [Bars with value labels](./examples/BarValues.svelte)
+- [Treemap: a tile per row, sized by its value and nested by grouping](./examples/Treemap.svelte)
+- [Treemap whose hover lightens the hovered tile and fades the rest](./examples/TreemapHover.svelte)
 - [Custom tooltip card](./examples/CustomTooltip.svelte)
 - [The smallest plot: rows, fields and a pixel size](./examples/FirstPlot.svelte)
 - [Line per series over a date axis, with end labels](./examples/LineDates.svelte)