@fundar/data-chart-telling 0.0.39 → 0.0.41

package/dist/plots/scatter/Plot.svelte

@@ -1,247 +1,271 @@
-<script
-  lang="ts"
-  generics="TData extends Record<string, unknown>"
->
-  import { resolveAccessor } from '../utils/accessors';
-  import { getConfiguration } from '../../configuration/config.svelte';
-  import { paletteColor } from '../../utils/color';
-  import { buildSeries } from '../../utils/grouping';
-  import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
-  import { disabledDotsOverride } from '../utils/legendDisabled';
-  import { buildScatterMarkers } from './buildScatterMarkers';
-  import { resolveRadiusPaddedDomain } from './resolveRadiusPaddedDomain';
-  import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
-  import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
-  import ValueLabels from './ValueLabels.svelte';
-  import { hasHoverMarker, resolveHoverStrategy, resolveHoverSync } from '../../layout/tooltip/utils';
-  import { buildGroupedSeries, validateSegments, buildScopedMarkerGroups } from '../utils/segments';
-  import { numericMargin } from '../../layout/plot/margins';
-  import type { BasePlotProps } from '../../types/plots/props';
-  import type { AxisValue, AxisBasedScalesConfig } from '../../types/layout/scales';
-  import type { Series } from '../../types/plots/data/common';
-  import type { ScatterDataProps } from '../../types/plots/data/scatter';
-  import type { AxisBasedStylesConfig } from '../../types/layout/styles';
-  import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
-  import type { AxisBasedMarkersConfig } from '../../types/markers/common';
-  import type { LegendDisabledStyle } from '../../types/layout/legend';
-
-  /**
-   * A point cloud on continuous x/y axes. Accepts either a pre-built `series`
-   * array or flat `data/x/y/z` props — mirrors the line/bar plot contract so
-   * the chart-level container/timeline/facet/legend wrap it unchanged. `r`
-   * gives every dot a per-row radius (bubble sizing), independent of `z`
-   * grouping/coloring — see {@link ScatterDataProps} for its auto-scaling
-   * behavior.
-   */
-  type Props = BasePlotProps<
-    ScatterDataProps<TData>,
-    TData,
-    AxisBasedStylesConfig,
-    ScatterSegmentStyle,
-    AxisBasedMarkersConfig,
-    AxisBasedScalesConfig<TData>
-  >;
-
-  let {
-    width,
-    height,
-    series,
-    data,
-    x,
-    y,
-    z,
-    r,
-    styles = {},
-    segments = {},
-    markers = [],
-    scales = {},
-    margins,
-    tooltip = undefined,
-  }: Props = $props();
-
-  const resolvedSeries = $derived(series ?? buildSeries(data!, x!, y!, z));
-  const legendInteraction = $derived(getLegendInteraction());
-
-  $effect(() => { validateSegments(segments); });
-
-  // A scatter point cloud is discrete (no connecting line), so adjacent
-  // segments never need a bridge point at their boundary — see
-  // buildGroupedSeries's own doc.
-  const groupedSeries = $derived(
-    buildGroupedSeries<Series<TData>, ScatterSegmentStyle>(resolvedSeries, segments, false),
-  );
-
-  const cfg = $derived(getConfiguration());
-  const showVals = $derived(styles.values?.show ?? false);
-  const formatValue = $derived(styles.values?.format ?? ((v: number) => `${v}`));
-  const hoverIsolate = $derived(styles.values?.hoverIsolate ?? false);
-
-  // A value label hovered while `styles.values.hoverIsolate` is on dims
-  // every other series exactly like a legend toggle would — local to this
-  // one `<Plot>` instance (not the shared HoverStore) so the gesture can't
-  // leak into unrelated tooltip/crosshair behavior.
-  let hoverIsolatedSeries = $state<string | null>(null);
-
-  function effectiveDisabledFor(name: string): LegendDisabledStyle | undefined {
-    return (
-      legendInteraction?.disabledSeries.get(name) ??
-      (hoverIsolate && hoverIsolatedSeries && hoverIsolatedSeries !== name
-        ? { opacity: cfg.legend.disabledOpacity }
-        : undefined)
-    );
-  }
-
-  const xAcc = $derived(resolveAccessor(resolvedSeries[0]?.x ?? ((d: TData) => d)));
-  const yAcc = $derived(resolveAccessor(resolvedSeries[0]?.y ?? ((d: TData) => d)));
-  const flat = $derived(resolvedSeries.flatMap((s) => s.data));
-
-  // A legend-disabled series is dimmed on the mark itself, but never surfaces
-  // in hover/tooltip — its points are simply absent from the candidate list.
-  const hoverPoints = $derived(
-    resolvedSeries.flatMap((s, idx) => {
-      if (legendInteraction?.disabledSeries.has(s.name)) return [];
-      const sx = resolveAccessor(s.x);
-      const sy = resolveAccessor(s.y);
-      return s.data.map((d) => ({
-        x: sx(d) as AxisValue,
-        y: Number(sy(d)),
-        row: d,
-        label: `${sx(d)}, ${sy(d)}`,
-        series: s.name,
-        color: paletteColor(idx, cfg.palette),
-      }));
-    }),
-  );
-
-  // Points scatter freely across x/y rather than sharing discrete x values —
-  // 'punctual' matches the single nearest point, not a whole column.
-  const hover = $derived({
-    active: tooltip != null || hasHoverMarker(markers),
-    points: hoverPoints,
-    label: (row: TData) => `${xAcc(row)}, ${yAcc(row)}`,
-    strategy: resolveHoverStrategy(tooltip?.strategy, markers, 'punctual'),
-    sync: resolveHoverSync(tooltip?.sync, markers),
-    tooltip,
-  });
-
-  const scatterMarkers = $derived(
-    buildScatterMarkers({
-      groupedSeries,
-      r,
-      disabledDotsFor: (name) => disabledDotsOverride(effectiveDisabledFor(name)),
-    }),
-  );
-
-  const scopedGroups = $derived(
-    buildScopedMarkerGroups<TData, Series<TData>, ScatterSegmentStyle>({
-      groupedSeries,
-      segments,
-      colorFor: (_series, seriesIndex) => paletteColor(seriesIndex, cfg.palette),
-      segmentColorFor: (style, defaultColor) => style?.dotFill ?? defaultColor,
-    }),
-  );
-
-  // svelteplot treats a per-row `r` (a field key or accessor function) as a
-  // proper channel bound to its own auto sqrt scale — the raw values it
-  // returns (e.g. a population in the millions) are data, not pixels, and
-  // get compressed into a modest, roughly data-magnitude-independent pixel
-  // range regardless of how large the raw numbers are. A literal constant
-  // `r` (or the theme/segment `dotRadius` fallback), by contrast, *is*
-  // already a literal pixel value. `AUTO_SCALED_RADIUS_ESTIMATE` stands in
-  // for whatever svelteplot's own r-scale ends up rendering at, since the
-  // real value isn't knowable until that scale is built.
-  const AUTO_SCALED_RADIUS_ESTIMATE = 20;
-
-  // The largest radius any dot actually renders at — pads the scale domain
-  // below so a point at the data extreme doesn't get its own circle clipped
-  // by the frame. svelteplot's own 'auto' margin only measures axis chrome,
-  // never mark geometry.
-  const maxDotRadius = $derived.by(() => {
-    let max = 0;
-    for (const marker of scatterMarkers) {
-      const rConst = typeof marker.r === 'number' ? marker.r : undefined;
-      const isChannel = typeof marker.r === 'function';
-      const fallbackR = marker.style?.dotRadius ?? cfg.scatter.dotRadius;
-      if (rConst !== undefined) {
-        max = Math.max(max, rConst);
-      } else if (isChannel) {
-        max = Math.max(max, AUTO_SCALED_RADIUS_ESTIMATE);
-      } else {
-        max = Math.max(max, fallbackR);
-      }
-    }
-    return max;
-  });
-
-  // Best-effort pre-render estimate of the plot's own inner content size —
-  // the real size isn't known until svelteplot measures its own axis
-  // chrome, so this is only used to convert a pixel radius into a domain
-  // padding amount, not as the actual rendered margin.
-  const estimatedMargins = $derived({ ...cfg.margins, ...margins });
-  const estimatedInnerWidth = $derived(
-    width - numericMargin('left', estimatedMargins.left) - numericMargin('right', estimatedMargins.right),
-  );
-  const estimatedInnerHeight = $derived(
-    height - numericMargin('top', estimatedMargins.top) - numericMargin('bottom', estimatedMargins.bottom),
-  );
-
-  const resolvedScales = $derived.by((): AxisBasedScalesConfig<TData> => {
-    if (maxDotRadius <= 0) return scales;
-    const xValues = flat.map((d) => Number(xAcc(d)));
-    const yValues = flat.map((d) => Number(yAcc(d)));
-    const paddedX = scales.x?.domain
-      ? undefined
-      : resolveRadiusPaddedDomain(xValues, maxDotRadius, estimatedInnerWidth);
-    const paddedY = scales.y?.domain
-      ? undefined
-      : resolveRadiusPaddedDomain(yValues, maxDotRadius, estimatedInnerHeight);
-    if (!paddedX && !paddedY) return scales;
-    return {
-      ...scales,
-      x: paddedX ? { ...scales.x, domain: paddedX } : scales.x,
-      y: paddedY ? { ...scales.y, domain: paddedY } : scales.y,
-    };
-  });
-
-  // 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
-  // measurement feeds into here, via a tracker local to this one `<Plot>`
-  // instance. See `labelOverflow.svelte.ts`.
-  const labelMargin = createLabelMarginTracker(() => margins);
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import { resolveAccessor } from '../utils/accessors';
+	import { getConfiguration } from '../../configuration/config.svelte';
+	import { paletteColor } from '../../utils/color';
+	import { buildSeries } from '../../utils/grouping';
+	import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
+	import { disabledDotsOverride } from '../utils/legendDisabled';
+	import { buildScatterMarkers } from './buildScatterMarkers';
+	import { resolveRadiusPaddedDomain } from './resolveRadiusPaddedDomain';
+	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
+	import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
+	import ValueLabels from './ValueLabels.svelte';
+	import {
+		hasHoverMarker,
+		resolveHoverStrategy,
+		resolveHoverSync
+	} from '../../layout/tooltip/utils';
+	import {
+		buildGroupedSeries,
+		validateSegments,
+		buildScopedMarkerGroups
+	} from '../utils/segments';
+	import { numericMargin } from '../../layout/plot/margins';
+	import type { BasePlotProps } from '../../types/plots/props';
+	import type { AxisValue, AxisBasedScalesConfig } from '../../types/layout/scales';
+	import type { Series } from '../../types/plots/data/common';
+	import type { ScatterDataProps } from '../../types/plots/data/scatter';
+	import type { AxisBasedStylesConfig } from '../../types/layout/styles';
+	import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
+	import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+	import type { LegendDisabledStyle } from '../../types/layout/legend';
+
+	/**
+	 * A point cloud on continuous x/y axes. Accepts either a pre-built `series`
+	 * array or flat `data/x/y/z` props — mirrors the line/bar plot contract so
+	 * the chart-level container/timeline/facet/legend wrap it unchanged. `r`
+	 * gives every dot a per-row radius (bubble sizing), independent of `z`
+	 * grouping/coloring — see {@link ScatterDataProps} for its auto-scaling
+	 * behavior.
+	 */
+	type Props = BasePlotProps<
+		ScatterDataProps<TData>,
+		TData,
+		AxisBasedStylesConfig,
+		ScatterSegmentStyle,
+		AxisBasedMarkersConfig,
+		AxisBasedScalesConfig<TData>
+	>;
+
+	let {
+		width,
+		height,
+		series,
+		data,
+		x,
+		y,
+		z,
+		r,
+		styles = {},
+		segments = {},
+		markers = [],
+		scales = {},
+		margins,
+		tooltip = undefined
+	}: Props = $props();
+
+	const resolvedSeries = $derived(series ?? buildSeries(data!, x!, y!, z));
+	const legendInteraction = $derived(getLegendInteraction());
+
+	$effect(() => {
+		validateSegments(segments);
+	});
+
+	// A scatter point cloud is discrete (no connecting line), so adjacent
+	// segments never need a bridge point at their boundary — see
+	// buildGroupedSeries's own doc.
+	const groupedSeries = $derived(
+		buildGroupedSeries<Series<TData>, ScatterSegmentStyle>(resolvedSeries, segments, false)
+	);
+
+	const cfg = $derived(getConfiguration());
+	const showVals = $derived(styles.values?.show ?? false);
+	const formatValue = $derived(styles.values?.format ?? ((v: number) => `${v}`));
+	const hoverIsolate = $derived(styles.values?.hoverIsolate ?? false);
+
+	// A value label hovered while `styles.values.hoverIsolate` is on dims
+	// every other series exactly like a legend toggle would — local to this
+	// one `<Plot>` instance (not the shared HoverStore) so the gesture can't
+	// leak into unrelated tooltip/crosshair behavior.
+	let hoverIsolatedSeries = $state<string | null>(null);
+
+	function effectiveDisabledFor(name: string): LegendDisabledStyle | undefined {
+		return (
+			legendInteraction?.disabledSeries.get(name) ??
+			(hoverIsolate && hoverIsolatedSeries && hoverIsolatedSeries !== name
+				? { opacity: cfg.legend.disabledOpacity }
+				: undefined)
+		);
+	}
+
+	const xAcc = $derived(resolveAccessor(resolvedSeries[0]?.x ?? ((d: TData) => d)));
+	const yAcc = $derived(resolveAccessor(resolvedSeries[0]?.y ?? ((d: TData) => d)));
+	const flat = $derived(resolvedSeries.flatMap((s) => s.data));
+
+	// A legend-disabled series is dimmed on the mark itself, but never surfaces
+	// in hover/tooltip — its points are simply absent from the candidate list.
+	const hoverPoints = $derived(
+		resolvedSeries.flatMap((s, idx) => {
+			if (legendInteraction?.disabledSeries.has(s.name)) return [];
+			const sx = resolveAccessor(s.x);
+			const sy = resolveAccessor(s.y);
+			return s.data.map((d) => ({
+				x: sx(d) as AxisValue,
+				y: Number(sy(d)),
+				row: d,
+				label: `${sx(d)}, ${sy(d)}`,
+				series: s.name,
+				color: paletteColor(idx, cfg.palette)
+			}));
+		})
+	);
+
+	// Points scatter freely across x/y rather than sharing discrete x values —
+	// 'punctual' matches the single nearest point, not a whole column.
+	const hover = $derived({
+		active: tooltip != null || hasHoverMarker(markers),
+		points: hoverPoints,
+		label: (row: TData) => `${xAcc(row)}, ${yAcc(row)}`,
+		strategy: resolveHoverStrategy(tooltip?.strategy, markers, 'punctual'),
+		sync: resolveHoverSync(tooltip?.sync, markers),
+		tooltip
+	});
+
+	const scatterMarkers = $derived(
+		buildScatterMarkers({
+			groupedSeries,
+			r,
+			disabledDotsFor: (name) => disabledDotsOverride(effectiveDisabledFor(name))
+		})
+	);
+
+	const scopedGroups = $derived(
+		buildScopedMarkerGroups<TData, Series<TData>, ScatterSegmentStyle>({
+			groupedSeries,
+			segments,
+			colorFor: (_series, seriesIndex) => paletteColor(seriesIndex, cfg.palette),
+			segmentColorFor: (style, defaultColor) => style?.dotFill ?? defaultColor
+		})
+	);
+
+	// svelteplot treats a per-row `r` (a field key or accessor function) as a
+	// proper channel bound to its own auto sqrt scale — the raw values it
+	// returns (e.g. a population in the millions) are data, not pixels, and
+	// get compressed into a modest, roughly data-magnitude-independent pixel
+	// range regardless of how large the raw numbers are. A literal constant
+	// `r` (or the theme/segment `dotRadius` fallback), by contrast, *is*
+	// already a literal pixel value. `AUTO_SCALED_RADIUS_ESTIMATE` stands in
+	// for whatever svelteplot's own r-scale ends up rendering at, since the
+	// real value isn't knowable until that scale is built.
+	const AUTO_SCALED_RADIUS_ESTIMATE = 20;
+
+	// The largest radius any dot actually renders at — pads the scale domain
+	// below so a point at the data extreme doesn't get its own circle clipped
+	// by the frame. svelteplot's own 'auto' margin only measures axis chrome,
+	// never mark geometry.
+	const maxDotRadius = $derived.by(() => {
+		let max = 0;
+		for (const marker of scatterMarkers) {
+			const rConst = typeof marker.r === 'number' ? marker.r : undefined;
+			const isChannel = typeof marker.r === 'function';
+			const fallbackR = marker.style?.dotRadius ?? cfg.scatter.dotRadius;
+			if (rConst !== undefined) {
+				max = Math.max(max, rConst);
+			} else if (isChannel) {
+				max = Math.max(max, AUTO_SCALED_RADIUS_ESTIMATE);
+			} else {
+				max = Math.max(max, fallbackR);
+			}
+		}
+		return max;
+	});
+
+	// Best-effort pre-render estimate of the plot's own inner content size —
+	// the real size isn't known until svelteplot measures its own axis
+	// chrome, so this is only used to convert a pixel radius into a domain
+	// padding amount, not as the actual rendered margin.
+	const estimatedMargins = $derived({ ...cfg.margins, ...margins });
+	const estimatedInnerWidth = $derived(
+		width -
+			numericMargin('left', estimatedMargins.left) -
+			numericMargin('right', estimatedMargins.right)
+	);
+	const estimatedInnerHeight = $derived(
+		height -
+			numericMargin('top', estimatedMargins.top) -
+			numericMargin('bottom', estimatedMargins.bottom)
+	);
+
+	const resolvedScales = $derived.by((): AxisBasedScalesConfig<TData> => {
+		if (maxDotRadius <= 0) return scales;
+		const xValues = flat.map((d) => Number(xAcc(d)));
+		const yValues = flat.map((d) => Number(yAcc(d)));
+		const paddedX = scales.x?.domain
+			? undefined
+			: resolveRadiusPaddedDomain(xValues, maxDotRadius, estimatedInnerWidth);
+		const paddedY = scales.y?.domain
+			? undefined
+			: resolveRadiusPaddedDomain(yValues, maxDotRadius, estimatedInnerHeight);
+		if (!paddedX && !paddedY) return scales;
+		return {
+			...scales,
+			x: paddedX ? { ...scales.x, domain: paddedX } : scales.x,
+			y: paddedY ? { ...scales.y, domain: paddedY } : scales.y
+		};
+	});
+
+	// 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
+	// measurement feeds into here, via a tracker local to this one `<Plot>`
+	// instance. See `labelOverflow.svelte.ts`. Resets on `resolvedSeries` so
+	// overflow from an earlier, differently-shaped frame doesn't linger once
+	// that frame is gone.
+	const labelMargin = createLabelMarginTracker(
+		() => margins,
+		() => resolvedSeries
+	);
 </script>
 
 <BasePlotLayout
-  {width}
-  {height}
-  {styles}
-  data={flat}
-  getX={xAcc}
-  getY={(d) => Number(yAcc(d))}
-  {hover}
-  scales={resolvedScales}
-  {...labelMargin.plotProps}
-  markers={[...scatterMarkers, ...markers]}
-  seriesData={resolvedSeries}
-  {scopedGroups}
+	{width}
+	{height}
+	{styles}
+	data={flat}
+	getX={xAcc}
+	getY={(d) => Number(yAcc(d))}
+	{hover}
+	scales={resolvedScales}
+	{...labelMargin.plotProps}
+	markers={[...scatterMarkers, ...markers]}
+	seriesData={resolvedSeries}
+	{scopedGroups}
 >
-  {#snippet children({ numericMargins })}
-    {#if showVals}
-      {#each groupedSeries as group (group.series.name)}
-        <ValueLabels
-          {group}
-          {formatValue}
-          values={styles.values}
-          defaultColor={cfg.axis.color}
-          disabled={effectiveDisabledFor(group.series.name)}
-          {width}
-          {height}
-          {numericMargins}
-          onHoverSeries={hoverIsolate ? () => { hoverIsolatedSeries = group.series.name; } : undefined}
-          onHoverEnd={hoverIsolate ? () => { hoverIsolatedSeries = null; } : undefined}
-          onOverflow={labelMargin.report}
-        />
-      {/each}
-    {/if}
-  {/snippet}
+	{#snippet children({ numericMargins })}
+		{#if showVals}
+			{#each groupedSeries as group (group.series.name)}
+				<ValueLabels
+					{group}
+					{formatValue}
+					values={styles.values}
+					defaultColor={cfg.axis.color}
+					disabled={effectiveDisabledFor(group.series.name)}
+					{width}
+					{height}
+					{numericMargins}
+					onHoverSeries={hoverIsolate
+						? () => {
+								hoverIsolatedSeries = group.series.name;
+							}
+						: undefined}
+					onHoverEnd={hoverIsolate
+						? () => {
+								hoverIsolatedSeries = null;
+							}
+						: undefined}
+					onOverflow={labelMargin.report}
+				/>
+			{/each}
+		{/if}
+	{/snippet}
 </BasePlotLayout>

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

@@ -39,8 +39,24 @@ export declare function watchLabelOverflow(args: {
  * "shrink margin → overflow reappears → grow margin → …". Each side is only
  * ever set when the caller's own `margins` prop hasn't already pinned it, so
  * an explicit caller override always wins over this auto-grown one.
+ *
+ * That monotonic growth is only sound for a *stable* dataset — it assumes
+ * every reading describes the same thing being measured, just possibly at an
+ * earlier, not-yet-settled frame. It stops being sound once the caller's own
+ * data changes identity underneath it (e.g. a timeline scrubber revealing a
+ * different slice of rows on every tick): an overflow measured against
+ * *that* frame's rendered labels doesn't describe the next frame's, so
+ * carrying it forward forever can leave a plot permanently — and wrongly —
+ * margin-inflated by whatever the single most cluttered frame it ever
+ * passed through needed, long after scrubbing away from it. `resetKey`, if
+ * given, is compared by identity on every call; a change drops `measured`
+ * back to zero so the next frame's overflow is measured fresh against only
+ * what's actually on screen now. Pass whatever reactive value identifies
+ * "what's currently being plotted" for the caller (e.g. its own resolved
+ * series list) — a plain reference/value comparison, not a deep one, so it
+ * only need change identity when the rendered content actually does.
  */
-export declare function createLabelMarginTracker(margins: () => MarginConfig | undefined): {
+export declare function createLabelMarginTracker(margins: () => MarginConfig | undefined, resetKey?: () => unknown): {
     report: (overflow: MarginOverflow) => void;
     readonly resolvedMargins: Partial<{
         top: number | "auto";

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

@@ -87,9 +87,42 @@ export function watchLabelOverflow(args) {
  * "shrink margin → overflow reappears → grow margin → …". Each side is only
  * ever set when the caller's own `margins` prop hasn't already pinned it, so
  * an explicit caller override always wins over this auto-grown one.
+ *
+ * That monotonic growth is only sound for a *stable* dataset — it assumes
+ * every reading describes the same thing being measured, just possibly at an
+ * earlier, not-yet-settled frame. It stops being sound once the caller's own
+ * data changes identity underneath it (e.g. a timeline scrubber revealing a
+ * different slice of rows on every tick): an overflow measured against
+ * *that* frame's rendered labels doesn't describe the next frame's, so
+ * carrying it forward forever can leave a plot permanently — and wrongly —
+ * margin-inflated by whatever the single most cluttered frame it ever
+ * passed through needed, long after scrubbing away from it. `resetKey`, if
+ * given, is compared by identity on every call; a change drops `measured`
+ * back to zero so the next frame's overflow is measured fresh against only
+ * what's actually on screen now. Pass whatever reactive value identifies
+ * "what's currently being plotted" for the caller (e.g. its own resolved
+ * series list) — a plain reference/value comparison, not a deep one, so it
+ * only need change identity when the rendered content actually does.
  */
-export function createLabelMarginTracker(margins) {
+export function createLabelMarginTracker(margins, resetKey) {
     let measured = $state(NO_OVERFLOW);
+    // Skips the reset on the very first run (there's nothing to reset yet,
+    // and `measured` already starts at `NO_OVERFLOW`) so only a later,
+    // genuine change to `resetKey` clears accumulated growth.
+    let resetKeyInitialized = false;
+    let lastResetKey;
+    $effect(() => {
+        const key = resetKey?.();
+        if (!resetKeyInitialized) {
+            resetKeyInitialized = true;
+            lastResetKey = key;
+            return;
+        }
+        if (key !== lastResetKey) {
+            lastResetKey = key;
+            measured = NO_OVERFLOW;
+        }
+    });
     function report(overflow) {
         const next = {
             left: Math.max(measured.left, overflow.left),
@@ -127,15 +160,18 @@ export function createLabelMarginTracker(margins) {
             out.bottom = AUTO_MARGIN_ESTIMATE.bottom + measured.bottom;
         return out;
     });
-    // Bundles `resolvedMargins` with a remount key derived from `measured`,
-    // 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, and from having to know it's `measured` that key
-    // must track.
+    // 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.
     const plotProps = $derived.by(() => ({
         margins: resolvedMargins,
-        marginRemountKey: JSON.stringify(measured)
+        marginRemountKey: JSON.stringify({ base: margins(), measured })
     }));
     return {
         report,

package/package.json

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