@fundar/data-chart-telling 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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

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/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/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/package.json

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