@fundar/data-chart-telling 1.17.0 → 1.18.0

package/dist/layout/hover/HoverLayers.js

@@ -0,0 +1,122 @@
+import { NumberFormat } from '../../utils/NumberFormat';
+/**
+ * The markers a `hover` marker draws in its `back` and `front` layers, over the hovered points: each with the
+ * points as its rows, unless it has `data` of its own, placed at them, and split by the slice of the band a point
+ * sits in (a grouped bar's series), to be moved into it - all but a `band`, which takes the slice itself.
+ */
+export class HoverLayers {
+    /** The kinds placed by `x` and `y`, which default to the point's. */
+    static #PLACED = new Set(['dot', 'text', 'tick', 'image', 'line', 'trail']);
+    /** `points` with their label written as `marker`'s number fields, or its `format`, ask. */
+    static labelled(points, marker, cfg) {
+        const numberOf = NumberFormat.maybe(NumberFormat.displayOf(marker), cfg);
+        const number = numberOf ?? NumberFormat.of(undefined, cfg);
+        const { format } = marker;
+        if (!format && !numberOf)
+            return [...points];
+        return points.map((point) => {
+            if (format)
+                return { ...point, label: format(point, number) };
+            const value = Number(point.label);
+            const written = point.label !== undefined && point.label !== '' && Number.isFinite(value)
+                ? numberOf(value)
+                : point.label;
+            return { ...point, label: written ?? '' };
+        });
+    }
+    /**
+     * The markers of `marker`'s `layer` over a group of points. A marker over points that sit in a slice of their
+     * band is one part per slice, which `slice` names, to be moved into it as it is drawn - the move is in pixels,
+     * so it is left to the drawing, which knows the band's width.
+     */
+    static parts(marker, layer, group, cfg) {
+        if (group.points.length === 0)
+            return [];
+        return (marker[layer] ?? []).flatMap((nested, i) => {
+            const key = `${layer}-${group.key}-${i}`;
+            const { points: which, ...own } = nested;
+            if (own.data)
+                return [{ key, marker: own }];
+            const rows = HoverLayers.#pointsOf(which, group);
+            if (rows.length === 0)
+                return [];
+            const placed = HoverLayers.#placed(HoverLayers.#inHover(own, cfg));
+            if (own.type === 'band')
+                return [{ key, marker: { ...placed, data: rows } }];
+            return HoverLayers.#bySlice(rows).map(({ slice, points }) => ({
+                key: `${key}-${slice ? `${slice.start},${slice.end}` : ''}`,
+                marker: { ...placed, data: points },
+                slice
+            }));
+        });
+    }
+    /** The points a nested marker draws: all of them, the one under the pointer, or those a function keeps. */
+    static #pointsOf(which, group) {
+        if (which === 'active')
+            return group.active ? [group.active] : [];
+        if (typeof which === 'function')
+            return group.points.filter(which);
+        return group.points;
+    }
+    /**
+     * `marker` with what it leaves unset taken from the hover: a `rule` at each point along its axis and a `band`
+     * around it, in its slice; a `text` writes the point's label; each in the configuration's `hover` look (a `rect`
+     * too, in its `area` one), and a `dot` and a `text` in the point's series color.
+     */
+    static #inHover(marker, cfg) {
+        const own = marker;
+        const color = (point) => point.color ?? 'currentColor';
+        switch (marker.type) {
+            case 'rule':
+                return {
+                    ...marker,
+                    value: own.value ?? ((point) => point[marker.axis]),
+                    styles: { ...cfg.hover.rule, ...own.styles }
+                };
+            case 'band':
+                return {
+                    ...marker,
+                    value: own.value ?? ((point) => point[marker.axis]),
+                    slice: own.slice ?? ((point) => point.areaInset),
+                    styles: { ...cfg.hover.area, ...own.styles }
+                };
+            case 'rect':
+                return { ...marker, styles: { ...cfg.hover.area, ...own.styles } };
+            case 'dot':
+                return {
+                    ...marker,
+                    styles: { ...cfg.hover.dot, dotFill: color, dotStroke: color, ...own.styles }
+                };
+            case 'text':
+                return {
+                    ...marker,
+                    text: own.text ?? ((point) => point.label),
+                    styles: { ...cfg.hover.font, fill: color, ...own.styles }
+                };
+            default:
+                return marker;
+        }
+    }
+    /** `marker` placed at the points: its own `x` and `y`, else the point's. */
+    static #placed(marker) {
+        if (!HoverLayers.#PLACED.has(marker.type))
+            return marker;
+        const own = marker;
+        return {
+            ...marker,
+            x: own.x ?? ((point) => point.x),
+            y: own.y ?? ((point) => point.y)
+        };
+    }
+    /** `points` split by the slice of the band each one sits in, in the order they come. */
+    static #bySlice(points) {
+        const groups = new Map();
+        for (const point of points) {
+            const slice = point.areaInset;
+            const id = slice ? `${slice.start},${slice.end}` : '';
+            const group = groups.get(id) ?? groups.set(id, { slice, points: [] }).get(id);
+            group.points.push(point);
+        }
+        return [...groups.values()];
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { TooltipContext, TooltipProp } from '../../types/layout/tooltip';
+import type { TooltipProp } from '../../types/layout/tooltip';
 import type { HoverPoint, HoverStrategy } from '../../types/layout/hover';
 import { PlotAxes } from '../../phases/data/PlotAxes';
 import type { HoverConfig, PointMatchingStrategy, TooltipConfig } from '../../types/plots/props';
@@ -31,7 +31,5 @@ export declare class HoverSettings<TRow extends Record<string, unknown>> {
         defaultStrategy: HoverStrategy;
         pointMatching?: PointMatchingStrategy;
         number?: (value: number) => string;
-        /** What the plot knows of a row, the third argument of the author's own `format` - see {@link TooltipContext}. */
-        context?: (row: TRow) => TooltipContext;
     }): HoverConfig<TRow>;
 }

package/dist/layout/hover/HoverSettings.js

@@ -1,3 +1,4 @@
+import { RowContext } from '../../phases/context/RowContext';
 import { PlotAxes } from '../../phases/data/PlotAxes';
 /**
  * A plot's hover as its `tooltip` and hover marker set it up: whether it is on,
@@ -33,7 +34,7 @@ export class HoverSettings {
     }
     /** A plot's `hover` config; its tooltip reads as `format` unless it sets its own. */
     static buildConfig(args) {
-        const { tooltip, format, sort, markers, points, label, defaultStrategy, pointMatching, context } = args;
+        const { tooltip, format, sort, markers, points, label, defaultStrategy, pointMatching } = args;
         const number = args.number ?? String;
         const settings = new HoverSettings(tooltip, markers, defaultStrategy);
         return {
@@ -45,7 +46,7 @@ export class HoverSettings {
             tooltip: tooltip && {
                 ...tooltip,
                 format: tooltip.format
-                    ? (row) => tooltip.format(row, number, context?.(row) ?? {})
+                    ? (row) => tooltip.format(row, number, RowContext.of(row))
                     : format,
                 ...(sort ? { sort } : {})
             },

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

@@ -0,0 +1,44 @@
+import type { HoverShapeStyle } from '../../types/markers/common';
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+type Row = Record<string, unknown>;
+type Role = 'active' | 'other';
+/** What a hover marker sets for the shapes linked to the hover. */
+type ShapeRule = {
+    active?: HoverShapeStyle;
+    others?: HoverShapeStyle;
+    series?: string;
+};
+/** What the plot tells about each row the shapes draw. */
+export type HoverShapesReach = {
+    /** How the hover reaches a row - see `PlotHover.roleOf`. */
+    roleOf: (row: Row, series?: string) => Role | null;
+    /** Whether the legend dims the row's series, which then keeps its own fill and opacities. */
+    dimmed: (row: Row) => boolean;
+    cfg: PlotStylesConfig;
+};
+/** One part of a marker: its rows that the hover styles alike, keyed by how. */
+export type HoverShapesPart<T> = {
+    key: string;
+    marker: T;
+};
+/**
+ * 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.
+ */
+export declare class HoverShapes {
+    #private;
+    constructor(markers: readonly ({
+        type: string;
+    } & ShapeRule)[]);
+    /** Whether any hover marker restyles shapes. */
+    get any(): boolean;
+    /** Whether `marker`'s shapes take the hover's styles. */
+    static links(marker: object): boolean;
+    /**
+     * `marker` in parts, each drawing the rows the hover styles alike - the shapes it does not style first, the
+     * hovered ones last, so their outline is on top. A marker the hover does not style is one part, as it is.
+     */
+    split<T extends object>(marker: T, rows: readonly unknown[], reach: HoverShapesReach): HoverShapesPart<T>[];
+}
+export {};

package/dist/layout/hover/HoverShapes.js

@@ -0,0 +1,103 @@
+import { MarkerStyles } from '../../phases/markers/MarkerStyles';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+/**
+ * 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.
+ */
+export class HoverShapes {
+    /** What the legend owns on a dimmed shape. */
+    static #LEGEND_KEYS = ['fill', 'fillOpacity', 'strokeOpacity'];
+    /** 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;
+    constructor(markers) {
+        this.#rules = markers.filter((m) => m.type === 'hover' && !!(m.active || m.others));
+    }
+    /** 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` in parts, each drawing the rows the hover styles alike - the shapes it does not style first, the
+     * hovered ones last, so their outline is on top. A marker the hover does not style is one part, as it is.
+     */
+    split(marker, rows, reach) {
+        const whole = [{ key: '', marker }];
+        if (!this.any || !HoverShapes.links(marker))
+            return whole;
+        const data = (marker.data ?? rows);
+        const buckets = new Map();
+        for (const row of data) {
+            const key = this.#signature(row, reach);
+            const bucket = buckets.get(key) ?? buckets.set(key, []).get(key);
+            bucket.push(row);
+        }
+        if (buckets.size === 1 && buckets.has(''))
+            return whole;
+        const plain = (key) => !key.includes('a');
+        return [...buckets.entries()]
+            .sort(([a], [b]) => Number(plain(b)) - Number(plain(a)))
+            .map(([key, part]) => ({
+            key,
+            marker: key === '' ? { ...marker, data: part } : this.#restyled(marker, part, key, reach)
+        }));
+    }
+    /**
+     * How the hover styles `row`: for each rule, `a` (active), `o` (other) or `-` (not at all), and `~` when the
+     * legend dims it. `''` while no rule styles it.
+     */
+    #signature(row, reach) {
+        const own = row[SERIES_KEY];
+        const roles = this.#rules.map((rule) => {
+            if (rule.series !== undefined && own !== rule.series)
+                return '-';
+            const role = reach.roleOf(row, rule.series);
+            if (role === 'active')
+                return rule.active ? 'a' : '-';
+            if (role === 'other')
+                return rule.others ? 'o' : '-';
+            return '-';
+        });
+        if (roles.every((role) => role === '-'))
+            return '';
+        return roles.join('') + (reach.dimmed(row) ? '~' : '');
+    }
+    /** `marker` over `rows`, with the styles `key` stands for over its own. */
+    #restyled(marker, rows, key, reach) {
+        const dimmed = key.endsWith('~');
+        const styles = this.#rules.reduce((merged, rule, i) => {
+            const role = key[i];
+            const style = role === 'a' ? rule.active : role === 'o' ? rule.others : undefined;
+            return {
+                ...merged,
+                ...HoverShapes.#named(HoverShapes.#defined(style, dimmed), marker)
+            };
+        }, { ...marker.styles });
+        return MarkerStyles.restyle({ ...marker, data: rows, styles }, { cfg: reach.cfg, rows });
+    }
+    /** `style` as `marker` names its fields: a `dot` marker's are its `dot` ones (`dotFill`...). */
+    static #named(style, marker) {
+        if (marker.type !== 'dot')
+            return style;
+        const keys = HoverShapes.#DOT_KEYS;
+        return Object.fromEntries(Object.entries(style).map(([name, value]) => [keys[name] ?? name, value]));
+    }
+    /** `style`'s set values, without what the legend owns on a dimmed shape. */
+    static #defined(style, dimmed) {
+        return Object.fromEntries(Object.entries(style ?? {}).filter(([name, value]) => value !== undefined &&
+            !(dimmed && HoverShapes.#LEGEND_KEYS.includes(name))));
+    }
+}

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/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;

package/dist/layout/styles/ValueLabels.d.ts

@@ -1,5 +1,6 @@
 import { Box } from '../margins/Box';
 import { PlotAxes } from '../../phases/data/PlotAxes';
+import type { PlotRowContext } from '../../types/layout/context';
 import type { PlotStylesConfig } from '../../types/configuration/styling';
 import type { ValuesStyle } from '../../types/layout/styles';
 import type { ValueLabelsOptions } from '../../types/phases/styles/phase';
@@ -8,7 +9,7 @@ import type { FontStyle, StrokeStyle } from '../../types/plots/styling';
 import type { LabelAnchor, TextAnchor, ValueAnchor } from '../../types/plots/constants';
 import type { BoxAnchors, EdgeBox } from '../../types/layout/box';
 import type { MarginSide } from '../../types/plots/props';
-import type { AxisPlotCtx, AxisPlotState, ProcessedData, ProcessedRow } from '../../types/phases';
+import type { AxisPlotEnv, AxisPlotState, ProcessedData, ProcessedRow } from '../../types/phases';
 import type { TextMarkerConfig } from '../../types/markers/common';
 import type { TextLabelConfig } from '../../types/markers/basic/text';
 /**
@@ -21,7 +22,12 @@ export declare class ValueLabels {
     #private;
     readonly show: boolean;
     readonly anchor: ValueAnchor;
-    readonly format: (value: number, seriesName: string, row?: Record<string, unknown>) => string;
+    /**
+     * A label's text for `value`: the author's `format`, else the kind's, else the value as the display fields ask.
+     * `row` is the row it labels, whose context the format reads; `series` names its series where there is no row
+     * (a label measured ahead of the rows).
+     */
+    readonly format: (value: number, row?: object, series?: string) => string;
     readonly hoverIsolate: boolean;
     readonly font: FontStyle | undefined;
     readonly fontSize: number;
@@ -34,6 +40,8 @@ export declare class ValueLabels {
     /** Where the labels are expected to sit: boxes around their points, on the edges those can reach. */
     readonly reach: EdgeBox[];
     constructor(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options?: Omit<ValueLabelsOptions<never>, 'reach'>, reach?: (labels: ValueLabels) => EdgeBox[]);
+    /** The context a label's `format` reads: its row's, with `series` when the row gives none. */
+    static contextOf(row: object | undefined, series?: string): PlotRowContext;
     /** A plot's value labels: `values` over `options`, the kind's own defaults, their reach read off `state`. */
     static build<TState>(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options: ValueLabelsOptions<TState>, state: TState): ValueLabels;
     /** The configuration the labels were built under, for a plot kind's own label defaults. */
@@ -79,7 +87,7 @@ export declare class ValueLabels {
      * dims with its row's series, and with `hoverIsolate`, hovering it
      * isolates that series. A row without a series gets the margins only.
      */
-    hooks(ctx: AxisPlotCtx): Pick<TextMarkerConfig, 'fitMargins' | 'onpointerenter' | 'onpointerleave' | 'styles'>;
+    hooks(env: AxisPlotEnv): Pick<TextMarkerConfig, 'fitMargins' | 'onpointerenter' | 'onpointerleave' | 'styles'>;
     /**
      * Where in a bar a label goes, from the `anchor` of `styles.values`: its `label` anchor, and whether it is beyond
      * the bar. `negative` tells a bar that runs to the left (or down) from its base from one that runs right (or up),
@@ -102,7 +110,7 @@ export declare class ValueLabels {
      * never reaches out of the plot, so only one `outside` has the margins grow to hold it; and it takes the default
      * `fill` only `outside`, for inside it is written in the color that contrasts with its shape.
      */
-    shapeLabel(ctx: AxisPlotCtx, text: (row: ProcessedRow) => string, defaults?: {
+    shapeLabel(env: AxisPlotEnv, text: (row: ProcessedRow) => string, defaults?: {
         fill?: string;
         fontSize?: number;
         fontWeight?: FontStyle['fontWeight'];