@fundar/data-chart-telling 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.15.0] - 2026-11-04
+
+### Fixed
+
+- A bar plot's value labels follow the bars that go below zero (or left of it): `'outside'` puts a label beyond its bar's tip on that side - to the left of a horizontal bar, under a vertical one - and the plot's margins make room for it. On a horizontal bar `'start'` is its left end and `'end'` its right one, both inside, and `'middle'` is its centre (it sat on the tip); a vertical bar's anchors are as they were.
+
+### Changed
+
+- On a line, the piece that joins two runs of a series is drawn as the first area segment that covers both of its ends - so a dashed projection that starts at the last observed year dashes the piece leaving that year, even where a faded range that ends there owns the point. It was always the catch-all's stroke, which left a solid piece at the start of the projection. A piece no area covers both ends of keeps the catch-all's stroke.
+
+## [1.14.0] - 2026-11-04
+
+### Added
+
+- The `hover` marker takes `decimals`, `prefix`, `suffix` and `signDisplay` for its label, and its `format` gets a second argument, `number`, that writes a value as they ask. With `numbers.decimals` set, its label is written with that count.
+- The `format` of `styles.values` gets `number` as its fourth argument, to write a value as the display fields ask while choosing which labels to show.
+- The `continuous` and `size` legend sections (so `legend.color` too) take `decimals`, `prefix`, `suffix` and `signDisplay` for their values - without `decimals` they keep the axes' format, and `numbers.decimals` does not reach them. Their `format` gets `number` as a second argument, and can return a number (`v * 100` for a share kept as a ratio), which is written as those fields ask.
+- A `delta`'s `formatDiff` can return a number: it is written as the marker's display fields ask.
+
 ## [1.13.0] - 2026-11-04
 
 ### Added
@@ -12,6 +31,7 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ### Changed
 
+- The `continuous` and `size` legend sections (so `legend.color` too) take `decimals`, `prefix`, `suffix` and `signDisplay` for their values - without `decimals` they keep the axes' format, and `numbers.decimals` does not reach them. Their `format` gets `number` as a second argument, and can return a number (`v * 100` for a share kept as a ratio), which is written as those fields ask.
 - A `delta` writes its distance in `axis.locale` (`12,3`), not with a dot (`12.3`), and with the configuration's `numbers.decimals` when set. One decimal remains the default.
 
 ## [1.12.0] - 2026-11-04
@@ -77,6 +97,7 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ### Fixed
 
+- The `continuous` and `size` legend sections (so `legend.color` too) take `decimals`, `prefix`, `suffix` and `signDisplay` for their values - without `decimals` they keep the axes' format, and `numbers.decimals` does not reach them. Their `format` gets `number` as a second argument, and can return a number (`v * 100` for a share kept as a ratio), which is written as those fields ask.
 - A `delta` marker at a `Date` position no longer turns a date `x` axis into a numeric one: it drew its dots, line and label at the position as a number, which svelteplot read next to the dates of the data as a linear scale, and the axis showed milliseconds.
 
 ## [1.6.0] - 2026-11-02

package/dist/layout/legend/AxisNumberFormat.d.ts

@@ -1,5 +1,6 @@
 import type { PlotStylesConfig } from '../../types/configuration/styling';
-import type { NumberFormat } from '../../utils/NumberFormat';
+import { NumberFormat } from '../../utils/NumberFormat';
+import type { NumberDisplay } from '../../types/layout/numbers';
 /** Numbers as the plots' axes write them, by `axis.locale` and `axis.compactDisplay`. */
 export declare class AxisNumberFormat {
     /**
@@ -8,6 +9,14 @@ export declare class AxisNumberFormat {
      * spans more than one order of magnitude, plain otherwise.
      */
     static of(domain: [number, number], cfg: Pick<PlotStylesConfig, 'axis'>, signDisplay?: ReturnType<typeof NumberFormat.sign>): (value: number) => string;
+    /**
+     * How a legend section writes its values: as its `decimals`, `prefix`, `suffix` and `signDisplay` ask, else as the
+     * axes write theirs over `domain` - the configuration's `numbers.decimals` does not reach it. Its own `format`
+     * writes by hand instead: it gets that writer as its second argument, and a number it returns is written by it.
+     */
+    static legend(section: NumberDisplay & {
+        format?: (v: number, number: (v: number) => string) => string | number;
+    }, domain: [number, number], cfg: Pick<PlotStylesConfig, 'axis'>): (value: number) => string;
     /** Whether ticks across `domain` read compact. */
     static compact([min, max]: [number, number]): boolean;
 }

package/dist/layout/legend/AxisNumberFormat.js

@@ -1,3 +1,4 @@
+import { NumberFormat } from '../../utils/NumberFormat';
 /** Numbers as the plots' axes write them, by `axis.locale` and `axis.compactDisplay`. */
 export class AxisNumberFormat {
     /**
@@ -14,6 +15,30 @@ export class AxisNumberFormat {
         });
         return (value) => format.format(value);
     }
+    /**
+     * How a legend section writes its values: as its `decimals`, `prefix`, `suffix` and `signDisplay` ask, else as the
+     * axes write theirs over `domain` - the configuration's `numbers.decimals` does not reach it. Its own `format`
+     * writes by hand instead: it gets that writer as its second argument, and a number it returns is written by it.
+     */
+    static legend(section, domain, cfg) {
+        const display = NumberFormat.displayOf(section);
+        const { prefix = '', suffix = '' } = display;
+        let number;
+        if (display.decimals !== undefined) {
+            number = NumberFormat.of(display, { ...cfg, numbers: {} });
+        }
+        else {
+            const write = AxisNumberFormat.of(domain, cfg, NumberFormat.sign(display));
+            number = (value) => `${prefix}${write(value)}${suffix}`;
+        }
+        const { format } = section;
+        if (!format)
+            return number;
+        return (value) => {
+            const written = format(value, number);
+            return typeof written === 'number' ? number(written) : written;
+        };
+    }
     /** Whether ticks across `domain` read compact. */
     static compact([min, max]) {
         if (!Number.isFinite(min) || !Number.isFinite(max))

package/dist/layout/legend/ContinuousSection.svelte

@@ -13,7 +13,7 @@
 	const checkerId = `dct-checker-${Math.random().toString(36).slice(2)}`;
 	const barWidth = $derived(section.width ?? 170);
 
-	const fmt = $derived(section.format ?? AxisNumberFormat.of([section.min, section.max], cfg));
+	const fmt = $derived(AxisNumberFormat.legend(section, [section.min, section.max], cfg));
 	const isInteractive = $derived(section.interactive?.enabled ?? false);
 
 	// How far the default handle bleeds past its 0/1 track position, so the

package/dist/layout/legend/SizeSection.svelte

@@ -15,7 +15,7 @@
 	let { section }: { section: SizeLegendSection } = $props();
 
 	const cfg = $derived(getConfiguration());
-	const fmt = $derived(section.format ?? AxisNumberFormat.of(section.domain, cfg));
+	const fmt = $derived(AxisNumberFormat.legend(section, section.domain, cfg));
 	/** A value's radius: `domain` onto `range` on a square-root scale. */
 	function radius(value: number): number {
 		const [d0, d1] = section.domain.map(Math.sqrt);

package/dist/layout/styles/ValueLabels.d.ts

@@ -59,8 +59,11 @@ export declare class ValueLabels {
         x?: number;
         y?: number;
     }, edges: MarginSide[]): EdgeBox;
-    /** Each series' value farthest from zero, read on `valueAxis` - the widest label it can show. */
-    extremes<S extends Series<any>>(series: S[], valueAxis?: 'x' | 'y'): {
+    /**
+     * Each series' value farthest from zero, read on `valueAxis` - the widest label it can show. With `'both'`,
+     * the farthest above zero and the farthest below it, whichever the series has.
+     */
+    extremes<S extends Series<any>>(series: S[], valueAxis?: 'x' | 'y', sides?: 'farthest' | 'both'): {
         series: S;
         value: number;
     }[];

package/dist/layout/styles/ValueLabels.js

@@ -34,8 +34,11 @@ export class ValueLabels {
         // The value as the display fields ask (else as it is), which a plot kind's own text builds on.
         const number = NumberFormat.maybe(NumberFormat.displayOf(values), cfg) ?? ((v) => `${v}`);
         const kindFormat = options.format;
-        this.format =
-            values?.format ?? (kindFormat ? (v, name) => kindFormat(v, name, number) : (v) => number(v));
+        this.format = values?.format
+            ? (v, name, row) => values.format(v, name, row, number)
+            : kindFormat
+                ? (v, name) => kindFormat(v, name, number)
+                : (v) => number(v);
         this.hoverIsolate = values?.hoverIsolate ?? false;
         this.font = values?.fontStyle;
         this.fontSize = typeof this.font?.fontSize === 'number' ? this.font.fontSize : 12;
@@ -85,21 +88,36 @@ export class ValueLabels {
         const box = this.textBox(text).beside({ x: at.x ?? 0, y: at.y ?? 0 }, side);
         return { box, edges };
     }
-    /** Each series' value farthest from zero, read on `valueAxis` - the widest label it can show. */
+    /**
+     * Each series' value farthest from zero, read on `valueAxis` - the widest label it can show. With `'both'`,
+     * the farthest above zero and the farthest below it, whichever the series has.
+     */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    extremes(series, valueAxis = 'y') {
+    extremes(series, valueAxis = 'y', sides = 'farthest') {
         return series.flatMap((s) => {
             const accessor = s[valueAxis];
             if (accessor === undefined)
                 return [];
             const y = resolveAccessor(accessor);
             let extreme;
+            let lowest;
+            let highest;
             for (const d of s.data) {
                 const v = Number(y(d));
-                if (!Number.isNaN(v) && (extreme === undefined || Math.abs(v) > Math.abs(extreme)))
+                if (Number.isNaN(v))
+                    continue;
+                if (extreme === undefined || Math.abs(v) > Math.abs(extreme))
                     extreme = v;
+                if (v < 0 && (lowest === undefined || v < lowest))
+                    lowest = v;
+                if (v >= 0 && (highest === undefined || v > highest))
+                    highest = v;
             }
-            return extreme === undefined ? [] : [{ series: s, value: extreme }];
+            if (extreme === undefined)
+                return [];
+            if (sides === 'farthest')
+                return [{ series: s, value: extreme }];
+            return [lowest, highest].flatMap((value) => value === undefined ? [] : [{ series: s, value }]);
         });
     }
     /**

package/dist/markers/hover/HoverMarker.svelte

@@ -5,6 +5,7 @@
 	import RuleMarker from '../rule/RuleMarker.svelte';
 	import BarMarker from '../bar/BarMarker.svelte';
 	import { getConfiguration } from '../../configuration/config.svelte';
+	import { NumberFormat } from '../../utils/NumberFormat';
 	import { BandNudge } from '../utils/BandNudge';
 	import type { BandSlice } from '../../types/layout/hover';
 	import type { HoverMarkerConfig } from '../../types/markers/common';
@@ -47,6 +48,10 @@
 			| 'area'
 			| 'dot'
 			| 'text'
+			| 'decimals'
+			| 'prefix'
+			| 'suffix'
+			| 'signDisplay'
 		>;
 		activePoint?: HoverDisplayPoint | null;
 		impliesCrosshairX?: boolean;
@@ -111,6 +116,16 @@
 	const areaY = $derived(marker.areaY === true ? (activePoint?.y ?? null) : null);
 	const showLabels = $derived(marker.showLabels ?? true);
 	const format = $derived(marker.format);
+	/** The hovered value as the marker's display fields ask; `undefined` while nothing does, so the plot's own label stays. */
+	const numberOf = $derived(NumberFormat.maybe(NumberFormat.displayOf(marker), cfg));
+	const number = $derived(numberOf ?? NumberFormat.of(undefined, cfg));
+	const labelOf = (d: HoverDisplayPoint): string => {
+		if (format) return format(d, number);
+		const value = Number(d.label);
+		return numberOf && d.label !== undefined && d.label !== '' && Number.isFinite(value)
+			? numberOf(value)
+			: (d.label ?? '');
+	};
 	const ruleStyle = $derived(marker.rule);
 	const areaStyle = $derived({ ...cfg.hover.area, ...marker.area });
 	const dotStyle = $derived(marker.dot);
@@ -242,7 +257,7 @@
 						data: [point],
 						x: (d: HoverDisplayPoint) => d.x,
 						y: (d: HoverDisplayPoint) => d.y,
-						text: (d: HoverDisplayPoint) => (format ? format(d) : (d.label ?? '')),
+						text: labelOf,
 						styles: resolveFontStyle(point)
 					}}
 				/>

package/dist/markers/hover/HoverMarker.svelte.d.ts

@@ -25,7 +25,7 @@ import type { HoverDisplayPoint } from '../../types/layout/hover';
 interface Props {
     data?: HoverDisplayPoint[];
     /** Narrowed to just the fields this component reads - `HoverMarkerConfig` also carries routing/scoping fields (`series`/`scope`/`strategy`/`sync`) it has no use for. */
-    marker: Pick<HoverMarkerConfig, 'ruleX' | 'ruleY' | 'areaX' | 'areaY' | 'showLabels' | 'format' | 'rule' | 'area' | 'dot' | 'text'>;
+    marker: Pick<HoverMarkerConfig, 'ruleX' | 'ruleY' | 'areaX' | 'areaY' | 'showLabels' | 'format' | 'rule' | 'area' | 'dot' | 'text' | 'decimals' | 'prefix' | 'suffix' | 'signDisplay'>;
     activePoint?: HoverDisplayPoint | null;
     impliesCrosshairX?: boolean;
     impliesCrosshairY?: boolean;

package/dist/plots/ranking/bar/defaults.js

@@ -68,15 +68,25 @@ export function buildBarDefaults() {
                     if (ProcessedPositions.span(state.processedData, axis).stacked)
                         return [];
                     if (!state.axes?.isHorizontal) {
-                        const at = { y: -labels.offset('y') };
-                        return [labels.edgeBox('0', { x: 'middle', y: 'before' }, at, ['top'])];
+                        const offset = labels.offset('y');
+                        const boxes = [
+                            labels.edgeBox('0', { x: 'middle', y: 'before' }, { y: -offset }, ['top'])
+                        ];
+                        // A bar below zero has its label under its tip.
+                        const hasNegative = labels
+                            .extremes(state.resolvedSeries ?? [], PlotAxes.valueOf(state), 'both')
+                            .some(({ value }) => value < 0);
+                        if (hasNegative)
+                            boxes.push(labels.edgeBox('0', { x: 'middle', y: 'after' }, { y: offset }, ['bottom']));
+                        return boxes;
                     }
-                    const at = { x: labels.offset('x') };
+                    // A bar below zero reaches out to the left, with its label turned that way.
+                    const offset = labels.offset('x');
                     return labels
-                        .extremes(state.resolvedSeries ?? [], PlotAxes.valueOf(state))
-                        .map(({ series, value }) => labels.edgeBox(labels.format(value, series.name), { x: 'after', y: 'middle' }, at, [
-                        'right'
-                    ]));
+                        .extremes(state.resolvedSeries ?? [], PlotAxes.valueOf(state), 'both')
+                        .map(({ series, value }) => value < 0
+                        ? labels.edgeBox(labels.format(value, series.name), { x: 'before', y: 'middle' }, { x: -offset }, ['left'])
+                        : labels.edgeBox(labels.format(value, series.name), { x: 'after', y: 'middle' }, { x: offset }, ['right']));
                 }
             }
         },

package/dist/plots/ranking/bar/markers.js

@@ -82,60 +82,59 @@ export function buildValueLabels(labels, state, ctx) {
     const geometry = buildBarGeometry(state, ctx.cfg.bar.seriesPadding);
     const { font, anchor, format } = labels;
     const valueOf = ValueLabels.valueOf(state);
-    const top = (d) => geometry.spanOf(d)?.[1] ?? 0;
-    const position = geometry.stacked
-        ? (d) => {
-            const [from, to] = geometry.spanOf(d) ?? [0, 0];
-            return (from + to) / 2;
-        }
-        : anchor === 'middle' && !isHorizontal
-            ? (d) => top(d) / 2
-            : anchor === 'end'
-                ? () => 0
-                : top;
-    // Outward from the bar's top along the value axis: up for a vertical bar, right for a horizontal one.
-    const outward = anchor === 'outside' ? 6 : anchor === 'start' ? -4 : anchor === 'end' ? 4 : 0;
-    const textAnchor = labels.textAnchor ??
-        (isHorizontal
-            ? anchor === 'outside' || anchor === 'end'
-                ? 'start'
-                : anchor === 'start'
-                    ? 'end'
-                    : 'middle'
-            : 'middle');
-    const lineAnchor = font?.lineAnchor ??
-        (isHorizontal
-            ? 'middle'
-            : anchor === 'outside' || anchor === 'end'
-                ? 'bottom'
-                : anchor === 'start'
-                    ? 'top'
-                    : 'middle');
+    const spanOf = (d) => geometry.spanOf(d) ?? [0, 0];
+    const lowOf = (d) => Math.min(...spanOf(d));
+    const highOf = (d) => Math.max(...spanOf(d));
+    const below = (d) => Number(valueOf(d)) < 0;
+    const place = (negative) => {
+        const mid = (d) => (lowOf(d) + highOf(d)) / 2;
+        if (geometry.stacked)
+            return { at: mid, side: 0 };
+        if (anchor === 'middle')
+            return { at: mid, side: 0 };
+        if (anchor === 'outside')
+            return isHorizontal
+                ? { at: negative ? lowOf : highOf, side: negative ? -1 : 1 }
+                : { at: negative ? lowOf : highOf, side: negative ? 1 : -1 };
+        if (anchor === 'start')
+            return isHorizontal ? { at: lowOf, side: 1 } : { at: highOf, side: 1 };
+        return isHorizontal ? { at: highOf, side: -1 } : { at: lowOf, side: -1 };
+    };
+    const gap = anchor === 'outside' ? 6 : 4;
     const labelled = processedData.data.filter((d) => d[GAP_VALUE] === undefined && geometry.spanOf(d) !== undefined);
     return (state.resolvedSeries ?? []).flatMap((s) => {
-        const data = labelled.filter((d) => d[SERIES_ID_KEY] === seriesIdOf(s));
-        if (data.length === 0)
-            return [];
-        return [
-            {
-                type: 'text',
-                data,
-                ...(isHorizontal
-                    ? { x: position, y: geometry.categoryOf }
-                    : { x: geometry.categoryOf, y: position }),
-                bandSlice: geometry.sliceOf(s.name),
-                text: (d) => format(Number(valueOf(d)), s.name, d),
-                styles: {
-                    ...font,
-                    fill: font?.fill ?? ctx.cfg.axis.color,
-                    fontSize: font?.fontSize ?? 12,
-                    dx: font?.dx ?? (isHorizontal ? outward : 0),
-                    dy: font?.dy ?? (isHorizontal ? 0 : -outward),
-                    textAnchor,
-                    lineAnchor
+        const own = labelled.filter((d) => d[SERIES_ID_KEY] === seriesIdOf(s));
+        // Only a label beyond the tip turns with the sign of its value.
+        const turns = !geometry.stacked && anchor === 'outside';
+        return (turns ? [false, true] : [false]).flatMap((negative) => {
+            const data = turns ? own.filter((d) => below(d) === negative) : own;
+            if (data.length === 0)
+                return [];
+            const { at, side } = place(negative);
+            // A horizontal label reads away from its point to `side`; a vertical one sits on the far side of it.
+            const textAnchor = labels.textAnchor ??
+                (isHorizontal ? (side === 1 ? 'start' : side === -1 ? 'end' : 'middle') : 'middle');
+            const lineAnchor = font?.lineAnchor ??
+                (isHorizontal ? 'middle' : side === 1 ? 'top' : side === -1 ? 'bottom' : 'middle');
+            return [
+                {
+                    type: 'text',
+                    data,
+                    ...(isHorizontal ? { x: at, y: geometry.categoryOf } : { x: geometry.categoryOf, y: at }),
+                    bandSlice: geometry.sliceOf(s.name),
+                    text: (d) => format(Number(valueOf(d)), s.name, d),
+                    styles: {
+                        ...font,
+                        fill: font?.fill ?? ctx.cfg.axis.color,
+                        fontSize: font?.fontSize ?? 12,
+                        dx: font?.dx ?? (isHorizontal ? side * gap : 0),
+                        dy: font?.dy ?? (isHorizontal ? 0 : side * gap),
+                        textAnchor,
+                        lineAnchor
+                    }
                 }
-            }
-        ];
+            ];
+        });
     });
 }
 /**

package/dist/plots/utils/segments.js

@@ -128,11 +128,34 @@ function resolveSeriesSegments(series, segmentsOfSeries, connect, base) {
     // the default palette color when the user has set a baseline via catch-all.
     // Dots are excluded to avoid duplicate marks at the shared boundary points.
     const catchAll = segs.find((s) => !s.areas || s.areas.length === 0);
-    const connectorStyle = (() => {
-        const rest = { ...(catchAll?.styles ?? baseStyle) };
+    const withoutDots = (style) => {
+        const rest = { ...style };
         delete rest.dot;
         return rest;
-    })();
+    };
+    const connectorStyle = withoutDots((catchAll?.styles ?? baseStyle));
+    // A segment's style as its own run is drawn with: an area segment over the catch-all's.
+    const styleOf = (idx) => {
+        const seg = segs[idx];
+        const own = seg.styles ?? {};
+        const isAreaSpecific = seg.areas != null && seg.areas.length > 0;
+        return isAreaSpecific && catchAll?.styles
+            ? merge(catchAll.styles, own)
+            : own;
+    };
+    // The line that joins two runs is drawn as the first area segment that covers both of its ends - a dashed
+    // projection that starts at the last observed year also dashes the piece leaving it, even where a faded
+    // range that ends there owns that year's point. Where none does, it is the catch-all's.
+    const covers = (idx, row) => {
+        const areas = segs[idx].areas;
+        return (areas != null &&
+            areas.length > 0 &&
+            areas.some((area) => areaMatchesXY(getX(row), getY(row), area)));
+    };
+    const joining = (from, to) => {
+        const covering = evalOrder.find(({ i }) => covers(i, from) && covers(i, to));
+        return covering ? withoutDots(styleOf(covering.i)) : connectorStyle;
+    };
     const defaultVisual = [];
     const connectors = [];
     const userVisual = [];
@@ -161,7 +184,7 @@ function resolveSeriesSegments(series, segmentsOfSeries, connect, base) {
                 if (r < runs.length - 1) {
                     connectors.push({
                         data: [last, runs[r + 1].data[0]],
-                        styles: connectorStyle,
+                        styles: joining(last, runs[r + 1].data[0]),
                         scales: undefined
                     });
                 }
@@ -188,7 +211,7 @@ function resolveSeriesSegments(series, segmentsOfSeries, connect, base) {
             if (connect && nextRun && nextRun.segIdx !== -1) {
                 connectors.push({
                     data: [run.data[run.data.length - 1], nextRun.data[0]],
-                    styles: connectorStyle,
+                    styles: joining(run.data[run.data.length - 1], nextRun.data[0]),
                     scales: undefined
                 });
             }

package/dist/types/layout/legend.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { SymbolType, LineStyle } from '../plots/constants';
 import type { StrokeStyle, DotStyle } from '../plots/styling';
+import type { NumberDisplay } from './numbers';
 import type { ColorScaleConfig, OpacityScaleConfig, SymbolScaleConfig } from './scales';
 export type LegendSectionType = 'discrete' | 'continuous' | 'size' | 'symbol';
 /**
@@ -127,7 +128,11 @@ export type ContinuousInteractiveConfig = {
     /** Custom renderer for the draggable lo/hi handles. */
     handle?: LegendHandleSnippet;
 };
-export type ContinuousLegendSection = {
+/**
+ * A continuous color or opacity scale. Its values read as {@link NumberDisplay} asks - with `decimals`, exactly
+ * that many; without, as the axes write theirs - unless `format` writes them.
+ */
+export type ContinuousLegendSection = NumberDisplay & {
     type: 'continuous';
     enabled?: boolean;
     title?: string;
@@ -146,7 +151,8 @@ export type ContinuousLegendSection = {
     opacity?: [number, number];
     ticks?: number[];
     width?: number;
-    format?: (v: number) => string;
+    /** A value's text, in place of the value. A number it returns (`v * 100` for a share kept as a ratio) is written as the display fields above ask; a string is shown as it is. `number` writes a value that way by hand. */
+    format?: (v: number, number: (v: number) => string) => string | number;
     interactive?: ContinuousInteractiveConfig;
 };
 /**
@@ -154,7 +160,7 @@ export type ContinuousLegendSection = {
  * the radius each value draws at, its value under each. `domain` maps to
  * `range` (px) on a square-root scale, so a dot's area follows its value.
  */
-export type SizeLegendSection = {
+export type SizeLegendSection = NumberDisplay & {
     type: 'size';
     enabled?: boolean;
     title?: string;
@@ -171,8 +177,8 @@ export type SizeLegendSection = {
     filled?: boolean;
     /** The dots' shape. Defaults to `'circle'`. */
     symbol?: SymbolType;
-    /** How each value reads. Defaults to the axes' own format (`axis.locale`, `axis.compactDisplay`). */
-    format?: (v: number) => string;
+    /** How each value reads, in place of the display fields' format (which defaults to the axes' own: `axis.locale`, `axis.compactDisplay`). A number it returns is written as those fields ask; `number` does the same by hand. */
+    format?: (v: number, number: (v: number) => string) => string | number;
 };
 /**
  * A categorical shape scale - the `symbol` channel of a plot's dots: each

package/dist/types/layout/styles/values.d.ts

@@ -39,7 +39,7 @@ export type ValuesStyle = NumberDisplay & {
      */
     color?: 'series' | (string & {});
     /** A label's text, in place of the value as `decimals`, `prefix`, `suffix` and `signDisplay` write it, from its row's own value (a histogram bin's count) and its series - and, on the plots that label one row each, that row, for the other fields of the data. */
-    format?: (value: number, seriesName: string, row?: Record<string, unknown>) => string;
+    format?: (value: number, seriesName: string, row?: Record<string, unknown>, number?: (value: number) => string) => string;
     /** Hovering a label dims every other series, like toggling them off in the legend. */
     hoverIsolate?: boolean;
     fontStyle?: FontStyle;

package/dist/types/markers/axis/delta.d.ts

@@ -18,8 +18,8 @@ export type DeltaConfig = NumberDisplay & {
     at: AxisValue;
     from: DeltaTarget;
     to?: DeltaTarget;
-    /** The distance's text, in place of the number as the display fields above write it. */
-    formatDiff?: (diff: number) => string;
+    /** The distance's text, in place of the distance. A number it returns is written as the display fields above ask (a percentage of a baseline, say); a string is shown as it is. */
+    formatDiff?: (diff: number) => string | number;
     stroke?: StrokeStyle;
     text?: FontStyle;
     dot?: DotStyle;

package/dist/types/markers/axis/hover.d.ts

@@ -1,7 +1,12 @@
 import type { AreaStyle, DotStyle, FontStyle, StrokeStyle } from '../../plots/styling';
 import type { HoverDisplayPoint, HoverStrategy } from '../../layout/hover';
-/** In-SVG hover highlight: crosshair, dot and label. */
-export type HoverMarkerConfig = {
+import type { NumberDisplay } from '../../layout/numbers';
+/**
+ * In-SVG hover highlight: crosshair, dot and label. The label is the hovered value as `decimals`, `prefix`,
+ * `suffix` and `signDisplay` write it - as the plot writes it while none of them (nor `numbers.decimals`) is set -
+ * unless `format` writes it.
+ */
+export type HoverMarkerConfig = NumberDisplay & {
     type: 'hover';
     series?: string;
     scope?: 'series' | 'segment';
@@ -13,7 +18,8 @@ export type HoverMarkerConfig = {
     areaX?: boolean;
     areaY?: boolean;
     showLabels?: boolean;
-    format?: (point: HoverDisplayPoint) => string;
+    /** The label's text for a point, in place of the value. `number` writes a value as the display fields above ask. */
+    format?: (point: HoverDisplayPoint, number: (value: number) => string) => string;
     rule?: StrokeStyle;
     area?: AreaStyle;
     dot?: DotStyle;

package/dist/types/plots/constants.d.ts

@@ -8,6 +8,11 @@
  *   of a pyramid bar from zero, right of a line's last point).
  * - `'middle'` - centred on the mark.
  * - `'end'` - at the baseline/zero end of the mark.
+ *
+ * On a bar plot the anchors read as the bars are drawn, whatever the sign of the value: `'outside'` is
+ * beyond the tip (left of a horizontal bar below zero, under a vertical one), `'start'` the left end of a
+ * horizontal bar or the top end of a vertical one, `'end'` the right or bottom end, both inside, and
+ * `'middle'` the centre.
  */
 export type ValueAnchor = 'outside' | 'start' | 'middle' | 'end';
 /**

package/docs/legend.md

@@ -187,8 +187,8 @@ A list replaces the automatic legend with exactly those sections:
 Section types:
 
 - `discrete` - `items` (`name`, `label`, `color`, `symbol`, `filled`, `opacity`, `lineStyle`), `columns`, `layout` (`{ type: 'vertical' }`, `{ type: 'horizontal', maxRows }` paginated, `{ type: 'flex' }`), `interactive`, `navButton`.
-- `continuous` - `min`, `max`, `colorMin`, `colorMax`, `scheme`, `pivot`, `opacity`, `ticks`, `width`, `format`, `interactive`.
-- `size` - `domain`, `range`, `values`, `color`, `filled`, `symbol`, `format`.
+- `continuous` - `min`, `max`, `colorMin`, `colorMax`, `scheme`, `pivot`, `opacity`, `ticks`, `width`, `decimals`, `prefix`, `suffix`, `signDisplay`, `format`, `interactive`.
+- `size` - `domain`, `range`, `values`, `color`, `filled`, `symbol`, `decimals`, `prefix`, `suffix`, `signDisplay`, `format`.
 - `symbol` - `items` of `{ name, symbol }`, `color`, `filled`, `layout`.
 
 ## Placement and look

package/docs/markers.md

@@ -48,7 +48,7 @@ A `text` marker's `text` is a string, a number, the name of a field of its rows,
 { type: 'text', data: rows, x: 'year', y: 'share', text: 'share', decimals: 1, suffix: ' %' }
 ```
 
-A `delta` writes its distance the same way, with one decimal unless `decimals` or `numbers.decimals` says otherwise. `formatDiff` writes it by hand instead.
+A `delta` writes its distance the same way, with one decimal unless `decimals` or `numbers.decimals` says otherwise. `formatDiff` writes it by hand instead: a string it returns is shown as it is, and a number (a percentage of a baseline, say) is written as the display fields ask.
 
 ## Fields every marker shares
 
@@ -125,7 +125,7 @@ Every other marker draws from `data` rows, one mark per row, so it already takes
 
 ## Hover highlight
 
-`{ type: 'hover' }` draws a crosshair, a dot and a label at the hovered point. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `ruleX`, `ruleY`, `areaX`, `areaY` (a band highlight on band scales), `showLabels`, `format`, and the styles `rule`, `area`, `dot`, `text`. See [Tooltip and hover](tooltip-and-hover.md).
+`{ type: 'hover' }` draws a crosshair, a dot and a label at the hovered point. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `ruleX`, `ruleY`, `areaX`, `areaY` (a band highlight on band scales), `showLabels`, `format`, the number fields `decimals`, `prefix`, `suffix` and `signDisplay` (they write the label's value; `format` gets a `number` function that does the same), and the styles `rule`, `area`, `dot`, `text`. See [Tooltip and hover](tooltip-and-hover.md).
 
 ## Custom components
 

package/docs/styles-and-segments.md

@@ -46,18 +46,18 @@
 
 ![End-of-line value labels](images/value-labels.png)
 
-| Field                                         | Meaning                                                                                                                                                                                                                   |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `show`                                        | Draws the labels. Off by default, except on a heatmap                                                                                                                                                                     |
-| `anchor`                                      | `'outside'`, `'start'`, `'middle'`, `'end'` - where a label sits on its mark                                                                                                                                              |
-| `select`                                      | Which row of each group is labelled: `'first'`, `'last'`, `'min'`, `'max'`, or a list of them. A group is a series on a line or area plot (default `'last'`), a category on the plots that join dots (default: every dot) |
-| `series`                                      | Labels only these series, by name                                                                                                                                                                                         |
-| `color`                                       | `'series'` writes each label in its series' color; any other CSS color writes them all in it (`fontStyle.fill` wins)                                                                                                      |
-| `decimals`, `prefix`, `suffix`, `signDisplay` | How the value reads, over `numbers.decimals` ([Number format](theming.md#number-format)); `format` replaces them                                                                                                          |
-| `format`                                      | `(value, seriesName, row) => string`; `row` is the labelled row, for its other fields                                                                                                                                     |
-| `hoverIsolate`                                | Hovering a label dims every other series                                                                                                                                                                                  |
-| `fontStyle`                                   | Text style: `fontSize`, `fill`, `dx`, `dy`, `textAnchor`, `lineAnchor`, `rotate`, `class`, ... Overrides the anchor's placement field by field                                                                            |
-| `strokeStyle`                                 | Style of the connector lines drawn from labels that had to move apart                                                                                                                                                     |
+| Field                                         | Meaning                                                                                                                                                                                                                                                      |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `show`                                        | Draws the labels. Off by default, except on a heatmap                                                                                                                                                                                                        |
+| `anchor`                                      | `'outside'`, `'start'`, `'middle'`, `'end'` - where a label sits on its mark. On a bar, `'outside'` is beyond its tip (on either side of zero), `'start'` / `'end'` its left / right end (top / bottom on a vertical bar), inside, and `'middle'` its centre |
+| `select`                                      | Which row of each group is labelled: `'first'`, `'last'`, `'min'`, `'max'`, or a list of them. A group is a series on a line or area plot (default `'last'`), a category on the plots that join dots (default: every dot)                                    |
+| `series`                                      | Labels only these series, by name                                                                                                                                                                                                                            |
+| `color`                                       | `'series'` writes each label in its series' color; any other CSS color writes them all in it (`fontStyle.fill` wins)                                                                                                                                         |
+| `decimals`, `prefix`, `suffix`, `signDisplay` | How the value reads, over `numbers.decimals` ([Number format](theming.md#number-format)); `format` replaces them                                                                                                                                             |
+| `format`                                      | `(value, seriesName, row) => string`; `row` is the labelled row, for its other fields                                                                                                                                                                        |
+| `hoverIsolate`                                | Hovering a label dims every other series                                                                                                                                                                                                                     |
+| `fontStyle`                                   | Text style: `fontSize`, `fill`, `dx`, `dy`, `textAnchor`, `lineAnchor`, `rotate`, `class`, ... Overrides the anchor's placement field by field                                                                                                               |
+| `strokeStyle`                                 | Style of the connector lines drawn from labels that had to move apart                                                                                                                                                                                        |
 
 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).
 
@@ -148,6 +148,7 @@ type Range = { from?: AxisValue; to?: AxisValue }; // inclusive on both ends
 - A segment applies to a data point (or heatmap cell) inside **any** of its `areas`.
 - An `Area` limits by `x`, `y` or both; leaving one out leaves that axis open.
 - A segment without `areas` is a **catch-all**: it matches every point, is evaluated last, and is overridden by any area-specific segment. A catch-all placed first is a baseline that highlighted ranges override.
+- On a line, the piece that joins two runs of a series is drawn as the first area segment that covers both of its ends (its stroke, not its dots): a dashed range that starts at a year dashes the piece leaving it, even where a faded range ending there owns that year's point. One no area covers both ends of is drawn as the catch-all.
 - `'default'` applies to every series; a named key applies to that series only, and wins over `'default'` where both match.
 - `legend` names the segment on the automatic [legend](legend.md).
 - `facet` limits the segment to the [facet panels](facets.md#markers-and-segments-in-some-panels) it names - a `by` value or a list of them. Without it the segment applies to every panel.

package/docs/theming.md

@@ -80,7 +80,7 @@ The same four fields set it where a plot needs something else, in `axis.locale`:
 | `suffix`      | Text after the number, spaces included: `' %'`                                                                                |
 | `signDisplay` | `'auto'` (default) writes only a minus, `'always'` also a plus on a positive number (never on zero), `'never'` no sign at all |
 
-They are fields of `scales.x` and `scales.y` (the ticks), of `tooltip`, of `styles.values` (value labels), and of a `text` and a `delta` marker. A tooltip writes the value on the plot's value axis - the `x` of horizontal bars - and a heatmap's color value; a `text` marker writes a number that its `text` gives (see [Markers](markers.md#numbers-in-text-and-delta-markers)).
+They are fields of `scales.x` and `scales.y` (the ticks), of `tooltip`, of `styles.values` (value labels), of a `hover` marker (its label), and of a `text` and a `delta` marker. A tooltip writes the value on the plot's value axis - the `x` of horizontal bars - and a heatmap's color value; a `text` marker writes a number that its `text` gives (see [Markers](markers.md#numbers-in-text-and-delta-markers)).
 
 A `scales` axis keeps its automatic ticks (abbreviated when they span orders of magnitude) unless it sets `decimals`: `numbers.decimals` does not reach the ticks, since a fixed count would write `5,0` for `5` on every axis. `prefix` and `suffix` alone keep the automatic format. An axis with its own `tickFormat` or `percent` ignores them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
   "license": "MIT",
   "author": "Ezequiel Puerta",