@fundar/data-chart-telling 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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
+
+- `decimals`, `prefix`, `suffix` and `signDisplay` (`'auto'`, `'always'` or `'never'`) write the numbers a plot shows, in `axis.locale`: on `scales.x` and `scales.y` (the ticks), `tooltip`, `styles.values` (value labels), and the `text` and `delta` markers. `'always'` writes a plus on positives, never on zero. `numbers.decimals` in the configuration sets the count everywhere but the ticks, which keep their automatic format unless `scales` sets `decimals`. A tooltip writes the value on the plot's value axis - the `x` of horizontal bars, not only the `y` - and a heatmap's color value.
+- A `text` marker's `text` can be a number, the name of a numeric field of the rows, or a function giving a number, besides a string: a number is written as the marker's display fields ask.
+- A tooltip's `format` gets a second argument, `number`, that writes a number as the tooltip's display fields ask. The `format` of a plot kind's value labels (`ValueLabelsOptions.format`) gets it too.
+
+### 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
 
 ### Added
@@ -65,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/configuration/config.svelte.js

@@ -65,6 +65,7 @@ export const DEFAULT_CONFIG = {
     margins: { top: 'auto', right: 'auto', bottom: 'auto', left: 'auto' },
     frameClip: { tolerance: 2 },
     // ── Features ────────────────────────────────────────────────────────────────
+    numbers: {},
     axis: {
         color: 'currentColor',
         fontSize: 14,

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export { resolveSymbolScale } from './utils/SymbolScale';
 export { Statistics } from './phases/statistics/Statistics';
 export type { AxisValue, ChannelValue, ChannelName, AxisChannelName, IndependentChannelName, SizeChannelName, ChannelAccessors } from './types/layout/mapping';
 export type { AxisScale, AxisBasedScalesConfig, ChannelScalesConfig } from './types/layout/scales';
+export type { NumberDisplay } from './types/layout/numbers';
 export type { Accessor, Series, SeriesProps, DataProps } from './types/plots/data/common';
 export type { BasePlotProps, PlotCoreProps, PlotChromeProps, FigureBoxProps, SegmentsConfig, ScalesConfig, MarginConfig, TooltipConfig, HoverConfig } from './types/plots/props';
 export type { AxisBasedStylesConfig, ConnectorBasedStylesConfig, BulletStylesConfig, GapsAwarePlotStylesConfig, CurveAwarePlotStylesConfig, GeoStylesConfig, GeoTileLayerConfig } from './types/layout/styles';

package/dist/layout/base/BasePlotLayout.svelte

@@ -15,6 +15,7 @@
 	import { SveltePlotScale } from '../scales/SveltePlotScale';
 	import { TickLabels } from '../scales/TickLabels';
 	import { TickLines } from '../scales/TickLines';
+	import { TickNumbers } from '../scales/TickNumbers';
 	import ScalesLayout from '../scales/ScalesLayout.svelte';
 	import GeometryLayout from '../geometry/GeometryLayout.svelte';
 	import CoordinatesLayout from '../coordinates/CoordinatesLayout.svelte';
@@ -197,8 +198,10 @@
 	const layoutScales = $derived.by(() => {
 		if (scales === undefined) return scales;
 		const rotate = tickLayout?.x?.rotate;
-		const x = withLines(rotate ? { ...scales.x, tickRotate: rotate } : scales.x);
-		return { ...scales, ...(x ? { x } : {}), ...(scales.y ? { y: withLines(scales.y) } : {}) };
+		const written = (scale: AxisScale<TData> | undefined) =>
+			withLines(TickNumbers.apply(scale as AxisScale<never> | undefined, cfg) as typeof scale);
+		const x = written(rotate ? { ...scales.x, tickRotate: rotate } : scales.x);
+		return { ...scales, ...(x ? { x } : {}), ...(scales.y ? { y: written(scales.y) } : {}) };
 	});
 	/** The category labels a crowded axis still writes: one in every few. */
 	const tickValues = $derived.by(() => {

package/dist/layout/hover/HoverSettings.d.ts

@@ -30,5 +30,6 @@ export declare class HoverSettings<TRow extends Record<string, unknown>> {
         label: (row: TRow) => string;
         defaultStrategy: HoverStrategy;
         pointMatching?: PointMatchingStrategy;
+        number?: (value: number) => string;
     }): HoverConfig<TRow>;
 }

package/dist/layout/hover/HoverSettings.js

@@ -34,6 +34,7 @@ export class HoverSettings {
     /** A plot's `hover` config; its tooltip reads as `format` unless it sets its own. */
     static buildConfig(args) {
         const { tooltip, format, sort, markers, points, label, defaultStrategy, pointMatching } = args;
+        const number = args.number ?? String;
         const settings = new HoverSettings(tooltip, markers, defaultStrategy);
         return {
             active: settings.active,
@@ -43,7 +44,7 @@ export class HoverSettings {
             sync: settings.sync,
             tooltip: tooltip && {
                 ...tooltip,
-                format: tooltip.format ?? format,
+                format: tooltip.format ? (row) => tooltip.format(row, number) : format,
                 ...(sort ? { sort } : {})
             },
             ...(pointMatching ? { pointMatching } : {})

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

@@ -1,4 +1,6 @@
 import type { PlotStylesConfig } from '../../types/configuration/styling';
+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 {
     /**
@@ -6,7 +8,15 @@ export declare class AxisNumberFormat {
      * ticks are: compact (`1,2 mil`, `1.2K`) when the domain crosses zero or
      * spans more than one order of magnitude, plain otherwise.
      */
-    static of(domain: [number, number], cfg: Pick<PlotStylesConfig, 'axis'>): (value: number) => string;
+    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 {
     /**
@@ -5,14 +6,39 @@ export class AxisNumberFormat {
      * ticks are: compact (`1,2 mil`, `1.2K`) when the domain crosses zero or
      * spans more than one order of magnitude, plain otherwise.
      */
-    static of(domain, cfg) {
+    static of(domain, cfg, signDisplay) {
         const format = new Intl.NumberFormat(cfg.axis.locale, {
             ...(AxisNumberFormat.compact(domain) ? { notation: 'compact' } : {}),
             useGrouping: 'min2',
-            compactDisplay: cfg.axis.compactDisplay
+            compactDisplay: cfg.axis.compactDisplay,
+            ...(signDisplay ? { signDisplay } : {})
         });
         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/scales/TickNumbers.d.ts

@@ -0,0 +1,22 @@
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+import type { NumberDisplay } from '../../types/layout/numbers';
+import type { AxisScale } from '../../types/layout/scales';
+type Config = Pick<PlotStylesConfig, 'axis' | 'numbers'>;
+type TickFormat = (d: unknown, index: number, ticks: unknown[]) => string;
+/** An axis' ticks written as the scale's `decimals`, `prefix`, `suffix` and `signDisplay` ask. */
+export declare class TickNumbers {
+    /** Whether `scale` sets any of the display fields. */
+    static isSet(scale: NumberDisplay | undefined): boolean;
+    /**
+     * `scale` with its display fields turned into a `tickFormat`, unless it sets one of its own (which wins) or reads
+     * as a `percent`. The fields are taken out either way.
+     */
+    static apply<TScale extends AxisScale<never> | undefined>(scale: TScale, cfg: Config): TScale;
+    /**
+     * A `tickFormat` for `display`. With `decimals`, every tick has exactly that many; without, ticks read as the
+     * axis writes them on its own (compact when they span orders of magnitude) - the configuration's
+     * `numbers.decimals` does not reach the ticks.
+     */
+    static format(display: NumberDisplay, cfg: Config): TickFormat;
+}
+export {};

package/dist/layout/scales/TickNumbers.js

@@ -0,0 +1,54 @@
+import { AxisNumberFormat } from '../legend/AxisNumberFormat';
+import { NumberFormat } from '../../utils/NumberFormat';
+/** An axis' ticks written as the scale's `decimals`, `prefix`, `suffix` and `signDisplay` ask. */
+export class TickNumbers {
+    /** Whether `scale` sets any of the display fields. */
+    static isSet(scale) {
+        return (scale?.decimals !== undefined ||
+            !!scale?.prefix ||
+            !!scale?.suffix ||
+            scale?.signDisplay !== undefined);
+    }
+    /**
+     * `scale` with its display fields turned into a `tickFormat`, unless it sets one of its own (which wins) or reads
+     * as a `percent`. The fields are taken out either way.
+     */
+    static apply(scale, cfg) {
+        if (!scale)
+            return scale;
+        const { decimals, prefix, suffix, signDisplay, ...rest } = scale;
+        const display = { decimals, prefix, suffix, signDisplay };
+        if (!TickNumbers.isSet(display))
+            return scale;
+        if (rest.tickFormat !== undefined || rest.percent)
+            return rest;
+        return { ...rest, tickFormat: TickNumbers.format(display, cfg) };
+    }
+    /**
+     * A `tickFormat` for `display`. With `decimals`, every tick has exactly that many; without, ticks read as the
+     * axis writes them on its own (compact when they span orders of magnitude) - the configuration's
+     * `numbers.decimals` does not reach the ticks.
+     */
+    static format(display, cfg) {
+        const { prefix = '', suffix = '' } = display;
+        const own = { ...cfg, numbers: {} };
+        if (display.decimals !== undefined) {
+            const fixed = NumberFormat.of(display, own);
+            return (d) => (typeof d === 'number' ? fixed(d) : String(d));
+        }
+        // As svelteplot's automatic format, judged by the ticks' own range, once per set of ticks.
+        let ticks;
+        let write = String;
+        const sign = NumberFormat.sign(display);
+        return (d, _index, all) => {
+            if (typeof d !== 'number')
+                return String(d);
+            if (ticks !== all) {
+                const numbers = all.filter((t) => typeof t === 'number' && Number.isFinite(t));
+                ticks = all;
+                write = AxisNumberFormat.of([Math.min(...numbers), Math.max(...numbers)], cfg, sign);
+            }
+            return `${prefix}${write(d)}${suffix}`;
+        };
+    }
+}

package/dist/layout/styles/ValueLabels.js

@@ -5,6 +5,7 @@ import { SERIES_ID_KEY, SERIES_KEY } from '../../phases/transforms/TransformsPha
 import { seriesIdOf } from '../../utils/grouping';
 import { isGapValue } from '../../plots/utils/gaps';
 import { PlotAxes } from '../../phases/data/PlotAxes';
+import { NumberFormat } from '../../utils/NumberFormat';
 /**
  * A plot's value labels: the author's `styles.values` over the plot kind's
  * own defaults, how their text measures, where they are expected to sit
@@ -30,7 +31,14 @@ export class ValueLabels {
     constructor(values, cfg, options = {}, reach) {
         this.show = values?.show ?? options.show ?? false;
         this.anchor = values?.anchor ?? options.anchor ?? 'outside';
-        this.format = values?.format ?? options.format ?? ((v) => `${v}`);
+        // 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
+            ? (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/layout/tooltip/TooltipState.svelte.d.ts

@@ -43,14 +43,15 @@ export declare class TooltipState {
      * the order the hover matched them in.
      */
     static descending<TRow>(valueOf: (row: TRow) => unknown): (a: TRow, b: TRow) => number;
-    /** A value as plain text: a date as a locale date, anything else as itself. */
-    static value(value: unknown): string;
+    /** A value as plain text: a date as a locale date, a number as `number` writes it (when given), anything else as itself. */
+    static value(value: unknown, number?: (value: number) => string): string;
     /**
      * How a hovered row reads by default, on every plot: its series, when the
      * plot groups its rows; then where it sits - `category: value` when one
      * axis is a band of categories (the row's own value, as its series reads
      * it), else `x: y` as the transforms left them; then the value its color
-     * shows, when that is a number (a heatmap's cells).
+     * shows, when that is a number (a heatmap's cells). With `number`, the values - the one on the value axis
+     * (the plot's `y` when neither axis holds categories) and the color's - read as it writes them.
      */
     static default(state: {
         processedData?: ProcessedData;
@@ -63,5 +64,5 @@ export declare class TooltipState {
             };
         };
         axes?: PlotAxes;
-    }): (row: ProcessedRow) => string;
+    }, number?: (value: number) => string): (row: ProcessedRow) => string;
 }

package/dist/layout/tooltip/TooltipState.svelte.js

@@ -62,31 +62,36 @@ export class TooltipState {
             return right - left;
         };
     }
-    /** A value as plain text: a date as a locale date, anything else as itself. */
-    static value(value) {
-        return value instanceof Date ? value.toLocaleDateString() : String(value);
+    /** A value as plain text: a date as a locale date, a number as `number` writes it (when given), anything else as itself. */
+    static value(value, number) {
+        if (value instanceof Date)
+            return value.toLocaleDateString();
+        return number && typeof value === 'number' ? number(value) : String(value);
     }
     /**
      * How a hovered row reads by default, on every plot: its series, when the
      * plot groups its rows; then where it sits - `category: value` when one
      * axis is a band of categories (the row's own value, as its series reads
      * it), else `x: y` as the transforms left them; then the value its color
-     * shows, when that is a number (a heatmap's cells).
+     * shows, when that is a number (a heatmap's cells). With `number`, the values - the one on the value axis
+     * (the plot's `y` when neither axis holds categories) and the color's - read as it writes them.
      */
-    static default(state) {
+    static default(state, number) {
         const processed = state.processedData;
         if (!processed)
             return () => '';
         const x = TooltipState.#axisText(processed, 'x');
         const y = TooltipState.#axisText(processed, 'y');
+        // With no band axis, the value is the y.
+        const valueY = TooltipState.#axisText(processed, 'y', number);
         const bandX = state.axes?.bands.includes('x') ?? false;
         const bandY = state.axes?.bands.includes('y') ?? false;
         const valueOf = ValueLabels.valueOf(state);
         const position = bandX && !bandY
-            ? (row) => `${x(row)}: ${TooltipState.value(valueOf(row))}`
+            ? (row) => `${x(row)}: ${TooltipState.value(valueOf(row), number)}`
             : bandY && !bandX
-                ? (row) => `${y(row)}: ${TooltipState.value(valueOf(row))}`
-                : (row) => `${x(row)}: ${y(row)}`;
+                ? (row) => `${y(row)}: ${TooltipState.value(valueOf(row), number)}`
+                : (row) => `${x(row)}: ${valueY(row)}`;
         const grouped = state.channels?.grouping !== undefined;
         const color = state.channels?.color;
         const colorName = typeof color?.source === 'string' ? color.source : 'color';
@@ -95,7 +100,7 @@ export class TooltipState {
             lines.push(position(row));
             const shown = color?.accessor(row);
             if (typeof shown === 'number' && Number.isFinite(shown)) {
-                lines.push(`${colorName}: ${TooltipState.value(shown)}`);
+                lines.push(`${colorName}: ${TooltipState.value(shown, number)}`);
             }
             return lines.join('\n');
         };
@@ -104,13 +109,13 @@ export class TooltipState {
      * How one axis reads on a processed row: its own channel, else the range
      * the transforms gave it - a stack's own share (`2 - 1`), any other span as `1-2`.
      */
-    static #axisText(processed, axis) {
+    static #axisText(processed, axis, number) {
         const { channels, transforms } = processed;
         const read = (channel) => resolveAccessor(channel);
         const point = channels[axis];
         if (point !== undefined) {
             const value = read(point);
-            return (row) => TooltipState.value(value(row));
+            return (row) => TooltipState.value(value(row), number);
         }
         const low = channels[`${axis}1`];
         const high = channels[`${axis}2`];
@@ -119,8 +124,8 @@ export class TooltipState {
         const from = read(low);
         const to = read(high);
         if (transforms.some((t) => t.type === STACKS[axis])) {
-            return (row) => TooltipState.value(Number(to(row)) - Number(from(row)));
+            return (row) => TooltipState.value(Number(to(row)) - Number(from(row)), number);
         }
-        return (row) => `${TooltipState.value(from(row))}-${TooltipState.value(to(row))}`;
+        return (row) => `${TooltipState.value(from(row), number)}-${TooltipState.value(to(row), number)}`;
     }
 }

package/dist/markers/delta/DeltaPoint.svelte

@@ -14,7 +14,8 @@
 	const plot = usePlot();
 
 	const resolved = $derived(Delta.build(marker.axis, data, marker));
-	const label = $derived(getConfiguration().delta.text[marker.axis]);
+	const cfg = $derived(getConfiguration());
+	const label = $derived(cfg.delta.text[marker.axis]);
 	const lineAnchor = $derived(marker.text?.lineAnchor ?? label.lineAnchor);
 
 	const clampRange = $derived.by((): [number, number] | undefined => {
@@ -97,7 +98,11 @@
 			type: 'text',
 			x: coords.textPt.x,
 			y: coords.textPt.y,
-			text: (marker.formatDiff ?? ((v: number) => v.toFixed(1)))(coords.diff),
+			text: marker.formatDiff ? marker.formatDiff(coords.diff) : coords.diff,
+			decimals: marker.decimals ?? cfg.numbers.decimals ?? 1,
+			prefix: marker.prefix,
+			suffix: marker.suffix,
+			signDisplay: marker.signDisplay,
 			styles: {
 				fontWeight: 'bold',
 				fontSize: 14,

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/markers/text/TextMarker.svelte

@@ -6,13 +6,16 @@
 	import { RowOffset } from '../utils/RowOffset';
 	import RowOffsetMarks from '../utils/RowOffsetMarks.svelte';
 	import { Declutter } from './Declutter';
+	import { NumberFormat } from '../../utils/NumberFormat';
 	import { PlotMargins } from '../../layout/margins/PlotMargins.svelte';
 	import { Box } from '../../layout/margins/Box';
 	import type { TextMarkerConfig } from '../../types/markers/common';
 	import type { TextAnchor } from '../../types/plots/constants';
 
 	/**
-	 * Renders one `'text'` marker. `x`/`y` also accept a literal number or Date.
+	 * Renders one `'text'` marker. `x`/`y` also accept a literal number or Date. A number its `text`
+	 * gives - a number, a numeric field of the rows, a function's result - is written as the marker's
+	 * `decimals`, `prefix`, `suffix` and `signDisplay` (over the configuration's `numbers`) ask.
 	 * A marker that declutters, flips at the edges or listens to the pointer
 	 * draws one label per row, inside the plot's content box. With
 	 * `fitMargins`, the plot's margins grow until the labels fit.
@@ -34,6 +37,7 @@
 	const x = $derived(marker.x);
 	const y = $derived(marker.y);
 	const text = $derived(marker.text ?? '');
+	const numberText = $derived(NumberFormat.of(NumberFormat.displayOf(marker), cfg));
 	const styles = $derived(marker.styles);
 
 	// A label placed by a literal (or by the frame) draws once without rows; one placed by a field of its rows draws nothing.
@@ -109,8 +113,19 @@
 		return () => value;
 	}
 
+	/** What a row's `text` comes to: a function's result, a field of the row, else the text itself. */
+	function valueOf(d: TData): unknown {
+		if (typeof text === 'function') return text(d);
+		if (typeof text === 'string' && typeof d === 'object' && d !== null && text in d) {
+			return (d as Record<string, unknown>)[text];
+		}
+		return text;
+	}
+
+	/** A row's text, a number written as the marker asks. */
 	function textOf(d: TData): string {
-		return typeof text === 'function' ? text(d) : text;
+		const value = valueOf(d);
+		return typeof value === 'number' ? numberText(value) : String(value ?? '');
 	}
 
 	function opacityOf(d: TData): number | undefined {
@@ -195,7 +210,10 @@
 			x={x ?? (marker.frameAnchor ? undefined : 0)}
 			y={y ?? (marker.frameAnchor ? undefined : 0)}
 			frameAnchor={marker.frameAnchor}
-			text={text ?? ''}
+			text={((d: TData) => {
+				const value = valueOf(d);
+				return typeof value === 'number' ? numberText(value) : value;
+			}) as (d: TData) => string}
 			dx={projected ? 0 : rowDx}
 			dy={projected ? 0 : rowDy}
 			fill={fill as never}
@@ -278,7 +296,7 @@
 	{/if}
 {/snippet}
 
-{#if text}
+{#if text !== ''}
 	{#if measured}
 		<g bind:this={groupEl}>{@render labels()}</g>
 	{:else}

package/dist/phases/hover/HoverPhase.js

@@ -2,6 +2,7 @@ import { ProcessedPositions } from '../transforms/ProcessedPositions';
 import { GAP_VALUE, SERIES_KEY } from '../transforms/TransformsPhase';
 import { HoverSettings } from '../../layout/hover/HoverSettings';
 import { PlotAxes } from '../data/PlotAxes';
+import { NumberFormat } from '../../utils/NumberFormat';
 import { isGapValue } from '../../plots/utils/gaps';
 import { LegendState } from '../../layout/legend/LegendState.svelte';
 /**
@@ -50,7 +51,8 @@ export class HoverPhase {
             points: points,
             label: label,
             defaultStrategy: options.strategy ?? HoverSettings.strategyOf(state.axes),
-            pointMatching: options.pointMatching
+            pointMatching: options.pointMatching,
+            number: NumberFormat.of(NumberFormat.displayOf(state.tooltip), ctx.cfg)
         });
         const hitAreas = options.hitAreas?.(state, hover, ctx) ?? [];
         return {

package/dist/phases/tooltip/TooltipPhase.d.ts

@@ -1,14 +1,15 @@
-import type { AxisPlotState, PhaseStage } from '../../types/phases';
+import type { AxisPlotCtx, AxisPlotState, PhaseStage } from '../../types/phases';
 type AnyAxisState = AxisPlotState<any, any, any, any>;
 /**
  * The "tooltip" phase every axis-based plot shares: how a hovered row reads,
  * as `tooltipFormat` - the same default on every plot, {@link TooltipState.default} -
  * and the order its rows read in, as `tooltipSort`: highest value first, by
- * each row's own value (a stacked row's share, not its running total). It
+ * each row's own value (a stacked row's share, not its running total). The value reads as the tooltip's
+ * `decimals`, `prefix`, `suffix` and `signDisplay` ask. It
  * runs after the scales, which say which axis holds categories.
  */
-export declare class TooltipPhase<TState extends AnyAxisState> implements PhaseStage<TState> {
+export declare class TooltipPhase<TState extends AnyAxisState> implements PhaseStage<TState, AxisPlotCtx> {
     readonly phase: "tooltip";
-    run: (state: TState) => TState;
+    run: (state: TState, ctx: AxisPlotCtx) => TState;
 }
 export {};

package/dist/phases/tooltip/TooltipPhase.js

@@ -1,17 +1,19 @@
 import { TooltipState } from '../../layout/tooltip/TooltipState.svelte';
 import { ValueLabels } from '../../layout/styles/ValueLabels';
+import { NumberFormat } from '../../utils/NumberFormat';
 /**
  * The "tooltip" phase every axis-based plot shares: how a hovered row reads,
  * as `tooltipFormat` - the same default on every plot, {@link TooltipState.default} -
  * and the order its rows read in, as `tooltipSort`: highest value first, by
- * each row's own value (a stacked row's share, not its running total). It
+ * each row's own value (a stacked row's share, not its running total). The value reads as the tooltip's
+ * `decimals`, `prefix`, `suffix` and `signDisplay` ask. It
  * runs after the scales, which say which axis holds categories.
  */
 export class TooltipPhase {
     phase = 'tooltip';
-    run = (state) => ({
+    run = (state, ctx) => ({
         ...state,
-        tooltipFormat: TooltipState.default(state),
+        tooltipFormat: TooltipState.default(state, NumberFormat.maybe(NumberFormat.displayOf(state.tooltip), ctx.cfg)),
         tooltipSort: TooltipState.descending(ValueLabels.valueOf(state))
     });
 }

package/dist/plots/evolution/area/defaults.js

@@ -12,7 +12,7 @@ export function buildAreaDefaults() {
         styles: {
             values: {
                 anchor: 'start',
-                format: (v, name) => `${name} - ${v}`,
+                format: (v, name, number) => `${name} - ${number(v)}`,
                 reach: (labels, state) => labels.reachAtSeriesEnds(state)
             }
         },

package/dist/plots/evolution/line/defaults.js

@@ -23,7 +23,7 @@ export function buildLineDefaults() {
         styles: {
             values: {
                 anchor: 'start',
-                format: (v, name) => `${name} - ${v}`,
+                format: (v, name, number) => `${name} - ${number(v)}`,
                 reach: (labels, state) => labels.reachAtSeriesEnds(state)
             }
         },

package/dist/plots/evolution/slope/defaults.js

@@ -23,7 +23,7 @@ export function buildSlopeDefaults() {
         styles: {
             values: {
                 anchor: 'start',
-                format: (v, name) => `${name} - ${v}`
+                format: (v, name, number) => `${name} - ${number(v)}`
             }
         },
         markers: { marks: buildMarks, valueLabels: buildValueLabels }

package/dist/plots/evolution/sparkline/defaults.js

@@ -15,7 +15,7 @@ export function buildSparklineDefaults() {
             values: {
                 ...line.styles?.values,
                 show: true,
-                format: (value) => `${value}`
+                format: (value, _name, number) => number(value)
             }
         },
         markers: { marks: buildMarks, valueLabels: line.markers.valueLabels }

package/dist/plots/map/geo/phases/hover.js

@@ -1,5 +1,6 @@
 import { LegendState } from '../../../../layout/legend/LegendState.svelte';
 import { HoverSettings } from '../../../../layout/hover/HoverSettings';
+import { NumberFormat } from '../../../../utils/NumberFormat';
 /** Whether a pointer event is over an `inset` marker's panel, which has its own hover. */
 export function isOverInset(e) {
     return e.target?.closest?.('.dct-geo-inset') != null;
@@ -26,7 +27,8 @@ export function buildHover(state, ctx) {
             label,
             defaultStrategy: 'punctual',
             // Match the feature under the cursor, not the nearest centroid.
-            pointMatching: 'contains'
+            pointMatching: 'contains',
+            number: NumberFormat.of(NumberFormat.displayOf(tooltip), ctx.cfg)
         }),
         // A map has no axes for a crosshair: 'punctual' only means an exact match.
         strategy: 'punctual',

package/dist/types/configuration/styling.d.ts

@@ -105,6 +105,11 @@ export type PlotStylesConfig = {
          */
         tolerance: number | string;
     };
+    /** How numbers read wherever a plot writes one, other than the automatic ticks. */
+    numbers: {
+        /** Exactly this many decimals in tooltips, value labels and text and delta markers. Unset (the default), as many as each number needs. An axis' ticks keep their automatic format unless `scales` sets `decimals`. */
+        decimals?: number;
+    };
     axis: {
         color: string;
         fontSize: number;

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/numbers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How a number reads where this package writes one: a tooltip, a value label, a text or delta marker, an
+ * axis' ticks. Each part is optional; what a place leaves unset takes the configuration's `numbers`
+ * (only `decimals`), else the natural reading in `axis.locale`.
+ */
+export type NumberDisplay = {
+    /** Exactly this many decimals (`1` writes `12` as `12,0`). Unset, the configuration's `numbers.decimals`, else as many as the number needs. */
+    decimals?: number;
+    /** Text before the number, spaces included (`'US$ '`). */
+    prefix?: string;
+    /** Text after the number, spaces included (`' %'`). */
+    suffix?: string;
+    /** The sign: `'auto'` (default) writes only a minus; `'always'` also writes a plus on a positive number - never on zero; `'never'` writes none. */
+    signDisplay?: 'auto' | 'always' | 'never';
+};

package/dist/types/layout/numbers.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,4 +1,5 @@
 import type { SymbolType } from '../plots/constants';
+import type { NumberDisplay } from './numbers';
 import type { AxisChannelName, IndependentChannelName } from './mapping';
 /** A continuous or categorical color ramp. */
 export type ColorScaleConfig = {
@@ -124,10 +125,12 @@ export type CategorySort = {
 };
 /**
  * Scale overrides for one plot axis - svelteplot's `ScaleOptions` and
- * `XScaleOptions`, plus this package's own fields. `TData` is the row type
+ * `XScaleOptions`, plus this package's own fields. `decimals`, `prefix`, `suffix` and `signDisplay` write the
+ * ticks of a numeric axis ({@link NumberDisplay}); they are ignored when `tickFormat` or `percent` is set. Without `decimals`
+ * the ticks keep their automatic format, abbreviated when they span orders of magnitude. `TData` is the row type
  * {@link AxisScale.sort} compares.
  */
-export type AxisScale<TData = Record<string, unknown>> = {
+export type AxisScale<TData = Record<string, unknown>> = NumberDisplay & {
     type?: 'auto' | ContinuousScaleType | TemporalScaleType | DiscreteScaleType | SequentialScaleType | DivergingScaleType | BinnedScaleType;
     domain?: (number | string | boolean | Date | null)[];
     range?: (number | string | boolean | Date | null)[];

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

@@ -1,5 +1,6 @@
 import type { ValueAnchor } from '../../plots/constants';
 import type { FontStyle, StrokeStyle } from '../../plots/styling';
+import type { NumberDisplay } from '../numbers';
 /**
  * Which of a group's rows get a value label: its first or last, or the one
  * with the lowest or highest value (read on the plot's value axis). The group
@@ -18,7 +19,7 @@ export type ValueSelect = 'first' | 'last' | 'min' | 'max';
  * provided - mirrors {@link DeltaConfig}'s `fontStyle`/`strokeStyle` split, so
  * label text and connector-line styling never mix into one flat bag of props.
  */
-export type ValuesStyle = {
+export type ValuesStyle = NumberDisplay & {
     /** Whether the labels are drawn. Off by default, except on a heatmap. */
     show?: boolean;
     /** Where each label sits on its mark - see {@link ValueAnchor}. */
@@ -37,8 +38,8 @@ export type ValuesStyle = {
      * CSS color writes them all in it. `fontStyle.fill` wins when it is set.
      */
     color?: 'series' | (string & {});
-    /** A label's text, 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;
+    /** 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>, 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/layout/tooltip.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
 import type { HoverStrategy } from './hover';
+import type { NumberDisplay } from './numbers';
 /**
  * Preferred horizontal placement of the tooltip beside the cursor; it moves
  * to the other side when it would overflow. Defaults to `'right'`.
@@ -11,14 +12,18 @@ export type TooltipAnchorY = 'top' | 'middle' | 'bottom';
 export type TooltipRow<TRow> = TRow & {
     seriesColor?: string;
 };
-/** Author-facing tooltip option on the chart kinds. `true` = enable with defaults. */
-export type TooltipOptions<TRow extends Record<string, unknown>> = {
+/**
+ * Author-facing tooltip option on the chart kinds. `true` = enable with defaults. `decimals`, `prefix`,
+ * `suffix` and `signDisplay` write the value the default text shows - the one on the plot's value axis (the
+ * x of a horizontal bar chart), and a heatmap's color value - and the numbers a custom `format` writes with its `number`.
+ */
+export type TooltipOptions<TRow extends Record<string, unknown>> = NumberDisplay & {
     /** Matching strategy. Defaults to the chart kind's own default. */
     strategy?: HoverStrategy;
     /** Highlight the hovered point in every synced plot too. Defaults to `false`. */
     sync?: boolean;
-    /** Custom tooltip text for a row (supports `\n`). Defaults per chart kind. */
-    format?: (row: TRow) => string;
+    /** Custom tooltip text for a row (supports `\n`). Defaults per chart kind. `number` writes a value as the display fields above ask. */
+    format?: (row: TRow, number: (value: number) => string) => string;
     /** Named subset of crossing series to include. Omitted = all matched. */
     series?: string[];
     /** Custom tooltip body; replaces `format` when given. Its rows carry a `seriesColor` - see {@link TooltipRow}. */

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

@@ -1,5 +1,6 @@
 import type { AxisValue } from '../../layout/mapping';
 import type { DotStyle, FontStyle, StrokeStyle } from '../../plots/styling';
+import type { NumberDisplay } from '../../layout/numbers';
 /** Which endpoint a delta measures from or to: a named series, or a fixed axis value. */
 export type DeltaTarget = {
     type: 'series';
@@ -8,13 +9,17 @@ export type DeltaTarget = {
     type: 'axis';
     value?: number;
 };
-/** Distance between two points on a line chart, along one axis. */
-export type DeltaConfig = {
+/**
+ * Distance between two points on a line chart, along one axis. The distance reads as {@link NumberDisplay}
+ * asks - `decimals` (default one), `prefix`, `suffix` and `signDisplay` - unless `formatDiff` writes it.
+ */
+export type DeltaConfig = NumberDisplay & {
     axis: 'x' | 'y';
     at: AxisValue;
     from: DeltaTarget;
     to?: DeltaTarget;
-    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/markers/basic/text.d.ts

@@ -4,6 +4,7 @@ import type { CommonMarkerConfigWithRowOffset } from '../channels/commonMarkerCo
 import type { Margins } from '../../../layout/margins/Margins';
 import type { BandSlice } from '../../layout/hover';
 import type { TextAnchor } from '../../plots/constants';
+import type { NumberDisplay } from '../../layout/numbers';
 /**
  * Spreads labels that would overlap apart vertically, all reaching out to one
  * shared column, each routed back to its own point by an elbow connector.
@@ -26,7 +27,12 @@ export type TextDeclutterConfig = {
 /** A text label per row (svelteplot's `Text`), usable on any plot kind. */
 export type TextMarkerConfig = CommonMarkerConfigWithRowOffset<{
     type: 'text';
-    text: string | ((d: any) => string);
+    /**
+     * What each label says: a text; a number; the name of a field of the rows (a number there reads as a number); or a function of
+     * the row giving a text or a number. A number is written as {@link NumberDisplay} asks - this marker's own
+     * `decimals`, `prefix`, `suffix` and `signDisplay`, over the configuration's `numbers`.
+     */
+    text: string | number | ((d: any) => string | number);
     styles?: FontStyle;
     /** Which side of its point the text sits on: a value, or a function of the row. Wins over `styles.textAnchor`. */
     textAnchor?: TextAnchor | ((d: any) => TextAnchor);
@@ -54,7 +60,7 @@ export type TextMarkerConfig = CommonMarkerConfigWithRowOffset<{
     onPointerEnter?: (d: any) => void;
     /** Fired when the pointer leaves a row's label. */
     onPointerLeave?: (d: any) => void;
-} & CommonMarkerConfig>;
+} & NumberDisplay & CommonMarkerConfig>;
 /** Where one decluttered label goes - see `Declutter.buildLanes`. */
 export type LabelLane = {
     /** Vertical shift (px) clearing its neighbours and the content box's edges. */

package/dist/types/phases/styles/phase.d.ts

@@ -7,8 +7,8 @@ export type ValueLabelsOptions<TState> = {
     show?: boolean;
     /** Where a label sits when `styles.values.anchor` is unset. Defaults to `'outside'`. */
     anchor?: ValueAnchor;
-    /** A label's text when `styles.values.format` is unset. Defaults to the bare value. */
-    format?: (value: number, seriesName: string) => string;
+    /** A label's text when `styles.values.format` is unset. Defaults to the bare value. `number` writes a value as the plot's `styles.values` display fields (`decimals`, `prefix`, `suffix`, `signDisplay`) ask. */
+    format?: (value: number, seriesName: string, number: (value: number) => string) => string;
     /**
      * Where the labels are expected to sit, from the whole data: boxes around
      * the points they label, on the plot edges those points can reach (see

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

@@ -52,7 +52,7 @@ export type HoverConfig<TRow extends Record<string, unknown>> = {
     /** Resolved sync flag for the *local* hover store (ignored once a shared store is in scope). */
     sync?: boolean;
     /** The resolved tooltip: its `format`, and the order its text reads the rows in (a `content` snippet gets them as matched). */
-    tooltip?: TooltipConfig<TRow> & {
+    tooltip?: Omit<TooltipConfig<TRow>, 'format'> & {
         format: (row: TRow) => string;
         sort?: (a: TRow, b: TRow) => number;
     };

package/dist/utils/NumberFormat.d.ts

@@ -0,0 +1,25 @@
+import type { PlotStylesConfig } from '../types/configuration/styling';
+import type { NumberDisplay } from '../types/layout/numbers';
+declare const SIGNS: {
+    readonly auto: "auto";
+    readonly always: "exceptZero";
+    readonly never: "never";
+};
+type Config = Pick<PlotStylesConfig, 'axis' | 'numbers'>;
+/** Numbers as a {@link NumberDisplay} writes them, in the configuration's `axis.locale`. */
+export declare class NumberFormat {
+    /** Whether `display`, or the configuration's `numbers.decimals`, asks for anything: when not, a number is left as the plot writes it by default. */
+    static isSet(display: NumberDisplay | undefined, cfg: Config): boolean;
+    /** `display`'s sign as `Intl.NumberFormat` names it. */
+    static sign(display: NumberDisplay | undefined): (typeof SIGNS)[keyof typeof SIGNS];
+    /**
+     * A formatter for numbers as `display` asks, over the configuration. `fallbackDecimals` is the count of a
+     * place with a default of its own, used when neither `display` nor the configuration sets one.
+     */
+    static of(display: NumberDisplay | undefined, cfg: Config, fallbackDecimals?: number): (value: number) => string;
+    /** {@link NumberFormat.of}, or `undefined` while nothing asks for it ({@link NumberFormat.isSet}). */
+    static maybe(display: NumberDisplay | undefined, cfg: Config): ((value: number) => string) | undefined;
+    /** The fields of `source` that are a {@link NumberDisplay}'s, for a config that carries them beside its own. */
+    static displayOf(source: NumberDisplay | boolean | undefined): NumberDisplay;
+}
+export {};

package/dist/utils/NumberFormat.js

@@ -0,0 +1,45 @@
+// `'always'` never writes `+0`: Intl's `'exceptZero'`.
+const SIGNS = { auto: 'auto', always: 'exceptZero', never: 'never' };
+/** Numbers as a {@link NumberDisplay} writes them, in the configuration's `axis.locale`. */
+export class NumberFormat {
+    /** Whether `display`, or the configuration's `numbers.decimals`, asks for anything: when not, a number is left as the plot writes it by default. */
+    static isSet(display, cfg) {
+        return ((display?.decimals ?? cfg.numbers.decimals) !== undefined ||
+            !!display?.prefix ||
+            !!display?.suffix ||
+            display?.signDisplay !== undefined);
+    }
+    /** `display`'s sign as `Intl.NumberFormat` names it. */
+    static sign(display) {
+        return SIGNS[display?.signDisplay ?? 'auto'];
+    }
+    /**
+     * A formatter for numbers as `display` asks, over the configuration. `fallbackDecimals` is the count of a
+     * place with a default of its own, used when neither `display` nor the configuration sets one.
+     */
+    static of(display, cfg, fallbackDecimals) {
+        const decimals = display?.decimals ?? cfg.numbers.decimals ?? fallbackDecimals;
+        const format = new Intl.NumberFormat(cfg.axis.locale, {
+            ...(decimals === undefined
+                ? {}
+                : { minimumFractionDigits: decimals, maximumFractionDigits: decimals }),
+            signDisplay: NumberFormat.sign(display)
+        });
+        const { prefix = '', suffix = '' } = display ?? {};
+        return (value) => `${prefix}${format.format(value)}${suffix}`;
+    }
+    /** {@link NumberFormat.of}, or `undefined` while nothing asks for it ({@link NumberFormat.isSet}). */
+    static maybe(display, cfg) {
+        return NumberFormat.isSet(display, cfg) ? NumberFormat.of(display, cfg) : undefined;
+    }
+    /** The fields of `source` that are a {@link NumberDisplay}'s, for a config that carries them beside its own. */
+    static displayOf(source) {
+        const own = typeof source === 'object' ? source : undefined;
+        return {
+            decimals: own?.decimals,
+            prefix: own?.prefix,
+            suffix: own?.suffix,
+            signDisplay: own?.signDisplay
+        };
+    }
+}

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

@@ -40,6 +40,16 @@
 
 Markers draw in array order. Type a markers array with `satisfies AxisBasedMarkersConfig[]` (or `GeoMarkersConfig[]`) to get completion.
 
+### Numbers in `text` and `delta` markers
+
+A `text` marker's `text` is a string, a number, the name of a field of its rows, or a function of the row giving a string or a number. A number - given, read from a field, or returned - is written as the marker's own `decimals`, `prefix`, `suffix` and `signDisplay` ask ([Number format](theming.md#number-format)); a string is drawn as it is.
+
+```ts
+{ 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 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
 
 | Field                      | Meaning                                                                                                                                                                                         |
@@ -115,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/scales.md

@@ -67,6 +67,8 @@ A category axis can be ordered by what its categories hold, without writing a co
 
 Number and date text defaults follow `axis.locale` and `axis.compactDisplay` in the [configuration](theming.md#locale).
 
+A numeric axis takes `prefix`, `suffix`, `decimals` and `signDisplay` to write its ticks (`suffix: '%'`, `prefix: 'US$ '`) without a `tickFormat`; see [Number format](theming.md#number-format). A `tickFormat` of its own wins over them.
+
 ## Color
 
 `scales.color` configures the `color` channel (and a choropleth on a map).

package/docs/styles-and-segments.md

@@ -46,17 +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)                                                                                                      |
-| `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                                                                                                                                              |
+| `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).
 

package/docs/theming.md

@@ -63,6 +63,27 @@ setConfiguration({ axis: { locale: 'en-US', compactDisplay: 'long' } });
 
 `axis.locale` updates plots already on screen. `axis.compactDisplay` is read when a plot mounts, so a later change shows on the next mount.
 
+## Number format
+
+`numbers.decimals` fixes how many decimals the numbers a plot writes have: tooltips, value labels, `text` and `delta` markers. Unset (the default), each number has as many as it needs.
+
+```ts
+setConfiguration({ numbers: { decimals: 1 } }); // 12 reads as 12,0
+```
+
+The same four fields set it where a plot needs something else, in `axis.locale`:
+
+| Field         | Meaning                                                                                                                       |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `decimals`    | Exactly this many decimals, over `numbers.decimals`                                                                           |
+| `prefix`      | Text before the number, spaces included: `'US$ '`                                                                             |
+| `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), 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.
+
 ## Edge ticks
 
 `axis.edgeTicks.x` and `axis.edgeTicks.y` (`{ enabled, collision }`, on for x and off for y, both `'drop-nice'`) add a tick at the data's first and last values beside the nice ones, on a continuous axis whose other axis is continuous too, so a reader sees where the data starts and ends. When one lands too close to a nice tick for both labels, `collision` picks what gives way: `'drop-nice'` keeps the data's tick, `'drop-edge'` keeps the nice one, `'extend'` widens the axis to the next nice tick past the data.

package/docs/tooltip-and-hover.md

@@ -43,6 +43,8 @@ A plot becomes interactive when it is given a `tooltip`, a `{ type: 'hover' }` m
 | `series`             | Only these series appear in the tooltip                                                                                                                                                                                                                                                                                                                            |
 | `anchorX`, `anchorY` | Preferred side of the cursor: `'left' \| 'middle' \| 'right'` (default `'right'`) and `'top' \| 'middle' \| 'bottom'` (default `'bottom'`). It moves to the other side when it would overflow                                                                                                                                                                      |
 
+`decimals`, `prefix`, `suffix` and `signDisplay` ([Number format](theming.md#number-format)) write the value the default text shows - the one on the value axis, the `x` of horizontal bars - and a heatmap's color value. A custom `format` gets a second argument, `number`, that writes a number the same way: `format: (row, number) => `${row.region}: ${number(row.value)}``.
+
 <!-- example: examples/CustomTooltip.svelte -->
 
 ```svelte

package/package.json

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