@fundar/data-chart-telling 1.18.0 → 1.19.0

package/dist/types/plots/part-of-a-whole/treemap/props.d.ts

@@ -1,3 +1,5 @@
+import type { WithValues } from '../../../layout/styles';
+import type { BoxLabelConfig } from '../../../markers/labels/box';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -24,6 +26,6 @@ export type TreemapTooltipContext = TreemapRowContext;
  * `TreemapPlot`'s public props: flat rows, a tile each, on no axes. `value` is a tile's area, and `grouping` what
  * the tiles nest by (`'sector.branch'`, outermost first), whose outermost level colors them.
  */
-export type TreemapPlotProps<TData extends Record<string, unknown>> = BasePlotProps<NonAxisDataProps<TData, 'value'>, TData, AxisBasedStylesConfig, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>, undefined, TreemapTooltipContext>;
+export type TreemapPlotProps<TData extends Record<string, unknown>> = BasePlotProps<NonAxisDataProps<TData, 'value'>, TData, WithValues<AxisBasedStylesConfig, BoxLabelConfig>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>, undefined, TreemapTooltipContext>;
 /** What `TreemapPlot`'s core draws from. */
-export type TreemapPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<NonAxisDataProps<TData, 'value'>, TData, AxisBasedStylesConfig, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type TreemapPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<NonAxisDataProps<TData, 'value'>, TData, WithValues<AxisBasedStylesConfig, BoxLabelConfig>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/bar/props.d.ts

@@ -1,3 +1,4 @@
+import type { WithValues, BarValueLabel } from '../../../layout/styles';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -5,6 +6,6 @@ import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { GapsAwarePlotStylesConfig } from '../../../layout/styles';
 import type { BarSegmentStyle } from '../../segments/common';
 /** `BarPlot`'s public props. */
-export type BarPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type BarPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<GapsAwarePlotStylesConfig<BarSegmentStyle>, BarValueLabel>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `BarPlot`'s core draws from. */
-export type BarPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type BarPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<GapsAwarePlotStylesConfig<BarSegmentStyle>, BarValueLabel>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/cleveland/props.d.ts

@@ -1,3 +1,4 @@
+import type { WithValues, DotValueLabel } from '../../../layout/styles';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -5,6 +6,6 @@ import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /** `ClevelandPlot`'s public props. */
-export type ClevelandPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type ClevelandPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `ClevelandPlot`'s core draws from. */
-export type ClevelandPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type ClevelandPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/dumbbell/props.d.ts

@@ -1,3 +1,4 @@
+import type { WithValues, DotValueLabel } from '../../../layout/styles';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -5,6 +6,6 @@ import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /** `DumbbellPlot`'s public props. */
-export type DumbbellPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type DumbbellPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `DumbbellPlot`'s core draws from. */
-export type DumbbellPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type DumbbellPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/forest/props.d.ts

@@ -1,3 +1,4 @@
+import type { WithValues, DotValueLabel } from '../../../layout/styles';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -17,7 +18,9 @@ export type ForestIntervalProps<TData extends Record<string, unknown>> = {
     /** The half-width of each row's interval: it reaches `error` below and above its value. `lower` and `upper` win where they are set. */
     error?: Accessor<TData, number>;
 };
+/** The values of a forest's row its value labels can write: its estimate, and its interval's ends. */
+export type ForestValuePart = 'value' | 'lower' | 'upper';
 /** `ForestPlot`'s public props. */
-export type ForestPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;
+export type ForestPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel, ForestValuePart>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;
 /** What `ForestPlot`'s core draws from. */
-export type ForestPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;
+export type ForestPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel, ForestValuePart>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;

package/dist/types/plots/ranking/lollipop/props.d.ts

@@ -1,3 +1,4 @@
+import type { WithValues, DotValueLabel } from '../../../layout/styles';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -5,6 +6,6 @@ import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /** `LollipopPlot`'s public props. */
-export type LollipopPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type LollipopPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `LollipopPlot`'s core draws from. */
-export type LollipopPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type LollipopPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, WithValues<ConnectorBasedStylesConfig, DotValueLabel>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

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

@@ -53,7 +53,7 @@ Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `Pyramid
 ## 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 }}`.
 
@@ -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.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 {};