@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/layout/grid/GridPlan.js

@@ -0,0 +1,167 @@
+import { Margins } from '../margins/Margins';
+/**
+ * Where a grid's cells sit, without Svelte: each cell's slot - a named
+ * `area`'s box in `areas`, an explicit `row`/`col` of its own, or, in order,
+ * the next slot nothing claimed (adding rows as needed) - the grid's size,
+ * which sides of each cell face no other cell, and the pixel tracks for a
+ * box ({@link GridPlan.tracks}). Without `areas`, `columns` defaults to the
+ * smallest square that fits every cell.
+ */
+export class GridPlan {
+    rows;
+    columns;
+    /** Each cell's slot, in the order the cells came. */
+    spans;
+    #areas;
+    #edges;
+    constructor(cells, options = {}) {
+        const args = { cells, ...options };
+        const areaRows = GridPlan.#parseAreas(args.areas);
+        const columns = Math.max(1, areaRows?.[0]?.length ?? args.columns ?? Math.ceil(Math.sqrt(args.cells.length || 1)));
+        const taken = new Set();
+        const claim = (span) => {
+            for (let r = span.row; r < span.row + span.rowSpan; r++)
+                for (let c = span.col; c < span.col + span.colSpan; c++)
+                    taken.add(`${r}:${c}`);
+        };
+        const spans = args.cells.map((cell) => {
+            const named = cell.area && areaRows ? GridPlan.#areaSpan(areaRows, cell.area) : null;
+            const span = named ??
+                (cell.row !== undefined || cell.col !== undefined
+                    ? {
+                        row: cell.row ?? 0,
+                        col: cell.col ?? 0,
+                        rowSpan: cell.rowSpan ?? 1,
+                        colSpan: cell.colSpan ?? 1
+                    }
+                    : null);
+            if (span)
+                claim(span);
+            return span;
+        });
+        // Named areas no cell uses still keep their slots, as CSS grid would.
+        areaRows?.forEach((row, r) => row.forEach((name, c) => name !== '.' && taken.add(`${r}:${c}`)));
+        let next = 0;
+        const placed = spans.map((span) => {
+            if (span)
+                return span;
+            while (taken.has(`${Math.floor(next / columns)}:${next % columns}`))
+                next++;
+            const flowed = {
+                row: Math.floor(next / columns),
+                col: next % columns,
+                rowSpan: 1,
+                colSpan: 1
+            };
+            claim(flowed);
+            return flowed;
+        });
+        const rows = Math.max(areaRows?.length ?? 0, args.rows ?? 1, 1, ...placed.map((span) => span.row + span.rowSpan));
+        this.#areas = areaRows;
+        this.rows = rows;
+        this.columns = columns;
+        this.spans = placed;
+    }
+    /** Which sides of each cell face no other cell - where an `'outer'` axis draws. */
+    get edges() {
+        this.#edges ??= this.#buildEdges();
+        return this.#edges;
+    }
+    /** The slot a named area covers, or `null` when it isn't in `areas`. */
+    areaSpan(name) {
+        return this.#areas ? GridPlan.#areaSpan(this.#areas, name) : null;
+    }
+    /**
+     * Pixel tracks for a `width` x `height` box and every cell's box. Each
+     * track's panel share follows its weight (`widths`, `heights`). With
+     * `margins` (one per cell, all reported), every column takes the widest
+     * left margin among cells starting in it and the widest right among cells
+     * ending in it - rows likewise - and those margins are pinned on the
+     * cells, so every plot area lines up with its row and column. `header` is
+     * the height each row spends above its cells (a label).
+     */
+    tracks(args) {
+        const { rows, columns, spans } = this;
+        const { width, height, gap, header = 0 } = args;
+        const aligned = args.margins != null && args.margins.every((m) => m !== undefined);
+        const marginOf = (i) => (aligned ? args.margins[i] : Margins.ZERO);
+        const colLeft = Array.from({ length: columns }, () => 0);
+        const colRight = Array.from({ length: columns }, () => 0);
+        const rowTop = Array.from({ length: rows }, () => 0);
+        const rowBottom = Array.from({ length: rows }, () => 0);
+        spans.forEach((span, i) => {
+            const m = marginOf(i);
+            const lastCol = span.col + span.colSpan - 1;
+            const lastRow = span.row + span.rowSpan - 1;
+            colLeft[span.col] = Math.max(colLeft[span.col], m.left);
+            colRight[lastCol] = Math.max(colRight[lastCol], m.right);
+            rowTop[span.row] = Math.max(rowTop[span.row], m.top);
+            rowBottom[lastRow] = Math.max(rowBottom[lastRow], m.bottom);
+        });
+        const sum = (values) => values.reduce((a, b) => a + b, 0);
+        const share = (total, weights) => {
+            const whole = sum(weights) || 1;
+            return weights.map((w) => (Math.max(0, total) * w) / whole);
+        };
+        const panelWidths = share(width - (columns - 1) * gap - sum(colLeft) - sum(colRight), GridPlan.#weights(args.widths, columns));
+        const panelHeights = share(height - (rows - 1) * gap - rows * header - sum(rowTop) - sum(rowBottom), GridPlan.#weights(args.heights, rows));
+        const colWidths = panelWidths.map((w, c) => colLeft[c] + w + colRight[c]);
+        const rowHeights = panelHeights.map((h, r) => header + rowTop[r] + h + rowBottom[r]);
+        const span = (tracks, from, count) => sum(tracks.slice(from, from + count)) + (count - 1) * gap;
+        const boxes = spans.map((s) => ({
+            width: Math.max(0, Math.floor(span(colWidths, s.col, s.colSpan))),
+            height: Math.max(0, Math.floor(span(rowHeights, s.row, s.rowSpan) - header)),
+            ...(aligned
+                ? {
+                    margins: new Margins(rowTop[s.row], colRight[s.col + s.colSpan - 1], rowBottom[s.row + s.rowSpan - 1], colLeft[s.col])
+                }
+                : {})
+        }));
+        return { colWidths, rowHeights, boxes };
+    }
+    #buildEdges() {
+        const occupied = new Set();
+        for (const span of this.spans)
+            for (let r = span.row; r < span.row + span.rowSpan; r++)
+                for (let c = span.col; c < span.col + span.colSpan; c++)
+                    occupied.add(`${r}:${c}`);
+        const any = (cells) => cells.some(([r, c]) => occupied.has(`${r}:${c}`));
+        const range = (from, count) => Array.from({ length: count }, (_, i) => from + i);
+        return this.spans.map((span) => {
+            const cols = range(span.col, span.colSpan);
+            const rows = range(span.row, span.rowSpan);
+            return {
+                top: !any(cols.map((c) => [span.row - 1, c])),
+                bottom: !any(cols.map((c) => [span.row + span.rowSpan, c])),
+                left: !any(rows.map((r) => [r, span.col - 1])),
+                right: !any(rows.map((r) => [r, span.col + span.colSpan]))
+            };
+        });
+    }
+    /** `areas` rows split into their cell names. */
+    static #parseAreas(areas) {
+        return areas?.map((row) => row.trim().split(/\s+/));
+    }
+    /** The slot a named area covers: the bounding box of its cells, or `null` when it isn't in `areas`. */
+    static #areaSpan(areas, name) {
+        let top = Infinity;
+        let left = Infinity;
+        let bottom = -1;
+        let right = -1;
+        areas.forEach((row, r) => row.forEach((cell, c) => {
+            if (cell !== name)
+                return;
+            top = Math.min(top, r);
+            left = Math.min(left, c);
+            bottom = Math.max(bottom, r);
+            right = Math.max(right, c);
+        }));
+        if (bottom < 0)
+            return null;
+        return { row: top, col: left, rowSpan: bottom - top + 1, colSpan: right - left + 1 };
+    }
+    /** `weights` when they match `count` tracks, else equal ones. */
+    static #weights(weights, count) {
+        return weights?.length === count ? weights : Array.from({ length: count }, () => 1);
+    }
+}

package/dist/layout/grid/Tags.d.ts

@@ -0,0 +1,8 @@
+import type { ComposerTags } from '../../types/layout/composer';
+/** A sequence of tags - one per composer cell, in the order the cells register. */
+export declare class Tags {
+    #private;
+    constructor(tags: ComposerTags);
+    /** The `index`-th tag. */
+    at(index: number): string | undefined;
+}

package/dist/layout/grid/Tags.js

@@ -0,0 +1,39 @@
+const ROMAN = [
+    [10, 'X'],
+    [9, 'IX'],
+    [5, 'V'],
+    [4, 'IV'],
+    [1, 'I']
+];
+/** A sequence of tags - one per composer cell, in the order the cells register. */
+export class Tags {
+    #tags;
+    constructor(tags) {
+        this.#tags = tags;
+    }
+    /** The `index`-th tag. */
+    at(index) {
+        const tags = this.#tags;
+        if (Array.isArray(tags))
+            return tags[index];
+        if (tags === 'A')
+            return String.fromCharCode(65 + (index % 26));
+        if (tags === 'a')
+            return String.fromCharCode(97 + (index % 26));
+        if (tags === 'I')
+            return Tags.#roman(index + 1);
+        if (tags === 'i')
+            return Tags.#roman(index + 1).toLowerCase();
+        return String(index + 1);
+    }
+    static #roman(n) {
+        let out = '';
+        for (const [value, numeral] of ROMAN) {
+            while (n >= value) {
+                out += numeral;
+                n -= value;
+            }
+        }
+        return out;
+    }
+}

package/dist/layout/hover/HoverScope.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+	import { HoverState } from './HoverState.svelte';
+	import type { Snippet } from 'svelte';
+
+	/** Gives every plot rendered inside its own hover scope - see {@link HoverState.provideScope}. */
+	let { id, children }: { id: string; children: Snippet } = $props();
+
+	HoverState.provideScope(() => id);
+</script>
+
+{@render children()}

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

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    id: string;
+    children: Snippet;
+};
+declare const HoverScope: import("svelte").Component<$$ComponentProps, {}, "">;
+type HoverScope = ReturnType<typeof HoverScope>;
+export default HoverScope;

package/dist/layout/hover/HoverSettings.d.ts

@@ -0,0 +1,20 @@
+import type { TooltipProp } from '../../types/layout/tooltip';
+import type { HoverStrategy } from '../../types/layout/hover';
+import type { TooltipConfig } from '../../types/plots/props';
+/**
+ * How the author set up a plot's hover, from its `tooltip` and its hover
+ * marker (`'hover'`, or `'geo-hover'` on a map): whether it is on, the
+ * strategy that matches points (the tooltip's, else the marker's, else the
+ * plot kind's `defaultStrategy`) and whether it syncs across plots.
+ */
+export declare class HoverSettings<TRow extends Record<string, unknown>> {
+    /** The tooltip, or `undefined` when off. */
+    readonly tooltip: TooltipConfig<TRow> | undefined;
+    /** Whether anything hovers: a tooltip or a hover marker. */
+    readonly active: boolean;
+    readonly strategy: HoverStrategy;
+    readonly sync: boolean;
+    constructor(tooltip: TooltipProp<TRow> | TooltipConfig<TRow> | undefined, markers: {
+        type: string;
+    }[] | undefined, defaultStrategy: HoverStrategy);
+}

package/dist/layout/hover/HoverSettings.js

@@ -0,0 +1,27 @@
+/**
+ * How the author set up a plot's hover, from its `tooltip` and its hover
+ * marker (`'hover'`, or `'geo-hover'` on a map): whether it is on, the
+ * strategy that matches points (the tooltip's, else the marker's, else the
+ * plot kind's `defaultStrategy`) and whether it syncs across plots.
+ */
+export class HoverSettings {
+    /** The tooltip, or `undefined` when off. */
+    tooltip;
+    /** Whether anything hovers: a tooltip or a hover marker. */
+    active;
+    strategy;
+    sync;
+    constructor(tooltip, markers, defaultStrategy) {
+        this.tooltip = !tooltip
+            ? undefined
+            : tooltip === true
+                ? { sync: false }
+                : { ...tooltip, sync: tooltip.sync ?? false };
+        const marker = markers?.find((m) => m.type === 'hover');
+        this.active =
+            this.tooltip !== undefined ||
+                (markers ?? []).some((m) => m.type === 'hover' || m.type === 'geo-hover');
+        this.strategy = this.tooltip?.strategy ?? marker?.strategy ?? defaultStrategy;
+        this.sync = this.tooltip?.sync ?? marker?.sync ?? false;
+    }
+}

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

@@ -0,0 +1,47 @@
+import type { AxisValue } from '../../types/layout/mapping';
+import type { HoverPoint, HoverStore, HoverStrategy } from '../../types/layout/hover';
+/**
+ * What the pointer is over, shared by every plot under one figure: the
+ * hovered x, y and series, where the cursor sits, which plot (hover scope)
+ * owns the hover, and the series a value label isolates. The single source
+ * every consumer reads the hover from.
+ */
+export declare class HoverState implements HoverStore {
+    #private;
+    activeX: AxisValue | null;
+    activeY: AxisValue | null;
+    activeSeries: string | null;
+    cursorFrac: {
+        x: number;
+        y: number;
+    } | null;
+    source: string | null;
+    strategy: HoverStrategy;
+    sync: boolean;
+    /** The enclosing figure's hover, or `null` outside one. Call during component init. */
+    static current(): HoverState | null;
+    /** A new hover, shared with every plot below. Call during component init. */
+    static provide(): HoverState;
+    /** The hover scope of the plots below: which one owns the hover, one per facet panel or composer cell. Call during component init. */
+    static provideScope(id: () => string): void;
+    /** The enclosing hover scope's id, or `''` outside any. Call during component init. */
+    static scope(): () => string;
+    /** Whether two axis values are the same - dates by their time. */
+    static same(a: AxisValue, b: AxisValue): boolean;
+    /** Whether the strategy draws a crosshair rule across x by default. */
+    get crosshairX(): boolean;
+    /** Whether the strategy draws a crosshair rule across y by default. */
+    get crosshairY(): boolean;
+    /** The `points` the current hover highlights, by its strategy. */
+    match<T>(points: HoverPoint<T>[]): HoverPoint<T>[];
+    /** Takes the hover from scope `source`: at `x`/`y`, on `series`. */
+    enter(source: string, x: AxisValue, y: AxisValue, series: string | null): void;
+    /** Ends the hover, if scope `source` owns it - keeping where the cursor is, unless `cursor` is `false`. */
+    leave(source: string, { cursor }?: {
+        cursor?: boolean | undefined;
+    }): void;
+    /** Isolates `series` from the plot in hover `scope` (a hovered value label), or ends it with `null`. */
+    isolate(series: string | null, scope: string): void;
+    /** The series isolated in `scope` - or in any, when the hover is synced. */
+    isolatedIn(scope: string): string | null;
+}

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

@@ -0,0 +1,99 @@
+import { getContext, setContext } from 'svelte';
+const HOVER_KEY = Symbol('dct-hover');
+const HOVER_SCOPE_KEY = Symbol('dct-hover-scope');
+/**
+ * What the pointer is over, shared by every plot under one figure: the
+ * hovered x, y and series, where the cursor sits, which plot (hover scope)
+ * owns the hover, and the series a value label isolates. The single source
+ * every consumer reads the hover from.
+ */
+export class HoverState {
+    activeX = $state(null);
+    activeY = $state(null);
+    activeSeries = $state(null);
+    cursorFrac = $state(null);
+    source = $state(null);
+    strategy = $state('x');
+    sync = $state(false);
+    #isolated = $state(null);
+    /** The enclosing figure's hover, or `null` outside one. Call during component init. */
+    static current() {
+        return getContext(HOVER_KEY) ?? null;
+    }
+    /** A new hover, shared with every plot below. Call during component init. */
+    static provide() {
+        const hover = new HoverState();
+        setContext(HOVER_KEY, hover);
+        return hover;
+    }
+    /** The hover scope of the plots below: which one owns the hover, one per facet panel or composer cell. Call during component init. */
+    static provideScope(id) {
+        setContext(HOVER_SCOPE_KEY, id);
+    }
+    /** The enclosing hover scope's id, or `''` outside any. Call during component init. */
+    static scope() {
+        return getContext(HOVER_SCOPE_KEY) ?? (() => '');
+    }
+    /** Whether two axis values are the same - dates by their time. */
+    static same(a, b) {
+        if (a instanceof Date && b instanceof Date)
+            return +a === +b;
+        return a === b;
+    }
+    /** Whether the strategy draws a crosshair rule across x by default. */
+    get crosshairX() {
+        return this.strategy === 'x' || this.strategy === 'punctual';
+    }
+    /** Whether the strategy draws a crosshair rule across y by default. */
+    get crosshairY() {
+        return this.strategy === 'y' || this.strategy === 'punctual';
+    }
+    /** The `points` the current hover highlights, by its strategy. */
+    match(points) {
+        const { strategy, activeX, activeY, activeSeries } = this;
+        if (strategy === 'x') {
+            return activeX == null ? [] : points.filter((p) => HoverState.same(p.x, activeX));
+        }
+        if (strategy === 'y') {
+            return activeY == null ? [] : points.filter((p) => HoverState.same(p.y, activeY));
+        }
+        if (strategy === 'series') {
+            return activeSeries == null ? [] : points.filter((p) => p.series === activeSeries);
+        }
+        // 'punctual': the exact x and y, of the same series when both sides tag one.
+        if (activeX == null || activeY == null)
+            return [];
+        return points.filter((p) => HoverState.same(p.x, activeX) &&
+            HoverState.same(p.y, activeY) &&
+            (activeSeries == null || p.series == null || p.series === activeSeries));
+    }
+    /** Takes the hover from scope `source`: at `x`/`y`, on `series`. */
+    enter(source, x, y, series) {
+        this.activeX = x;
+        this.activeY = y;
+        this.activeSeries = series;
+        this.source = source;
+    }
+    /** Ends the hover, if scope `source` owns it - keeping where the cursor is, unless `cursor` is `false`. */
+    leave(source, { cursor = false } = {}) {
+        if (this.source !== source)
+            return;
+        this.activeX = null;
+        this.activeY = null;
+        this.activeSeries = null;
+        this.source = null;
+        if (!cursor)
+            this.cursorFrac = null;
+    }
+    /** Isolates `series` from the plot in hover `scope` (a hovered value label), or ends it with `null`. */
+    isolate(series, scope) {
+        this.#isolated = series === null ? null : { series, scope };
+    }
+    /** The series isolated in `scope` - or in any, when the hover is synced. */
+    isolatedIn(scope) {
+        const isolated = this.#isolated;
+        if (!isolated)
+            return null;
+        return isolated.scope === scope || this.sync ? isolated.series : null;
+    }
+}

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

@@ -0,0 +1,63 @@
+import { HoverState } from './HoverState.svelte';
+import type { AxisValue } from '../../types/layout/mapping';
+import type { HoverPoint } from '../../types/layout/hover';
+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>> = {
+    /** The plot's hover config: its points, label, strategy, sync and tooltip. */
+    hover: () => HoverConfig<T>;
+    getX: () => (d: T) => AxisValue;
+    getY: () => (d: T) => AxisValue;
+    /** The plot's box, to carry the cursor to synced plots as a fraction of it. */
+    width: () => number;
+    height: () => number;
+};
+/**
+ * One plot's hover: the figure's {@link HoverState} (or its own, outside a
+ * figure) seen from the plot's hover scope. It turns the pointer into the
+ * shared hover (`onPointer`, `onMove`, `onLeave`) and reads back what the
+ * plot draws: the highlighted points, the hovered one, its crosshairs and
+ * its tooltip. Create it during component init.
+ */
+export declare class PlotHover<T extends Record<string, unknown>> {
+    #private;
+    readonly state: HoverState;
+    constructor(inputs: PlotHoverInputs<T>);
+    /** 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. */
+    readonly points: {
+        x: AxisValue;
+        y: AxisValue;
+        label: string;
+        series: string | undefined;
+        color: string | undefined;
+        areaInset: import("../../types/layout/hover").BandSlice | undefined;
+        row: T;
+    }[];
+    /**
+     * The matched point actually under the cursor: of the hovered series, and
+     * among ties, the one at the hovered x and y. Crosshair rules sit on it.
+     */
+    readonly activePoint: HoverPoint<T> | null;
+    /** 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;
+    /** 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. */
+    get tooltipPosition(): {
+        x: number;
+        y: number;
+    } | null;
+    /** The rows under the pointer, from svelteplot's `Pointer` or a mark's own hit area. */
+    onPointer: (rows: T[]) => void;
+    onMove: (e: PointerEvent) => void;
+    onLeave: () => void;
+    /** The hovered point's pixel position, as the hover marker drew it. */
+    reportActivePointPixel: (position: {
+        x: number;
+        y: number;
+    } | null) => void;
+}

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

@@ -0,0 +1,133 @@
+import { HoverState } from './HoverState.svelte';
+/**
+ * One plot's hover: the figure's {@link HoverState} (or its own, outside a
+ * figure) seen from the plot's hover scope. It turns the pointer into the
+ * shared hover (`onPointer`, `onMove`, `onLeave`) and reads back what the
+ * plot draws: the highlighted points, the hovered one, its crosshairs and
+ * its tooltip. Create it during component init.
+ */
+export class PlotHover {
+    state;
+    #inputs;
+    #scope;
+    #cursor = $state(null);
+    // The hovered point's pixel position, as `HoverMarker` reports it.
+    #activePixel = $state(null);
+    constructor(inputs) {
+        this.#inputs = inputs;
+        this.#scope = HoverState.scope();
+        const shared = HoverState.current();
+        this.state = shared ?? new HoverState();
+        // Outside a figure, the plot's own config drives its own hover.
+        if (!shared) {
+            $effect(() => {
+                this.state.strategy = inputs.hover().strategy ?? 'x';
+                this.state.sync = inputs.hover().sync ?? false;
+            });
+        }
+    }
+    /** Whether this plot owns the hover. */
+    get #owner() {
+        return this.state.source === this.#scope();
+    }
+    /** The point a hit row is: by identity, else by its x and y (svelteplot's `Pointer` hands back clones). */
+    #pointFor(row) {
+        const points = this.#inputs.hover().points;
+        const byIdentity = points.find((p) => p.row === row);
+        if (byIdentity)
+            return byIdentity;
+        const x = this.#inputs.getX()(row);
+        const y = this.#inputs.getY()(row);
+        return points.find((p) => HoverState.same(p.x, x) && HoverState.same(p.y, y));
+    }
+    // The points matched here: in the owning plot, or in every one while synced.
+    #matched = $derived.by(() => {
+        if (!this.#owner && !this.state.sync)
+            return [];
+        return this.state.match(this.#inputs.hover().points);
+    });
+    /** 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;
+        if (!series || series.length === 0)
+            return this.#matched;
+        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 }) => ({
+        x,
+        y,
+        label,
+        series,
+        color,
+        areaInset,
+        row
+    })));
+    /**
+     * The matched point actually under the cursor: of the hovered series, and
+     * among ties, the one at the hovered x and y. Crosshair rules sit on it.
+     */
+    activePoint = $derived.by(() => {
+        const matched = this.#matched;
+        if (matched.length === 0)
+            return null;
+        const { activeSeries, activeX, activeY } = this.state;
+        const bySeries = matched.filter((p) => p.series === activeSeries);
+        const candidates = bySeries.length > 0 ? bySeries : matched;
+        if (candidates.length === 1 || activeX == null || activeY == null)
+            return candidates[0];
+        return (candidates.find((p) => HoverState.same(p.x, activeX) && HoverState.same(p.y, activeY)) ??
+            candidates[0]);
+    });
+    /** 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;
+    }
+    /** Whether a crosshair rule runs across y. */
+    get impliesCrosshairY() {
+        return this.#inputs.hover().crosshair !== false && this.state.crosshairY;
+    }
+    /** Whether the tooltip shows: under the cursor in the owning plot, in every synced one. */
+    get showTooltip() {
+        if (this.matchedRows.length === 0)
+            return false;
+        return this.#owner ? this.#cursor != null : this.state.sync;
+    }
+    /** Where the tooltip sits: the cursor, else the hovered point, else the owning plot's cursor carried over. */
+    get tooltipPosition() {
+        if (this.#cursor)
+            return this.#cursor;
+        if (this.#activePixel)
+            return this.#activePixel;
+        const frac = this.state.cursorFrac;
+        return frac ? { x: frac.x * this.#inputs.width(), y: frac.y * this.#inputs.height() } : null;
+    }
+    /** The rows under the pointer, from svelteplot's `Pointer` or a mark's own hit area. */
+    onPointer = (rows) => {
+        const row = rows[0];
+        if (row === undefined) {
+            this.state.leave(this.#scope(), { cursor: true });
+            return;
+        }
+        const point = this.#pointFor(row);
+        this.state.enter(this.#scope(), point?.x ?? this.#inputs.getX()(row), point?.y ?? this.#inputs.getY()(row), point?.series ?? null);
+    };
+    onMove = (e) => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const y = e.clientY - rect.top;
+        this.#cursor = { x, y };
+        const width = this.#inputs.width();
+        const height = this.#inputs.height();
+        if (width > 0 && height > 0)
+            this.state.cursorFrac = { x: x / width, y: y / height };
+    };
+    onLeave = () => {
+        this.#cursor = null;
+        this.state.leave(this.#scope());
+    };
+    /** The hovered point's pixel position, as the hover marker drew it. */
+    reportActivePointPixel = (position) => {
+        this.#activePixel = position;
+    };
+}

package/dist/layout/interaction/PlotInteraction.svelte.d.ts

@@ -0,0 +1,38 @@
+import { LegendState } from '../legend/LegendState.svelte';
+import { HoverState } from '../hover/HoverState.svelte';
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+import type { LegendDisabledStyle } from '../../types/layout/legend';
+import type { DotStyle, StrokeStyle } from '../../types/plots/styling';
+/**
+ * What the reader is doing with one plot: the legend's toggles and the
+ * figure's hover, read in the plot's own hover scope. Its phases ask it how
+ * each series draws - dimmed when the legend turns it off, or when a value
+ * label isolates another one - and its value labels tell it what they
+ * isolate. A core takes the enclosing figure's ({@link PlotInteraction.current});
+ * a run outside any core builds one from the legend it has.
+ */
+export declare class PlotInteraction {
+    #private;
+    readonly legend: LegendState | null;
+    readonly hover: HoverState;
+    constructor(cfg: () => PlotStylesConfig, parts?: {
+        legend?: LegendState | null;
+        hover?: HoverState;
+        scope?: () => string;
+    });
+    /** The enclosing figure's legend and hover, in the plot's own hover scope. Call during component init. */
+    static current(cfg: () => PlotStylesConfig): PlotInteraction;
+    /** How `series` dims: the legend's off style, else the legend's opacity while another series is isolated. */
+    dimmed(series: string): LegendDisabledStyle | undefined;
+    /** `series`' fill while dimmed. */
+    fillFor(series: string): {
+        fill?: string;
+        fillOpacity?: number;
+    } | undefined;
+    /** `series`' stroke while dimmed. */
+    strokeFor(series: string): StrokeStyle | undefined;
+    /** `series`' dots while dimmed. */
+    dotsFor(series: string): DotStyle | undefined;
+    /** Isolates `series` - every other one dims - or ends it with `null`. */
+    isolate(series: string | null): void;
+}