@fundar/data-chart-telling 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.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 +21,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 +87,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.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;

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/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/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/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.14.0",
   "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
   "license": "MIT",
   "author": "Ezequiel Puerta",