@fundar/data-chart-telling 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.8.1] - 2026-11-02
+
+### Fixed
+
+- `styles.values.format` gets the labelled row as its third argument on `BarPlot`, `PyramidPlot`, `HistogramPlot`, `ScatterPlot` and the end-of-line labels of `LinePlot` and `AreaPlot`, as its documentation says; only `ClevelandPlot` did. A format that returns no text for some rows - the only way to label some pieces of a stacked bar and not others - had no row to decide by.
+
+## [1.8.0] - 2026-11-02
+
+### Added
+
+- `scales.x.lines` and `scales.y.lines` write each label of a category axis on up to that many lines, split at its spaces so the lines are as even as they can be, and keep the `x` labels upright instead of turning them. A `tickFormat` is applied first.
+- A band `y` axis whose `scales.y.tickFormat` gives a label on several lines (a list of strings, or a text with line breaks) writes it on those lines, and its left margin grows to the widest one. svelteplot's own axis joined the lines with spaces, so only the `x` axis could wrap its labels.
+
 ## [1.7.0] - 2026-11-02
 
 ### Added

package/dist/layout/base/BasePlotLayout.svelte

@@ -14,6 +14,7 @@
 	import { getConfiguration } from '../../configuration/config.svelte';
 	import { SveltePlotScale } from '../scales/SveltePlotScale';
 	import { TickLabels } from '../scales/TickLabels';
+	import { TickLines } from '../scales/TickLines';
 	import ScalesLayout from '../scales/ScalesLayout.svelte';
 	import GeometryLayout from '../geometry/GeometryLayout.svelte';
 	import CoordinatesLayout from '../coordinates/CoordinatesLayout.svelte';
@@ -160,7 +161,12 @@
 			x?: ReturnType<typeof TickLabels.layout>;
 			y?: { every: number; values: string[] };
 		} = {};
-		if (bands.includes('x') && scales?.x?.tickRotate === undefined) {
+		// Labels split in lines are meant to stay upright, so they are not judged by how long one line would be.
+		if (
+			bands.includes('x') &&
+			scales?.x?.tickRotate === undefined &&
+			!((scales?.x?.lines ?? 1) > 1)
+		) {
 			out.x = TickLabels.layout(
 				categories('x'),
 				width - estimate.left - estimate.right,
@@ -180,11 +186,19 @@
 		}
 		return out;
 	});
-	/** `scales` with the rotation the tick layout chose for the x labels. */
+	/** An axis' scale with its labels split in the `lines` it asks for, as a `tickFormat` that gives them. */
+	function withLines<TScale extends AxisScale<TData> | undefined>(scale: TScale): TScale {
+		if (!scale?.lines || scale.lines < 2) return scale;
+		const { lines, tickFormat, ...rest } = scale;
+		const format = typeof tickFormat === 'function' ? tickFormat : undefined;
+		return { ...rest, tickFormat: TickLines.wrapped(format, lines) } as TScale;
+	}
+	/** `scales` with the rotation the tick layout chose for the x labels, and the labels split in lines. */
 	const layoutScales = $derived.by(() => {
+		if (scales === undefined) return scales;
 		const rotate = tickLayout?.x?.rotate;
-		if (!rotate || scales === undefined) return scales;
-		return { ...scales, x: { ...scales.x, tickRotate: rotate } };
+		const x = withLines(rotate ? { ...scales.x, tickRotate: rotate } : scales.x);
+		return { ...scales, ...(x ? { x } : {}), ...(scales.y ? { y: withLines(scales.y) } : {}) };
 	});
 	/** The category labels a crowded axis still writes: one in every few. */
 	const tickValues = $derived.by(() => {
@@ -252,9 +266,9 @@
 		return (label ? { ...out, label } : out) as SveltePlotProps['x'];
 	});
 	const resolvedY = $derived.by(() => {
-		const built = SveltePlotScale.build(scales?.y, data, getY);
+		const built = SveltePlotScale.build(layoutScales?.y, data, getY);
 		const domain = edgeDomains.get('y');
-		const label = titleOfEmpty('y', scales?.y);
+		const label = titleOfEmpty('y', layoutScales?.y);
 		const out = domain ? { ...built, domain, nice: false } : built;
 		return (label ? { ...out, label } : out) as SveltePlotProps['y'];
 	});

package/dist/layout/scales/MultilineYTicks.svelte

@@ -0,0 +1,101 @@
+<script lang="ts">
+	import { getContext, untrack } from 'svelte';
+	import type { Writable } from 'svelte/store';
+	import { usePlot } from '../plot/usePlot';
+
+	/**
+	 * The labels of a band y axis, each on the lines it was given. svelteplot's own axis joins the lines of a
+	 * label with spaces, so an axis whose `tickFormat` gives several lines hides its labels and has them
+	 * drawn here. The left margin grows to the widest line, as the axis does for its own labels.
+	 */
+	let {
+		ticks,
+		lines,
+		tickSize,
+		tickPadding,
+		fontSize
+	}: {
+		ticks: unknown[];
+		/** The lines of each tick, in the order of `ticks`. */
+		lines: string[][];
+		tickSize: number;
+		tickPadding: number;
+		fontSize: number;
+	} = $props();
+
+	const LINE_HEIGHT = 1.15;
+
+	const plot = usePlot().svelteplot;
+	const marginLeft = $derived(Number(plot.options.marginLeft) || 0);
+
+	const placed = $derived(
+		ticks.map((tick, i) => {
+			const scale = plot.scales.y.fn;
+			return {
+				lines: lines[i] ?? [],
+				y: Number(scale(tick as never)) + (scale.bandwidth?.() ?? 0) / 2
+			};
+		})
+	);
+
+	let labels: (SVGTextElement | undefined)[] = $state([]);
+
+	const { autoMarginLeft } = getContext<{ autoMarginLeft: Writable<Map<string, number>> }>(
+		'svelteplot/autoMargins'
+	);
+	const marginId = `dct-multiline-y-ticks-${Math.random().toString(36).slice(2)}`;
+
+	$effect(() => {
+		// Read so new labels or a new size measure again.
+		void [lines, fontSize, tickSize, tickPadding];
+		let frame: number | undefined;
+		let cancelled = false;
+		const measure = () => {
+			if (cancelled) return;
+			const widest = Math.max(
+				0,
+				...labels.map((label) => label?.getBoundingClientRect().width ?? 0)
+			);
+			const wanted = Math.ceil(widest) + Math.max(0, tickSize + tickPadding);
+			untrack(() => {
+				if ($autoMarginLeft.get(marginId) !== wanted) $autoMarginLeft.set(marginId, wanted);
+			});
+		};
+		// Text measures right only once its fonts load.
+		(document.fonts?.ready ?? Promise.resolve()).then(() => {
+			if (!cancelled) frame = requestAnimationFrame(measure);
+		});
+		return () => {
+			cancelled = true;
+			if (frame !== undefined) cancelAnimationFrame(frame);
+		};
+	});
+	$effect(() => () => {
+		$autoMarginLeft.delete(marginId);
+	});
+
+	const x = $derived(marginLeft - tickSize - tickPadding);
+</script>
+
+<g class="dct-multiline-y-ticks">
+	{#each placed as tick, i (i)}
+		<text
+			bind:this={labels[i]}
+			{x}
+			y={tick.y}
+			text-anchor="end"
+			font-size={fontSize}
+			fill="currentColor"
+		>
+			{#each tick.lines as line, l (l)}
+				<!-- The block of lines is centred on the tick: the first sits half the others above it. -->
+				<tspan
+					{x}
+					dy={l === 0
+						? `${0.32 - ((tick.lines.length - 1) / 2) * LINE_HEIGHT}em`
+						: `${LINE_HEIGHT}em`}>{line}</tspan
+				>
+			{/each}
+		</text>
+	{/each}
+</g>

package/dist/layout/scales/MultilineYTicks.svelte.d.ts

@@ -0,0 +1,11 @@
+type $$ComponentProps = {
+    ticks: unknown[];
+    /** The lines of each tick, in the order of `ticks`. */
+    lines: string[][];
+    tickSize: number;
+    tickPadding: number;
+    fontSize: number;
+};
+declare const MultilineYTicks: import("svelte").Component<$$ComponentProps, {}, "">;
+type MultilineYTicks = ReturnType<typeof MultilineYTicks>;
+export default MultilineYTicks;

package/dist/layout/scales/ScalesLayout.svelte

@@ -6,6 +6,8 @@
 	import { getConfiguration } from '../../configuration/config.svelte';
 	import { NiceTicks } from './NiceTicks';
 	import { EdgeTicks } from './EdgeTicks';
+	import { TickLines } from './TickLines';
+	import MultilineYTicks from './MultilineYTicks.svelte';
 	import { DISCRETE_SCALE_TYPES } from '../../types/layout/scales';
 	import type { AxisBasedScalesConfig } from '../../types/layout/scales';
 	import type { AxisValue } from '../../types/layout/mapping';
@@ -200,6 +202,18 @@
 		unknown
 	>;
 
+	/**
+	 * The labels of a band y axis whose `tickFormat` writes some on several lines. svelteplot's axis joins the
+	 * lines of a label with spaces, so such an axis hides its labels and `MultilineYTicks` draws them.
+	 */
+	const multilineY = $derived.by(() => {
+		const format = scales?.y?.tickFormat;
+		if (typeof format !== 'function' || plot.scales.y.type !== 'band') return undefined;
+		const ticks: unknown[] = tickValues?.y ?? plot.scales.y.fn?.domain?.() ?? [];
+		const lines = TickLines.ofTicks(ticks, format);
+		return TickLines.isMultiline(lines) ? { ticks, lines } : undefined;
+	});
+
 	const yTitleFontSize = $derived(scales?.y?.titleFontSize ?? cfg.axis.titleFontSize);
 
 	/**
@@ -327,6 +341,7 @@
 {#snippet axisY()}
 	<AxisY
 		ticks={(yEdgeTicks?.ticks ?? tickValues?.y) as string[] | undefined}
+		tickFormat={multilineY ? () => '' : undefined}
 		tickCount={yTickCount}
 		interval={yTickInterval}
 		tickSize={scales?.y?.tickSize ?? cfg.axis.yTickSize}
@@ -339,6 +354,15 @@
 	<g style:visibility="hidden">{@render axisY()}</g>
 {:else if scales?.y?.axisDisplay !== 'none'}
 	{@render axisY()}
+	{#if multilineY}
+		<MultilineYTicks
+			ticks={multilineY.ticks}
+			lines={multilineY.lines}
+			tickSize={scales?.y?.tickSize ?? cfg.axis.yTickSize}
+			tickPadding={scales?.y?.tickPadding ?? cfg.axis.yTickPadding}
+			fontSize={cfg.axis.fontSize}
+		/>
+	{/if}
 {/if}
 {#if verticalYLabel && (scales?.y?.axisDisplay ?? 'visible') === 'visible'}
 	<text

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

@@ -0,0 +1,19 @@
+/** What a `tickFormat` returns for one tick, as the lines it is written on. */
+export declare class TickLines {
+    /** The lines of `label`: a list as it is, a text split at its line breaks. */
+    static of(label: string | string[]): string[];
+    /** The lines of every tick of `ticks` under `format`. */
+    static ofTicks(ticks: unknown[], format: (d: unknown, index: number, ticks: unknown[]) => string | string[]): string[][];
+    /**
+     * `label` on up to `lines` lines, split at its spaces so that the longest line is as short as it can be
+     * (ties go to the earlier break). A label of one word, or `lines` below 2, stays on one line.
+     */
+    static split(label: string, lines: number): string[];
+    /**
+     * A `tickFormat` that gives the lines of its tick: `format`'s text (or the tick as it is, with none) split in
+     * `lines`, and a list `format` gives as it is.
+     */
+    static wrapped(format: ((d: unknown, index: number, ticks: unknown[]) => string | string[]) | undefined, lines: number): (d: unknown, index: number, ticks: unknown[]) => string[];
+    /** Whether some tick needs more than one line. */
+    static isMultiline(lines: string[][]): boolean;
+}

package/dist/layout/scales/TickLines.js

@@ -0,0 +1,58 @@
+/** What a `tickFormat` returns for one tick, as the lines it is written on. */
+export class TickLines {
+    /** The lines of `label`: a list as it is, a text split at its line breaks. */
+    static of(label) {
+        return Array.isArray(label) ? label : String(label).split('\n');
+    }
+    /** The lines of every tick of `ticks` under `format`. */
+    static ofTicks(ticks, format) {
+        return ticks.map((tick, i) => TickLines.of(format(tick, i, ticks)));
+    }
+    /**
+     * `label` on up to `lines` lines, split at its spaces so that the longest line is as short as it can be
+     * (ties go to the earlier break). A label of one word, or `lines` below 2, stays on one line.
+     */
+    static split(label, lines) {
+        const words = label.split(' ').filter((word) => word !== '');
+        const count = Math.min(Math.floor(lines), words.length);
+        if (count < 2)
+            return [label];
+        const width = (from, to) => words.slice(from, to).reduce((sum, word) => sum + word.length, 0) + (to - from - 1);
+        // best[k][i]: the shortest the longest line can be when the first i words take k lines, and where the last begins.
+        const best = Array.from({ length: count + 1 }, () => []);
+        for (let i = 1; i <= words.length; i++)
+            best[1][i] = { cost: width(0, i), from: 0 };
+        for (let k = 2; k <= count; k++) {
+            for (let i = k; i <= words.length; i++) {
+                let choice = { cost: Infinity, from: k - 1 };
+                for (let from = k - 1; from < i; from++) {
+                    const cost = Math.max(best[k - 1][from].cost, width(from, i));
+                    if (cost < choice.cost)
+                        choice = { cost, from };
+                }
+                best[k][i] = choice;
+            }
+        }
+        const out = [];
+        for (let k = count, end = words.length; k >= 1; k--) {
+            const { from } = best[k][end];
+            out.unshift(words.slice(from, end).join(' '));
+            end = from;
+        }
+        return out;
+    }
+    /**
+     * A `tickFormat` that gives the lines of its tick: `format`'s text (or the tick as it is, with none) split in
+     * `lines`, and a list `format` gives as it is.
+     */
+    static wrapped(format, lines) {
+        return (d, index, ticks) => {
+            const text = format ? format(d, index, ticks) : String(d);
+            return Array.isArray(text) ? text : TickLines.split(text, lines);
+        };
+    }
+    /** Whether some tick needs more than one line. */
+    static isMultiline(lines) {
+        return lines.some((tick) => tick.length > 1);
+    }
+}

package/dist/layout/styles/ValueLabels.js

@@ -206,7 +206,7 @@ export class ValueLabels {
             x: (processed.channels.x ?? position.x),
             y: (processed.channels.y2 ?? processed.channels.y ?? topOf),
             grouping: SERIES_ID_KEY,
-            text: (d) => format(Number(valueOf(d)), nameOf(d)),
+            text: (d) => format(Number(valueOf(d)), nameOf(d), d),
             styles: {
                 ...font,
                 ...(this.fill ? { fill: this.fill } : {}),

package/dist/plots/correlation/scatter/markers.js

@@ -21,7 +21,7 @@ export function buildValueLabels(labels, state, ctx) {
             data: processedData.data,
             x: position.x,
             y: position.y,
-            text: (d) => format(Number(valueOf(d)), nameOf(d)),
+            text: (d) => format(Number(valueOf(d)), nameOf(d), d),
             styles: {
                 ...font,
                 fill: font?.fill ?? ctx.cfg.axis.color,

package/dist/plots/distribution/histogram/markers.js

@@ -41,7 +41,7 @@ export function buildValueLabels(labels, state, ctx) {
         [binned]: position[binned],
         [value]: along,
         transforms: [{ type: 'filter', filter: (d) => countOf(d) > 0 }],
-        text: (d) => format(countOf(d), nameOf(d)),
+        text: (d) => format(countOf(d), nameOf(d), d),
         styles: {
             ...font,
             fill: font?.fill ?? ctx.cfg.axis.color,

package/dist/plots/distribution/pyramid/markers.js

@@ -57,7 +57,7 @@ export function buildValueLabels(labels, state, ctx) {
                 data,
                 [valueAxis]: at,
                 [categoryAxis]: series[categoryAxis],
-                text: (d) => format(magnitude(d), series.name),
+                text: (d) => format(magnitude(d), series.name, d),
                 styles: {
                     ...font,
                     fill: font?.fill ?? ctx.cfg.axis.color,

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

@@ -124,7 +124,7 @@ export function buildValueLabels(labels, state, ctx) {
                     ? { x: position, y: geometry.categoryOf }
                     : { x: geometry.categoryOf, y: position }),
                 bandSlice: geometry.sliceOf(s.name),
-                text: (d) => format(Number(valueOf(d)), s.name),
+                text: (d) => format(Number(valueOf(d)), s.name, d),
                 styles: {
                     ...font,
                     fill: font?.fill ?? ctx.cfg.axis.color,

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

@@ -169,6 +169,7 @@ export type AxisScale<TData = Record<string, unknown>> = {
     tickSize?: number;
     tickPadding?: number;
     tickRotate?: number;
+    lines?: number;
     tickFormat?: false | Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | ((d: unknown, index: number, ticks: unknown[]) => string | string[]);
 };
 /** Each {@link AxisChannelName}'s own scale-config shape - both use {@link AxisScale}. */

package/docs/scales.md

@@ -50,7 +50,8 @@ Each axis takes an `AxisScale`.
 | `edgeTicks`                                                                  | Ticks at the data's first and last values beside the nice ones. `false` turns them off, `true` on, `{ collision: 'drop-nice' \| 'drop-edge' \| 'extend' }` picks what happens when one crowds a nice tick. Defaults to `axis.edgeTicks.x` / `.y` in the [configuration](theming.md#edge-ticks) (on for x, off for y); ignored when the axis sets `ticks`, `tickSpacing`, `interval` or `domain`                                      |
 | `label`, `labelAnchor`, `labelOrientation`, `labelPosition`, `titleFontSize` | The axis title (`label: false` hides it)                                                                                                                                                                                                                                                                                                                                                                                             |
 | `ticks`, `tickSpacing`, `tickSize`, `tickPadding`, `tickRotate`              | Tick placement and size                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `tickFormat`                                                                 | `false`, an `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object, or `(d, index, ticks) => string`                                                                                                                                                                                                                                                                                                                       |
+| `tickFormat`                                                                 | `false`, an `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object, or `(d, index, ticks) => string \| string[]`                                                                                                                                                                                                                                                                                                           |
+| `lines`                                                                      | Labels of a category axis on up to this many lines, split at their spaces                                                                                                                                                                                                                                                                                                                                                            |
 | `grid`                                                                       | `true` or a stroke style for gridlines                                                                                                                                                                                                                                                                                                                                                                                               |
 | `axisDisplay`                                                                | `'visible'` (default), `'hidden'` (keeps the space, so aligned panels stay aligned) or `'none'`                                                                                                                                                                                                                                                                                                                                      |
 | `padding`, `paddingInner`, `paddingOuter`, `align`                           | Band and point spacing                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -58,6 +59,8 @@ Each axis takes an `AxisScale`.
 | `interval`, `base`, `constant`                                               | Time/discrete intervals, log base, symlog constant                                                                                                                                                                                                                                                                                                                                                                                   |
 | `sort`                                                                       | Category order: a comparator of two rows, or by what the categories hold (below)                                                                                                                                                                                                                                                                                                                                                     |
 
+A category axis writes its labels on several lines with `lines`: `lines: 2` splits each label at its spaces, as evenly as it can, in up to two lines (a `tickFormat` is applied first), and the `x` labels stay upright. To split them where you choose, `tickFormat` returns a list of strings, one for each line, or a text with line breaks. A band `y` axis grows its left margin to the widest line.
+
 A category axis whose labels do not fit side by side turns them by itself: to 45 degrees, else to 90, and when even that is not enough it writes only every few labels (and a vertical category axis, such as the one of horizontal bars, does the same). The margin grows to fit the turned labels. An axis with a `tickRotate` of its own - 0 included, which keeps the labels flat - is left as the author set it, and `axis.autoRotate: false` in the [configuration](theming.md) turns this off for every plot.
 
 A category axis can be ordered by what its categories hold, without writing a comparator: `sort: { by: 'value', series?, order? }` orders them by their value in one `series` (or, without it, by the sum of their values) and `sort: { by: 'range', order? }` by the spread between their lowest and their highest value; `order` is `'ascending'` (default) or `'descending'`. `grouped: true` orders within each series instead of across all of them: the series stay together, in the order they first appear. On a plot with intervals (`lower`/`upper`) the range counts the interval's ends. A category with nothing to order by goes last. An explicit `domain` wins. With [facets](facets.md) the order is read off every panel's rows, so the panels share it.

package/package.json

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