@fundar/data-chart-telling 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.5.0] - 2026-10-31
+
+### Changed
+
+- Zooming or panning a map no longer re-projects every feature on each wheel tick or drag move. The features already drawn are carried to the new view with an SVG transform and the projection is moved, and the features redrawn, once the view has been still for 120 ms. A map of 6,000 features goes from about 340 ms to about 50 ms per wheel tick. Strokes and dots are briefly scaled while the view moves.
+
+### Fixed
+
+- A series' catch-all segments that name different facets, or a facet next to the unscoped one, no longer log the warning for two catch-alls: they do not compete.
+
+## [1.4.0] - 2026-10-30
+
+### Added
+
+- `legend.off` in the automatic legend's configuration turns series off from code, as if the reader had clicked them: a list of names (dimmed), or a map to an opacity or to a `dim`, `hide` or `omit` action; a series left out is turned back on. `legend.highlight` is its inverse, keeping the series it names and dimming the rest. A plot with facets can dim a series exactly when no panel shows it.
+
+### Fixed
+
+- Value labels that fit margins measure what reaches past the plot against the area svelteplot lays the plot out by, not against the estimate an `'auto'` margin has until its axes are sized. A label inside the plot could read as overflow in that moment and grow the margins for good, so the same plot drew with different margins from one render to the next.
+
 ## [1.3.0] - 2026-10-30
 
 ### Added

package/dist/layout/coordinates/ProjectionZoom.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { getContext, setContext, type Snippet } from 'svelte';
+	import { getContext, setContext, untrack, type Snippet } from 'svelte';
 	import { ZoomedProjection } from './ZoomedProjection';
 	import type { GeoZoomTransform } from './zoom.svelte';
 	import type { StreamingProjection } from '../../plots/utils/tiles';
@@ -10,31 +10,65 @@
 	 * positions, while dots, text and strokes keep their size. Works by handing
 	 * the marks below a view of svelteplot's plot state whose `scales.projection`
 	 * is the moved one.
+	 *
+	 * Re-projecting every mark is the cost of that, and a map with thousands of
+	 * features pays it on each wheel tick. So while the view is moving, the marks
+	 * already drawn are carried to it with an SVG transform (cheap, if briefly
+	 * coarser: strokes and dots scale with it), and the projection is only moved,
+	 * and the marks redrawn, once the view has been still for `settleDelay` ms.
 	 */
 	let {
 		inner,
 		outer,
+		settleDelay = 120,
 		children
-	}: { inner: GeoZoomTransform; outer: GeoZoomTransform; children: Snippet } = $props();
+	}: {
+		inner: GeoZoomTransform;
+		outer: GeoZoomTransform;
+		/** Milliseconds the view must be still before the marks are re-projected */
+		settleDelay?: number;
+		children: Snippet;
+	} = $props();
+
+	const same = (a: GeoZoomTransform, b: GeoZoomTransform) =>
+		a.k === b.k && a.x === b.x && a.y === b.y;
+
+	// The view the marks are drawn for; the first one is the one they mount with.
+	let settled = $state.raw(untrack(() => ({ inner: { ...inner }, outer: { ...outer } })));
+
+	$effect(() => {
+		const next = { inner: { ...inner }, outer: { ...outer } };
+		if (same(next.inner, settled.inner) && same(next.outer, settled.outer)) return;
+		const timer = setTimeout(() => (settled = next), settleDelay);
+		return () => clearTimeout(timer);
+	});
+
+	const carry = $derived(
+		ZoomedProjection.between(
+			ZoomedProjection.compose(settled.inner, settled.outer),
+			ZoomedProjection.compose(inner, outer)
+		)
+	);
+	const carrying = $derived(carry.k !== 1 || carry.x !== 0 || carry.y !== 0);
 
 	type Scales = { projection?: StreamingProjection & { aspectRatio?: number } } | undefined;
 	type PlotState = { scales: Scales; publicState: object };
 	type PlotContext = { getPlotState: () => PlotState } & Record<string, unknown>;
 
 	const context = getContext<PlotContext>('svelteplot');
-	const state = context.getPlotState();
+	const plot = context.getPlotState();
 
 	const scales = $derived.by((): Scales => {
-		const own = state.scales;
+		const own = plot.scales;
 		return own?.projection
-			? { ...own, projection: ZoomedProjection.of(own.projection, inner, outer) }
+			? { ...own, projection: ZoomedProjection.of(own.projection, settled.inner, settled.outer) }
 			: own;
 	});
 
-	const publicState = new Proxy(state.publicState, {
+	const publicState = new Proxy(plot.publicState, {
 		get: (target, key) => (key === 'scales' ? scales : Reflect.get(target, key, target))
 	});
-	const movedState = new Proxy(state, {
+	const movedState = new Proxy(plot, {
 		get: (target, key) => {
 			if (key === 'scales') return scales;
 			if (key === 'publicState') return publicState;
@@ -45,4 +79,6 @@
 	setContext('svelteplot', { ...context, getPlotState: () => movedState });
 </script>
 
-{@render children()}
+<g transform={carrying ? `translate(${carry.x} ${carry.y}) scale(${carry.k})` : undefined}>
+	{@render children()}
+</g>

package/dist/layout/coordinates/ProjectionZoom.svelte.d.ts

@@ -3,6 +3,8 @@ import type { GeoZoomTransform } from './zoom.svelte';
 type $$ComponentProps = {
     inner: GeoZoomTransform;
     outer: GeoZoomTransform;
+    /** Milliseconds the view must be still before the marks are re-projected */
+    settleDelay?: number;
     children: Snippet;
 };
 declare const ProjectionZoom: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/layout/coordinates/ZoomedProjection.d.ts

@@ -2,6 +2,10 @@ import type { GeoZoomTransform } from './zoom.svelte';
 import type { StreamingProjection } from '../../plots/utils/tiles';
 /** A fitted projection with a pan and scale applied to where it puts things, so positions move and zoom while what is drawn at them keeps its size. */
 export declare class ZoomedProjection {
+    /** `outer` over `inner` as one pan and scale of the pixels. */
+    static compose(inner: GeoZoomTransform, outer: GeoZoomTransform): GeoZoomTransform;
+    /** The pan and scale that carries what is drawn through `settled` to where `live` puts it. */
+    static between(settled: GeoZoomTransform, live: GeoZoomTransform): GeoZoomTransform;
     /** `projection`, then `outer` over `inner` (each a pan and scale) as one move in pixels. */
     static of(projection: StreamingProjection & {
         aspectRatio?: number;

package/dist/layout/coordinates/ZoomedProjection.js

@@ -1,11 +1,18 @@
 import { geoTransform } from 'd3-geo';
 /** A fitted projection with a pan and scale applied to where it puts things, so positions move and zoom while what is drawn at them keeps its size. */
 export class ZoomedProjection {
+    /** `outer` over `inner` as one pan and scale of the pixels. */
+    static compose(inner, outer) {
+        return { k: inner.k * outer.k, x: outer.k * inner.x + outer.x, y: outer.k * inner.y + outer.y };
+    }
+    /** The pan and scale that carries what is drawn through `settled` to where `live` puts it. */
+    static between(settled, live) {
+        const k = live.k / settled.k;
+        return { k, x: live.x - settled.x * k, y: live.y - settled.y * k };
+    }
     /** `projection`, then `outer` over `inner` (each a pan and scale) as one move in pixels. */
     static of(projection, inner, outer) {
-        const k = inner.k * outer.k;
-        const x = outer.k * inner.x + outer.x;
-        const y = outer.k * inner.y + outer.y;
+        const { k, x, y } = ZoomedProjection.compose(inner, outer);
         if (k === 1 && x === 0 && y === 0)
             return projection;
         const move = geoTransform({

package/dist/layout/figure/Figure.svelte

@@ -98,6 +98,11 @@
 		legend && typeof legend === 'object' && !Array.isArray(legend) ? legend : undefined
 	);
 
+	const offTargets = $derived(legendState.offTargets(extension));
+	$effect(() => {
+		legendState.setOff(offTargets);
+	});
+
 	/** What the legend shows: the author's sections, the ones its plots read as (with `extension`), or none. */
 	const legendMode = $derived(
 		Array.isArray(legend)

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

@@ -37,6 +37,17 @@ export declare class LegendState {
     turnOn(series: string): void;
     /** Turns `series` off with `action`, or back on. */
     toggle(series: string, action: LegendDisabledAction): void;
+    /**
+     * What `extension`'s `off` and `highlight` turn off, by series name: `off`
+     * as listed, and every other series the plots draw for a `highlight`.
+     */
+    offTargets(extension: Pick<LegendExtension, 'off' | 'highlight'> | undefined): Map<string, LegendDisabledAction>;
+    /**
+     * Turns off exactly `targets`, turning back on what an earlier call turned
+     * off and this one leaves out. A series the reader turned off, or turned
+     * off any other way, is left alone.
+     */
+    setOff(targets: Map<string, LegendDisabledAction>): void;
     /** Whether any series is off with `'omit'` - which changes the plot's own rows, not just how they draw. */
     get omits(): boolean;
     /** `series` without those turned off with `'omit'`. */

package/dist/layout/legend/LegendState.svelte.js

@@ -1,5 +1,5 @@
 import { getContext, setContext, untrack } from 'svelte';
-import { SvelteMap } from 'svelte/reactivity';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { getConfiguration } from '../../configuration/config.svelte';
 import { MarkerKinds } from '../../markers/MarkerKinds';
 import { LegendChannels } from './LegendChannels';
@@ -20,6 +20,8 @@ export class LegendState {
     /** The narrowed range of the first interactive continuous section, or `null`. */
     range = $state(null);
     #sources = new SvelteMap();
+    /** What {@link setOff} last turned off, to turn back on what it no longer lists. */
+    #managed = new SvelteMap();
     /** The enclosing figure's legend, or `null` outside one. Call during component init. */
     static current() {
         return getContext(LEGEND_KEY) ?? null;
@@ -67,6 +69,56 @@ export class LegendState {
         else
             this.turnOff(series, action);
     }
+    /**
+     * What `extension`'s `off` and `highlight` turn off, by series name: `off`
+     * as listed, and every other series the plots draw for a `highlight`.
+     */
+    offTargets(extension) {
+        const targets = new SvelteMap();
+        if (extension?.highlight !== undefined) {
+            const kept = new SvelteSet([extension.highlight].flat());
+            for (const entry of this.entries) {
+                if (entry.type === 'series' && !kept.has(entry.name))
+                    targets.set(entry.name, { mode: 'dim' });
+            }
+        }
+        const off = extension?.off;
+        const listed = Array.isArray(off)
+            ? off.map((name) => [name, undefined])
+            : Object.entries(off ?? {});
+        for (const [name, what] of listed) {
+            targets.set(name, typeof what === 'number'
+                ? { mode: 'dim', style: { opacity: what } }
+                : (what ?? { mode: 'dim' }));
+        }
+        return targets;
+    }
+    /**
+     * Turns off exactly `targets`, turning back on what an earlier call turned
+     * off and this one leaves out. A series the reader turned off, or turned
+     * off any other way, is left alone.
+     */
+    setOff(targets) {
+        untrack(() => {
+            const ours = (name) => {
+                const current = this.actionOf(name);
+                const set = this.#managed.get(name);
+                return current && set && JSON.stringify(current) === JSON.stringify(set);
+            };
+            for (const name of this.#managed.keys()) {
+                if (!targets.has(name) && ours(name))
+                    this.turnOn(name);
+            }
+            for (const [name, action] of targets) {
+                if (this.isOff(name) && !ours(name))
+                    continue;
+                if (ours(name) && JSON.stringify(this.#managed.get(name)) === JSON.stringify(action))
+                    continue;
+                this.turnOff(name, action);
+            }
+            this.#managed = new SvelteMap(targets);
+        });
+    }
     /** Whether any series is off with `'omit'` - which changes the plot's own rows, not just how they draw. */
     get omits() {
         return [...this.disabled.values()].some((action) => action.mode === 'omit');

package/dist/layout/margins/PlotMargins.svelte.d.ts

@@ -55,9 +55,12 @@ export declare class PlotMargins {
     static current(): PlotMargins | null;
     /**
      * Measures `el`'s rendered box once its readings settle - again whenever
-     * the content box or `deps` change - and reports how far it reaches past
-     * the content box: to `onOverflow`, and, when `grow` holds, into the room
-     * the margins grow by. Call during component init.
+     * the plot's area or `deps` change - and reports how far it reaches past
+     * that area: to `onOverflow`, and, when `grow` holds, into the room the
+     * margins grow by. The area is where svelteplot draws the marks (see
+     * {@link follow}), not the {@link contentBox}'s estimate: an `'auto'` side
+     * is only its estimate until svelteplot sizes its axes, and what a label
+     * reaches past that is no overflow. Call during component init.
      */
     watch(el: () => SVGGraphicsElement | undefined, options: {
         grow?: () => boolean;
@@ -68,8 +71,9 @@ export declare class PlotMargins {
     reportOverflow(overflow: Margins): void;
     /**
      * Follows the margins svelteplot settles on - `plot` is its `usePlot()`,
-     * only readable inside its `<Plot>` - and reports them to the enclosing
-     * aligned grid cell, if any. Call during the init of a component inside it.
+     * only readable inside its `<Plot>` - to measure against the area they
+     * leave ({@link watch}), and reports them to the enclosing aligned grid
+     * cell, if any. Call during the init of a component inside it.
      */
     follow(plot: {
         options: Record<string, unknown>;

package/dist/layout/margins/PlotMargins.svelte.js

@@ -25,6 +25,8 @@ export class PlotMargins {
     #measured = $state.raw(Margins.ZERO);
     /** The sides the labels settled on, as last handed to `settle`. */
     #settled;
+    /** What svelteplot's own `<Plot>` lays the plot out by, once {@link follow} is handed it. */
+    #plot = $state.raw();
     constructor(inputs) {
         this.#inputs = inputs;
         setContext(PLOT_MARGINS_KEY, this);
@@ -54,14 +56,17 @@ export class PlotMargins {
     }
     /**
      * Measures `el`'s rendered box once its readings settle - again whenever
-     * the content box or `deps` change - and reports how far it reaches past
-     * the content box: to `onOverflow`, and, when `grow` holds, into the room
-     * the margins grow by. Call during component init.
+     * the plot's area or `deps` change - and reports how far it reaches past
+     * that area: to `onOverflow`, and, when `grow` holds, into the room the
+     * margins grow by. The area is where svelteplot draws the marks (see
+     * {@link follow}), not the {@link contentBox}'s estimate: an `'auto'` side
+     * is only its estimate until svelteplot sizes its axes, and what a label
+     * reaches past that is no overflow. Call during component init.
      */
     watch(el, options) {
         $effect(() => {
             const element = el();
-            const bounds = this.contentBox;
+            const bounds = this.#plotArea ?? this.contentBox;
             options.deps?.();
             if (!element)
                 return;
@@ -113,10 +118,12 @@ export class PlotMargins {
     }
     /**
      * Follows the margins svelteplot settles on - `plot` is its `usePlot()`,
-     * only readable inside its `<Plot>` - and reports them to the enclosing
-     * aligned grid cell, if any. Call during the init of a component inside it.
+     * only readable inside its `<Plot>` - to measure against the area they
+     * leave ({@link watch}), and reports them to the enclosing aligned grid
+     * cell, if any. Call during the init of a component inside it.
      */
     follow(plot) {
+        this.#plot = plot;
         const cell = this.#cell;
         if (!cell)
             return;
@@ -236,6 +243,27 @@ export class PlotMargins {
     });
     /** The plot's own area, in pixels: what its margins leave inside its box. */
     contentBox = $derived.by(() => this.numeric.contentBox(this.box.width, this.box.height));
+    /**
+     * The plot's own area as svelteplot lays it out, by the margins it settled on, or `undefined` until
+     * the plot is followed. {@link contentBox} reads an `'auto'` side as its estimate, which is not where
+     * svelteplot draws the marks until its axes are sized.
+     */
+    #plotArea = $derived.by(() => {
+        const options = this.#plot?.options;
+        if (!options)
+            return undefined;
+        const sides = [
+            options.marginTop,
+            options.marginRight,
+            options.marginBottom,
+            options.marginLeft
+        ];
+        if (sides.some((side) => typeof side !== 'number' || !Number.isFinite(side)))
+            return undefined;
+        const [top, right, bottom, left] = sides;
+        const { width, height } = this.#inputs.size();
+        return new Margins(top, right, bottom, left).contentBox(width, height);
+    });
     /**
      * Where something of `size` sits next to `point`, on its preferred side
      * per axis, without leaving the plot's box - see {@link Box.placeNear}.

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

@@ -17,8 +17,11 @@ export declare function resolveSegmentsForSeries<TStyle>(segments: SegmentsConfi
 export declare function matchesSegmentX<TStyle>(xVal: AxisValue, seg: Segment<TStyle>): boolean;
 /**
  * Warns about obvious configuration mistakes: multiple catch-all segments
- * (no `areas`) in the same series list. Since catch-alls are evaluated last
- * and in order, only the first one can ever match; later ones are dead code.
+ * (no `areas`) in the same series list that reach the same facet panels.
+ * Since catch-alls are evaluated last and in order, only the first one can
+ * ever match; later ones are dead code. A catch-all that names a `facet`
+ * does not compete with one for another panel, nor with the unscoped one,
+ * which it overrides in its own panels.
  */
 export declare function validateSegments<TStyle>(segments: SegmentsConfig<TStyle>): void;
 export declare function buildGroupedSeries<S extends Series<any>, TStyle = LineSegmentStyle>(seriesList: S[], segments?: SegmentsConfig<TStyle>, connect?: boolean): VisualGroup<S, TStyle>[];

package/dist/plots/utils/segments.js

@@ -49,12 +49,22 @@ function areaMatchesXY(xVal, yVal, area) {
 /* eslint-enable @typescript-eslint/no-explicit-any */
 /**
  * Warns about obvious configuration mistakes: multiple catch-all segments
- * (no `areas`) in the same series list. Since catch-alls are evaluated last
- * and in order, only the first one can ever match; later ones are dead code.
+ * (no `areas`) in the same series list that reach the same facet panels.
+ * Since catch-alls are evaluated last and in order, only the first one can
+ * ever match; later ones are dead code. A catch-all that names a `facet`
+ * does not compete with one for another panel, nor with the unscoped one,
+ * which it overrides in its own panels.
  */
 export function validateSegments(segments) {
     const check = (label, segs) => {
-        const catchAlls = segs.filter((s) => !s.areas || s.areas.length === 0).length;
+        const perScope = new Map();
+        for (const seg of segs) {
+            if (seg.areas && seg.areas.length > 0)
+                continue;
+            const scope = JSON.stringify(seg.facet ?? null);
+            perScope.set(scope, (perScope.get(scope) ?? 0) + 1);
+        }
+        const catchAlls = Math.max(0, ...perScope.values());
         if (catchAlls > 1) {
             console.warn(`segments ${label}: ${catchAlls} entries have no areas - ` +
                 `only the first catch-all's style will be used.`);

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

@@ -292,6 +292,20 @@ export type ColorOverride = Omit<ContinuousLegendSection, 'type' | 'min' | 'max'
  * ramp `interactive`, and only its first ramp is.
  */
 export type LegendExtension = {
+    /**
+     * Series to turn off from code, as if the reader had clicked them: a list
+     * of names (each dimmed, to `legend.disabledOpacity`), or a name → what
+     * turning it off does map - an opacity to dim to, or a full
+     * {@link LegendDisabledAction} (`dim`, `hide` or `omit`). It follows the
+     * value it is given: a series left out is turned back on. One the reader
+     * turned off themselves is left as it is.
+     */
+    off?: string[] | Record<string, number | LegendDisabledAction>;
+    /**
+     * The series to keep on: every other series is dimmed, the inverse of
+     * listing the rest in `off`. An entry of `off` for a series wins.
+     */
+    highlight?: string | string[];
     items?: LegendItem[];
     sections?: LegendSection[];
     series?: Omit<DiscreteLegendSection, 'type' | 'items'>;

package/docs/legend.md

@@ -101,6 +101,20 @@ legend={{
 
 Each key is the name of the channel (the plot's own prop: `r` for the size section) and adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
 
+### Turning series off from code
+
+`off` turns series off as if the reader had clicked them, without a click: a list of names (each dimmed, to `legend.disabledOpacity`), or a name → opacity or name → action map, where an action is the same `{ mode: 'dim' | 'hide' | 'omit' }` a toggle does. `highlight` is its inverse: it keeps the series it names on and dims all the others. An `off` entry for a series wins over `highlight`.
+
+```ts
+legend={{ off: ['2020'] }}                                  // dim
+legend={{ off: { '2020': 0.1, '2021': { mode: 'omit' } } }} // dim to 0.1, drop from the plot
+legend={{ highlight: 'Argentina' }}                         // everything else dims
+// A facet plot: dim a series only when no panel shows it.
+legend={{ off: ages.filter((age) => facets.every((f) => !visible[f].includes(age))) }}
+```
+
+They follow the value they are given: a series left out is turned back on, and one the reader turned off themselves is left as it is.
+
 ## Explicit sections
 
 A list replaces the automatic legend with exactly those sections:

package/package.json

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