@fundar/data-chart-telling 0.0.46 → 0.0.48

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { setConfiguration, getConfiguration, resetConfiguration, configToCssVars
 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 { makeColorScale, normalize, resolveCssColor, paletteColor, contrastTextColor, contrastRatio } from './utils/color';
 export { estimateCategoricalAxisMargin } from './plots/utils/categoricalAxisMargin';
 export { estimateLineValueLabelMargin } from './plots/line/valueLabelMargin';
 export type { AxisValue, AxisScale, AxisBasedScalesConfig } from './types/layout/scales';
@@ -58,7 +58,7 @@ export type { GeoMarkersConfig, GeoInsetMarkerConfig, GeoInsetTooltipConfig, Geo
 export type { ChartPlotContext, ChartPlotSnippet } from './types/charts/common';
 export type { TimeValue, Orientation, TimelineConfig } from './types/layout/timeline';
 export type { Responsive, FacetColumns, FacetMode, FacetNavLayout, FacetConfig, FacetIndicatorContext, FacetIndicatorSnippet, FacetNavDirection, FacetNavContext, FacetNavSnippet } from './types/layout/facet';
-export type { LegendSection, DiscreteLegendSection, ContinuousLegendSection, LegendItem, LegendDisabledStyle, LegendItemsLayout, LegendNavDirection, LegendNavContext, LegendNavSnippet, LegendInteractionStore, LegendPlotContext } from './types/layout/legend';
+export type { LegendSection, DiscreteLegendSection, ContinuousLegendSection, LegendItem, LegendDisabledStyle, LegendItemsLayout, LegendInteractiveStyle, DiscreteInteractiveConfig, ContinuousInteractiveConfig, LegendNavDirection, LegendNavContext, LegendNavSnippet, LegendInteractionStore, LegendPlotContext } from './types/layout/legend';
 export type { HoverStrategy, TooltipOptions, TooltipProp, TooltipAnchorX, TooltipAnchorY } from './types/layout/tooltip';
 export type { ChartConfig, ChartConfigInput, TextStyle } from './types/configuration/styling';
 export type { ChartProps, GapsAwareChartProps } from './types/charts/props';

package/dist/index.js

@@ -42,6 +42,6 @@ export { setConfiguration, getConfiguration, resetConfiguration, configToCssVars
 export { THEMES } from './configuration/themes';
 // ── Utils ─────────────────────────────────────────────────────────────────────
 export { groupBy, buildSeries } from './utils/grouping';
-export { makeColorScale, normalize, resolveCssColor, paletteColor } from './utils/color';
+export { makeColorScale, normalize, resolveCssColor, paletteColor, contrastTextColor, contrastRatio } from './utils/color';
 export { estimateCategoricalAxisMargin } from './plots/utils/categoricalAxisMargin';
 export { estimateLineValueLabelMargin } from './plots/line/valueLabelMargin';

package/dist/layout/legend/ContinuousSection.svelte

@@ -12,16 +12,17 @@
   const barWidth = $derived(section.width ?? 170);
 
   const fmt = $derived(section.format ?? ((v: number) => String(v)));
+  const isInteractive = $derived(section.interactive?.enabled ?? false);
 
   // Fill/opacity for the excluded-margin rects.
   const excludedStyle = $derived.by((): { fill: string; opacity: number } => {
-    const d = section.disabledStyle;
+    const d = section.interactive?.disabledStyle;
     if (d?.fill) return { fill: d.fill, opacity: d.fillOpacity ?? d.opacity ?? 1 };
     return { fill: 'currentColor', opacity: d?.fillOpacity ?? d?.opacity ?? 0.35 };
   });
 
   const tickPositions = $derived(
-    section.interactive
+    isInteractive
       ? []
       : (section.ticks ?? []).map((v) => ({
           v,
@@ -68,7 +69,9 @@
   const hiT = $derived(toT(hi));
 
   const colorDomain = $derived.by((): [number, number] =>
-    section.interactive && (section.mode ?? 'filter') === 'rescale' ? [lo, hi] : [section.min, section.max],
+    isInteractive && (section.interactive?.mode ?? 'filter') === 'rescale'
+      ? [lo, hi]
+      : [section.min, section.max],
   );
   const colorScale = $derived(
     makeColorScale(
@@ -88,21 +91,21 @@
   );
 
   $effect(() => {
-    if (!section.interactive) return;
+    if (!isInteractive) return;
     interaction.continuousRange =
       lo <= section.min && hi >= section.max
         ? null
         : {
             min: lo,
             max: hi,
-            mode: section.mode ?? 'filter',
-            disabledStyle: section.disabledStyle ?? { opacity: cfg.legend.disabledOpacity },
+            mode: section.interactive?.mode ?? 'filter',
+            disabledStyle: section.interactive?.disabledStyle ?? { opacity: cfg.legend.disabledOpacity },
           };
   });
 
   // Mirrors an externally-set `interaction.continuousRange` into lo/hi.
   $effect(() => {
-    if (!section.interactive) return;
+    if (!isInteractive) return;
     const range = interaction.continuousRange;
     if (range === null) {
       if (untrack(() => loAdjusted || hiAdjusted)) {
@@ -122,7 +125,7 @@
 
   function startDrag(which: 'lo' | 'hi') {
     return (event: PointerEvent) => {
-      if (!section.interactive) return;
+      if (!isInteractive) return;
       event.preventDefault();
       if (which === 'lo') loAdjusted = true;
       else hiAdjusted = true;
@@ -179,22 +182,22 @@
       <rect class="dct-continuous__tick-mark" x={tick.t * barWidth} y="12" />
     {/each}
 
-    {#if section.interactive}
+    {#if isInteractive}
       {#if loT > 0}
         <rect x="0" y="0" width={loT * barWidth} height="12" rx="2" fill={excludedStyle.fill} fill-opacity={excludedStyle.opacity} />
       {/if}
       {#if hiT < 1}
         <rect x={hiT * barWidth} y="0" width={barWidth - hiT * barWidth} height="12" rx="2" fill={excludedStyle.fill} fill-opacity={excludedStyle.opacity} />
       {/if}
-      {#if section.handle}
-        {@render section.handle({
+      {#if section.interactive?.handle}
+        {@render section.interactive.handle({
           which: 'lo',
           value: lo,
           position: loT,
           onpointerdown: startDrag('lo'),
           ondoubleclick: resetHandle('lo'),
         })}
-        {@render section.handle({
+        {@render section.interactive.handle({
           which: 'hi',
           value: hi,
           position: hiT,
@@ -233,7 +236,7 @@
   </svg>
 
   <div class="dct-continuous__labels" style:width="{barWidth}px">
-    {#if section.interactive}
+    {#if isInteractive}
       <span class="dct-continuous__tick dct-continuous__tick--handle-lo" style:left="{loT * barWidth}px">{fmt(lo)}</span>
       <span class="dct-continuous__tick dct-continuous__tick--handle-hi" style:left="{hiT * barWidth}px">{fmt(hi)}</span>
     {:else}

package/dist/layout/legend/DiscreteBadgeItem.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+	import { contrastTextColor } from '../../utils/color';
+	import DiscreteSymbolIcon from './DiscreteSymbolIcon.svelte';
+	import type { LegendItem } from '../../types/layout/legend';
+
+	/**
+	 * The `interactive.legendStyle: 'badge'` item look: a pill filled with the
+	 * series color, its symbol icon (unless `showIcon` is off) and label
+	 * auto-contrasted against that fill, and an eye icon that's crossed out
+	 * while `disabled`. The toggled-off dim itself is applied by the parent
+	 * `.dct-discrete__item`.
+	 */
+	let {
+		item,
+		color,
+		disabled,
+		showIcon = true
+	}: { item: LegendItem; color: string; disabled: boolean; showIcon?: boolean } = $props();
+	const textColor = $derived(contrastTextColor(color));
+</script>
+
+<span class="dct-discrete__badge" style:background={color} style:color={textColor}>
+	{#if showIcon}
+		<DiscreteSymbolIcon {item} color={textColor} />
+	{/if}
+	<span class="dct-discrete__label">{item.label || item.name}</span>
+	<svg class="dct-discrete__eye" viewBox="0 0 24 24" aria-hidden="true">
+		{#if disabled}
+			<path
+				d="M17.94 17.94A10.94 10.94 0 0 1 12 20c-7 0-11-8-11-8a18.5 18.5 0 0 1 5.06-5.94M9.9 4.24A9.12 9.12 0 0 1 12 4c7 0 11 8 11 8a18.5 18.5 0 0 1-2.16 3.19m-6.72-1.07a3 3 0 1 1-4.24-4.24"
+			/>
+			<line x1="1" y1="1" x2="23" y2="23" />
+		{:else}
+			<path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" />
+			<circle cx="12" cy="12" r="3" />
+		{/if}
+	</svg>
+</span>
+
+<style>
+	.dct-discrete__badge {
+		display: flex;
+		align-items: center;
+		gap: 0.4rem;
+		min-width: 0;
+		padding: var(--dct-legend-badge-pad, 0.25rem 0.65rem);
+		border-radius: var(--dct-legend-badge-radius, 999px);
+	}
+	.dct-discrete__label {
+		font-size: var(--dct-legend-size, 0.875rem);
+		font-weight: var(--dct-legend-weight, 400);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		min-width: 0;
+	}
+	.dct-discrete__eye {
+		width: var(--dct-legend-badge-eye-size, 0.9rem);
+		height: var(--dct-legend-badge-eye-size, 0.9rem);
+		flex-shrink: 0;
+		fill: none;
+		stroke: currentColor;
+		stroke-width: 2;
+		stroke-linecap: round;
+		stroke-linejoin: round;
+	}
+</style>

package/dist/layout/legend/DiscreteBadgeItem.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { LegendItem } from '../../types/layout/legend';
+type $$ComponentProps = {
+    item: LegendItem;
+    color: string;
+    disabled: boolean;
+    showIcon?: boolean;
+};
+declare const DiscreteBadgeItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type DiscreteBadgeItem = ReturnType<typeof DiscreteBadgeItem>;
+export default DiscreteBadgeItem;

package/dist/layout/legend/DiscreteSwatchItem.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+	import DiscreteSymbolIcon from './DiscreteSymbolIcon.svelte';
+	import type { LegendItem } from '../../types/layout/legend';
+
+	let { item, color }: { item: LegendItem; color: string } = $props();
+</script>
+
+<DiscreteSymbolIcon {item} {color} />
+<span class="dct-discrete__label">{item.label || item.name}</span>
+
+<style>
+	.dct-discrete__label {
+		font-size: var(--dct-legend-size, 0.875rem);
+		font-weight: var(--dct-legend-weight, 400);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		min-width: 0;
+	}
+</style>

package/dist/layout/legend/DiscreteSwatchItem.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { LegendItem } from '../../types/layout/legend';
+type $$ComponentProps = {
+    item: LegendItem;
+    color: string;
+};
+declare const DiscreteSwatchItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type DiscreteSwatchItem = ReturnType<typeof DiscreteSwatchItem>;
+export default DiscreteSwatchItem;

package/dist/layout/legend/DiscreteSymbolIcon.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+	import type { LegendItem } from '../../types/layout/legend';
+	import type { LineStyle } from '../../types/plots/constants';
+
+	/**
+	 * The series' symbol/line-style icon, shared by both discrete item looks
+	 * (`DiscreteSwatchItem` and `DiscreteBadgeItem`) so the two stay in sync.
+	 * `color` is caller-supplied rather than read off `item` — the swatch look
+	 * fills it with the series color, the badge look with its own label color.
+	 */
+	let { item, color }: { item: LegendItem; color: string } = $props();
+
+	function dashArray(style?: LineStyle): string | undefined {
+		switch (style) {
+			case 'dashed':
+				return '2,5';
+			case 'dotted':
+				return '1,4';
+			case 'dashdot':
+				return '5,3,1,3';
+			default:
+				return undefined;
+		}
+	}
+</script>
+
+<svg class="dct-discrete__swatch" viewBox="0 0 15 10">
+	{#if item.symbol === 'circle'}
+		<circle cx="5" cy="5" r="4" fill={color} />
+	{:else if item.symbol === 'square'}
+		<rect x="1" y="1" width="8" height="8" rx="2" fill={color} />
+	{:else if item.symbol === 'triangle'}
+		<path
+			d="M 6 2 L 9 7.5 A 1.5 1.5 0 0 1 7.8 10 L 2.2 10 A 1.5 1.5 0 0 1 1 7.5 L 4 2 A 1.5 1.5 0 0 1 6 2"
+			fill={color}
+			transform="translate(0,-1)"
+		/>
+	{:else if item.symbol === 'line'}
+		<line
+			x1="2"
+			y1="5"
+			x2="13"
+			y2="5"
+			stroke={color}
+			stroke-width="3"
+			stroke-linecap="round"
+			stroke-dasharray={dashArray(item.lineStyle)}
+		/>
+	{:else}
+		<rect x="1" y="1" width="8" height="8" fill={color} />
+	{/if}
+</svg>
+
+<style>
+	.dct-discrete__swatch {
+		width: var(--dct-legend-swatch, 1.25rem);
+		height: var(--dct-legend-swatch, 1.25rem);
+		flex-shrink: 0;
+	}
+</style>

package/dist/layout/legend/DiscreteSymbolIcon.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { LegendItem } from '../../types/layout/legend';
+type $$ComponentProps = {
+    item: LegendItem;
+    color: string;
+};
+declare const DiscreteSymbolIcon: import("svelte").Component<$$ComponentProps, {}, "">;
+type DiscreteSymbolIcon = ReturnType<typeof DiscreteSymbolIcon>;
+export default DiscreteSymbolIcon;

package/dist/plots/bar/Plot.svelte

@@ -11,7 +11,10 @@
 		buildScopedMarkerGroups
 	} from '../utils/segments';
 	import { createBarLayout } from './layout.svelte';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
 	import { estimateValueLabelMargin } from '../utils/valueLabelMargin';
 	import { buildHoverPoints } from './hoverPoints';
 	import { buildBarMarkers } from './buildBarMarkers';
@@ -258,6 +261,9 @@
 		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
@@ -266,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,7 +8,10 @@
 	import { buildLineMarkers } from './buildLineMarkers';
 	import { buildGapMarkers } from './buildGapMarkers';
 	import { isGapValue } from '../utils/gaps';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
 	import { estimateLineValueLabelMargin } from './valueLabelMargin';
 	import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
 	import ValueLabels from './ValueLabels.svelte';
@@ -167,14 +170,8 @@
 			.filter((p): p is { series: Series<TData>; lastRow: TData; color: string } => p !== undefined)
 	);
 
-	// 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.
+	// Estimated overflow for the end-of-line label fan and its own vertical
+	// reach — see `estimateLineValueLabelMargin`'s own doc comment.
 	const valueLabelFloor = $derived.by((): MarginOverflow | undefined => {
 		if (!showVals) return undefined;
 		return estimateLineValueLabelMargin(resolvedSeries, {
@@ -185,17 +182,8 @@
 		});
 	});
 
-	// A facet cramped enough that its own end-of-line label can never fully
-	// fit would otherwise grow `measured` without bound (see
-	// `createLabelMarginTracker`'s own doc comment) — capped at half of each
-	// dimension, so the plot's own content box never shrinks past the other
-	// half no matter how little room a label has to work with.
-	const maxLabelOverflow = $derived({
-		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)
-	});
+	// 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

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

@@ -3,20 +3,12 @@ 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.
+ * `LinePlot`'s value-label margin estimate: the end-of-line fan's
+ * horizontal reach (`left` or `right`, whichever side it fans toward, with
+ * the same amount mirrored to the other side for a fan that can flip),
+ * plus the label text's own vertical reach on `top`/`bottom`. Stable across
+ * a timeline scrubber or dataset change, not DOM-measured. Also used by a
+ * faceted caller to build a shared `FacetConfig.marginsForFacet`.
  */
 export declare function estimateLineValueLabelMargin<TData extends Record<string, unknown>>(series: Series<TData>[], options?: {
     valAnchor?: ValueAnchor;
@@ -24,4 +16,4 @@ export declare function estimateLineValueLabelMargin<TData extends Record<string
     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;
+}): MarginOverflow;

package/dist/plots/line/valueLabelMargin.js

@@ -1,21 +1,13 @@
 import { resolveAccessor } from '../utils/accessors';
 import { getConfiguration } from '../../configuration/config.svelte';
-import { estimateValueLabelMargin, laneReachUpperBound } from '../utils/valueLabelMargin';
+import { estimateValueLabelMargin, estimateValueLabelVerticalMargin, 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.
+ * `LinePlot`'s value-label margin estimate: the end-of-line fan's
+ * horizontal reach (`left` or `right`, whichever side it fans toward, with
+ * the same amount mirrored to the other side for a fan that can flip),
+ * plus the label text's own vertical reach on `top`/`bottom`. Stable across
+ * a timeline scrubber or dataset change, not DOM-measured. Also used by a
+ * faceted caller to build a shared `FacetConfig.marginsForFacet`.
  */
 export function estimateLineValueLabelMargin(series, options = {}) {
     const cfg = getConfiguration();
@@ -24,12 +16,11 @@ export function estimateLineValueLabelMargin(series, options = {}) {
     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 dir = Math.sign(baseDx) || 1;
     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 outwardFraction = 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;
@@ -56,6 +47,19 @@ export function estimateLineValueLabelMargin(series, options = {}) {
     // +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 };
+    const horizontal = estimateValueLabelMargin(texts, { canvasFont, textFraction: outwardFraction, reach }) + 2;
+    const defaultDy = valAnchor === 'outside' ? -8 : 0;
+    const defaultLA = valAnchor === 'outside' ? 'bottom' : 'middle';
+    const dy = typeof font?.dy === 'number' ? font.dy : defaultDy;
+    const { top, bottom } = estimateValueLabelVerticalMargin({
+        fontSize,
+        lineAnchor: font?.lineAnchor ?? defaultLA,
+        dy
+    });
+    return {
+        left: dir === -1 ? horizontal : 0,
+        right: dir === 1 ? horizontal : seriesCount > 1 ? horizontal : 0,
+        top,
+        bottom
+    };
 }

package/dist/plots/pyramid/Plot.svelte

@@ -6,7 +6,10 @@
 	import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
 	import { disabledFillOverride } from '../utils/legendDisabled';
 	import { buildPyramidBarMarkers } from './buildPyramidBarMarkers';
-	import { createLabelMarginTracker } from '../utils/labelOverflow.svelte';
+	import {
+		createLabelMarginTracker,
+		halfDimensionOverflowCap
+	} from '../utils/labelOverflow.svelte';
 	import { estimateValueLabelMargin } from '../utils/valueLabelMargin';
 	import {
 		buildGroupedSeries,
@@ -301,6 +304,9 @@
 		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
@@ -308,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/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.

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.
@@ -145,18 +162,23 @@ maxOverflow) {
             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 cap = maxOverflow?.() ?? {
-            left: Infinity,
-            right: Infinity,
-            top: Infinity,
-            bottom: Infinity
-        };
         const next = {
-            left: Math.min(cap.left, Math.max(measured.left, overflow.left)),
-            right: Math.min(cap.right, Math.max(measured.right, overflow.right)),
-            top: Math.min(cap.top, Math.max(measured.top, overflow.top)),
-            bottom: Math.min(cap.bottom, Math.max(measured.bottom, overflow.bottom))
+            left: Math.max(measured.left, overflow.left),
+            right: Math.max(measured.right, overflow.right),
+            top: Math.max(measured.top, overflow.top),
+            bottom: Math.max(measured.bottom, overflow.bottom)
         };
         if (next.left !== measured.left ||
             next.right !== measured.right ||
@@ -173,33 +195,55 @@ maxOverflow) {
     // 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

@@ -1,3 +1,4 @@
+import type { LineAnchor } from '../../types/plots/constants';
 /**
  * The one calculation every value-label-drawing plot (`LinePlot`, `BarPlot`,
  * `PyramidPlot`, …) needs to reserve margin for its own value labels ahead of
@@ -35,6 +36,18 @@ export declare function estimateValueLabelMargin(texts: string[], options: {
      */
     reach?: number;
 }): number;
+/** Estimated full rendered height of a single-line value label at `fontSize`. */
+export declare function estimateLabelHeight(fontSize: number): number;
+/** Vertical analogue of `estimateValueLabelMargin`: how far a value label's text extends above/below its anchor point. */
+export declare function estimateValueLabelVerticalMargin(options: {
+    fontSize: number;
+    lineAnchor: LineAnchor;
+    /** Pixel offset from the anchor point to the label's line-anchor edge, same sign as SVG's `dy`. */
+    dy?: number;
+}): {
+    top: number;
+    bottom: 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

package/dist/plots/utils/valueLabelMargin.js

@@ -21,6 +21,26 @@ export function estimateValueLabelMargin(texts, options) {
     const reach = options.reach ?? 0;
     return Math.ceil(reach + textFraction * maxWidth);
 }
+/** Estimated full rendered height of a single-line value label at `fontSize`. */
+export function estimateLabelHeight(fontSize) {
+    return fontSize * 1.2;
+}
+/** Vertical analogue of `estimateValueLabelMargin`: how far a value label's text extends above/below its anchor point. */
+export function estimateValueLabelVerticalMargin(options) {
+    const height = estimateLabelHeight(options.fontSize);
+    const dy = options.dy ?? 0;
+    if (options.lineAnchor === 'top') {
+        return { top: 0, bottom: Math.ceil(Math.max(0, dy) + height) + 2 };
+    }
+    if (options.lineAnchor === 'bottom') {
+        return { top: Math.ceil(Math.max(0, -dy) + height) + 2, bottom: 0 };
+    }
+    const half = height / 2;
+    return {
+        top: Math.ceil(Math.max(0, half - dy)) + 2,
+        bottom: Math.ceil(Math.max(0, half + dy)) + 2
+    };
+}
 /**
  * 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

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

@@ -60,6 +60,26 @@ export type LegendHandleContext = {
 };
 /** Custom drag-handle renderer for an interactive continuous section. */
 export type LegendHandleSnippet = Snippet<[LegendHandleContext]>;
+/**
+ * Item look for an interactive discrete section. `'badge'` (the default once
+ * `interactive.enabled` is on) draws each item as a pill filled with its
+ * series color, with the symbol icon and label auto-contrasted against that
+ * fill and an eye icon on the right — crossed out once the item is toggled
+ * off. `'basic'` keeps the plain swatch + label, same as a non-interactive
+ * section.
+ */
+export type LegendInteractiveStyle = 'badge' | 'basic';
+/** Click-to-toggle configuration for a discrete section: whether it's on, how toggled items look, and the style applied to a toggled-off one. */
+export type DiscreteInteractiveConfig = {
+    /** Turns click-to-toggle on for every item in the section. */
+    enabled?: boolean;
+    /** Item look while `enabled`. Defaults to `'badge'`. */
+    legendStyle?: LegendInteractiveStyle;
+    /** Style applied to a toggled-off item. Defaults to `{ opacity: cfg.legend.disabledOpacity }`. */
+    disabledStyle?: LegendDisabledStyle;
+    /** Shows the symbol icon inside a `'badge'` pill. Defaults to `true`; ignored by `'basic'`, which always shows it. */
+    showIcon?: boolean;
+};
 export type DiscreteLegendSection = {
     type: 'discrete';
     title?: string;
@@ -67,10 +87,24 @@ export type DiscreteLegendSection = {
     columns?: number;
     /** Item flow direction. Defaults to `{ type: 'vertical' }` (unchanged prior behaviour). */
     layout?: LegendItemsLayout;
-    interactive?: boolean;
-    disabledStyle?: LegendDisabledStyle;
+    interactive?: DiscreteInteractiveConfig;
     navButton?: LegendNavSnippet;
 };
+/** Drag-to-narrow configuration for a continuous section: whether it's on, how the range behaves, and its look. */
+export type ContinuousInteractiveConfig = {
+    /** Turns drag-to-narrow on, adding lo/hi handles at the edges of the excluded range. */
+    enabled?: boolean;
+    /**
+     * How the color ramp responds to a narrowed range: `'rescale'` reprojects
+     * it onto the new bounds, `'filter'` keeps the original domain and only
+     * excludes out-of-range values. Defaults to `'filter'`.
+     */
+    mode?: 'rescale' | 'filter';
+    /** Style applied to the excluded (narrowed-out) range. Defaults to `{ opacity: cfg.legend.disabledOpacity }`. */
+    disabledStyle?: LegendDisabledStyle;
+    /** Custom renderer for the draggable lo/hi handles. */
+    handle?: LegendHandleSnippet;
+};
 export type ContinuousLegendSection = {
     type: 'continuous';
     title?: string;
@@ -82,16 +116,7 @@ export type ContinuousLegendSection = {
     ticks?: number[];
     width?: number;
     format?: (v: number) => string;
-    interactive?: boolean;
-    /**
-     * How the color ramp responds to a narrowed range: `'rescale'` reprojects
-     * it onto the new bounds, `'filter'` keeps the original domain and only
-     * excludes out-of-range values. Defaults to `'filter'`.
-     */
-    mode?: 'rescale' | 'filter';
-    disabledStyle?: LegendDisabledStyle;
-    /** Custom renderer for the draggable lo/hi handles. */
-    handle?: LegendHandleSnippet;
+    interactive?: ContinuousInteractiveConfig;
 };
 export type LegendSection = DiscreteLegendSection | ContinuousLegendSection;
 /**

package/dist/utils/color.d.ts

@@ -2,4 +2,13 @@ export declare function resolveCssColor(color: string): string;
 export declare function normalize(v: number, min: number, max: number): number;
 /** Cycles through a discrete palette by series index — the default colour for an unstyled series. */
 export declare function paletteColor(index: number, palette: string[]): string;
+/** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
+export declare function contrastRatio(colorA: string, colorB: string): number;
+/**
+ * The `candidates` entry with the highest WCAG contrast ratio against
+ * `background`. Defaults to plain white/black; pass a grayscale or other
+ * palette to widen the choice. Falls back to the first candidate when
+ * `background` can't be parsed.
+ */
+export declare function contrastTextColor(background: string, candidates?: string[]): string;
 export declare function makeColorScale(min: number, max: number, colorMin: string, colorMax: string): (v: number) => string;

package/dist/utils/color.js

@@ -23,6 +23,68 @@ export function paletteColor(index, palette) {
         return 'currentColor';
     return palette[index % palette.length];
 }
+function parseRgb(color) {
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+    if (hex) {
+        const digits = hex[1].length === 3 ? hex[1].split('').map((c) => c + c).join('') : hex[1];
+        const num = parseInt(digits, 16);
+        return [(num >> 16) & 255, (num >> 8) & 255, num & 255];
+    }
+    const rgb = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(color);
+    if (rgb)
+        return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+    // Named colors, hsl(), and any other CSS color syntax: resolved to
+    // `rgb(...)` via the browser's computed style, then reparsed.
+    if (!isBrowser)
+        return null;
+    const el = document.createElement('div');
+    el.style.color = color;
+    document.body.appendChild(el);
+    const computed = getComputedStyle(el).color;
+    document.body.removeChild(el);
+    if (!computed || computed === color)
+        return null;
+    return parseRgb(computed);
+}
+function relativeLuminance([r, g, b]) {
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+/** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
+export function contrastRatio(colorA, colorB) {
+    const a = parseRgb(resolveCssColor(colorA));
+    const b = parseRgb(resolveCssColor(colorB));
+    if (!a || !b)
+        return 1;
+    const lA = relativeLuminance(a);
+    const lB = relativeLuminance(b);
+    const lighter = Math.max(lA, lB);
+    const darker = Math.min(lA, lB);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * The `candidates` entry with the highest WCAG contrast ratio against
+ * `background`. Defaults to plain white/black; pass a grayscale or other
+ * palette to widen the choice. Falls back to the first candidate when
+ * `background` can't be parsed.
+ */
+export function contrastTextColor(background, candidates = ['#ffffff', '#000000']) {
+    if (candidates.length === 0)
+        return '#000000';
+    let best = candidates[0];
+    let bestRatio = -Infinity;
+    for (const candidate of candidates) {
+        const ratio = contrastRatio(background, candidate);
+        if (ratio > bestRatio) {
+            bestRatio = ratio;
+            best = candidate;
+        }
+    }
+    return best;
+}
 export function makeColorScale(min, max, colorMin, colorMax) {
     const resolvedMin = resolveCssColor(colorMin);
     const resolvedMax = resolveCssColor(colorMax);

package/package.json

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