@fundar/data-chart-telling 1.18.0 → 1.20.0

package/dist/utils/ConfigEquality.js

@@ -0,0 +1,37 @@
+/** Whether two configuration values hold the same, for a plot to tell a new configuration from one built again. */
+export class ConfigEquality {
+    /** How many levels of objects and arrays it looks into; a value nested deeper only matches as the same object. */
+    static MAX_DEPTH = 6;
+    /**
+     * Whether `a` and `b` are the same value, or plain objects and arrays alike all the way down, dates of one
+     * time; anything else - a function, a class instance - only if it is the same object.
+     */
+    static same(a, b, depth = 0) {
+        if (Object.is(a, b))
+            return true;
+        if (depth >= ConfigEquality.MAX_DEPTH)
+            return false;
+        if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+            return false;
+        if (a instanceof Date || b instanceof Date) {
+            return a instanceof Date && b instanceof Date && +a === +b;
+        }
+        if (Array.isArray(a) || Array.isArray(b)) {
+            return (Array.isArray(a) &&
+                Array.isArray(b) &&
+                a.length === b.length &&
+                a.every((value, i) => ConfigEquality.same(value, b[i], depth + 1)));
+        }
+        if (!ConfigEquality.#isPlain(a) || !ConfigEquality.#isPlain(b))
+            return false;
+        const keys = Reflect.ownKeys(a);
+        if (keys.length !== Reflect.ownKeys(b).length)
+            return false;
+        return keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) &&
+            ConfigEquality.same(a[key], b[key], depth + 1));
+    }
+    static #isPlain(value) {
+        const proto = Object.getPrototypeOf(value);
+        return proto === Object.prototype || proto === null;
+    }
+}

package/docs/architecture.md

@@ -23,7 +23,7 @@ Solid arrows are "renders"; the dotted line is "builds".
 flowchart TD
     Kind["<b>Plot.svelte</b><br/>BarPlot, LinePlot, ..."]
     Defaults["<b>defaults.ts</b><br/>phase options, markers, hover, timeline"]
-    Plot["<b>Plot</b><br/>builds the Pipeline, one core per slice"]
+    AbstractPlot["<b>AbstractPlot</b><br/>builds the Pipeline, one core per slice"]
     Figure["<b>Figure</b><br/>box or grid cell, hover store, legend toggles"]
     Chrome["<b>FigureChrome</b><br/>title, legend, caption"]
     Timeline["<b>TimelineLayout</b>"]
@@ -32,9 +32,9 @@ flowchart TD
     Core["<b>Core</b><br/>its panel phases, or every phase"]
     Base["<b>BasePlotLayout</b><br/>svelteplot Plot, axes, markers"]
 
-    Kind -->|core props + defaults| Plot
+    Kind -->|core props + defaults| AbstractPlot
     Kind -.- Defaults
-    Plot --> Figure
+    AbstractPlot --> Figure
     Figure -->|with chrome| Chrome
     Figure -->|with a timeline| Timeline
     Figure -->|without one| Facet
@@ -44,12 +44,12 @@ flowchart TD
     Core --> Base
 
     classDef public stroke-width:3px
-    class Kind,Plot public
+    class Kind,AbstractPlot public
     linkStyle default stroke:#8a8f98,stroke-width:2px
 ```
 
-1. A kind's `Plot.svelte` splits its props into chrome (`title`, `legend`, ...), `timeline`, `facet` and the core props, and renders the shared `Plot` with its `defaults` builder.
-2. `Plot` builds the kind's **`Pipeline`** once and renders a `Figure` whose body is the `TimelineLayout`, wrapping the `FacetLayout`, wrapping one `Core` per slice. Without a timeline or a facet, the one cell is the whole plot. Each facet's cell gets its scales (shared or free, per `facet.scales`) and whether its axes draw (per `facet.axes` and its edges in the grid).
+1. A kind's `Plot.svelte` splits its props into chrome (`title`, `legend`, ...), `timeline`, `facet` and the core props, and renders the shared `AbstractPlot` with its `defaults` builder.
+2. `AbstractPlot` builds the kind's **`Pipeline`** once and renders a `Figure` whose body is the `TimelineLayout`, wrapping the `FacetLayout`, wrapping one `Core` per slice. Without a timeline or a facet, the one cell is the whole plot. Each facet's cell gets its scales (shared or free, per `facet.scales`) and whether its axes draw (per `facet.axes` and its edges in the grid).
 3. `FacetLayout` turns the rows into facets - one per `by` value, flowed into `columns`, or one per `rows` x `cols` combination - and places them on a `Grid`, one `GridCell` each. Every plot reports the margins it settled on; once all have, each column and row pins its widest ones, so the plot areas line up.
 4. `Core` runs the pipeline over its props and hands the result to `BasePlotLayout`, which draws the svelteplot plot, the axes and the markers.
 
@@ -70,7 +70,7 @@ A `Pipeline` is an ordered list of **phase stages**, each a class in `phases/`.
 | `markers`          | per panel     | Composes the kind's marks, author markers and value labels      |
 | `tooltip`, `hover` | per panel     | Tooltip text, hover points and strategy                         |
 
-The first six are the **data phases** (`Pipeline.DATA_PHASES`). With a facet, `Plot` runs them once over every row (`PanelRun`, reused for a timeline step or a legend that omits a series), and each panel's `Core` runs only the rest. Without a facet, one `Core` runs every phase. Stages declared out of order still run in phase order, with a warning.
+The first six are the **data phases** (`Pipeline.DATA_PHASES`). With a facet, `AbstractPlot` runs them once over every row (`PanelRun`, reused for a timeline step or a legend that omits a series), and each panel's `Core` runs only the rest. Without a facet, one `Core` runs every phase. Stages declared out of order still run in phase order, with a warning.
 
 ## Facets and the composer share one grid
 
@@ -115,7 +115,7 @@ Dependencies between layers go through Svelte context, so a layer never imports
 | Hover store     | `Figure` (the outermost; nested figures share it)                   | every core's tooltip and hover sync                                   |
 | Legend toggles  | `Figure` (a figure with its own `legend` scopes them)               | legends and every core below                                          |
 | Timeline        | `Figure`                                                            | the plot's timeline layout, the player bar, `useFigure().timeline`    |
-| Shared timeline | `PlotComposer` with a `timeline`                                    | `Plot`, which then draws no control of its own                        |
+| Shared timeline | `PlotComposer` with a `timeline`                                    | `AbstractPlot`, which then draws no control of its own                |
 | Hover scope     | `GridCell` in a composer's grid, and `HoverScope` around each facet | hover sync, to tell panels and facets apart                           |
 | Grid            | `Grid`                                                              | `GridCell` (registers, gets its box and tag), `Figure` (takes a cell) |
 | Cell alignment  | `GridCell`                                                          | `BasePlotLayout` (pinned margins), `MarginReporter`                   |
@@ -126,7 +126,7 @@ The public readers of that state are `useFigure()` and `usePlot()` ([Reading plo
 
 1. Define its props and state types under `types/plots/<kind>/`.
 2. Write `plots/<kind>/defaults.ts`: a builder returning the options of each phase it customises (`data`, `mapping`, `scales`, `styles`, `markers`, `hover`, `timeline`, ...).
-3. Write `plots/<kind>/Plot.svelte`: split chrome, `timeline`, `facet` and core props and render the shared `Plot` with the builder.
+3. Write `plots/<kind>/Plot.svelte`: split chrome, `timeline`, `facet` and core props and render the shared `AbstractPlot` with the builder.
 4. Export it from `src/lib/index.ts`, add stories under `stories/plots/<kind>/`, tests under `tests/unit/plots/<kind>/`, and a page in `docs/plots/` with a row in the [Plots](plots.md) table.
 
 ## Conventions

package/docs/facets.md

@@ -168,3 +168,15 @@ Panels line up: each plot reports the margins it settled on, and once all have,
 ## Maps
 
 `GeoPlot` takes `facet` and reads the field from each feature's `properties` (and from each marker row); features without the field are drawn in every panel.
+
+The panels need not come from the features. `values` (or a grid's `rowValues` and `colValues`) name them, and they exist even when no feature carries the field: one layer of features serves every panel, with no copy of it per value. Each callback that reads a feature - `color`, `opacity`, `grouping`, `featureId`, `styles.onFeatureClick` - gets the slice it is drawn in as its last argument, `{ facet?: { value, row?, col? }, time? }`, and a tooltip's `format` finds the same `facet` and `time` in its context:
+
+```svelte
+<GeoPlot
+	data={provinces}
+	facet={{ by: 'sex', values: ['Women', 'Men'] }}
+	color={(f, { facet }) => valueFor(f.properties.name, facet?.value)}
+/>
+```
+
+The ramp spans every panel, each read in its own slice. See [Facets and timeline](geo.md#facets-and-timeline) on maps.

package/docs/geo.md

@@ -19,13 +19,13 @@
 
 ## Data
 
-| Prop           | Meaning                                                                                                                                                                                                      |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `data`         | A GeoJSON `FeatureCollection`, an array of `Feature`s, or a TopoJSON `Topology`                                                                                                                              |
-| `object`       | Required for a `Topology`: the key under `topology.objects` to draw. Needs the optional `topojson-client` package                                                                                            |
-| `featureId`    | Accessor for each feature's stable id. Default: `feature.id ?? properties.id ?? properties.name`. It is the key of `segments`, and identifies features in hover and click                                    |
-| `color`        | `(feature) => number \| undefined` - the value of a choropleth. Features without one use `styles.fill` or their `segments`                                                                                   |
-| `excludeParts` | `(part, feature) => boolean`, where `part` is `{ centroid, geometry }` - drops geometry parts from drawing and hover (a distant territory drawn in an inset instead). `segments` still apply to what remains |
+| Prop           | Meaning                                                                                                                                                                                                                |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`         | A GeoJSON `FeatureCollection`, an array of `Feature`s, or a TopoJSON `Topology`                                                                                                                                        |
+| `object`       | Required for a `Topology`: the key under `topology.objects` to draw. Needs the optional `topojson-client` package                                                                                                      |
+| `featureId`    | Accessor for each feature's stable id. Default: `feature.id ?? properties.id ?? properties.name`. It is the key of `segments`, and identifies features in hover and click                                              |
+| `color`        | `(feature, slice) => number \| undefined` - the value of a choropleth. Features without one use `styles.fill` or their `segments`. `slice` is the [facet panel and timeline step](#facets-and-timeline) it is drawn in |
+| `excludeParts` | `(part, feature) => boolean`, where `part` is `{ centroid, geometry }` - drops geometry parts from drawing and hover (a distant territory drawn in an inset instead). `segments` still apply to what remains           |
 
 ## Styles
 
@@ -146,6 +146,34 @@ An `inset` draws part of the map (or other data) in its own small panel, such as
 
 `location` is one of the 17 anchors (`'top-left'`, `'bottom-right'`, `'middle-left'`, ...); `features` filters by id from the plot's `data` (or give the inset its own `data`); `featurePartsFilter` narrows to geometry parts; `width` and `height` are fractions of the plot; an inset always fits its own content.
 
+## Facets and timeline
+
+`facet` and `timeline` slice the map by a field each feature carries in its `properties` (and each marker's own rows by the same field); what lacks the field is drawn in every slice. To draw one layer of features in every panel, with no field on them, name the panels instead: `facet.values` for `by`, `rowValues` and `colValues` for `rows` and `cols`, or `timeline.values` for the steps. A slice's values are the ones named, in that order, then any more found in the features.
+
+Every callback that reads a feature gets the slice it is drawn in as its last argument - `color`, `opacity`, `grouping`, `featureId` and `styles.onFeatureClick` - and a tooltip's `format` has it in its context:
+
+| Field         | Meaning                                                            |
+| ------------- | ------------------------------------------------------------------ |
+| `facet.value` | The panel: its `by` value, or a grid's `row · col`                 |
+| `facet.row`   | The panel's `rows` value, on a grid                                |
+| `facet.col`   | The panel's `cols` value, on a grid                                |
+| `time`        | The timeline step; the context is empty without `facet`/`timeline` |
+
+```svelte
+<GeoPlot
+	data={provinces}
+	facet={{ by: 'sex', values: ['Women', 'Men'] }}
+	color={(f, { facet }) => valueFor(f.properties.name, facet?.value)}
+	tooltip={{
+		sync: true,
+		format: (f, number, { facet }) => `${f.properties.name} · ${facet?.value}`
+	}}
+	coordinates={{ projection: { type: 'mercator', domain: 'data' } }}
+/>
+```
+
+The color ramp spans every panel and step, each read in its own slice, so colors compare across them; `facet.scales: 'free'` (or `timeline.scales`, with no facet) fits each slice's own instead, for panels that show different variables. To give each panel its own scheme too, return the panel from `grouping` and set `scales.color` in a `segments` entry per panel. With `projection.domain: 'data'`, each panel fits its own features. See also [Facets](facets.md#maps).
+
 ## Tooltip and hover
 
 `tooltip` works as on other plots with the hovered feature as the row (`format: (feature) => string`, or a `content` snippet). Add `{ type: 'geo-hover' }` for an in-map highlight. Hover matches the browser's own SVG hit-testing, so a feature is hovered where it is drawn.

package/docs/legend.md

@@ -86,6 +86,12 @@ A continuous section narrows with `interactive: { enabled: true, mode: 'filter'
 
 Series can be toggled from code too: `useFigure().legend` has `off`, `isOff(name)`, `toggle`, `turnOff`, `turnOn` (see [Reading plot state](state.md)).
 
+The range of a continuous section can be set from code as well: `useFigure().legend.setRange([min, max])` does what dragging the handles does - they move, and the plots filter or rescale to it, in the mode the section was set up with (a second argument, `'filter'` or `'rescale'`, overrides it). `setRange(null)`, or a span that covers the whole ramp, resets it; `legend.range` reads it back. A mini legend per panel can use it to apply its own panel's range to the figure's legend on a click.
+
+```svelte
+<button onclick={() => figure.legend?.setRange([panelMin, panelMax])}>Use this range</button>
+```
+
 ## Adjusting the automatic legend
 
 An object adjusts the automatic legend while keeping what the plots read:

package/docs/markers.md

@@ -174,16 +174,14 @@ A color or an opacity the function returns is drawn as it is, not mapped through
 
 ## A label in each shape
 
-A `rect`, `cell`, `bar` or `waffle` marker takes a `label`: a text written in the middle of each shape, with every option of a `text` marker but `type`, `data`, `x` and `y`, which the shape sets. It never takes the pointer from the shape under it, so `onclick` and the hover go on as they were.
+A marker writes a label on each of its shapes with `label`: in each bar, cell, rect or waffle by default, beside the points of a line, an area or a dot, or along an edge or a line, with every option of a `text` marker besides. A list of labels writes each of them.
 
 ```ts
 { type: 'rect', data: tiles, x1: 'x1', x2: 'x2', y1: 'y1', y2: 'y2',
   label: { text: 'name', styles: { fill: 'white' }, fit: { fallback: 'value' } } }
 ```
 
-`anchor` puts the label against an edge (`'top'`, `'bottom'`, `'left'`, `'right'`) or in a corner (`'top-left'`...) instead of the middle, and `outside` puts one anchored to an edge beyond it; `gap` is its distance from the edge. A label outside is not fitted, and `fitMargins: true` grows the plot's margins to hold it where it would run past them. A label with a handler of its own (`onpointerenter`...) listens for the pointer; the others leave it to the shape. Its styles take functions of the row, to dim the label of a series, say. A label inside its shape with no `fill` of its own is written in the color that reads best on the shape's own - white on a dark one, near black on a light one - picked per row from the configuration's `text.label.contrast` (`['#ffffff', '#111827']`), or white or black where neither reaches the WCAG AA ratio of 4.5:1. The shape is read as it is seen: a `fillOpacity` under 1 blends it with the plot's `background`. One outside keeps its plot's color.
-
-The label is fitted to its shape unless `fit` is `false`. One too big is written smaller, down to `minFontSize`; at that size it breaks into the lines the shape holds and the last one is cut short with an ellipsis; when fewer than `minLetters` letters would show, `fallback` - a value, a field or a function of the row - is written instead; and when not even that fits, nothing is. `padding` is the room kept free inside each edge. The defaults of `gap`, `padding`, `minFontSize` (8) and `minLetters` (3) are the configuration's `text.label`: `setConfiguration({ text: { label: { gap: 6 } } })`. A `text` marker of your own takes the same `fit` with a box of its own (`x1`, `x2`, `y1`, `y2`), which is rarely what you want.
+Its layouts and their options are those of a plot's value labels: see [Labels on markers](value-labels.md#labels-on-markers).
 
 ## Events
 

package/docs/plots/ranking/bar.md

@@ -53,7 +53,7 @@ Bars where one axis holds the categories and the other the values. Categories on
 ![Horizontal grouped bars](../../images/horizontal-bars.png)
 
 - Several series sharing a category sit side by side, each in its slice of the category band. The gap between them is `bar.seriesPadding` in the configuration.
-- `transforms={[{ type: 'stackY' }]}` stacks the series instead. Stacking is always `stackY`, also for horizontal bars, because the value channel is the one stacked.
+- `transforms={[{ type: 'stackY' }]}` stacks the series instead of putting them side by side. The stack runs along the value axis: `stackY` for vertical bars (values on `y`), `stackX` for horizontal ones (values on `x`, categories on `y`). The other one turns the category axis into a numeric one and the bars come out empty.
 - `scales.x.paddingInner` / `paddingOuter` set the spacing between category bands.
 - `styles.values.show` labels each bar; `styles.values.anchor` places the label (`'outside'`, `'middle'`, `'top'`, `'bottom'`, `'left'`, `'right'`, a corner such as `'top-left'`, or `'tip'` and `'base'`, the ends of the bar away from zero and on it).
 - The tooltip triggers anywhere over a bar's whole band, not just over the visible bar.

package/docs/plots/ranking/cleveland.md

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

package/docs/state.md

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

package/docs/styles-and-segments.md

@@ -46,20 +46,7 @@
 
 ![End-of-line value labels](images/value-labels.png)
 
-| 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).
+`styles.values` writes the plot's values on its own shapes: past the tip of each bar, beside the last point of each line, around each dot. Any of its options turns them on. `format` writes their text, `select` and `series` pick the rows labelled, and `layout` - `'point'`, `'path'` or `'box'` - changes where they go, with the options of each. See [Value labels](value-labels.md) for all of it.
 
 ### Frame
 

package/docs/timeline.md

@@ -43,7 +43,7 @@
 | `values`                           | The steps, when not every distinct value of `accessor` - read like `accessor`'s values                                                                                                                                                                                          |
 | `filterMode`                       | `'exact'` shows the rows of the current step; `'upTo'` shows every row up to it (a cumulative reveal). `LinePlot` defaults to `'upTo'`                                                                                                                                          |
 | `interpolate`                      | Tween values between steps so a scrub is smooth: `true`, or `{ key, value, create, progressEasing, segmentEasing }`. Line and bar plots default to interpolating their value channel                                                                                            |
-| `scales`                           | `'shared'` (default): axes span every step, so they hold still while scrubbing; `'free'` refits both to each step; `'free-x'` / `'free-y'` refit one and keep the other still                                                                                                   |
+| `scales`                           | `'shared'` (default): axes span every step (the widest any step reaches on its own rows), so they hold still while scrubbing; `'free'` refits both to each step; `'free-x'` / `'free-y'` refit one and keep the other still                                                     |
 | `onprogress`, `onvalue`            | Called with the new position (`0`-`1`) and with the step it lands on - a `Date` on a timeline of dates, else the number                                                                                                                                                         |
 | `orientation`, `show`, `thickness` | A rule's direction (`'vertical'` default, beside the plot; `'horizontal'`), visibility and size                                                                                                                                                                                 |
 

package/docs/transforms-and-statistics.md

@@ -72,7 +72,7 @@ Both derive rows from the data before drawing. A **transform** reshapes the rows
 | 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.
+A bar plot stacks along its value axis: `stackY` for vertical bars, `stackX` for horizontal ones. 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.
 
 ## Statistics
 

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

@@ -48,12 +48,12 @@ Two ways to give data, one per plot:
 | `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`, `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`).
+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; its `facet.values` name the panels of one layer of features, and `color`, `opacity`, `grouping`, `featureId` and the tooltip `format` get the slice `{ facet?, time? }` (`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'`. 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`.
+- **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 }}`.
 
@@ -69,7 +69,7 @@ Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `Pyramid
 8. Narrow plots with long category or series names: shorten the text in the data, format with `tickFormat` / `values.format`, or give `margins` more room.
 9. In Svelte 5 components, `state` is taken by the `$state` rune: name local variables otherwise.
 10. In a `facet`, every panel draws the plot's `markers` and `segments`. Give one a `facet` (a `by` value, a list of them, or `{ row, col }` in a `rows`/`cols` grid) to draw it only in the panels it names: `markers={[{ type: 'rule', axis: 'y', value: 10, facet: 'GBA' }]}`, `segments={{ Services: [{ facet: 'Cuyo', styles: { stroke: { strokeDasharray: '4 4' } } }] }}`. A plot with no facet leaves out whatever names one.
-10. Stacking is `transforms={[{ type: 'stackY' }]}`, also for horizontal bars (the value channel is the one stacked).
+10. Bars stack along their value axis: `transforms={[{ type: 'stackY' }]}` for vertical bars (values on `y`), `transforms={[{ type: 'stackX' }]}` for horizontal ones (values on `x`, categories on `y`); the wrong one draws no bars.
 
 ## Reading and driving plot state (custom UI)
 
@@ -78,7 +78,7 @@ Inside a plot's snippets (`header`, `footer`, tooltip `content`) or any child of
 - `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), 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`.
+- `legend.off` (names of hidden series), `legend.setRange([min, max] | null)` (narrows a continuous section), `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`.
 
@@ -102,7 +102,7 @@ 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)
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "1.18.0",
+  "version": "1.20.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",