@fundar/data-chart-telling 0.0.45 → 0.0.47

package/dist/charts/BaseChart.svelte

@@ -23,9 +23,9 @@
    * The leaf snippet receives `{ data, width, height, facetValue?, selectedValue?,
    * margins? }` and knows nothing about how that box or that data slice was
    * produced, which is what lets any plot (line, bar, heatmap, …) drop in
-   * unchanged. `margins` is only present when `facet.labelsForMargin` is
-   * given — forward it to the plot's own `margins` prop so every facet
-   * shares the same content box.
+   * unchanged. `margins` only has a side set when `facet.marginsForFacet`
+   * reports it — forward it to the plot's own `margins` prop so every facet
+   * shares the same content box on that side.
    */
   let {
     width,
@@ -86,7 +86,7 @@
       formatIndicator={facet.formatIndicator}
       indicator={facet.indicator}
       navButton={facet.navButton}
-      labelsForMargin={facet.labelsForMargin}
+      marginsForFacet={facet.marginsForFacet}
       width={w}
       height={h}
     >

package/dist/index.d.ts

@@ -36,6 +36,8 @@ export { THEMES } from './configuration/themes';
 export type { ThemeName } from './configuration/themes';
 export { groupBy, buildSeries } from './utils/grouping';
 export { makeColorScale, normalize, resolveCssColor, paletteColor } from './utils/color';
+export { estimateCategoricalAxisMargin } from './plots/utils/categoricalAxisMargin';
+export { estimateLineValueLabelMargin } from './plots/line/valueLabelMargin';
 export type { AxisValue, AxisScale, AxisBasedScalesConfig } from './types/layout/scales';
 export type { Accessor, Series, SeriesProps, DataProps } from './types/plots/data/common';
 export type { BasePlotProps, StylesConfig, MarkersConfig, SegmentsConfig, ScalesConfig, MarginConfig, TooltipConfig, HoverConfig, PointMatchingStrategy } from './types/plots/props';

package/dist/index.js

@@ -43,3 +43,5 @@ export { THEMES } from './configuration/themes';
 // ── Utils ─────────────────────────────────────────────────────────────────────
 export { groupBy, buildSeries } from './utils/grouping';
 export { makeColorScale, normalize, resolveCssColor, paletteColor } from './utils/color';
+export { estimateCategoricalAxisMargin } from './plots/utils/categoricalAxisMargin';
+export { estimateLineValueLabelMargin } from './plots/line/valueLabelMargin';

package/dist/layout/facet/FacetLayout.svelte

@@ -2,8 +2,6 @@
   import { isMobile } from '../../stores/device';
   import { groupBy } from '../../utils/grouping';
   import FacetIndicator from './FacetIndicator.svelte';
-  import { getConfiguration } from '../../configuration/config.svelte';
-  import { measureMaxLabelWidth } from '../plot/measureText';
   import type {
     FacetColumns,
     FacetMode,
@@ -27,9 +25,13 @@
    * out at once; `'paginated'` pages through the same grid in fixed chunks;
    * `'carousel'` shows `visible` groups at a time with touch-drag/snap.
    *
-   * `labelsForMargin`, if given, sizes one shared left margin across every
-   * facet — pass it through `cell`'s own `margins` to a faceted plot's
-   * `margins` prop so they all share the same content box.
+   * `marginsForFacet`, if given, sizes one shared margin (any/all sides)
+   * across every facet — pass it through `cell`'s own `margins` to a
+   * faceted plot's `margins` prop so they all share the same content box,
+   * instead of each facet growing its own margin independently off what its
+   * own content happens to need (which drifts out of alignment facet to
+   * facet, and — for a facet cramped enough that its content can never fully
+   * fit — can grow without bound).
    */
   let {
     data,
@@ -47,7 +49,7 @@
     width,
     height,
     cell,
-    labelsForMargin,
+    marginsForFacet,
   }: {
     data: TRow[];
     by: Accessor<TRow, unknown>;
@@ -64,7 +66,7 @@
     width: number;
     height: number;
     cell: FacetCellSnippet<TRow>;
-    labelsForMargin?: (rows: TRow[]) => string[];
+    marginsForFacet?: (rows: TRow[]) => MarginConfig;
   } = $props();
 
   function resolveResponsive<T>(value: Responsive<T>, mobile: boolean): T {
@@ -83,16 +85,30 @@
       .map((v) => [v, groups.get(v)!] as [string, TRow[]]);
   });
 
-  // One shared left margin, sized to the widest label across every facet —
-  // measured off-DOM (canvas), so it's correct from the very first render
-  // with no mount/remount needed. `undefined` when `labelsForMargin` isn't given.
-  const cfg = $derived(getConfiguration());
-  const axisFont = $derived(`${cfg.axis.fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`);
+  // One shared margin, sized to whatever each facet's own `marginsForFacet`
+  // reports it naturally needs — componentwise `max` per side across every
+  // facet. `FacetLayout` itself measures nothing here (no font, no axis
+  // config, no plot-specific knowledge at all) — that's each plot type's
+  // own concern, expressed however it estimates its own margin (see e.g.
+  // `estimateLineValueLabelMargin`); this just compares already-resolved
+  // numbers. `undefined` when `marginsForFacet` isn't given; any side no
+  // facet reports (or reports as `'auto'`, which isn't comparable) stays
+  // unset, falling back to the plot's own default ('auto') sizing.
+  const MARGIN_SIDES = ['left', 'right', 'top', 'bottom'] as const;
   const cellMargins = $derived.by((): MarginConfig | undefined => {
-    if (!labelsForMargin) return undefined;
-    const labels = entries.flatMap(([, rows]) => labelsForMargin(rows));
-    const left = Math.ceil(measureMaxLabelWidth(labels, axisFont)) + cfg.axis.yTickSize + cfg.axis.yTickPadding;
-    return { left };
+    if (!marginsForFacet) return undefined;
+    const perFacet = entries.map(([, rows]) => marginsForFacet(rows));
+    const out: MarginConfig = {};
+    for (const side of MARGIN_SIDES) {
+      let max: number | undefined;
+      for (const margin of perFacet) {
+        const value = margin[side];
+        if (typeof value !== 'number') continue;
+        max = max === undefined ? value : Math.max(max, value);
+      }
+      if (max !== undefined) out[side] = max;
+    }
+    return out;
   });
 
   const resolvedMode = $derived(resolveResponsive(mode, $isMobile));

package/dist/layout/facet/FacetLayout.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { FacetColumns, FacetMode, FacetNavLayout, Responsive, FacetCellSnippet, FacetIndicatorSnippet, FacetNavSnippet } from '../../types/layout/facet';
 import type { Accessor } from '../../types/plots/data/common';
+import type { MarginConfig } from '../../types/plots/props';
 declare function $$render<TRow extends Record<string, unknown>>(): {
     props: {
         data: TRow[];
@@ -17,7 +18,7 @@ declare function $$render<TRow extends Record<string, unknown>>(): {
         width: number;
         height: number;
         cell: FacetCellSnippet<TRow>;
-        labelsForMargin?: (rows: TRow[]) => string[];
+        marginsForFacet?: (rows: TRow[]) => MarginConfig;
     };
     exports: {};
     bindings: "";

package/dist/plots/bar/Plot.svelte

@@ -11,8 +11,11 @@
 		buildScopedMarkerGroups
 	} from '../utils/segments';
 	import { createBarLayout } from './layout.svelte';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
-	import { measureTextWidth } from '../../layout/plot/measureText';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
+	import { estimateValueLabelMargin } from '../utils/valueLabelMargin';
 	import { buildHoverPoints } from './hoverPoints';
 	import { buildBarMarkers } from './buildBarMarkers';
 	import { resolveGapsForSeries, resolveDiscreteGapFills } from '../utils/gaps';
@@ -235,7 +238,7 @@
 		const canvasFont = `${fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
 		if (isHorizontal) {
 			const offset = Math.abs(typeof font?.dx === 'number' ? font.dx : 6);
-			let widestLabel = 0;
+			const texts: string[] = [];
 			for (const s of resolvedSeries) {
 				const sy = resolveAccessor(s.y);
 				let extremeValue = 0;
@@ -249,14 +252,18 @@
 					}
 				}
 				if (extremeRow === undefined) continue;
-				widestLabel = Math.max(widestLabel, measureTextWidth(formatValue(extremeValue, s.name), canvasFont));
+				texts.push(formatValue(extremeValue, s.name));
 			}
-			return { left: 0, right: Math.ceil(offset + widestLabel), top: 0, bottom: 0 };
+			const right = estimateValueLabelMargin(texts, { canvasFont, reach: offset });
+			return { left: 0, right, top: 0, bottom: 0 };
 		}
 		const offset = Math.abs(typeof font?.dy === 'number' ? font.dy : 6);
 		return { left: 0, right: 0, top: Math.ceil(offset + fontSize * 1.2), bottom: 0 };
 	});
 
+	// See `halfDimensionOverflowCap`'s own doc comment.
+	const maxLabelOverflow = $derived(halfDimensionOverflowCap(width, height));
+
 	// A bar's value label can grow past the plot's own content box (e.g. a
 	// tall bar's `anchor: 'outside'` label pushing past the top margin) —
 	// `valueLabelFloor` covers the common case up front; each label's own
@@ -265,7 +272,8 @@
 	const labelMargin = createLabelMarginTracker(
 		() => margins,
 		() => resolvedSeries,
-		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 }
+		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 },
+		() => maxLabelOverflow
 	);
 </script>
 

package/dist/plots/line/Plot.svelte

@@ -8,8 +8,11 @@
 	import { buildLineMarkers } from './buildLineMarkers';
 	import { buildGapMarkers } from './buildGapMarkers';
 	import { isGapValue } from '../utils/gaps';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
-	import { measureTextWidth } from '../../layout/plot/measureText';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
+	import { estimateLineValueLabelMargin } from './valueLabelMargin';
 	import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
 	import ValueLabels from './ValueLabels.svelte';
 	import {
@@ -167,90 +170,27 @@
 			.filter((p): p is { series: Series<TData>; lastRow: TData; color: string } => p !== undefined)
 	);
 
-	// Estimated overflow for a rightward-fanning end-of-line label (the
-	// default: `valAnchor: 'start'`, or any anchor whose resolved `dx` isn't
-	// negative). `lanesUsed` (see `declutter1D`/`laneAssignment`) never
-	// exceeds the series count, so that bounds the reach even without
-	// knowing which points will actually end up clustered together. A
-	// leftward fan (negative `dx`) instead flips itself to the right when it
-	// runs out of room — see `ValueLabels.svelte`'s own doc comment — so it
-	// carries no such risk and is left to the DOM-measured fallback below.
-	//
-	// Only the fraction of the label that actually extends to the right of
-	// its own anchor point counts toward the margin — `textAnchor: 'start'`
-	// (the default `'start'`/`'outside'`-less case) puts the whole label
-	// there, but `'middle'` (`valAnchor: 'outside'`, or the shared-anchor
-	// default for anything other than `'start'`/`'end'`) centers it on the
-	// anchor, so only half sticks out; `'end'` puts none of it there at all.
-	// Same `preferredTA` derivation as `ValueLabels.svelte` (`'outside'`
-	// itself is a `dy`/`lineAnchor` shorthand, not a real textAnchor value —
-	// it resolves through `defaultTA` same as an unset one).
-	//
-	// The widest label is measured from `scales.y.domain` when the caller
-	// pins one (e.g. a shared domain covering a whole timeline range) rather
-	// than from `resolvedSeries`'s own values — a timeline scrubber's `data`
-	// is only the currently-revealed slice, so measuring straight off it
-	// would keep changing the floor (and, via `resetKey`, remounting the
-	// plot) on every tick even though the true worst case across the whole
-	// range never changes. Without a pinned domain there's no such stable
-	// source, so this falls back to the current frame's own values, same as
-	// no floor at all for a caller not pinning a domain in the first place.
-	//
-	// This estimate is close but not exact (declutter's real elbow/connector
-	// geometry vs. this reach formula) — with a pinned domain, that gap can
-	// still cost one extra DOM-measured correction (and its remount) on
-	// whichever tick first renders real declutter geometry, but never more
-	// than one across a whole scrub — see `LinePlot.ValueLabelStability`'s
-	// own test for what "settled" means here.
+	// Estimated overflow for a rightward-fanning end-of-line label — see
+	// `estimateLineValueLabelMargin`'s own doc comment for the covered case,
+	// the stability rationale (worst-case lane count, domain-pinned text), and
+	// its "close but not exact" caveat versus `ValueLabels.svelte`'s real
+	// declutter/connector geometry (see `LinePlot.ValueLabelStability`'s own
+	// test for what "settled" means here). Shared with a faceted caller's own
+	// `FacetConfig.marginsForFacet`, so a single plot and a facet-wide margin
+	// are always computed by the exact same code.
 	const valueLabelFloor = $derived.by((): MarginOverflow | undefined => {
 		if (!showVals) return undefined;
-		const font = styles.values?.fontStyle;
-		const defaultDx = valAnchor === 'start' ? 6 : valAnchor === 'end' ? -6 : 0;
-		const baseDx = typeof font?.dx === 'number' ? font.dx : defaultDx;
-		if ((Math.sign(baseDx) || 1) !== 1) return undefined;
-
-		const defaultTA = valAnchor === 'start' ? 'start' : valAnchor === 'end' ? 'end' : 'middle';
-		const resolvedTextAnchor = font?.textAnchor === 'outside' ? undefined : font?.textAnchor;
-		const preferredTA = resolvedTextAnchor ?? defaultTA;
-		const rightFraction = preferredTA === 'start' ? 1 : preferredTA === 'end' ? 0 : 0.5;
-
-		const fontSize = typeof font?.fontSize === 'number' ? font.fontSize : 12;
-		const canvasFont = `${fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
-		const lineCfg = cfg.line.valueLabels;
-		const seriesCount = resolvedSeries.length;
-		const reach =
-			seriesCount > 1
-				? lineCfg.elbowGap + (seriesCount - 1) * lineCfg.laneStep + lineCfg.labelGap
-				: Math.abs(baseDx);
-
-		const pinnedDomain = scales.y?.domain;
-		let maxLabelWidth = 0;
-		if (pinnedDomain && pinnedDomain.length >= 2) {
-			const lo = Number(pinnedDomain[0]);
-			const hi = Number(pinnedDomain[pinnedDomain.length - 1]);
-			for (const s of resolvedSeries) {
-				maxLabelWidth = Math.max(
-					maxLabelWidth,
-					measureTextWidth(formatValue(lo, s.name), canvasFont),
-					measureTextWidth(formatValue(hi, s.name), canvasFont)
-				);
-			}
-		} else {
-			for (const s of resolvedSeries) {
-				const sy = resolveAccessor(s.y);
-				for (const d of s.data) {
-					const v = Number(sy(d));
-					if (Number.isNaN(v)) continue;
-					maxLabelWidth = Math.max(maxLabelWidth, measureTextWidth(formatValue(v, s.name), canvasFont));
-				}
-			}
-		}
-		// +2px: canvas text measurement and svelteplot's own rendered SVG text
-		// can disagree by a pixel or so (different rendering engines) — a small
-		// buffer that narrows, but doesn't eliminate, the gap noted above.
-		return { left: 0, right: Math.ceil(reach + rightFraction * maxLabelWidth) + 2, top: 0, bottom: 0 };
+		return estimateLineValueLabelMargin(resolvedSeries, {
+			valAnchor,
+			fontStyle: styles.values?.fontStyle,
+			formatValue,
+			yDomain: scales.y?.domain
+		});
 	});
 
+	// See `halfDimensionOverflowCap`'s own doc comment.
+	const maxLabelOverflow = $derived(halfDimensionOverflowCap(width, height));
+
 	// Grows the plot's margin to fit value labels that overflow the content
 	// box. `valueLabelFloor` covers the common rightward case up front; each
 	// label's own rendered overflow still feeds `labelMargin.report` for
@@ -258,7 +198,8 @@
 	const labelMargin = createLabelMarginTracker(
 		() => margins,
 		() => resolvedSeries,
-		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 }
+		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 },
+		() => maxLabelOverflow
 	);
 
 	// Writes the resolved margin back into the bindable `margins` prop once it

package/dist/plots/line/valueLabelMargin.d.ts

@@ -0,0 +1,27 @@
+import type { MarginOverflow } from '../utils/labelOverflow.svelte';
+import type { Series } from '../../types/plots/data/common';
+import type { FontStyle } from '../../types/plots/styling';
+import type { ValueAnchor } from '../../types/plots/constants';
+/**
+ * `LinePlot`'s own value-label margin estimate — stable across a timeline
+ * scrubber or a dataset change, since it's a fixed function of `series` and
+ * config, never DOM-measured (see `estimateValueLabelMargin`'s own doc
+ * comment). Used two ways: `LinePlot` itself calls this internally as its
+ * single-plot `valueLabelFloor`, and a faceted caller (e.g. `ChartPanel` in
+ * the consuming app) calls it per facet against that facet's own rows to
+ * build a shared `FacetConfig.marginsForFacet` — both get the exact same
+ * number for the exact same series, by construction, instead of the two call
+ * sites drifting apart with their own separate formulas.
+ *
+ * Only covers the common case: a rightward-fanning end-of-line label
+ * (`anchor: 'start'`, or any anchor whose resolved `dx` isn't negative) —
+ * see `LinePlot`'s own `valueLabelFloor` doc comment (unchanged) for why a
+ * leftward fan isn't covered here and is left to the DOM-measured fallback.
+ */
+export declare function estimateLineValueLabelMargin<TData extends Record<string, unknown>>(series: Series<TData>[], options?: {
+    valAnchor?: ValueAnchor;
+    fontStyle?: FontStyle;
+    formatValue?: (value: number, name: string) => string;
+    /** A pinned y domain (e.g. `scales.y.domain`), covering the whole range a timeline scrubber might reveal — see this function's own stability note above. Falls back to `series`'s own current values when omitted. */
+    yDomain?: readonly (number | string | boolean | Date | null)[];
+}): MarginOverflow | undefined;

package/dist/plots/line/valueLabelMargin.js

@@ -0,0 +1,61 @@
+import { resolveAccessor } from '../utils/accessors';
+import { getConfiguration } from '../../configuration/config.svelte';
+import { estimateValueLabelMargin, laneReachUpperBound } from '../utils/valueLabelMargin';
+/**
+ * `LinePlot`'s own value-label margin estimate — stable across a timeline
+ * scrubber or a dataset change, since it's a fixed function of `series` and
+ * config, never DOM-measured (see `estimateValueLabelMargin`'s own doc
+ * comment). Used two ways: `LinePlot` itself calls this internally as its
+ * single-plot `valueLabelFloor`, and a faceted caller (e.g. `ChartPanel` in
+ * the consuming app) calls it per facet against that facet's own rows to
+ * build a shared `FacetConfig.marginsForFacet` — both get the exact same
+ * number for the exact same series, by construction, instead of the two call
+ * sites drifting apart with their own separate formulas.
+ *
+ * Only covers the common case: a rightward-fanning end-of-line label
+ * (`anchor: 'start'`, or any anchor whose resolved `dx` isn't negative) —
+ * see `LinePlot`'s own `valueLabelFloor` doc comment (unchanged) for why a
+ * leftward fan isn't covered here and is left to the DOM-measured fallback.
+ */
+export function estimateLineValueLabelMargin(series, options = {}) {
+    const cfg = getConfiguration();
+    const valAnchor = options.valAnchor ?? 'start';
+    const formatValue = options.formatValue ?? ((v, name) => `${name} - ${v}`);
+    const font = options.fontStyle;
+    const defaultDx = valAnchor === 'start' ? 6 : valAnchor === 'end' ? -6 : 0;
+    const baseDx = typeof font?.dx === 'number' ? font.dx : defaultDx;
+    if ((Math.sign(baseDx) || 1) !== 1)
+        return undefined;
+    const defaultTA = valAnchor === 'start' ? 'start' : valAnchor === 'end' ? 'end' : 'middle';
+    const resolvedTextAnchor = font?.textAnchor === 'outside' ? undefined : font?.textAnchor;
+    const preferredTA = resolvedTextAnchor ?? defaultTA;
+    const rightFraction = preferredTA === 'start' ? 1 : preferredTA === 'end' ? 0 : 0.5;
+    const fontSize = typeof font?.fontSize === 'number' ? font.fontSize : 12;
+    const canvasFont = `${fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
+    const seriesCount = series.length;
+    const reach = seriesCount > 1 ? laneReachUpperBound(seriesCount, cfg.line.valueLabels) : Math.abs(baseDx);
+    const texts = [];
+    if (options.yDomain && options.yDomain.length >= 2) {
+        const lo = Number(options.yDomain[0]);
+        const hi = Number(options.yDomain[options.yDomain.length - 1]);
+        for (const s of series) {
+            texts.push(formatValue(lo, s.name), formatValue(hi, s.name));
+        }
+    }
+    else {
+        for (const s of series) {
+            const sy = resolveAccessor(s.y);
+            for (const d of s.data) {
+                const v = Number(sy(d));
+                if (Number.isNaN(v))
+                    continue;
+                texts.push(formatValue(v, s.name));
+            }
+        }
+    }
+    // +2px: canvas text measurement and svelteplot's own rendered SVG text
+    // can disagree by a pixel or so (different rendering engines) — a small
+    // buffer that narrows, but doesn't eliminate, the gap noted above.
+    const right = estimateValueLabelMargin(texts, { canvasFont, textFraction: rightFraction, reach }) + 2;
+    return { left: 0, right, top: 0, bottom: 0 };
+}

package/dist/plots/pyramid/Plot.svelte

@@ -6,8 +6,11 @@
 	import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
 	import { disabledFillOverride } from '../utils/legendDisabled';
 	import { buildPyramidBarMarkers } from './buildPyramidBarMarkers';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
-	import { measureTextWidth } from '../../layout/plot/measureText';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
+	import { estimateValueLabelMargin } from '../utils/valueLabelMargin';
 	import {
 		buildGroupedSeries,
 		validateSegments,
@@ -277,8 +280,8 @@
 		const canvasFont = `${fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
 		const offset = Math.abs(typeof font?.dx === 'number' ? font.dx : 6);
 
-		let leftWidth = 0;
-		let rightWidth = 0;
+		const leftTexts: string[] = [];
+		const rightTexts: string[] = [];
 		for (const s of resolvedSeries) {
 			const sy = resolveAccessor(s.y);
 			let extreme = 0;
@@ -292,13 +295,18 @@
 				}
 			}
 			if (extremeRow === undefined) continue;
-			const labelWidth = measureTextWidth(formatValue(extreme, s.name), canvasFont);
-			if (s.side === 'left') leftWidth = Math.max(leftWidth, labelWidth);
-			else rightWidth = Math.max(rightWidth, labelWidth);
+			const text = formatValue(extreme, s.name);
+			if (s.side === 'left') leftTexts.push(text);
+			else rightTexts.push(text);
 		}
-		return { left: Math.ceil(offset + leftWidth), right: Math.ceil(offset + rightWidth), top: 0, bottom: 0 };
+		const left = estimateValueLabelMargin(leftTexts, { canvasFont, reach: offset });
+		const right = estimateValueLabelMargin(rightTexts, { canvasFont, reach: offset });
+		return { left, right, top: 0, bottom: 0 };
 	});
 
+	// See `halfDimensionOverflowCap`'s own doc comment.
+	const maxLabelOverflow = $derived(halfDimensionOverflowCap(width, height));
+
 	// A pyramid bar's value label can grow past the plot's own content box —
 	// `valueLabelFloor` covers the common case up front; each label's own
 	// rendered overflow still feeds `labelMargin.report` for whatever that
@@ -306,7 +314,8 @@
 	const labelMargin = createLabelMarginTracker(
 		() => margins,
 		() => resolvedSeries,
-		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 }
+		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 },
+		() => maxLabelOverflow
 	);
 </script>
 

package/dist/plots/scatter/Plot.svelte

@@ -7,7 +7,10 @@
 	import { disabledDotsOverride } from '../utils/legendDisabled';
 	import { buildScatterMarkers } from './buildScatterMarkers';
 	import { resolveRadiusPaddedDomain } from './resolveRadiusPaddedDomain';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
 	import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
 	import ValueLabels from './ValueLabels.svelte';
 	import {
@@ -214,6 +217,11 @@
 		};
 	});
 
+	// See `halfDimensionOverflowCap`'s own doc comment — relevant here mainly
+	// for a corner point with no room in any direction even after
+	// `resolveEdgeAwareAnchor`'s own flip.
+	const maxLabelOverflow = $derived(halfDimensionOverflowCap(width, height));
+
 	// A scatter point's value label can grow past the plot's own content box
 	// (e.g. a point volcado toward a corner, past what its own edge-aware flip
 	// can fit) — reserving real space there is what each label's own overflow
@@ -223,7 +231,9 @@
 	// that frame is gone.
 	const labelMargin = createLabelMarginTracker(
 		() => margins,
-		() => resolvedSeries
+		() => resolvedSeries,
+		undefined,
+		() => maxLabelOverflow
 	);
 </script>
 

package/dist/plots/utils/categoricalAxisMargin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How much margin an axis needs to fit the widest of `labels` in the
+ * theme's own axis font, plus its tick size/padding — any plot's own margin
+ * whenever what sits along that axis is plain tick-label text: `BarPlot`'s
+ * left margin when its main dimension draws as a category axis, or any
+ * plot's numeric axis whose tick-label width can vary a lot (e.g. `"5"` vs
+ * `"500,000"`). Off-DOM (canvas) and synchronous, so it's correct from the
+ * very first render and stable across a timeline scrubber or dataset
+ * change, the same way `estimateValueLabelMargin` is for value labels.
+ * Exported for a faceted caller (e.g. `ChartPanel` in the consuming app) to
+ * call per facet against that facet's own labels, building a shared
+ * `FacetConfig.marginsForFacet`.
+ */
+export declare function estimateCategoricalAxisMargin(labels: string[]): number;

package/dist/plots/utils/categoricalAxisMargin.js

@@ -0,0 +1,20 @@
+import { getConfiguration } from '../../configuration/config.svelte';
+import { measureMaxLabelWidth } from '../../layout/plot/measureText';
+/**
+ * How much margin an axis needs to fit the widest of `labels` in the
+ * theme's own axis font, plus its tick size/padding — any plot's own margin
+ * whenever what sits along that axis is plain tick-label text: `BarPlot`'s
+ * left margin when its main dimension draws as a category axis, or any
+ * plot's numeric axis whose tick-label width can vary a lot (e.g. `"5"` vs
+ * `"500,000"`). Off-DOM (canvas) and synchronous, so it's correct from the
+ * very first render and stable across a timeline scrubber or dataset
+ * change, the same way `estimateValueLabelMargin` is for value labels.
+ * Exported for a faceted caller (e.g. `ChartPanel` in the consuming app) to
+ * call per facet against that facet's own labels, building a shared
+ * `FacetConfig.marginsForFacet`.
+ */
+export function estimateCategoricalAxisMargin(labels) {
+    const cfg = getConfiguration();
+    const axisFont = `${cfg.axis.fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
+    return (Math.ceil(measureMaxLabelWidth(labels, axisFont)) + cfg.axis.yTickSize + cfg.axis.yTickPadding);
+}

package/dist/plots/utils/labelOverflow.svelte.d.ts

@@ -6,6 +6,16 @@ export type MarginOverflow = {
     top: number;
     bottom: number;
 };
+/**
+ * A generic `maxOverflow` cap for {@link createLabelMarginTracker}: half of
+ * each dimension, so a facet cramped enough that its own value label can
+ * never fully fit still leaves the plot's own content box the other half,
+ * rather than `measured` growing without bound (see that function's own
+ * `maxOverflow` doc comment). The same backstop applies regardless of *what*
+ * overflows or *why* — every value-label-drawing plot (line/bar/pyramid/
+ * scatter) passes this, sized off its own `width`/`height`.
+ */
+export declare function halfDimensionOverflowCap(width: number, height: number): MarginOverflow;
 /**
  * Watches an SVG group's rendered bounding box against the plot's own
  * content box (`bounds`) and reports how far it overflows on each side.
@@ -66,7 +76,18 @@ export declare function createLabelMarginTracker(margins: () => MarginConfig | u
  * every reset). DOM measurement can still grow past it for whatever this
  * estimate doesn't cover.
  */
-floor?: () => MarginOverflow): {
+floor?: () => MarginOverflow, 
+/**
+ * Ceiling on how far `measured` can grow on each side, independent of
+ * `floor`. Without one, a cell too small to ever fully fit its own label
+ * (e.g. a narrow facet) keeps reporting overflow after every growth-
+ * triggered remount — since the label's absolute size never shrinks —
+ * and `measured` grows without bound, eventually leaving nothing for the
+ * plot's own content box. Capping it trades a permanently-clipped label
+ * in that case for a plot that still renders. Pass `Infinity` on a side
+ * (the default) to leave it uncapped.
+ */
+maxOverflow?: () => MarginOverflow): {
     report: (overflow: MarginOverflow) => void;
     readonly resolvedMargins: Partial<{
         top: number | "auto";

package/dist/plots/utils/labelOverflow.svelte.js

@@ -1,5 +1,22 @@
 import { AUTO_MARGIN_ESTIMATE } from '../../layout/plot/margins';
 const NO_OVERFLOW = { left: 0, right: 0, top: 0, bottom: 0 };
+/**
+ * A generic `maxOverflow` cap for {@link createLabelMarginTracker}: half of
+ * each dimension, so a facet cramped enough that its own value label can
+ * never fully fit still leaves the plot's own content box the other half,
+ * rather than `measured` growing without bound (see that function's own
+ * `maxOverflow` doc comment). The same backstop applies regardless of *what*
+ * overflows or *why* — every value-label-drawing plot (line/bar/pyramid/
+ * scatter) passes this, sized off its own `width`/`height`.
+ */
+export function halfDimensionOverflowCap(width, height) {
+    return {
+        left: Math.max(0, width * 0.5),
+        right: Math.max(0, width * 0.5),
+        top: Math.max(0, height * 0.5),
+        bottom: Math.max(0, height * 0.5)
+    };
+}
 /**
  * Watches an SVG group's rendered bounding box against the plot's own
  * content box (`bounds`) and reports how far it overflows on each side.
@@ -114,7 +131,18 @@ export function createLabelMarginTracker(margins, resetKey,
  * every reset). DOM measurement can still grow past it for whatever this
  * estimate doesn't cover.
  */
-floor) {
+floor, 
+/**
+ * Ceiling on how far `measured` can grow on each side, independent of
+ * `floor`. Without one, a cell too small to ever fully fit its own label
+ * (e.g. a narrow facet) keeps reporting overflow after every growth-
+ * triggered remount — since the label's absolute size never shrinks —
+ * and `measured` grows without bound, eventually leaving nothing for the
+ * plot's own content box. Capping it trades a permanently-clipped label
+ * in that case for a plot that still renders. Pass `Infinity` on a side
+ * (the default) to leave it uncapped.
+ */
+maxOverflow) {
     const floorValue = () => floor?.() ?? NO_OVERFLOW;
     let measured = $state(floorValue());
     // Skips the reset on the very first run (there's nothing to reset yet,
@@ -134,6 +162,17 @@ floor) {
             measured = floorValue();
         }
     });
+    // Pure `Math.max` — no `maxOverflow` cap here. `measured` is a *tracked*
+    // value, not the applied margin, and must stay strictly monotonic
+    // regardless of anything else changing (see this function's own doc
+    // comment on why shrinking it back oscillates). `maxOverflow` is
+    // typically sized off the plot's own live `width`/`height` (see
+    // `halfDimensionOverflowCap`), which moves continuously during a resize
+    // — capping *here* would let a shrinking cap force `measured` down mid-
+    // resize, immediately re-exposing the overflow that grew it in the first
+    // place and re-triggering growth, over and over, fast enough to trip
+    // Svelte's `effect_update_depth_exceeded` guard. The cap is applied only
+    // where it can't feed back into `measured` itself — see `resolvedMargins`.
     function report(overflow) {
         const next = {
             left: Math.max(measured.left, overflow.left),
@@ -156,33 +195,55 @@ floor) {
     // number that only accounts for the value label. `AUTO_MARGIN_ESTIMATE` is
     // a fixed constant, not `numericMargins`' own already-grown value, so this
     // can't compound into unbounded growth across repeated reports.
+    //
+    // `maxOverflow`, if given, clamps `measured` down to a live cap *here*,
+    // read-only — every render re-reads the current cap and applies it fresh
+    // to the unclamped, monotonically-tracked `measured`, without ever
+    // writing the clamped value back into `measured` itself (see `report`'s
+    // own doc comment for why that distinction matters).
     const resolvedMargins = $derived.by(() => {
         const base = margins();
-        if (measured.left <= 0 && measured.right <= 0 && measured.top <= 0 && measured.bottom <= 0)
+        const cap = maxOverflow?.() ?? {
+            left: Infinity,
+            right: Infinity,
+            top: Infinity,
+            bottom: Infinity
+        };
+        const clamped = {
+            left: Math.min(measured.left, cap.left),
+            right: Math.min(measured.right, cap.right),
+            top: Math.min(measured.top, cap.top),
+            bottom: Math.min(measured.bottom, cap.bottom)
+        };
+        if (clamped.left <= 0 && clamped.right <= 0 && clamped.top <= 0 && clamped.bottom <= 0)
             return base;
         const out = { ...base };
-        if (measured.right > 0 && base?.right === undefined)
-            out.right = AUTO_MARGIN_ESTIMATE.right + measured.right;
-        if (measured.left > 0 && base?.left === undefined)
-            out.left = AUTO_MARGIN_ESTIMATE.left + measured.left;
-        if (measured.top > 0 && base?.top === undefined)
-            out.top = AUTO_MARGIN_ESTIMATE.top + measured.top;
-        if (measured.bottom > 0 && base?.bottom === undefined)
-            out.bottom = AUTO_MARGIN_ESTIMATE.bottom + measured.bottom;
+        if (clamped.right > 0 && base?.right === undefined)
+            out.right = AUTO_MARGIN_ESTIMATE.right + clamped.right;
+        if (clamped.left > 0 && base?.left === undefined)
+            out.left = AUTO_MARGIN_ESTIMATE.left + clamped.left;
+        if (clamped.top > 0 && base?.top === undefined)
+            out.top = AUTO_MARGIN_ESTIMATE.top + clamped.top;
+        if (clamped.bottom > 0 && base?.bottom === undefined)
+            out.bottom = AUTO_MARGIN_ESTIMATE.bottom + clamped.bottom;
         return out;
     });
     // Bundles `resolvedMargins` with a remount key, ready to spread straight
     // onto `<BasePlotLayout>` as its `margins`/`marginRemountKey` props (see
     // that prop's doc comment for *why* a remount key is needed here at all)
-    // — keeps the caller from re-deriving the same key by hand. Tracks both
-    // `measured` (this tracker's own auto-grown overflow) and the caller's
-    // own `margins()` — a caller that changes its explicit margins prop
-    // after mount (e.g. locking in a previously-measured value) needs that
-    // picked up just as cleanly as internal growth does; keying only on
-    // `measured` would silently miss it.
+    // — keeps the caller from re-deriving the same key by hand. Keyed off
+    // `resolvedMargins` itself (the actually-applied value) rather than raw
+    // `measured` — with a `maxOverflow` cap in play, `measured` can keep
+    // climbing past the point where it's clamped without the applied margin
+    // changing at all, and remounting for that would be pure waste. Also
+    // tracks the caller's own `margins()` — a caller that changes its
+    // explicit margins prop after mount (e.g. locking in a previously-
+    // measured value) needs that picked up just as cleanly as internal
+    // growth does; `resolvedMargins` alone already reflects that too, but
+    // spelling it out keeps the key's intent obvious.
     const plotProps = $derived.by(() => ({
         margins: resolvedMargins,
-        marginRemountKey: JSON.stringify({ base: margins(), measured })
+        marginRemountKey: JSON.stringify({ base: margins(), resolvedMargins })
     }));
     return {
         report,

package/dist/plots/utils/valueLabelMargin.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The one calculation every value-label-drawing plot (`LinePlot`, `BarPlot`,
+ * `PyramidPlot`, …) needs to reserve margin for its own value labels ahead of
+ * time, stable across a timeline scrubber or a dataset change: measure the
+ * widest candidate label (already off-DOM/canvas via `measureMaxLabelWidth`,
+ * so this is synchronous and exact, not an approximation needing a later
+ * DOM-measured correction), then add a fixed `reach` — whatever fixed gap
+ * sits between the anchor point and where the text itself starts, which
+ * differs per plot (a bar/pyramid's anchor offset; a line's elbow-routed
+ * lane geometry, see `laneReachUpperBound`).
+ *
+ * `texts` is the plot's own candidate list (its own concern — which values
+ * count as "the widest this could ever need to be", e.g. every row's value
+ * vs. just a pinned domain's extremes) — this function only measures and
+ * combines, it never decides which labels matter.
+ */
+export declare function estimateValueLabelMargin(texts: string[], options: {
+    /** Canvas font shorthand, e.g. `"12px sans-serif"`, matching the labels' own rendered font. */
+    canvasFont: string;
+    /**
+     * Fraction of the widest label's own width that extends toward the
+     * margin being reserved — `1` (the default) for a label anchored so
+     * its whole width reaches outward (`textAnchor: 'start'`), `0.5` for
+     * one centered on its anchor (`'middle'`), `0` for one anchored back
+     * over the plot's own content (no text-width contribution, though
+     * `reach` can still apply).
+     */
+    textFraction?: number;
+    /**
+     * Fixed gap (px) between the anchor point and the start of the label
+     * text — always reserved, even when `texts` is empty, matching every
+     * caller's existing behaviour of never collapsing to zero margin
+     * outright (a plot with no value-label-bearing data yet still keeps
+     * whatever fixed offset its style config asks for).
+     */
+    reach?: number;
+}): number;
+/**
+ * Upper bound on how far `LinePlot`'s end-of-line labels can ever fan out
+ * into lanes (see `plots/utils/declutter.ts`'s `laneAssignment`): a run of
+ * colliding labels never uses more lanes than it has members, and a run can
+ * never have more members than there are series total — so `elbowGap +
+ * (seriesCount - 1) * laneStep + labelGap` is always >= the real, rendered
+ * reach, for *any* arrangement `declutter1D`/`laneAssignment` could ever
+ * produce. That's what makes it safe to use as a stable floor: it doesn't
+ * depend on which series happen to collide on the current frame (which can
+ * change tick to tick as a timeline scrubs), only on how many series exist —
+ * so the margin it implies never needs to change across a scrub either.
+ */
+export declare function laneReachUpperBound(seriesCount: number, cfg: {
+    elbowGap: number;
+    laneStep: number;
+    labelGap: number;
+}): number;

package/dist/plots/utils/valueLabelMargin.js

@@ -0,0 +1,40 @@
+import { measureMaxLabelWidth } from '../../layout/plot/measureText';
+/**
+ * The one calculation every value-label-drawing plot (`LinePlot`, `BarPlot`,
+ * `PyramidPlot`, …) needs to reserve margin for its own value labels ahead of
+ * time, stable across a timeline scrubber or a dataset change: measure the
+ * widest candidate label (already off-DOM/canvas via `measureMaxLabelWidth`,
+ * so this is synchronous and exact, not an approximation needing a later
+ * DOM-measured correction), then add a fixed `reach` — whatever fixed gap
+ * sits between the anchor point and where the text itself starts, which
+ * differs per plot (a bar/pyramid's anchor offset; a line's elbow-routed
+ * lane geometry, see `laneReachUpperBound`).
+ *
+ * `texts` is the plot's own candidate list (its own concern — which values
+ * count as "the widest this could ever need to be", e.g. every row's value
+ * vs. just a pinned domain's extremes) — this function only measures and
+ * combines, it never decides which labels matter.
+ */
+export function estimateValueLabelMargin(texts, options) {
+    const maxWidth = measureMaxLabelWidth(texts, options.canvasFont);
+    const textFraction = options.textFraction ?? 1;
+    const reach = options.reach ?? 0;
+    return Math.ceil(reach + textFraction * maxWidth);
+}
+/**
+ * Upper bound on how far `LinePlot`'s end-of-line labels can ever fan out
+ * into lanes (see `plots/utils/declutter.ts`'s `laneAssignment`): a run of
+ * colliding labels never uses more lanes than it has members, and a run can
+ * never have more members than there are series total — so `elbowGap +
+ * (seriesCount - 1) * laneStep + labelGap` is always >= the real, rendered
+ * reach, for *any* arrangement `declutter1D`/`laneAssignment` could ever
+ * produce. That's what makes it safe to use as a stable floor: it doesn't
+ * depend on which series happen to collide on the current frame (which can
+ * change tick to tick as a timeline scrubs), only on how many series exist —
+ * so the margin it implies never needs to change across a scrub either.
+ */
+export function laneReachUpperBound(seriesCount, cfg) {
+    if (seriesCount <= 1)
+        return 0;
+    return cfg.elbowGap + (seriesCount - 1) * cfg.laneStep + cfg.labelGap;
+}

package/dist/types/charts/common.d.ts

@@ -14,7 +14,7 @@ export type ChartPlotContext<TRow extends Record<string, unknown>> = {
     facetValue?: string;
     selectedValue?: TimeValue;
     legend?: LegendPlotContext;
-    /** Present only when faceted with `facet.labelsForMargin` — forward to the plot's own `margins` prop so every facet shares the same content box. */
+    /** Present only when faceted with `facet.marginsForFacet` — forward to the plot's own `margins` prop so every facet shares the same content box. */
     margins?: MarginConfig;
 };
 export type ChartPlotSnippet<TRow extends Record<string, unknown>> = Snippet<[

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

@@ -13,7 +13,7 @@ export type FacetCellContext<TRow extends Record<string, unknown>> = {
     data: TRow[];
     width: number;
     height: number;
-    /** Left margin sized to the widest label across every facet — see `labelsForMargin`. Present only when it's given. */
+    /** Margin sized off every facet's own natural need, per side — see `marginsForFacet`. Present only when it's given. */
     margins?: MarginConfig;
 };
 export type FacetCellSnippet<TRow extends Record<string, unknown>> = Snippet<[
@@ -43,6 +43,23 @@ export type FacetConfig<TRow extends Record<string, unknown>> = {
     formatIndicator?: (current: number, total: number) => string;
     indicator?: FacetIndicatorSnippet;
     navButton?: FacetNavSnippet;
-    /** Candidate label strings for one facet's own rows — measured across every facet to size a shared left margin (`cell`'s own `margins`). */
-    labelsForMargin?: (rows: TRow[]) => string[];
+    /**
+     * One facet's own natural margin need, per side — measured across every
+     * facet and combined with `Math.max` per side (`FacetLayout`'s own
+     * `cellMargins`) to size one shared margin every facet's `cell` receives
+     * through its own `margins`, instead of each facet growing its own margin
+     * independently off what its own content happens to need (which drifts
+     * out of alignment facet to facet, and — for a facet cramped enough that
+     * its content can never fully fit — can grow without bound). A plot type
+     * that draws content needing this (a categorical axis's labels, a value
+     * label's own text) implements this by calling its own margin-estimating
+     * export against the facet's rows — e.g. `BarPlot`'s left margin from its
+     * category labels, `LinePlot`'s right margin from its end-of-line value
+     * labels (see each plot's own docs for what its estimator assumes, such as
+     * `LinePlot`'s one-line-per-facet caveat) — this callback only carries
+     * that per-facet result up to where every facet's results can be compared.
+     * Any side left unset by every facet stays unpinned, falling back to the
+     * plot's own default (`'auto'`) sizing.
+     */
+    marginsForFacet?: (rows: TRow[]) => MarginConfig;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "type": "module",
   "files": [
     "dist"