@fundar/data-chart-telling 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.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/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/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.4.0",
   "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
   "license": "MIT",
   "author": "Ezequiel Puerta",