@fundar/data-chart-telling 1.17.0 → 1.19.0

package/dist/layout/hover/HoverShapes.js

@@ -0,0 +1,163 @@
+import { MarkerStyles } from '../../phases/markers/MarkerStyles';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+import { RowStyle } from '../../markers/utils/RowStyle';
+/**
+ * The look the plot's hover markers give the shapes of every marker linked to the hover (`hover: true` or
+ * `'style'`): the hovered ones take `active`, the others `others`, each over the shape's own style. A shape
+ * the legend dims keeps its own fill and opacities; one the hover cannot reach (hidden, omitted) is untouched.
+ *
+ * The marker stays one marker over all its rows, whatever is hovered: each style the hover sets is a function of
+ * the row that asks the hover how it reaches it. Moving the pointer then only draws the marker's shapes again in
+ * their new look - their rows and options do not change, so svelteplot never works the plot's scales out again
+ * (it does so from every mark's data and options, and a style with no scale is never read for them).
+ */
+export class HoverShapes {
+    /** What the legend owns on a dimmed shape. */
+    static #LEGEND_KEYS = new Set(['fill', 'fillOpacity', 'strokeOpacity']);
+    /** The fields that draw a shape's outline. */
+    static #OUTLINE_KEYS = [
+        'stroke',
+        'strokeWidth',
+        'strokeOpacity',
+        'strokeDasharray'
+    ];
+    /** The fields that hold an opacity, fully opaque unless set. */
+    static #OPACITY_KEYS = new Set(['fillOpacity', 'strokeOpacity']);
+    /** The fields that hold a color: a string is the field of the rows it names, else the color itself. */
+    static #COLOR_KEYS = new Set(['fill', 'stroke']);
+    /** A shape style's field as a `dot` marker names it. */
+    static #DOT_KEYS = {
+        fill: 'dotFill',
+        fillOpacity: 'dotFillOpacity',
+        stroke: 'dotStroke',
+        strokeWidth: 'dotStrokeWidth',
+        strokeOpacity: 'dotStrokeOpacity',
+        strokeDasharray: 'dotStrokeDasharray'
+    };
+    #rules;
+    /** The fields any rule sets, in either role. */
+    #fields;
+    constructor(markers) {
+        this.#rules = markers.filter((m) => m.type === 'hover' && !!(m.active || m.others));
+        this.#fields = [
+            ...new Set(this.#rules.flatMap((rule) => [rule.active, rule.others].flatMap((style) => Object.entries(style ?? {})
+                .filter(([, value]) => value !== undefined)
+                .map(([name]) => name))))
+        ];
+    }
+    /** Whether any hover marker restyles shapes. */
+    get any() {
+        return this.#rules.length > 0;
+    }
+    /** Whether `marker`'s shapes take the hover's styles. */
+    static links(marker) {
+        const hover = marker.hover;
+        return hover === true || hover === 'style';
+    }
+    /**
+     * `marker` with each style the hover sets as a function of the row: the hovered rows take `active`, the others
+     * `others`, and while nothing is hovered every row its own style. A marker the hover does not style is returned
+     * as it is. `rows` are what the marker draws without `data` of its own.
+     *
+     * The outline `active` sets is not the shape's own: {@link outline} draws it over every shape, whole.
+     */
+    styled(marker, rows, reach) {
+        return this.#styled(marker, rows, reach, false);
+    }
+    /** {@link styled}, with `active`'s outline on the shapes themselves when `outlined`. */
+    #styled(marker, rows, reach, outlined) {
+        if (!this.any || !HoverShapes.links(marker))
+            return marker;
+        const own = { ...marker.styles };
+        const data = (marker.data ?? rows);
+        const isDot = marker.type === 'dot';
+        const styles = { ...own };
+        for (const field of this.#fields) {
+            const name = isDot ? HoverShapes.#DOT_KEYS[field] : field;
+            const base = HoverShapes.#reader(field, own[name], data);
+            styles[name] = (row, index) => {
+                const value = this.#hovered(field, row, index, reach, outlined);
+                return value === undefined ? base(row, index) : value;
+            };
+        }
+        return MarkerStyles.restyle({ ...marker, styles }, { cfg: reach.cfg, rows: [...data] });
+    }
+    /** Whether any rule outlines the hovered shapes: an `active` that sets one of the stroke's fields. */
+    get outlines() {
+        return this.#rules.some((rule) => HoverShapes.#outlining(rule));
+    }
+    /**
+     * The outline of `marker`'s hovered shapes, to draw over every shape of the plot: the marker over its hovered
+     * rows only, with no fill, no label and no pointer of its own. A shape is drawn in its marker's order, so its
+     * neighbours drawn after it would cover part of its outline - a treemap's tile, a heatmap's cell with no gap.
+     * `undefined` when no rule outlines the shapes or nothing of the marker is hovered.
+     */
+    outline(marker, rows, reach) {
+        if (!this.outlines || !HoverShapes.links(marker))
+            return undefined;
+        const rules = this.#rules.filter((rule) => HoverShapes.#outlining(rule));
+        const data = (marker.data ?? rows).filter((row) => rules.some((rule) => (rule.series === undefined || row?.[SERIES_KEY] === rule.series) &&
+            reach.roleOf(row, rule.series) === 'active'));
+        if (data.length === 0)
+            return undefined;
+        const styled = this.#styled(marker, rows, reach, true);
+        const isDot = marker.type === 'dot';
+        const unfilled = isDot
+            ? { dotFill: 'none', dotFillOpacity: 0 }
+            : { fill: 'none', fillOpacity: 0 };
+        const rest = Object.fromEntries(Object.entries(styled).filter(([key]) => key !== 'label' && key !== 'hover' && !key.startsWith('on')));
+        return {
+            ...rest,
+            data,
+            styles: { ...styled.styles, ...unfilled }
+        };
+    }
+    static #outlining(rule) {
+        const active = rule.active ?? {};
+        return HoverShapes.#OUTLINE_KEYS.some((key) => active[key] !== undefined);
+    }
+    /**
+     * What the hover sets `field` to on `row` - the last rule that reaches the row and sets it wins - or `undefined`
+     * when none does: the row is not hovered, or the legend dims it and `field` is the legend's. An outline `active`
+     * sets is left to the outline drawn over every shape, unless `outlined`.
+     */
+    #hovered(field, row, index, reach, outlined) {
+        let value;
+        let dimmed;
+        for (const rule of this.#rules) {
+            if (rule.series !== undefined && row?.[SERIES_KEY] !== rule.series)
+                continue;
+            const role = reach.roleOf(row, rule.series);
+            const style = role === 'active' ? rule.active : role === 'other' ? rule.others : undefined;
+            const own = style?.[field];
+            if (own === undefined)
+                continue;
+            if (role === 'active' &&
+                !outlined &&
+                HoverShapes.#OUTLINE_KEYS.includes(field) &&
+                HoverShapes.#outlining(rule))
+                continue;
+            dimmed ??= HoverShapes.#LEGEND_KEYS.has(field) && reach.dimmed(row);
+            if (dimmed)
+                return undefined;
+            value = typeof own === 'function' ? own(row, index) : own;
+        }
+        return value;
+    }
+    /** How the shape's own `style` for `field` reads on a row, as the marker would draw it. */
+    static #reader(field, style, rows) {
+        if (typeof style === 'function')
+            return style;
+        // An opacity is a channel of the mark, and svelteplot leaves out a row whose channel reads nothing.
+        if (style === undefined && HoverShapes.#OPACITY_KEYS.has(field))
+            return () => 1;
+        if (typeof style !== 'string' || field === 'strokeDasharray')
+            return () => style;
+        if (HoverShapes.#COLOR_KEYS.has(field)) {
+            const color = RowStyle.colorOf(style, rows);
+            return color ? (row) => color(row) : () => style;
+        }
+        // A number (an opacity, a width) a string names the field of.
+        return (row) => row?.[style];
+    }
+}

package/dist/layout/hover/PlotHover.svelte.d.ts

@@ -1,6 +1,7 @@
 import { HoverState } from './HoverState.svelte';
 import type { AxisValue } from '../../types/layout/mapping';
 import type { HoverPoint } from '../../types/layout/hover';
+import type { HoverLook } from '../../types/markers/common';
 import type { HoverConfig } from '../../types/plots/props';
 /** What a plot's hover is built from, each read reactively. */
 export type PlotHoverInputs<T extends Record<string, unknown>> = {
@@ -23,6 +24,12 @@ export declare class PlotHover<T extends Record<string, unknown>> {
     #private;
     readonly state: HoverState;
     constructor(inputs: PlotHoverInputs<T>);
+    /**
+     * How the hover reaches `row`: `'active'` while it is matched, `'other'` while it can be hovered but is not,
+     * `null` while nothing is hovered here or it is no row the hover can reach (one the legend hides). A row is
+     * found by identity, else by its x, y and `series`. `series` narrows the active rows to that series.
+     */
+    roleOf(row: T, series?: string): 'active' | 'other' | null;
     /** The matched points the tooltip reads: only the tooltip's `series`, when it names some. */
     readonly matchedRows: HoverPoint<T>[];
     /** The points the hover marker highlights. */
@@ -33,6 +40,7 @@ export declare class PlotHover<T extends Record<string, unknown>> {
         series: string | undefined;
         color: string | undefined;
         areaInset: import("../../types/layout/hover").BandSlice | undefined;
+        context: import("../..").PlotRowContext | undefined;
         row: T;
     }[];
     /**
@@ -40,10 +48,20 @@ export declare class PlotHover<T extends Record<string, unknown>> {
      * among ties, the one at the hovered x and y. Crosshair rules sit on it.
      */
     readonly activePoint: HoverPoint<T> | null;
+    /**
+     * The plot kind's own hover under the strategy in force - the figure's, which a composer or a scrolly step can
+     * change while the plot is shown - for an author's `hover` marker to be laid over.
+     */
+    get look(): HoverLook;
     /** Whether a crosshair rule runs across x - the strategy's, unless the config turns them off. */
     get impliesCrosshairX(): boolean;
     /** Whether a crosshair rule runs across y. */
     get impliesCrosshairY(): boolean;
+    /** The pointer's position in the plot's box, while it is over this plot. */
+    get cursor(): {
+        x: number;
+        y: number;
+    } | null;
     /** Whether the tooltip shows: under the cursor in the owning plot, in every synced one. */
     get showTooltip(): boolean;
     /** Where the tooltip sits: the cursor, else the hovered point, else the owning plot's cursor carried over. */

package/dist/layout/hover/PlotHover.svelte.js

@@ -1,3 +1,4 @@
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
 import { HoverState } from './HoverState.svelte';
 /**
  * One plot's hover: the figure's {@link HoverState} (or its own, outside a
@@ -46,6 +47,46 @@ export class PlotHover {
             return [];
         return this.state.match(this.#inputs.hover().points);
     });
+    /** A row's place, as a key: its x, y and series. */
+    static #keyOf(x, y, series) {
+        const plain = (value) => (value instanceof Date ? +value : value);
+        return JSON.stringify([plain(x), plain(y), series ?? null]);
+    }
+    // The rows the hover can reach, and the matched ones: by identity, and by their place. Built whole
+    // inside this derivation and never changed after it, so they have nothing to react to.
+    #reach = $derived.by(() => {
+        const points = this.#inputs.hover().points;
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const matched = new Set(this.#matched);
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const byRow = new Map(points.map((p) => [p.row, p]));
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const byPlace = new Map(points.map((p) => [PlotHover.#keyOf(p.x, p.y, p.series), p]));
+        return { matched, byRow, byPlace };
+    });
+    /**
+     * How the hover reaches `row`: `'active'` while it is matched, `'other'` while it can be hovered but is not,
+     * `null` while nothing is hovered here or it is no row the hover can reach (one the legend hides). A row is
+     * found by identity, else by its x, y and `series`. `series` narrows the active rows to that series.
+     */
+    roleOf(row, series) {
+        const { matched, byRow, byPlace } = this.#reach;
+        if (matched.size === 0)
+            return null;
+        const point = byRow.get(row) ?? this.#placed(byPlace, row);
+        if (!point)
+            return null;
+        return matched.has(point) && (series === undefined || point.series === series)
+            ? 'active'
+            : 'other';
+    }
+    /** The point at `row`'s place: of its own series, else of none (a heatmap's cell). */
+    #placed(byPlace, row) {
+        const x = this.#inputs.getX()(row);
+        const y = this.#inputs.getY()(row);
+        const series = row[SERIES_KEY];
+        return (byPlace.get(PlotHover.#keyOf(x, y, series)) ?? byPlace.get(PlotHover.#keyOf(x, y, undefined)));
+    }
     /** The matched points the tooltip reads: only the tooltip's `series`, when it names some. */
     matchedRows = $derived.by(() => {
         const series = this.#inputs.hover().tooltip?.series;
@@ -54,13 +95,14 @@ export class PlotHover {
         return this.#matched.filter((p) => p.series != null && series.includes(p.series));
     });
     /** The points the hover marker highlights. */
-    points = $derived(this.#matched.map(({ x, y, label, series, color, areaInset, row }) => ({
+    points = $derived(this.#matched.map(({ x, y, label, series, color, areaInset, context, row }) => ({
         x,
         y,
         label,
         series,
         color,
         areaInset,
+        context,
         row
     })));
     /**
@@ -79,6 +121,13 @@ export class PlotHover {
         return (candidates.find((p) => HoverState.same(p.x, activeX) && HoverState.same(p.y, activeY)) ??
             candidates[0]);
     });
+    /**
+     * The plot kind's own hover under the strategy in force - the figure's, which a composer or a scrolly step can
+     * change while the plot is shown - for an author's `hover` marker to be laid over.
+     */
+    get look() {
+        return this.#inputs.hover().look?.(this.state.strategy) ?? {};
+    }
     /** Whether a crosshair rule runs across x - the strategy's, unless the config turns them off. */
     get impliesCrosshairX() {
         return this.#inputs.hover().crosshair !== false && this.state.crosshairX;
@@ -87,6 +136,10 @@ export class PlotHover {
     get impliesCrosshairY() {
         return this.#inputs.hover().crosshair !== false && this.state.crosshairY;
     }
+    /** The pointer's position in the plot's box, while it is over this plot. */
+    get cursor() {
+        return this.#cursor;
+    }
     /** Whether the tooltip shows: under the cursor in the owning plot, in every synced one. */
     get showTooltip() {
         if (this.matchedRows.length === 0)

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

@@ -31,6 +31,8 @@ export declare class LegendState {
     }): boolean;
     /** Whether `series` is turned off. */
     isOff(series: string): boolean;
+    /** Whether `series` is out of the hover: turned off any way but `'dim'`, which leaves it drawn and hoverable. */
+    isUnhoverable(series: string): boolean;
     /** What turning `series` off does, while it is off. */
     actionOf(series: string): LegendDisabledAction | undefined;
     turnOff(series: string, action: LegendDisabledAction): void;

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

@@ -52,6 +52,11 @@ export class LegendState {
     isOff(series) {
         return this.disabled.has(series);
     }
+    /** Whether `series` is out of the hover: turned off any way but `'dim'`, which leaves it drawn and hoverable. */
+    isUnhoverable(series) {
+        const action = this.disabled.get(series);
+        return action !== undefined && action.mode !== 'dim';
+    }
     /** What turning `series` off does, while it is off. */
     actionOf(series) {
         return this.disabled.get(series);

package/dist/layout/margins/Box.d.ts

@@ -37,6 +37,10 @@ export declare class Box {
     get empty(): boolean;
     /** How far this box reaches out from its origin (the point it sits around), in whole pixels. */
     get reach(): Margins;
+    /** Whether this box and `other` share any area. */
+    intersects(other: Box): boolean;
+    /** Whether this box lies wholly inside `bounds`. */
+    inside(bounds: Box): boolean;
     /** This box grown by `px` on every side. */
     pad(px: number): Box;
     /**

package/dist/layout/margins/Box.js

@@ -61,6 +61,20 @@ export class Box {
     get reach() {
         return this.overflow(Box.size(0, 0));
     }
+    /** Whether this box and `other` share any area. */
+    intersects(other) {
+        return (this.left < other.right &&
+            other.left < this.right &&
+            this.top < other.bottom &&
+            other.top < this.bottom);
+    }
+    /** Whether this box lies wholly inside `bounds`. */
+    inside(bounds) {
+        return (this.left >= bounds.left &&
+            this.right <= bounds.right &&
+            this.top >= bounds.top &&
+            this.bottom <= bounds.bottom);
+    }
     /** This box grown by `px` on every side. */
     pad(px) {
         return new Box(this.x - px, this.y - px, this.width + 2 * px, this.height + 2 * px);

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

@@ -1,4 +1,5 @@
 import { getContext, setContext } from 'svelte';
+import { get } from 'svelte/store';
 import { Margins } from './Margins';
 import { Box } from './Box';
 import { CellAlignment } from '../grid/GridAlignment.svelte';
@@ -27,6 +28,17 @@ export class PlotMargins {
     #settled;
     /** What svelteplot's own `<Plot>` lays the plot out by, once {@link follow} is handed it. */
     #plot = $state.raw();
+    /** The room svelteplot's axes ask of each side, whether or not it is `'auto'`, once {@link follow} reads it. */
+    #autoMargins = $state.raw();
+    #auto = $derived.by(() => {
+        const maps = this.#autoMargins;
+        if (!maps)
+            return {};
+        return Object.fromEntries(Margins.SIDES.flatMap((side) => {
+            const values = [...maps[side].values()];
+            return values.length ? [[side, Math.max(...values)]] : [];
+        }));
+    });
     constructor(inputs) {
         this.#inputs = inputs;
         setContext(PLOT_MARGINS_KEY, this);
@@ -124,6 +136,10 @@ export class PlotMargins {
      */
     follow(plot) {
         this.#plot = plot;
+        const stores = getContext('svelteplot/autoMargins');
+        if (stores) {
+            this.#autoMargins = Object.fromEntries(Margins.SIDES.map((side) => [side, get(stores[PlotMargins.#AUTO_STORE[side]])]));
+        }
         const cell = this.#cell;
         if (!cell)
             return;
@@ -132,6 +148,12 @@ export class PlotMargins {
             cell.report(new Margins(Number(marginTop) || 0, Number(marginRight) || 0, Number(marginBottom) || 0, Number(marginLeft) || 0));
         });
     }
+    static #AUTO_STORE = {
+        top: 'autoMarginTop',
+        right: 'autoMarginRight',
+        bottom: 'autoMarginBottom',
+        left: 'autoMarginLeft'
+    };
     /** The room the `reserve` boxes take past the edges their points can sit on. */
     #reserved = $derived.by(() => this.#inputs.reserve().reduce((room, { box, edges }) => {
         const reach = box.reach;
@@ -143,7 +165,10 @@ export class PlotMargins {
         const settled = this.#settled;
         const { width, height } = this.#inputs.size();
         const growth = this.#measured.max(this.#reserved).min(Margins.half(width, height));
-        const estimate = this.#inputs.estimate();
+        // A side grows from at least the room svelteplot's axes take on it: their ticks and title.
+        const estimate = this.#inputs
+            .estimate()
+            .map((value, side) => Math.max(value, this.#auto[side] ?? 0));
         const out = {};
         for (const side of Margins.SIDES) {
             const own = author?.[side];

package/dist/layout/plot/{Plot.svelte.d.ts → AbstractPlot.svelte.d.ts}

@@ -45,6 +45,6 @@ interface $$IsomorphicComponent {
     <TRow extends Record<string, unknown>, TScales extends object, TCore extends PlotCoreBase>(internal: unknown, props: ReturnType<__sveltets_Render<TRow, TScales, TCore>['props']> & {}): ReturnType<__sveltets_Render<TRow, TScales, TCore>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any, any, any>['bindings']>;
 }
-declare const Plot: $$IsomorphicComponent;
-type Plot<TRow extends Record<string, unknown>, TScales extends object, TCore extends PlotCoreBase> = InstanceType<typeof Plot<TRow, TScales, TCore>>;
-export default Plot;
+declare const AbstractPlot: $$IsomorphicComponent;
+type AbstractPlot<TRow extends Record<string, unknown>, TScales extends object, TCore extends PlotCoreBase> = InstanceType<typeof AbstractPlot<TRow, TScales, TCore>>;
+export default AbstractPlot;

package/dist/layout/plot/Core.svelte

@@ -47,12 +47,12 @@
 
 	const cfg = $derived(getConfiguration());
 	const interaction = PlotInteraction.current(() => cfg);
-	const ctx = $derived({ cfg, interaction, range: interaction.legend?.range });
+	const env = $derived({ cfg, interaction, range: interaction.legend?.range });
 
 	const plotState = $derived(
 		pipeline!.run(
 			{ ...rest, width, height, styles, segments, markers, scales, margins },
-			ctx,
+			env,
 			panelState
 		)
 	);

package/dist/layout/plot/PublicPlotContext.d.ts

@@ -7,6 +7,7 @@ import type { PlotHover } from '../hover/PlotHover.svelte';
 import type { Margins } from '../margins/Margins';
 import type { PlotAxes } from '../../phases/data/PlotAxes';
 import type { AxisValue } from '../../types/layout/mapping';
+import type { PlotRowContext } from '../../types/layout/context';
 import type { HoverPoint, HoverStrategy } from '../../types/layout/hover';
 import type { PlayerControl, TimeInput, TimelineStep } from '../../types/layout/timeline';
 import type { LegendDisabledAction, LegendEntry, LegendRange } from '../../types/layout/legend';
@@ -126,6 +127,11 @@ export declare class PublicPlotContext<T extends Record<string, unknown> = Recor
     get axes(): PlotAxes | undefined;
     /** The rows the plot draws and hovers over. */
     get data(): T[];
+    /**
+     * What the plot knows of one of the rows it draws (or a copy of it, as a mark's accessor gets it): its series,
+     * where it sits, the value it shows and whatever the plot kind works out for it - see {@link PlotRowContext}.
+     */
+    contextOf<TContext extends PlotRowContext<T> = PlotRowContext<T>>(row: unknown): TContext;
     /** The color a series is drawn in, by its name - `undefined` for a plot with no series (a map). */
     get colorForSeries(): ((name: string) => string) | undefined;
     get width(): number;

package/dist/layout/plot/PublicPlotContext.js

@@ -2,6 +2,7 @@ import { usePlot as usePlotFromSvelteplot } from 'svelteplot';
 import { HoverState } from '../hover/HoverState.svelte';
 import { LegendState } from '../legend/LegendState.svelte';
 import { PlotContext } from './PlotContext';
+import { RowContext } from '../../phases/context/RowContext';
 import { TimelineState } from '../timeline/TimelineState.svelte';
 /** What the pointer is over, shared by every plot in a figure. Read-only. */
 export class PublicHover {
@@ -231,6 +232,13 @@ export class PublicPlotContext {
     get data() {
         return this.#context.data;
     }
+    /**
+     * What the plot knows of one of the rows it draws (or a copy of it, as a mark's accessor gets it): its series,
+     * where it sits, the value it shows and whatever the plot kind works out for it - see {@link PlotRowContext}.
+     */
+    contextOf(row) {
+        return RowContext.of(row);
+    }
     /** The color a series is drawn in, by its name - `undefined` for a plot with no series (a map). */
     get colorForSeries() {
         return this.#context.colorForSeries;