@fundar/data-chart-telling 0.0.47 → 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/line/Plot.svelte

@@ -170,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, {

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/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.47",
+  "version": "0.0.48",
   "type": "module",
   "files": [
     "dist"