@fundar/data-chart-telling 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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.12.0] - 2026-11-04
+
+### Added
+
+- `labels` on a discrete legend section (`legend.series.labels`, or on an explicit section): `prefix`, `suffix` and `replace` rewrite the label of every item - to add a unit (`' years'`) or shorten a word (`{ Quintile: 'Q' }`, or `[[/^Quartile /, 'Q: ']]`) - without removing the automatic items to write them again. The names are left as they are, so turning series off still goes by them.
+
+## [1.11.0] - 2026-11-04
+
+### Changed
+
+- The dots of a `delta` take the color of the series their end measures, as the plot draws it. Before, they took the line's `stroke` and, with none set, a neutral color. The line's `stroke` still wins when it is set, and the delta's own `dot` wins over both; an end on an axis keeps the neutral color. `usePlot()` now also gives `colorForSeries`.
+- **Breaking:** a delta's line is styled with `stroke`, not `line`, like the rest of the styles (`DeltaMarkerConfig.line`, also as a function of the position). Rename it where it is set.
+
 ## [1.10.0] - 2026-11-03
 
 ### Added

package/dist/layout/base/BasePlotLayout.svelte

@@ -238,7 +238,8 @@
 		scales: () => scales,
 		axes: () => state.axes,
 		data: () => data,
-		size: () => ({ width, height })
+		size: () => ({ width, height }),
+		colorForSeries: () => state.colorForSeries
 	});
 
 	/** The domains `ScalesLayout` widens an axis to, for an edge tick's `'extend'` (see `EdgeTicks`). */

package/dist/layout/figure/Figure.svelte

@@ -13,6 +13,7 @@
 	} from '../../configuration/config.svelte';
 	import { HoverState } from '../hover/HoverState.svelte';
 	import { LegendState } from '../legend/LegendState.svelte';
+	import { LegendLabels } from '../legend/LegendLabels';
 	import type { HoverStrategy } from '../../types/layout/hover';
 	import type { FigureBoxProps, PlotChromeConfig } from '../../types/plots/props';
 	import type { PlotBoxSnippet } from '../../types/layout/figure';
@@ -112,11 +113,14 @@
 				: 'auto'
 	);
 	const sections = $derived(
-		legendMode === 'explicit'
-			? legendState.colorize(legend as LegendSection[])
-			: legendMode === 'auto'
-				? legendState.sections(extension)
-				: []
+		LegendLabels.apply(
+			legendMode === 'explicit'
+				? legendState.colorize(legend as LegendSection[])
+				: legendMode === 'auto'
+					? legendState.sections(extension)
+					: [],
+			cfg
+		)
 	);
 
 	/**

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

@@ -0,0 +1,12 @@
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+import type { LegendLabels as LegendLabelsConfig, LegendSection } from '../../types/layout/legend';
+/** How a discrete section rewrites the labels its items show: swaps, then a prefix and a suffix. */
+export declare class LegendLabels {
+    /**
+     * `sections`, with the labels of every discrete section that sets `labels` rewritten. An item is
+     * rewritten from the text it would show - its `label`, else its name as the legend writes it.
+     */
+    static apply(sections: LegendSection[], cfg: Pick<PlotStylesConfig, 'legend'>): LegendSection[];
+    /** `text` after `labels`' swaps, in order (each replaces every match), with its prefix and suffix around it. */
+    static rewrite(text: string, labels: LegendLabelsConfig): string;
+}

package/dist/layout/legend/LegendLabels.js

@@ -0,0 +1,35 @@
+import { LegendText } from './LegendText';
+/** How a discrete section rewrites the labels its items show: swaps, then a prefix and a suffix. */
+export class LegendLabels {
+    /**
+     * `sections`, with the labels of every discrete section that sets `labels` rewritten. An item is
+     * rewritten from the text it would show - its `label`, else its name as the legend writes it.
+     */
+    static apply(sections, cfg) {
+        return sections.map((section) => {
+            if (section.type !== 'discrete' || !section.labels)
+                return section;
+            const { labels } = section;
+            return {
+                ...section,
+                items: section.items.map((item) => ({
+                    ...item,
+                    label: LegendLabels.rewrite(item.label || LegendText.of(item.name, cfg), labels)
+                }))
+            };
+        });
+    }
+    /** `text` after `labels`' swaps, in order (each replaces every match), with its prefix and suffix around it. */
+    static rewrite(text, labels) {
+        const swaps = Array.isArray(labels.replace)
+            ? labels.replace
+            : Object.entries(labels.replace ?? {});
+        let result = text;
+        for (const [pattern, replacement] of swaps)
+            result =
+                typeof pattern === 'string'
+                    ? result.replaceAll(pattern, () => replacement)
+                    : result.replace(pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`), replacement);
+        return `${labels.prefix ?? ''}${result}${labels.suffix ?? ''}`;
+    }
+}

package/dist/layout/plot/PlotContext.d.ts

@@ -16,6 +16,8 @@ export type PlotContextParts<T extends Record<string, unknown>> = {
         width: number;
         height: number;
     };
+    /** Each series' color, by name - axis kinds only. */
+    colorForSeries?: () => ((name: string) => string) | undefined;
 };
 /**
  * Everything one plot is, gathered where what draws inside it can reach it:
@@ -36,6 +38,7 @@ export declare class PlotContext<T extends Record<string, unknown> = Record<stri
     get scales(): object | undefined;
     get axes(): PlotAxes | undefined;
     get data(): T[];
+    get colorForSeries(): ((name: string) => string) | undefined;
     get width(): number;
     get height(): number;
 }

package/dist/layout/plot/PlotContext.js

@@ -37,6 +37,9 @@ export class PlotContext {
     get data() {
         return this.#parts.data();
     }
+    get colorForSeries() {
+        return this.#parts.colorForSeries?.();
+    }
     get width() {
         return this.#parts.size().width;
     }

package/dist/layout/plot/PublicPlotContext.d.ts

@@ -126,6 +126,8 @@ export declare class PublicPlotContext<T extends Record<string, unknown> = Recor
     get axes(): PlotAxes | undefined;
     /** The rows the plot draws and hovers over. */
     get data(): T[];
+    /** The color a series is drawn in, by its name - `undefined` for a plot with no series (a map). */
+    get colorForSeries(): ((name: string) => string) | undefined;
     get width(): number;
     get height(): number;
 }

package/dist/layout/plot/PublicPlotContext.js

@@ -231,6 +231,10 @@ export class PublicPlotContext {
     get data() {
         return this.#context.data;
     }
+    /** The color a series is drawn in, by its name - `undefined` for a plot with no series (a map). */
+    get colorForSeries() {
+        return this.#context.colorForSeries;
+    }
     get width() {
         return this.#context.width;
     }

package/dist/markers/delta/Delta.d.ts

@@ -18,7 +18,7 @@ export declare class Delta {
     #private;
     /**
      * The deltas a marker draws: one for its `at`, or one for each position of a list, each with the
-     * `line`, `text` and `dot` its style functions give for that position.
+     * `stroke`, `text` and `dot` its style functions give for that position.
      */
     static points(marker: DeltaMarkerConfig): DeltaPointConfig[];
     /** The delta `config` asks for over `allSeries`, or `undefined` while an end has no value there. */

package/dist/markers/delta/Delta.js

@@ -7,7 +7,7 @@ import { resolveAccessor } from '../../utils/accessors';
 export class Delta {
     /**
      * The deltas a marker draws: one for its `at`, or one for each position of a list, each with the
-     * `line`, `text` and `dot` its style functions give for that position.
+     * `stroke`, `text` and `dot` its style functions give for that position.
      */
     static points(marker) {
         const positions = Array.isArray(marker.at) ? marker.at : [marker.at];
@@ -15,7 +15,7 @@ export class Delta {
         return positions.map((at) => ({
             ...marker,
             at,
-            line: own(marker.line, at),
+            stroke: own(marker.stroke, at),
             text: own(marker.text, at),
             dot: own(marker.dot, at)
         }));

package/dist/markers/delta/DeltaMarker.svelte

@@ -6,7 +6,7 @@
 
 	/**
 	 * A delta annotation: one at `marker.at`, or, when it is a list, one at each position - all with the
-	 * same ends. `line`, `text` and `dot` can be functions of the position.
+	 * same ends. `stroke`, `text` and `dot` can be functions of the position.
 	 */
 	let { marker, data = [] }: { marker: DeltaMarkerConfig; data?: Series<TData>[] } = $props();
 

package/dist/markers/delta/DeltaPoint.svelte

@@ -3,6 +3,7 @@
 	import DotMarker from '../dot/DotMarker.svelte';
 	import TextMarker from '../text/TextMarker.svelte';
 	import { Delta } from './Delta';
+	import { usePlot } from '../../layout/plot/usePlot';
 	import { getConfiguration } from '../../configuration/config.svelte';
 	import type { Series } from '../../types/plots/data/common';
 	import type { DeltaPointConfig } from '../../types/markers/axis/delta';
@@ -10,6 +11,8 @@
 	/** One delta, at the one position `marker.at` names. See {@link DeltaMarker} for a list of them. */
 	let { marker, data = [] }: { marker: DeltaPointConfig; data?: Series<TData>[] } = $props();
 
+	const plot = usePlot();
+
 	const resolved = $derived(Delta.build(marker.axis, data, marker));
 	const label = $derived(getConfiguration().delta.text[marker.axis]);
 	const lineAnchor = $derived(marker.text?.lineAnchor ?? label.lineAnchor);
@@ -54,13 +57,22 @@
 		};
 	});
 
-	const dotStyles = $derived({
-		dotRadius: 4,
-		dotFill: marker.line?.stroke,
-		dotStroke: marker.line?.stroke,
-		dotStrokeWidth: 2,
-		...marker.dot
-	});
+	/**
+	 * The dot of one end: in the delta's own `stroke` when it sets one, else in the color of the series the end
+	 * measures - an axis end has none, and takes the dot's default. `dot` wins over both.
+	 */
+	function dotStyles(target: DeltaPointConfig['from'] | undefined) {
+		const color =
+			marker.stroke?.stroke ??
+			(target?.type === 'series' ? plot.colorForSeries?.(target.series) : undefined);
+		return {
+			dotRadius: 4,
+			dotFill: color,
+			dotStroke: color,
+			dotStrokeWidth: 2,
+			...marker.dot
+		};
+	}
 </script>
 
 {#if coords}
@@ -68,14 +80,18 @@
 		data={coords.lineData}
 		x={(p) => p.x}
 		y={(p) => p.y}
-		stroke={marker.line?.stroke ?? 'currentColor'}
-		strokeWidth={marker.line?.strokeWidth ?? 2}
-		strokeOpacity={marker.line?.strokeOpacity ?? 0.8}
-		strokeDasharray={marker.line?.strokeDasharray ?? '6 6'}
-		strokeLinecap={marker.line?.strokeLinecap ?? 'round'}
+		stroke={marker.stroke?.stroke ?? 'currentColor'}
+		strokeWidth={marker.stroke?.strokeWidth ?? 2}
+		strokeOpacity={marker.stroke?.strokeOpacity ?? 0.8}
+		strokeDasharray={marker.stroke?.strokeDasharray ?? '6 6'}
+		strokeLinecap={marker.stroke?.strokeLinecap ?? 'round'}
+	/>
+	<DotMarker
+		marker={{ type: 'dot', x: coords.fromPt.x, y: coords.fromPt.y, styles: dotStyles(marker.from) }}
+	/>
+	<DotMarker
+		marker={{ type: 'dot', x: coords.toPt.x, y: coords.toPt.y, styles: dotStyles(marker.to) }}
 	/>
-	<DotMarker marker={{ type: 'dot', x: coords.fromPt.x, y: coords.fromPt.y, styles: dotStyles }} />
-	<DotMarker marker={{ type: 'dot', x: coords.toPt.x, y: coords.toPt.y, styles: dotStyles }} />
 	<TextMarker
 		marker={{
 			type: 'text',
@@ -86,7 +102,7 @@
 				fontWeight: 'bold',
 				fontSize: 14,
 				textAnchor: label.textAnchor,
-				fill: marker.line?.stroke ?? 'currentColor',
+				fill: marker.stroke?.stroke ?? 'currentColor',
 				...marker.text,
 				dx: marker.text?.dx ?? label.dx,
 				dy: marker.text?.dy ?? label.dy,

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

@@ -89,11 +89,27 @@ export type DiscreteInteractiveConfig = {
     /** Shows the symbol icon inside a `'badge'` pill. Defaults to `true`; ignored by `'basic'`, which always shows it. */
     showIcon?: boolean;
 };
+/**
+ * How a discrete section rewrites the label of each of its items, to add a unit or shorten a word without
+ * writing the items again. `replace` goes first, then `prefix` and `suffix` go around the result.
+ */
+export type LegendLabels = {
+    prefix?: string;
+    suffix?: string;
+    /**
+     * What to swap in every label, in order: a text for the text that replaces it (every match), or a list of
+     * `[pattern, replacement]` pairs where the pattern may be a regular expression - `{ Quintile: 'Q' }`,
+     * `[[/^Quartile /, 'Q: ']]`.
+     */
+    replace?: Record<string, string> | [string | RegExp, string][];
+};
 export type DiscreteLegendSection = {
     type: 'discrete';
     enabled?: boolean;
     title?: string;
     items: LegendItem[];
+    /** Rewrites the label of each item - see {@link LegendLabels}. */
+    labels?: LegendLabels;
     columns?: number;
     /** Item flow direction. Defaults to horizontal for a lone section, vertical once there's more than one. */
     layout?: LegendItemsLayout;

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

@@ -15,7 +15,7 @@ export type DeltaConfig = {
     from: DeltaTarget;
     to?: DeltaTarget;
     formatDiff?: (diff: number) => string;
-    line?: StrokeStyle;
+    stroke?: StrokeStyle;
     text?: FontStyle;
     dot?: DotStyle;
 };
@@ -29,12 +29,12 @@ export type DeltaPointConfig = {
 export type PerPosition<T> = T | ((at: AxisValue) => T);
 /**
  * A delta annotation between two points on a line chart. `at` can be a list of positions: one delta is
- * drawn at each, with the same ends. `line`, `text` and `dot` can be functions of the position, to style
+ * drawn at each, with the same ends. `stroke`, `text` and `dot` can be functions of the position, to style
  * each delta on its own - a label to the left of the last one, say, so it stays inside the plot.
  */
-export type DeltaMarkerConfig = Omit<DeltaPointConfig, 'at' | 'line' | 'text' | 'dot'> & {
+export type DeltaMarkerConfig = Omit<DeltaPointConfig, 'at' | 'stroke' | 'text' | 'dot'> & {
     at: AxisValue | AxisValue[];
-    line?: PerPosition<StrokeStyle>;
+    stroke?: PerPosition<StrokeStyle>;
     text?: PerPosition<FontStyle>;
     dot?: PerPosition<DotStyle>;
 };

package/docs/legend.md

@@ -118,6 +118,18 @@ legend={{ color: { match: 'temperature', enabled: false } }}  // not that ramp
 legend={{ removeItems: ['2017/18'] }}
 ```
 
+### Rewriting the labels
+
+`labels` on a discrete section rewrites the label of every item without writing the items again - to add a unit or shorten a word. Each is optional; `replace` goes first, then `prefix` and `suffix` go around the result. An item is rewritten from the text it would show: its `label`, else its name as the legend writes it.
+
+```ts
+legend={{ series: { labels: { suffix: ' years' } } }}                       // 25-29 → 25-29 years
+legend={{ series: { labels: { replace: { Quintile: 'Q' }, suffix: '%' } } }} // Quintile 1 → Q 1%
+legend={{ series: { labels: { replace: [[/^Quartile /, 'Q: ']] } } }}        // Quartile 3 → Q: 3 (a pattern, in order)
+```
+
+`replace` is a record of text → replacement (every match; a text with spaces or dashes is a quoted key, `{ 'Quintile ': 'Q: ' }`), or a list of `[pattern, replacement]` pairs where the pattern may be a regular expression. The names are left as they are, so `off` and the toggles still go by them. An explicit section takes `labels` too.
+
 ### Turning series off from code
 
 `off` turns series off as if the reader had clicked them, without a click: a list of names (each dimmed, to `legend.disabledOpacity`), or a name → opacity or name → action map, where an action is the same `{ mode: 'dim' | 'hide' | 'omit' }` a toggle does. `highlight` is its inverse: it keeps the series it names on and dims all the others. An `off` entry for a series wins over `highlight`.

package/docs/markers.md

@@ -102,7 +102,7 @@ markers={[
 ]}
 ```
 
-A delta's `line`, `text` and `dot` can be functions of the position, to style each one on its own - a label to the left of the last one, say, so it stays inside the plot:
+A delta's `stroke`, `text` and `dot` can be functions of the position, to style each one on its own - a label to the left of the last one, say, so it stays inside the plot:
 
 ```ts
 {

package/package.json

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