@fundar/data-chart-telling 1.17.0 → 1.19.0

package/docs/value-labels.md

@@ -0,0 +1,159 @@
+# Value labels
+
+A plot can write its values on its own shapes: the value of each bar, the last value of each line, the count of each bin. They are the plot's `styles.values`. This page goes from turning them on to placing them precisely; the _Layout/Values_ stories in Storybook show every option drawn.
+
+## Turning them on
+
+```svelte
+<BarPlot {data} x="province" y="value" styles={{ values: { show: true } }} />
+```
+
+Setting any option of `styles.values` turns the labels on, so `show: true` is only needed alone: `styles={{ values: { decimals: 1 } }}` draws them too. `show: false` turns them off whatever else is set. A heatmap and a treemap show theirs by default.
+
+Each plot kind places them its own way: past the tip of each bar, beside the last point of each line, on a free spot around each dot of a scatter, in the middle of each cell. The rest of this page is about changing that.
+
+## What a label says
+
+A label writes the value it labels - its row context's `value` - as `decimals`, `prefix`, `suffix` and `signDisplay` ask, over the configuration's `numbers` (see [Number format](theming.md#number-format)):
+
+```ts
+styles: { values: { decimals: 1, signDisplay: 'always', suffix: ' yrs' } }
+```
+
+`format(value, number, context)` writes anything else. `number` writes a value as the fields above ask; `context` is what the plot knows of the labelled row (see [Row context](state.md#row-context)): its `series`, its `row` with the other fields of the data, and what the plot kind works out, such as a histogram bin's `count` or a treemap tile's `share`.
+
+```ts
+format: (value, number, { series, row }) => `${row.country}: ${number(value)}`;
+```
+
+## Which values of a row
+
+Most plots have one value per row. On a plot whose rows have several, each one is a **part** of the row's context, and `parts` picks the ones written:
+
+| Plot      | Parts                                                        | Default                    |
+| --------- | ------------------------------------------------------------ | -------------------------- |
+| Box       | `'min'`, `'p25'`, `'median'`, `'p75'`, `'max'`, `'outliers'` | `['min', 'median', 'max']` |
+| Violin    | the same                                                     | `['median']`               |
+| Bullet    | `'value'` (its bar), `'target'`, `'ranges'` (each bound)     | `['value']`                |
+| Forest    | `'value'` (its estimate), `'lower'`, `'upper'`               | `['value']`                |
+| Any other | `'value'`                                                    | `['value']`                |
+
+Each part is written beside its shape at its own value: a box's beside the box, an interval's ends past each end. A part holding several values - a box's `'outliers'`, a bullet's `'ranges'` - writes a label for each. `parts` is a list, or a record turning each on (`true`) or giving it options of its own - where it sits, its `format`:
+
+```ts
+styles: { values: { parts: ['median'] } }
+styles: { values: { parts: { median: true, max: { format: (v) => `max ${v}` } }, series: 'virginica' } }
+```
+
+Its type takes only the parts of the plot, and `format`'s `context.part` names the one written. A worked-out part - a quartile - is rounded to two decimals first.
+
+## Which rows
+
+`select` picks the rows labelled of each group: `'first'`, `'last'`, `'min'`, `'max'`, or a list of them. A group is a series on a line or area plot (where the default is `'last'`) and a category on the plots that join dots; elsewhere every row is labelled. `series` labels only the series named.
+
+```ts
+styles: { values: { select: ['min', 'max'], series: 'female' } }
+```
+
+On a bar, a heatmap or a histogram, `select` applies to the `'point'` layout below, which labels some shapes and leaves the others bare.
+
+## Layouts
+
+Where a label goes is its layout, one of three, named by the geometry it is laid out on:
+
+| Layout    | Where                                                                                | Example                                            |
+| --------- | ------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| `'point'` | Beside a point of the shape: a line's last point, a dot, a corner of a bar           | `{ layout: 'point', side: 'above' }`               |
+| `'path'`  | Along an edge or a stroke of the shape: past a bar's tip, along a line, around a dot | `{ layout: 'path', edge: 'base', side: 'inside' }` |
+| `'box'`   | Inside the box of each shape, fitted to it: a bar, a cell, a tile                    | `{ layout: 'box', anchor: 'top' }`                 |
+
+A plot kind takes the layouts its shapes can write, and its `styles.values` type takes only those: a line has no box to write in, so `LinePlot` takes `'point'` and `'path'`. Changing the layout is explicit, with `layout`; each kind brings its own defaults for every layout it takes, so `{ layout: 'path' }` alone is enough.
+
+| Plot                                           | Default                                                | Also                                                  |
+| ---------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------- |
+| Line, slope, sparkline                         | `'point'` after the last point                         | `'path'`: each series' name along its line            |
+| Area                                           | `'point'` after the last point                         | `'path'`: along the top (or bottom) edge of each area |
+| Bar, bullet, pyramid                           | `'path'` past each bar's tip; `'box'` on a stacked bar | `'box'`, `'point'`                                    |
+| Histogram                                      | `'path'` past each bin's top                           | `'box'`, `'point'`                                    |
+| Heatmap                                        | `'box'`                                                | `'path'`, `'point'`                                   |
+| Treemap                                        | `'box'`                                                |                                                       |
+| Scatter, Cleveland, dumbbell, lollipop, forest | `'point'` beside each dot                              | `'path'`: around each dot's rim                       |
+| Density                                        | `'point'` over each curve's peak, naming it            | `'path'`: each name along its curve, at its peak      |
+| Box, violin                                    | `'point'` beside each box, at each part's value        |                                                       |
+
+## Beside a point: `'point'`
+
+The point depends on the shape: on a line or an area, a row's own point; on a dot, its center; on a bar or a cell, a point of its box, which `anchor` names - an edge's middle (`'top'`...) or a corner (`'top-left'`...).
+
+From that point, `side` says where the text goes, as it reads: `'after'` it (to its right), `'before'` it, `'above'`, `'below'` or `'on'` it. `gap` is how far, 6px across and 8px up or down by default.
+
+```ts
+styles: { values: { side: 'above', gap: 12 } }                      // a line's last value, over its point
+styles: { values: { layout: 'point', anchor: 'top', select: 'max' } } // only the longest bar, over its top
+```
+
+Labels that would overlap move apart:
+
+- On a line, they fan out into lanes along one column, each joined back to its point by an elbow; `strokeStyle` styles those connectors. The margin on that side grows to hold them while it is `'auto'`.
+- On a scatter, each takes a free spot around its dot - above it first (its own `side`), then on clockwise - clear of the other labels and dots, and one with no room is left out.
+- A label on its own point (`side: 'on'`) stays there; where a shape drawn after its own covers it, it is left out. Of dots drawn over one another, only the top one's value shows.
+
+## Along a path: `'path'`
+
+The path depends on the shape:
+
+- On a bar or a cell, an edge of its box, which `edge` names: `'top'`, `'bottom'`, `'left'` or `'right'` as the page draws them, and on a bar `'tip'`, the end its value runs to, or `'base'`, the one at zero. The tip is read per row, so a bar below zero has its tip at its bottom, and a label past it goes under it.
+- On a line, the line itself, curving with it: one label per series, its series' name unless `format` writes another.
+- On an area, its top edge, or its bottom one with `edge: 'bottom'`; on a stack, each band's own.
+- On a dot, its rim, over its top.
+
+`side` is which side of the path the text sits on: on a shape `'outside'` (the default), `'inside'` or `'on'` its edge; on a line or an area `'above'` (the default), `'below'` or `'on'` it, where the text is drawn over a halo of the background. `offset` is where along the path, from its left or top end: `'start'`, `'middle'`, `'end'` or a percentage of its length; on a line or an area, `'max'` and `'min'` put each label at its own peak or trough. A label centred near an end of its line is moved in just enough to be written whole. `gap` is how far from it.
+
+```ts
+styles: { values: { layout: 'path', edge: 'tip', side: 'inside' } } // inside each bar's end
+styles: { values: { layout: 'path', side: 'on', offset: '60%' } }    // each name on its line
+```
+
+A label along a path is written whole, not fitted to its shape. Along a straight-segmented line or area, it follows a smooth curve through the same points, so its letters do not spread apart at the corners.
+
+## In a box: `'box'`
+
+The label is written in the middle of its shape's box. `anchor` puts it against an edge (`'top'`, `'bottom'`, `'left'`, `'right'`) or in a corner (`'top-left'`...), `gap` from it.
+
+A label in a box is fitted to it: one too wide is written smaller, down to `minFontSize`; at that size it breaks into the lines the box holds and the last one is cut short with an ellipsis; and when not even that fits, it is left out. `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 } } })`.
+
+## How labels look
+
+- A label inside its shape - in a box, or along an edge with `side: 'inside'` - with no color of its own is written in the color that reads best on the shape: white on a dark one, near black on a light one, picked per shape from the configuration's `text.label.contrast`. The shape is read as it is seen: a `fillOpacity` under 1 blends it with the plot's `background`.
+- A label outside its shape is written in its series' color on a line or an area, and in the axis color elsewhere. `color: 'series'` writes each in its series' color, and any other CSS color writes them all in it.
+- `fontStyle` sets the text's look - `fontSize`, `fontWeight`, `fill`, `rotate`, `class`... - but never where it sits, which is the layout's.
+- `hoverIsolate: true` dims every other series while the pointer is over a label.
+
+## Labels on markers
+
+A marker writes the same labels on its shapes with `label`, which takes a layout and its options like `styles.values`, with every option of a `text` marker besides (`text`, `styles`, `fit`, `declutter`...):
+
+```ts
+{ type: 'line', data, x: 'year', y: 'value', grouping: 'country',
+  label: { layout: 'path', text: 'country', offset: '80%' } }
+```
+
+`text` is a field of the row, a function of it, or a literal. A list of labels writes each of them: `label: [{ text: 'value', anchor: 'top' }, { text: 'name', anchor: 'bottom' }]`. Each marker kind takes the layouts its shapes can write, `'box'` by default on shapes with a box and `'point'` on the others:
+
+| Marker          | `'box'` | `'path'`                            | `'point'`                     |
+| --------------- | ------- | ----------------------------------- | ----------------------------- |
+| `bar`, `waffle` | default | its edges, `'tip'` and `'base'` too | a point of its box (`anchor`) |
+| `rect`, `cell`  | default | its edges                           | a point of its box (`anchor`) |
+| `line`, `trail` |         | the line                            | default: each row's point     |
+| `area`          |         | its top or bottom edge              | default: each row's top       |
+| `dot`           |         | its rim                             | default: its center           |
+
+On a marker:
+
+- `select` picks a `'point'` label's rows of each `grouping` of the marker; it also takes a function of the row. Rows without a place (a gap) are never labelled.
+- `declutter: true` (or `'lanes'`) fans overlapping point labels into lanes, `declutter: 'around'` moves each to a free spot around its point. The point labels of every marker of a plot are laid out together, so the ends of several lines fan out as one.
+- A label takes the pointer only with a handler of its own (`onpointerenter`...); the others leave it to the shape under it, so `onclick` and the hover go on as they were. Its styles take functions of the row, to dim the label of a series, say.
+- A box label's `fit` takes `false`, or an object: `minFontSize`, `minLetters`, `padding`, and `fallback` - a value, a field or a function of the row, written instead when fewer than `minLetters` letters would show.
+- `fitMargins: true` grows the plot's margins to hold a label that runs past them.
+
+A `text` marker of your own takes the same `declutter`, and `covers`: the shape each row's point sits in, so a label covered by a later row's shape is left out.

package/examples/BarValues.svelte

@@ -10,5 +10,5 @@
 	data={REGION_VALUES.filter((row) => row.date === MONTHS.at(-1))}
 	x="region"
 	y="value"
-	styles={{ values: { show: true, anchor: 'outside' } }}
+	styles={{ values: { show: true } }}
 />

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/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/llms-full.txt

@@ -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 }`; `format(row, number, context)`, `context` holding the row's `series` and what the kind adds (a treemap's `share`). 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. `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); `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` and `share` (0-100); `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**: any option of `styles.values` turns them on (`{ show: true }` alone too). Each kind places them its own way: past each bar's tip, after a line's last point (overlapping ones fan out into lanes and the margin grows to fit them; keep `margins.right` at `'auto'`), around each scatter dot, in each heatmap cell. `layout` changes it, with the options of each: `'point'` (`side: 'after' | 'before' | 'above' | 'below' | 'on'`, `gap`; `anchor` on bars and cells), `'path'` (`edge`, with `'tip'`/`'base'` on bars; `side`; `offset: 'start' | 'middle' | 'end' | '40%'`; on a line it writes each series' name along it), `'box'` (`anchor`, fitted to the shape). A kind's `styles.values` type takes only its layouts. Text: `format: (value, number, context) => string` (`context.series`, `context.row`), or `decimals`/`prefix`/`suffix`/`signDisplay`; `select` and `series` pick the rows; `color: 'series'`; `fontStyle` styles the text but never places it. On a plot whose rows have several values, `parts` picks which: `BoxPlot`/`ViolinPlot` `'min' | 'p25' | 'median' | 'p75' | 'max' | 'outliers'` (box default `['min','median','max']`), `BulletPlot` `'value' | 'target' | 'ranges'`, `ForestPlot` `'value' | 'lower' | 'upper'`; a list, or a record with per-part options (`{ median: { format } }`); every value is read off the row context (`context.part` in `format`). `DensityPlot` names each curve at its peak. A marker's `label` takes the same layouts. See `docs/value-labels.md`.
 - **Toggling series from the legend**: `interactive.enabled` on the series section.
 - **A frame** around the plot area: `styles={{ frame: true }}`.
 
@@ -76,7 +76,8 @@ 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).
+- `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 }`).
@@ -101,13 +102,14 @@ GeoPlot: `graticule sphere dot text vector link contour inset geo-hover geo-comp
 
 ## Docs (in `docs/`)
 
-`getting-started.md`, `concepts.md`, `plots.md` (an index: one page per plot kind in `plots/`), `scales.md`, `styles-and-segments.md`, `markers.md`, `transforms-and-statistics.md`, `tooltip-and-hover.md`, `legend.md`, `timeline.md`, `chrome.md`, `facets.md`, `composer.md`, `state.md`, `geo.md`, `theming.md`.
+`getting-started.md`, `concepts.md`, `plots.md` (an index: one page per plot kind in `plots/`), `scales.md`, `styles-and-segments.md`, `value-labels.md`, `markers.md`, `transforms-and-statistics.md`, `tooltip-and-hover.md`, `legend.md`, `timeline.md`, `chrome.md`, `facets.md`, `composer.md`, `state.md`, `geo.md`, `theming.md`.
 
 ## Examples (in `examples/`, all runnable)
 
 - `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

@@ -33,6 +33,7 @@ Start with the full guide: it lists the mental model, the props every plot share
   - [ScatterPlot](./docs/plots/correlation/scatter.md)
 - [Scales](./docs/scales.md): axes and channel scales
 - [Styles and segments](./docs/styles-and-segments.md): value labels, frame, gaps, ranges of data
+- [Value labels](./docs/value-labels.md): `styles.values` and a marker's `label`, their `'point'`, `'path'` and `'box'` layouts and options
 - [Markers](./docs/markers.md): annotations, regions, hover highlight, custom components
 - [Transforms and statistics](./docs/transforms-and-statistics.md): stacking, binning, smoothing, regression, and the statistics `regression`, `movingAverage`, `bollinger`, `density`, `density2d`, `box`, `deviation` with their options
 - [Tooltip and hover](./docs/tooltip-and-hover.md): tooltip options, hover marker, sync
@@ -41,7 +42,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
 
@@ -57,6 +58,7 @@ Start with the full guide: it lists the mental model, the props every plot share
 - [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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
   "license": "MIT",
   "author": "Ezequiel Puerta",
@@ -57,6 +57,7 @@
     "d3-interpolate": "^3.0.1",
     "d3-scale-chromatic": "^3.1.0",
     "d3-selection": "^3.0.0",
+    "d3-shape": "^3.2.0",
     "d3-zoom": "^3.0.0"
   },
   "peerDependencies": {
@@ -86,6 +87,7 @@
     "@types/d3-interpolate": "^3.0.4",
     "@types/d3-scale-chromatic": "^3.1.0",
     "@types/d3-selection": "^3.0.11",
+    "@types/d3-shape": "^3.2.0",
     "@types/d3-zoom": "^3.0.8",
     "@types/node": "^22",
     "@vitest/browser": "^4.1.7",

package/dist/markers/utils/BoxLabel.d.ts

@@ -1,58 +0,0 @@
-import type { TextMarkerConfig } from '../../types/markers/common';
-import type { TextLabelConfig } from '../../types/markers/basic/text';
-/** Where a row's edge along an axis is: a field of the rows, the symbol a transform keyed it by, a function of the row, or a literal. */
-type Edge = unknown;
-/** The edges of the box each row spans, in the data's own terms. */
-export type BoxChannels = {
-    x1: Edge;
-    x2: Edge;
-    y1: Edge;
-    y2: Edge;
-};
-/** The scales a box is measured on. */
-export type BoxScales = Record<string, {
-    type?: string;
-    fn: any;
-} | undefined>;
-/** The pixel size of the box of a row, for the markers whose boxes are bands of a category axis rather than edges. */
-export type BoxSizer = (row: unknown, scales: BoxScales) => {
-    width: number;
-    height: number;
-} | undefined;
-/** The `text` marker that labels the boxes a marker draws, and where each label's box is. */
-export type BoxLabelMarker = {
-    marker: TextMarkerConfig;
-    box: BoxChannels | BoxSizer;
-};
-/** What a marker has to say for its boxes to be labelled. */
-export type Labelled = {
-    type?: string;
-    data?: unknown[];
-    label?: TextLabelConfig;
-    x?: Edge;
-    y?: Edge;
-    x1?: Edge;
-    x2?: Edge;
-    y1?: Edge;
-    y2?: Edge;
-    isHorizontal?: boolean;
-    role?: string;
-    thickness?: number;
-    /** The marker's styles: the insets of a cell or a bar are read off them. */
-    styles?: object;
-};
-/**
- * How a marker that draws a box per row writes a label in each: the `text` marker for them, centred on the box,
- * and where the box is for it to fit to. A `rect` says it with its edges, a `cell` is a band of each axis, and a bar
- * or a waffle is a band of its category axis and the stretch of its value.
- */
-export declare class BoxLabel {
-    #private;
-    /** `undefined` when the marker has no label, or does not say where its boxes are. */
-    static of(marker: Labelled, plot?: {
-        isHorizontal?: boolean;
-        scales?: () => BoxScales | undefined;
-        gap?: number;
-    }): BoxLabelMarker | undefined;
-}
-export {};

package/dist/markers/utils/BoxLabel.js

@@ -1,175 +0,0 @@
-const read = (edge) => (row) => typeof edge === 'function'
-    ? edge(row)
-    : typeof edge === 'string' || typeof edge === 'symbol'
-        ? row?.[edge]
-        : edge;
-/** The middle of two positions along an axis, whether numbers or dates. */
-const middle = (from, to) => from instanceof Date || to instanceof Date
-    ? new Date((Number(from) + Number(to)) / 2)
-    : (Number(from) + Number(to)) / 2;
-const bandwidth = (scale) => scale?.type === 'band' ? Number(scale.fn.bandwidth()) : undefined;
-const distance = (scale, from, to) => scale ? Math.abs(Number(scale.fn(to)) - Number(scale.fn(from))) : undefined;
-/**
- * How a marker that draws a box per row writes a label in each: the `text` marker for them, centred on the box,
- * and where the box is for it to fit to. A `rect` says it with its edges, a `cell` is a band of each axis, and a bar
- * or a waffle is a band of its category axis and the stretch of its value.
- */
-export class BoxLabel {
-    /** `undefined` when the marker has no label, or does not say where its boxes are. */
-    static of(marker, plot = {}) {
-        if (!marker.label)
-            return undefined;
-        const own = BoxLabel.#shape(marker, plot.isHorizontal ?? marker.isHorizontal ?? false);
-        if (!own)
-            return undefined;
-        const { anchor, outside, gap, ...label } = marker.label;
-        const size = typeof own.box === 'function' ? own.box : own.size;
-        const placed = BoxLabel.#anchored({
-            anchor,
-            outside,
-            gap: gap ?? plot.gap
-        }, label, size, plot.scales);
-        return {
-            box: own.box,
-            marker: {
-                // A label outside its shape has nothing to fit to.
-                fit: !outside,
-                ...label,
-                ...placed,
-                type: 'text',
-                data: marker.data,
-                x: own.x,
-                y: own.y
-            }
-        };
-    }
-    /**
-     * What puts a label at `anchor` of its shape: the pixels it is moved from the middle - a function of the row, for
-     * the size of its shape is the row's own - and the sides of its point it is written on. `{}` for the middle.
-     */
-    static #anchored(where, label, size, scales) {
-        const { anchor = 'middle', outside = false } = where;
-        if (anchor === 'middle' || !size)
-            return {};
-        const gap = where.gap ?? 4;
-        const horizontal = anchor.endsWith('left') ? -1 : anchor.endsWith('right') ? 1 : 0;
-        const vertical = anchor.startsWith('top') ? -1 : anchor.startsWith('bottom') ? 1 : 0;
-        // Beyond an edge only means something for an edge: a corner is inside its shape.
-        const beyond = outside && horizontal * vertical === 0;
-        const away = beyond ? 1 : -1;
-        const move = (axis, side, row) => {
-            // Read when a label is drawn, not when its marker is made: the scales move as the labels register.
-            const current = scales?.();
-            const box = current ? size(row, current) : undefined;
-            return box ? side * (box[axis] / 2 + away * gap) : 0;
-        };
-        // A number of the label's own (or its styles') is added to the move: it is the push from the anchor.
-        const own = (value, fallback) => Number(typeof value === 'number' ? value : (fallback ?? 0));
-        const baseX = own(label.dx, label.styles?.dx);
-        const baseY = own(label.dy, label.styles?.dy);
-        return {
-            dx: horizontal === 0 ? label.dx : (row) => baseX + move('width', horizontal, row),
-            dy: vertical === 0 ? label.dy : (row) => baseY + move('height', vertical, row),
-            styles: {
-                ...label.styles,
-                textAnchor: label.styles?.textAnchor ??
-                    (horizontal === 0 ? 'middle' : (horizontal === 1) === beyond ? 'start' : 'end'),
-                lineAnchor: label.styles?.lineAnchor ??
-                    (vertical === 0 ? 'middle' : (vertical === 1) === beyond ? 'top' : 'bottom')
-            }
-        };
-    }
-    /** A style of the marker, when it is a number: a function of the row says nothing of a box in general. */
-    static #style(marker, name) {
-        const value = marker.styles?.[name];
-        return typeof value === 'number' ? value : undefined;
-    }
-    static #shape(marker, isHorizontal) {
-        if (marker.type === 'cell')
-            return BoxLabel.#cell(marker);
-        if (marker.type === 'bar') {
-            return marker.role === 'segment'
-                ? BoxLabel.#bar(marker, marker.isHorizontal ?? false)
-                : undefined;
-        }
-        if (marker.type === 'waffle')
-            return BoxLabel.#bar(marker, isHorizontal);
-        return BoxLabel.#edges(marker);
-    }
-    /** A rectangle: the box is between its edges. */
-    static #edges({ x, y, x1, x2, y1, y2 }) {
-        // A side with a value and no start, next to one with both its edges, runs from zero to it, as a bar does.
-        if (y1 === undefined &&
-            y2 === undefined &&
-            y !== undefined &&
-            x1 !== undefined &&
-            x2 !== undefined) {
-            [y1, y2] = [0, y];
-        }
-        if (x1 === undefined &&
-            x2 === undefined &&
-            x !== undefined &&
-            y1 !== undefined &&
-            y2 !== undefined) {
-            [x1, x2] = [0, x];
-        }
-        if ([x1, x2, y1, y2].some((edge) => edge === undefined))
-            return undefined;
-        const [left, right, top, bottom] = [x1, x2, y1, y2].map(read);
-        const size = (row, scales) => {
-            const [width, height] = [
-                distance(scales.x, left(row), right(row)),
-                distance(scales.y, top(row), bottom(row))
-            ];
-            return width === undefined || height === undefined ? undefined : { width, height };
-        };
-        return {
-            box: { x1, x2, y1, y2 },
-            size,
-            x: (row) => middle(left(row), right(row)),
-            y: (row) => middle(top(row), bottom(row))
-        };
-    }
-    /** A cell: a band of each axis, less its inset. */
-    static #cell(marker) {
-        if (marker.x === undefined || marker.y === undefined)
-            return undefined;
-        const inset = Number(BoxLabel.#style(marker, 'inset') ?? 0.5);
-        const box = (_, scales) => {
-            const [width, height] = [bandwidth(scales.x), bandwidth(scales.y)];
-            return width === undefined || height === undefined
-                ? undefined
-                : { width: width - 2 * inset, height: height - 2 * inset };
-        };
-        return { box: box, x: marker.x, y: marker.y };
-    }
-    /** A bar or a waffle: a band of the category axis, as wide as its insets leave it, and as long as its value. */
-    static #bar(marker, isHorizontal) {
-        const [category, from, to] = isHorizontal
-            ? [marker.y, marker.x1, marker.x2]
-            : [marker.x, marker.y1, marker.y2];
-        const value = isHorizontal ? marker.x : marker.y;
-        // Without both ends, the bar runs from zero to its value.
-        const [start, end] = from !== undefined && to !== undefined ? [from, to] : [0, value];
-        if (category === undefined || end === undefined)
-            return undefined;
-        const [first, last] = [start, end].map(read);
-        const [before, after] = isHorizontal
-            ? [BoxLabel.#style(marker, 'insetTop'), BoxLabel.#style(marker, 'insetBottom')]
-            : [BoxLabel.#style(marker, 'insetLeft'), BoxLabel.#style(marker, 'insetRight')];
-        const middleOf = (row) => middle(first(row), last(row));
-        const box = (row, scales) => {
-            const band = bandwidth(isHorizontal ? scales.y : scales.x);
-            const length = distance(isHorizontal ? scales.x : scales.y, first(row), last(row));
-            if (band === undefined || length === undefined)
-                return undefined;
-            const thickness = marker.thickness ?? band * (1 - Number(before ?? 0) - Number(after ?? 0));
-            return isHorizontal
-                ? { width: length, height: thickness }
-                : { width: thickness, height: length };
-        };
-        return isHorizontal
-            ? { box: box, x: middleOf, y: category }
-            : { box: box, x: category, y: middleOf };
-    }
-}

package/dist/markers/utils/MarkerLabel.svelte

@@ -1,33 +0,0 @@
-<script lang="ts">
-	import TextMarker from '../text/TextMarker.svelte';
-	import { getConfiguration } from '../../configuration/config.svelte';
-	import { usePlot } from '../../layout/plot/usePlot';
-	import { BoxLabel, type Labelled } from './BoxLabel';
-	import { MARK_EVENTS } from '../../types/markers/channels/commonMarkerEvents';
-	import type { TextLabelConfig } from '../../types/markers/basic/text';
-
-	/**
-	 * The `label` of a marker that draws a box per row: a `text` marker anchored in each box and fitted to it. A marker
-	 * with a label only has to render `<MarkerLabel {marker} />` after its own shapes. Nothing is drawn without a
-	 * `label`, or when the marker does not say where its boxes are.
-	 */
-	const { marker }: { marker: Labelled & { label?: TextLabelConfig } } = $props();
-	const plot = usePlot();
-	const cfg = $derived(getConfiguration());
-
-	const labelled = $derived(
-		BoxLabel.of(marker, {
-			isHorizontal: plot.axes?.isHorizontal,
-			gap: cfg.text.label.gap,
-			scales: () => plot.svelteplot.scales as never
-		})
-	);
-	/** A label with a handler of its own listens for the pointer; one without leaves it to the shape under it. */
-	const listens = $derived(MARK_EVENTS.some((name) => !!marker.label?.[name]));
-</script>
-
-{#if labelled}
-	<g pointer-events={listens ? undefined : 'none'}>
-		<TextMarker marker={labelled.marker} box={labelled.box} />
-	</g>
-{/if}