@fundar/data-chart-telling 1.16.0 → 1.18.0

package/dist/phases/Pipeline.d.ts

@@ -1,16 +1,17 @@
-import type { AxisPlotState, AxisPlotCtx, AxisPlotKind, AxisPlotDefaults, DataRunState, HoverStageOptions, PhaseStage, PlotPhase } from '../types/phases';
+import type { AxisPlotState, AxisPlotEnv, AxisPlotKind, AxisPlotDefaults, DataRunState, HoverStageOptions, PhaseStage, PlotPhase } from '../types/phases';
 import type { PlotStylesConfig } from '../types/configuration/styling';
 import type { FacetConfig } from '../types/layout/facet';
 import type { LegendState } from '../layout/legend/LegendState.svelte';
 import type { HoverStrategy } from '../types/layout/hover';
 import type { Accessor } from '../types/plots/data/common';
+import type { GroupingAccessor } from '../types/layout/mapping';
 /** The core props an axis plot kind seeds its pipeline from. */
 export type AxisPipelineProps<TData extends Record<string, unknown>> = {
     series?: unknown[];
     data?: TData[];
     x?: Accessor<TData, unknown>;
     y?: Accessor<TData, unknown>;
-    grouping?: Accessor<TData, unknown>;
+    grouping?: GroupingAccessor<TData>;
     color?: Accessor<TData, unknown>;
     opacity?: unknown;
     r?: unknown;
@@ -20,6 +21,7 @@ export type AxisPipelineProps<TData extends Record<string, unknown>> = {
     error?: Accessor<TData, unknown>;
     target?: unknown;
     ranges?: unknown[];
+    value?: Accessor<TData, unknown>;
     segments?: unknown;
     styles?: {
         gaps?: unknown;
@@ -53,7 +55,7 @@ export type PipelineOptions<TState> = {
  * Stages declared out of phase order still run in it - with a warning, once,
  * since the declared order would otherwise read as the one that runs.
  */
-export declare class Pipeline<TState, TCtx = unknown> {
+export declare class Pipeline<TState, TEnv = unknown> {
     #private;
     /**
      * The phases that work on the plot's rows - everything before its scales,
@@ -63,25 +65,25 @@ export declare class Pipeline<TState, TCtx = unknown> {
     static readonly DATA_PHASES: readonly PlotPhase[];
     /** Every {@link PlotPhase}, in the order they run: the data phases, then each panel's own. */
     static readonly ORDER: readonly PlotPhase[];
-    readonly stages: readonly PhaseStage<TState, TCtx>[];
-    constructor(stages: PhaseStage<TState, TCtx>[], options?: PipelineOptions<TState>);
+    readonly stages: readonly PhaseStage<TState, TEnv>[];
+    constructor(stages: PhaseStage<TState, TEnv>[], options?: PipelineOptions<TState>);
     /**
      * An axis-based plot kind's pipeline: the shared stages, each set up with
      * the kind's own options - its marks and value labels among them - started
      * from a core's props. Built once per kind object.
      */
-    static ofAxisKind<TState extends AxisPlotState<any, any, any, any>, TCtx extends AxisPlotCtx>(kind: AxisPlotKind<TState, TCtx> & Pick<AxisPlotDefaults<any, any>, 'timeline'>): Pipeline<TState, TCtx>;
+    static ofAxisKind<TState extends AxisPlotState<any, any, any, any>, TEnv extends AxisPlotEnv>(kind: AxisPlotKind<TState, TEnv> & Pick<AxisPlotDefaults<any, any>, 'timeline'>): Pipeline<TState, TEnv>;
     /** A plot's pipeline from what its kind gives: its axis-kind defaults, or a pipeline of its own. */
     static of(defaults: AxisPlotDefaults<any, any> | Pipeline<any, any>): Pipeline<any, any>;
     /** The stage of `phase`, if the pipeline has one. */
-    stage(phase: PlotPhase): PhaseStage<TState, TCtx> | undefined;
+    stage(phase: PlotPhase): PhaseStage<TState, TEnv> | undefined;
     /**
      * A core's run: every stage over the state its `input` (an axis core's
      * props) seeds - or, given `panelState` (one facet panel's part of
      * {@link runData}), only the stages after the data phases, over that state
      * with the input's own props (its box, margins and scales) on top.
      */
-    run: (input: unknown, ctx: TCtx, panelState?: object) => TState;
+    run: (input: unknown, env: TEnv, panelState?: object) => TState;
     /** Whether the pipeline has data phases to run once over every facet panel ({@link runData}). */
     get facets(): boolean;
     /**

package/dist/phases/Pipeline.js

@@ -2,6 +2,7 @@ import { FacetPhase } from './facet/FacetPhase';
 import { DataPhase } from './data/DataPhase';
 import { MappingPhase } from './mapping/MappingPhase';
 import { TransformsPhase } from './transforms/TransformsPhase';
+import { ContextPhase } from './context/ContextPhase';
 import { StatisticsPhase } from './statistics/StatisticsPhase';
 import { ScalesPhase } from './scales/ScalesPhase';
 import { SharedScalesPhase } from './sharedScales/SharedScalesPhase';
@@ -33,6 +34,7 @@ export class Pipeline {
         'data',
         'mapping',
         'transforms',
+        'context',
         'statistics',
         'sharedScales'
     ];
@@ -79,6 +81,7 @@ export class Pipeline {
             new DataPhase(kind.data),
             new MappingPhase(kind.mapping),
             new TransformsPhase(kind.transforms, kind.data?.segments?.connect),
+            new ContextPhase(kind.context),
             new StatisticsPhase(kind.statistics),
             new SharedScalesPhase(kind.sharedScales, scales),
             scales,
@@ -112,12 +115,12 @@ export class Pipeline {
      * {@link runData}), only the stages after the data phases, over that state
      * with the input's own props (its box, margins and scales) on top.
      */
-    run = (input, ctx, panelState) => {
+    run = (input, env, panelState) => {
         const seed = this.#seed(input);
         if (!panelState)
-            return Pipeline.#through(this.stages, seed, ctx);
+            return Pipeline.#through(this.stages, seed, env);
         this.#panel ??= this.stages.filter((stage) => !Pipeline.DATA_PHASES.includes(stage.phase));
-        return Pipeline.#through(this.#panel, { ...panelState, ...seed }, ctx);
+        return Pipeline.#through(this.#panel, { ...panelState, ...seed }, env);
     };
     /** Whether the pipeline has data phases to run once over every facet panel ({@link runData}). */
     get facets() {
@@ -131,7 +134,7 @@ export class Pipeline {
     runData(props, rows, facet, legendInteraction, cfg) {
         this.#data ??= this.stages.filter((stage) => Pipeline.DATA_PHASES.includes(stage.phase));
         const seed = { ...this.#seed(props, rows), facet };
-        return Pipeline.#through(this.#data, seed, Pipeline.#ctxFor(cfg, legendInteraction));
+        return Pipeline.#through(this.#data, seed, Pipeline.#envFor(cfg, legendInteraction));
     }
     /**
      * The plot's hover strategy when neither its `tooltip` nor a hover marker
@@ -143,7 +146,7 @@ export class Pipeline {
         if (fixed !== undefined)
             return fixed;
         const upToData = this.stages.filter((s) => s.phase === 'data');
-        const state = Pipeline.#through(upToData, this.#seed(props), Pipeline.#ctxFor(cfg, null));
+        const state = Pipeline.#through(upToData, this.#seed(props), Pipeline.#envFor(cfg, null));
         return HoverSettings.strategyOf(state.axes);
     }
     /** The plot's default `timeline.filterMode`. */
@@ -162,7 +165,7 @@ export class Pipeline {
             return undefined;
         const upToMapping = this.stages.filter((s) => s.phase === 'data' || s.phase === 'mapping');
         // Without a legend: the channels read the same whatever it turns off.
-        const state = Pipeline.#through(upToMapping, this.#seed(props), Pipeline.#ctxFor(cfg, null));
+        const state = Pipeline.#through(upToMapping, this.#seed(props), Pipeline.#envFor(cfg, null));
         const channel = (ref) => {
             const name = ref === 'value' || ref === 'category' ? state.axes?.[ref] : ref;
             if (name === undefined)
@@ -186,11 +189,11 @@ export class Pipeline {
         return this.#options.seed ? this.#options.seed(input, rows) : input;
     }
     /** `stages` over `state`, in order. */
-    static #through(stages, state, ctx) {
-        return stages.reduce((acc, stage) => stage.run(acc, ctx), state);
+    static #through(stages, state, env) {
+        return stages.reduce((acc, stage) => stage.run(acc, env), state);
     }
     /** The context a plot-level run reads, outside any core: the configuration and the legend. */
-    static #ctxFor(cfg, legendInteraction) {
+    static #envFor(cfg, legendInteraction) {
         const interaction = new PlotInteraction(() => cfg, { legend: legendInteraction });
         return { cfg, interaction };
     }
@@ -215,6 +218,7 @@ export class Pipeline {
             error: props.error,
             target: props.target,
             ranges: props.ranges,
+            value: props.value,
             segments: props.segments ?? {},
             styles: props.styles,
             gaps: props.styles?.gaps,

package/dist/phases/context/ContextPhase.d.ts

@@ -0,0 +1,22 @@
+import type { ContextStageOptions } from '../../types/phases/context/phase';
+import type { PhaseStage, ProcessedData } from '../../types/phases';
+import type { PlotAxes } from '../data/PlotAxes';
+import type { Series } from '../../types/plots/data/common';
+/** What the "context" phase reads. */
+type ContextStageState = {
+    processedData?: ProcessedData;
+    resolvedSeries?: Series<any>[];
+    axes?: PlotAxes;
+};
+/**
+ * The "context" phase every axis-based plot shares: right after the transforms, it works out once what the plot
+ * knows of each processed row - the shared {@link RowContext}, with what the kind adds - and keeps it on the row,
+ * for the tooltip, the hover, the value labels and the author's own markers to read.
+ */
+export declare class ContextPhase<TState extends ContextStageState, TEnv = unknown> implements PhaseStage<TState, TEnv> {
+    #private;
+    readonly phase: "context";
+    constructor(kind?: ContextStageOptions<TState, TEnv>);
+    run: (state: TState, env: TEnv) => TState;
+}
+export {};

package/dist/phases/context/ContextPhase.js

@@ -0,0 +1,23 @@
+import { RowContext } from './RowContext';
+/**
+ * The "context" phase every axis-based plot shares: right after the transforms, it works out once what the plot
+ * knows of each processed row - the shared {@link RowContext}, with what the kind adds - and keeps it on the row,
+ * for the tooltip, the hover, the value labels and the author's own markers to read.
+ */
+export class ContextPhase {
+    phase = 'context';
+    #kind;
+    constructor(kind) {
+        this.#kind = kind;
+    }
+    run = (state, env) => {
+        const rows = state.processedData?.data;
+        if (!rows?.length)
+            return state;
+        const shared = RowContext.shared(state);
+        const own = this.#kind?.(state, env);
+        for (const row of rows)
+            RowContext.tag(row, { ...shared(row), ...own?.(row) });
+        return state;
+    };
+}

package/dist/phases/context/RowContext.d.ts

@@ -0,0 +1,35 @@
+import { PlotAxes } from '../data/PlotAxes';
+import type { PlotRowContext } from '../../types/layout/context';
+import type { Series } from '../../types/plots/data/common';
+import type { ProcessedData, ProcessedRow } from '../../types/phases';
+/** What the shared context is worked out from. */
+type ContextSource = {
+    processedData?: ProcessedData;
+    resolvedSeries?: Series<any>[];
+    axes?: PlotAxes;
+};
+/**
+ * The context of the rows a plot draws ({@link PlotRowContext}): worked out once per row by the "context" phase,
+ * kept on the row itself, and read back from it - or from any copy of it - with {@link of}.
+ */
+export declare class RowContext {
+    #private;
+    /**
+     * What the plot knows of `row`: its series, where it sits, the value it shows and whatever its kind works out
+     * for it, with the row itself. A row no plot drew reads as its series alone.
+     */
+    static of<TContext extends PlotRowContext = PlotRowContext>(row: unknown): TContext;
+    /** Keeps `context` on `row`, for {@link of} to read back. */
+    static tag(row: ProcessedRow, context: PlotRowContext): void;
+    /** Whether `row` carries a context already. */
+    static has(row: unknown): boolean;
+    /** A reader of the rows of `state`: the context each carries, else the shared one, for a row no phase tagged. */
+    static reader(state: ContextSource): (row: ProcessedRow) => PlotRowContext;
+    /**
+     * The context every plot gives a processed row: its series; its `x` and `y` - each its series' own value
+     * (a stacked row's own, not the running total), else where the transforms put it (a density's estimate, a
+     * bin's centre); and its value on the plot's value axis, when that is a number.
+     */
+    static shared(state: ContextSource): (row: ProcessedRow) => PlotRowContext;
+}
+export {};

package/dist/phases/context/RowContext.js

@@ -0,0 +1,95 @@
+import { SERIES_ID_KEY, SERIES_KEY } from '../transforms/TransformsPhase';
+import { ProcessedPositions } from '../transforms/ProcessedPositions';
+import { PlotAxes } from '../data/PlotAxes';
+import { resolveAccessor } from '../../utils/accessors';
+import { seriesIdOf } from '../../utils/grouping';
+/** Where a row's context is kept on it: under a symbol, which survives the copies svelteplot makes of a row. */
+const KEY = Symbol('dct-row-context');
+/**
+ * The context of the rows a plot draws ({@link PlotRowContext}): worked out once per row by the "context" phase,
+ * kept on the row itself, and read back from it - or from any copy of it - with {@link of}.
+ */
+export class RowContext {
+    /**
+     * What the plot knows of `row`: its series, where it sits, the value it shows and whatever its kind works out
+     * for it, with the row itself. A row no plot drew reads as its series alone.
+     */
+    static of(row) {
+        if (row == null || typeof row !== 'object')
+            return {};
+        const record = row;
+        const own = record[KEY];
+        if (own)
+            return { ...own, row };
+        const series = record[SERIES_KEY];
+        return { ...(typeof series === 'string' ? { series } : {}), row };
+    }
+    /** Keeps `context` on `row`, for {@link of} to read back. */
+    static tag(row, context) {
+        row[KEY] = context;
+    }
+    /** Whether `row` carries a context already. */
+    static has(row) {
+        return row != null && typeof row === 'object' && KEY in row;
+    }
+    /** A reader of the rows of `state`: the context each carries, else the shared one, for a row no phase tagged. */
+    static reader(state) {
+        let shared;
+        return (row) => {
+            if (RowContext.has(row))
+                return RowContext.of(row);
+            shared ??= RowContext.shared(state);
+            return { ...shared(row), row };
+        };
+    }
+    /**
+     * The context every plot gives a processed row: its series; its `x` and `y` - each its series' own value
+     * (a stacked row's own, not the running total), else where the transforms put it (a density's estimate, a
+     * bin's centre); and its value on the plot's value axis, when that is a number.
+     */
+    static shared(state) {
+        const processed = state.processedData;
+        if (!processed)
+            return () => ({});
+        const valueAxis = PlotAxes.valueOf(state);
+        const placed = ProcessedPositions.of(processed, valueAxis);
+        const x = RowContext.#along(state, 'x', RowContext.#stacked(processed, 'x') ?? placed.x);
+        const y = RowContext.#along(state, 'y', RowContext.#stacked(processed, 'y') ?? placed.y);
+        return (row) => {
+            const series = row[SERIES_KEY];
+            const at = { x: x(row), y: y(row) };
+            const raw = at[valueAxis];
+            const value = raw instanceof Date || raw === null || raw === '' ? NaN : Number(raw);
+            return {
+                ...(typeof series === 'string' ? { series } : {}),
+                ...at,
+                ...(Number.isFinite(value) ? { value } : {})
+            };
+        };
+    }
+    /** A stacked row's own value along `axis` - its span, not the running total - or `undefined` with no stack there. */
+    static #stacked(processed, axis) {
+        const from = processed.channels[`${axis}1`];
+        const to = processed.channels[`${axis}2`];
+        const stack = axis === 'x' ? 'stackX' : 'stackY';
+        if (from === undefined || to === undefined)
+            return undefined;
+        if (!processed.transforms.some((t) => t.type === stack))
+            return undefined;
+        const low = resolveAccessor(from);
+        const high = resolveAccessor(to);
+        return (row) => Number(high(row)) - Number(low(row));
+    }
+    /** A row's value along `axis`: its series' own channel, else `placed`. */
+    static #along(state, axis, placed) {
+        const bySeries = new Map((state.resolvedSeries ?? []).flatMap((s) => {
+            const accessor = s[axis];
+            return accessor === undefined ? [] : [[seriesIdOf(s), resolveAccessor(accessor)]];
+        }));
+        return (row) => {
+            const own = bySeries.get(String(row[SERIES_ID_KEY]));
+            const value = own?.(row);
+            return value === undefined ? placed(row) : value;
+        };
+    }
+}

package/dist/phases/data/DataPhase.d.ts

@@ -1,4 +1,4 @@
-import type { AxisPlotState, AxisPlotCtx, DataStageOptions, PhaseStage } from '../../types/phases';
+import type { AxisPlotState, AxisPlotEnv, DataStageOptions, PhaseStage } from '../../types/phases';
 type AnyAxisState = AxisPlotState<any, any, any, any>;
 /**
  * The "data" phase every axis-based plot shares: its series (from `series`,
@@ -10,10 +10,10 @@ type AnyAxisState = AxisPlotState<any, any, any, any>;
  * Colors and axes come from every series, before any is omitted or split by
  * facet panel, so they stay put and every panel agrees.
  */
-export declare class DataPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+export declare class DataPhase<TState extends AnyAxisState, TEnv extends AxisPlotEnv> implements PhaseStage<TState, TEnv> {
     #private;
     readonly phase: "data";
-    constructor(options?: DataStageOptions<TState, TCtx>);
-    run: (state: TState, ctx: TCtx) => TState;
+    constructor(options?: DataStageOptions<TState, TEnv>);
+    run: (state: TState, env: TEnv) => TState;
 }
 export {};

package/dist/phases/data/DataPhase.js

@@ -1,5 +1,5 @@
-import { buildSeries } from '../../utils/grouping';
-import { ColorRamp } from '../../utils/color';
+import { buildSeries, Grouping } from '../../utils/grouping';
+import { ColorRamp, ColorTones } from '../../utils/color';
 import { resolveAccessor } from '../../utils/accessors';
 import { buildGroupedSeries, buildScopedMarkerGroups } from '../../plots/utils/segments';
 import { buildGapFillMaps, isGapValue } from '../../plots/utils/gaps';
@@ -22,11 +22,11 @@ export class DataPhase {
     constructor(options = {}) {
         this.#options = options;
     }
-    run = (state, ctx) => {
+    run = (state, env) => {
         const options = this.#options;
         const { series, data, segments, scales } = state;
         const { connect = true, color: segmentColor } = options.segments ?? {};
-        const seriesGrouping = DataPhase.#buildGrouping(state);
+        const seriesGrouping = DataPhase.#buildGrouping(state, options.nested);
         const built = series ?? buildSeries(data ?? [], state.x, state.y, seriesGrouping);
         const fullSeries = options.orderSeries ? options.orderSeries(built, state) : built;
         const axes = PlotAxes.build({
@@ -35,11 +35,18 @@ export class DataPhase {
             given: { x: state.x !== undefined, y: state.y !== undefined },
             discrete: options.discreteAxes
         });
-        const colorForSeries = ColorRamp.resolve(scales.color, (options.colorOrder ? options.colorOrder(fullSeries) : fullSeries).map((s) => s.name), ctx.cfg.palette);
+        const seriesColors = ColorRamp.resolve(scales.color, (options.colorOrder ? options.colorOrder(fullSeries) : fullSeries).map((s) => s.name), env.cfg.palette);
+        const colorForPath = series ? undefined : DataPhase.#buildPathColors(state, env);
+        // A plot that splits its series by every level colors each one by its path; a nested one by its outermost.
+        const colorForSeries = colorForPath && !options.nested
+            ? DataPhase.#byPath(state, colorForPath, seriesColors)
+            : seriesColors;
         const panelSeries = state.panels && state.panelOf && !series
             ? FacetPanels.splitSeries(fullSeries, state.panels, state.panelOf)
             : fullSeries;
-        const resolvedSeries = ctx.interaction?.legend?.withoutOmitted(panelSeries) ?? panelSeries;
+        const legend = env.interaction?.legend;
+        const resolvedSeries = legend?.withoutOmitted(panelSeries) ?? panelSeries;
+        const removedSeries = legend?.removed(panelSeries);
         const baseFor = BasicStyles.of(state.styles, options.segments?.base);
         const groupedSeries = buildGroupedSeries(resolvedSeries, segments, connect, baseFor);
         const scopedGroups = buildScopedMarkerGroups({
@@ -57,6 +64,7 @@ export class DataPhase {
             ...state,
             axes,
             resolvedSeries,
+            ...(removedSeries ? { removedSeries } : {}),
             seriesGrouping,
             allSeriesNames: fullSeries.map((s) => s.name),
             groupedSeries,
@@ -64,20 +72,53 @@ export class DataPhase {
             flat: resolvedSeries.flatMap((s) => s.data),
             scopedGroups,
             colorForSeries,
+            ...(colorForPath ? { colorForPath } : {}),
             ...(gapFillMaps ? { gapFillMaps } : {})
         };
-        return options.extend ? options.extend(next, ctx) : next;
+        return options.extend ? options.extend(next, env) : next;
     };
     /**
-     * The key a plot's rows split into series by: its `grouping`, or its `color`
-     * when that names categories. A numeric `color` is a continuous value (a
-     * heatmap's cells), so it colors rows without grouping them.
+     * The color of a path of the plot's `grouping` levels, when `scales.color.depth` reaches past the outermost
+     * one: each outermost value its categorical color, and every path down to `depth` a tone of it (see
+     * {@link ColorTones.hierarchy}). `undefined` for a grouping of one level, or a depth of 1.
      */
-    static #buildGrouping(state
+    static #buildPathColors(state, env) {
+        const depth = state.scales.color?.depth ?? 1;
+        const rows = state.data ?? [];
+        const levels = Grouping.levels(state.grouping, rows).map((level) => resolveAccessor(level));
+        if (depth <= 1 || levels.length <= 1)
+            return undefined;
+        const paths = rows.map((row) => levels.map((read) => String(read(row))));
+        const outermost = [...new Set(paths.map((path) => path[0]))];
+        const colorOf = ColorRamp.resolve(state.scales.color, outermost, env.cfg.palette);
+        return ColorTones.hierarchy(paths, depth, (value) => colorOf(value));
+    }
+    /** A series' color as the color of its path - its name is the key its levels make together. */
+    static #byPath(state, colorForPath, fallback) {
+        const rows = state.data ?? [];
+        const key = resolveAccessor(Grouping.key(state.grouping, rows));
+        const levels = Grouping.levels(state.grouping, rows).map((level) => resolveAccessor(level));
+        const pathOf = new Map();
+        for (const row of rows) {
+            const name = String(key(row));
+            if (!pathOf.has(name))
+                pathOf.set(name, levels.map((read) => String(read(row))));
+        }
+        return (name) => {
+            const path = pathOf.get(name);
+            return path ? colorForPath(path) : fallback(name);
+        };
+    }
+    /**
+     * The key a plot's rows split into series by: its `grouping` (its levels together, or the outermost
+     * one alone for a `nested` kind), or its `color` when that names categories. A numeric `color` is a
+     * continuous value (a heatmap's cells), so it colors rows without grouping them.
+     */
+    static #buildGrouping(state, nested = false
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ) {
         if (state.grouping !== undefined)
-            return state.grouping;
+            return Grouping.key(state.grouping, state.data, nested);
         const color = state.color;
         if (color === undefined || !state.data)
             return color;

package/dist/phases/hover/HoverPhase.d.ts

@@ -1,6 +1,6 @@
 import type { HoverDisplayPoint, HoverPoint } from '../../types/layout/hover';
 import { LegendState } from '../../layout/legend/LegendState.svelte';
-import type { AxisPlotCtx, AxisPlotState, HoverPosition, HoverStageOptions, PhaseStage, ProcessedData } from '../../types/phases';
+import type { AxisPlotEnv, AxisPlotState, HoverPosition, HoverStageOptions, PhaseStage, ProcessedData } from '../../types/phases';
 type AnyAxisState = AxisPlotState<any, any, any, any>;
 /**
  * The "hover" phase every axis-based plot shares: what the pointer can match
@@ -9,15 +9,16 @@ type AnyAxisState = AxisPlotState<any, any, any, any>;
  * hover `rows`) of the series the legend shows, except gap rows and rows
  * outside the legend's narrowed range.
  */
-export declare class HoverPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+export declare class HoverPhase<TState extends AnyAxisState, TEnv extends AxisPlotEnv> implements PhaseStage<TState, TEnv> {
     #private;
     readonly phase: "hover";
-    constructor(options?: HoverStageOptions<TState, TCtx>);
-    run: (state: TState, ctx: TCtx) => TState;
+    constructor(options?: HoverStageOptions<TState, TEnv>);
+    run: (state: TState, env: TEnv) => TState;
     /**
      * Hover candidates for a plot's own processed rows: each visible row at its
      * position (a stacked row's top, a bin's centre), in its series' color. A
-     * series the legend turned off is left out, as is any row `include` rejects.
+     * series the legend hides, omits or rescales away is left out (a dimmed one
+     * stays), as is any row `include` rejects.
      */
     static buildProcessedHoverPoints<TRow extends Record<string, unknown>>(args: {
         processed: ProcessedData;
@@ -25,8 +26,6 @@ export declare class HoverPhase<TState extends AnyAxisState, TCtx extends AxisPl
         legendInteraction?: LegendState | null;
         label: (row: TRow) => string;
         include?: (row: TRow) => boolean;
-        /** The row a hovered point reads as, e.g. with derived fields added. Defaults to the processed row. */
-        row?: (row: TRow) => TRow;
         /** Fields to add to (or replace on) each point. */
         decorate?: (row: TRow) => Partial<HoverDisplayPoint>;
         /** Where a row sits, as is. Defaults to its processed position, with `y` as a number. */

package/dist/phases/hover/HoverPhase.js

@@ -1,10 +1,12 @@
 import { ProcessedPositions } from '../transforms/ProcessedPositions';
 import { GAP_VALUE, SERIES_KEY } from '../transforms/TransformsPhase';
 import { HoverSettings } from '../../layout/hover/HoverSettings';
+import { RowContext } from '../context/RowContext';
 import { PlotAxes } from '../data/PlotAxes';
 import { NumberFormat } from '../../utils/NumberFormat';
 import { isGapValue } from '../../plots/utils/gaps';
 import { LegendState } from '../../layout/legend/LegendState.svelte';
+import { HoverDefaults } from '../../layout/hover/HoverDefaults';
 /**
  * The "hover" phase every axis-based plot shares: what the pointer can match
  * (`hover`), the rows it hovers over (`hoverRows`) and where each sits
@@ -18,7 +20,7 @@ export class HoverPhase {
     constructor(options = {}) {
         this.#options = options;
     }
-    run = (state, ctx) => {
+    run = (state, env) => {
         const options = this.#options;
         const valueAxis = PlotAxes.valueOf(state);
         const raw = options.position?.(state) ??
@@ -28,20 +30,23 @@ export class HoverPhase {
         const position = options.position || state.axes?.isDiscrete(valueAxis)
             ? raw
             : { ...raw, [valueAxis]: (row) => Number(raw[valueAxis](row)) };
+        // A row's label is the value its context gives it, else its value channel's.
         const label = options.label?.(state) ??
-            ((row) => String(state.channels[valueAxis].accessor(row)));
+            ((row) => {
+                const { value } = RowContext.of(row);
+                return String(value ?? state.channels[valueAxis].accessor(row));
+            });
         const processed = options.rows
             ? { ...state.processedData, data: options.rows(state) }
             : state.processedData;
         const points = HoverPhase.buildProcessedHoverPoints({
             processed,
             colorFor: state.colorForSeries,
-            legendInteraction: ctx.interaction?.legend,
+            legendInteraction: env.interaction?.legend,
             label: label,
             position,
-            include: HoverPhase.#hoverable(state, ctx, raw, valueAxis),
-            row: options.row?.(state),
-            decorate: options.decorate?.(state, ctx)
+            include: HoverPhase.#hoverable(state, env, raw, valueAxis),
+            decorate: options.decorate?.(state, env)
         });
         const hover = HoverSettings.buildConfig({
             tooltip: state.tooltip,
@@ -52,12 +57,18 @@ export class HoverPhase {
             label: label,
             defaultStrategy: options.strategy ?? HoverSettings.strategyOf(state.axes),
             pointMatching: options.pointMatching,
-            number: NumberFormat.of(NumberFormat.displayOf(state.tooltip), ctx.cfg)
+            number: NumberFormat.of(NumberFormat.displayOf(state.tooltip), env.cfg)
         });
-        const hitAreas = options.hitAreas?.(state, hover, ctx) ?? [];
+        const hitAreas = options.hitAreas?.(state, hover, env) ?? [];
+        const own = options.marker?.(state, env);
+        const look = typeof own === 'function'
+            ? own
+            : own
+                ? () => own
+                : (strategy) => HoverDefaults.of(strategy, hover.crosshair);
         return {
             ...state,
-            hover,
+            hover: { ...hover, look },
             hoverPosition: position,
             hoverRows: processed.data,
             ...(hitAreas.length > 0 ? { markers: [...(state.markers ?? []), ...hitAreas] } : {})
@@ -66,10 +77,11 @@ export class HoverPhase {
     /**
      * Hover candidates for a plot's own processed rows: each visible row at its
      * position (a stacked row's top, a bin's centre), in its series' color. A
-     * series the legend turned off is left out, as is any row `include` rejects.
+     * series the legend hides, omits or rescales away is left out (a dimmed one
+     * stays), as is any row `include` rejects.
      */
     static buildProcessedHoverPoints(args) {
-        const { processed, colorFor, legendInteraction, label, include, row: rowOf, decorate } = args;
+        const { processed, colorFor, legendInteraction, label, include, decorate } = args;
         const processedPosition = ProcessedPositions.of(processed);
         const position = args.position ?? {
             x: processedPosition.x,
@@ -78,7 +90,7 @@ export class HoverPhase {
         const x = position.x;
         const y = position.y;
         return processed.data
-            .filter((d) => !legendInteraction?.isOff(d[SERIES_KEY]))
+            .filter((d) => !legendInteraction?.isUnhoverable(d[SERIES_KEY]))
             .filter((d) => !include || include(d))
             .map((d) => {
             const row = d;
@@ -86,7 +98,8 @@ export class HoverPhase {
             return {
                 x: x(d),
                 y: y(d),
-                row: rowOf ? rowOf(row) : row,
+                row,
+                context: RowContext.of(row),
                 label: label(row),
                 series: seriesName,
                 color: colorFor(seriesName),
@@ -99,8 +112,8 @@ export class HoverPhase {
      * filled in by `styles.gaps`), and, while the legend narrows a continuous
      * color to a range, not outside it. A dimmed row stays drawn, never matched.
      */
-    static #hoverable(state, ctx, position, valueAxis) {
-        const range = ctx.interaction?.legend?.range;
+    static #hoverable(state, env, position, valueAxis) {
+        const range = env.interaction?.legend?.range;
         const color = state.channels?.color?.accessor;
         return (row) => {
             if (isGapValue(position[valueAxis](row)) || row[GAP_VALUE] !== undefined)

package/dist/phases/mapping/MappingPhase.d.ts

@@ -1,4 +1,4 @@
-import type { AxisPlotState, AxisPlotCtx, MappingStageOptions, PhaseStage } from '../../types/phases';
+import type { AxisPlotState, AxisPlotEnv, MappingStageOptions, PhaseStage } from '../../types/phases';
 type AnyAxisState = AxisPlotState<any, any, any, any>;
 /**
  * The "mapping" phase every axis-based plot shares: every channel resolved to
@@ -8,10 +8,10 @@ type AnyAxisState = AxisPlotState<any, any, any, any>;
  * its prop is set, and a size channel given a number stays that literal size.
  * An unset `x`/`y` reads each row itself, with no `source`.
  */
-export declare class MappingPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+export declare class MappingPhase<TState extends AnyAxisState, TEnv extends AxisPlotEnv> implements PhaseStage<TState, TEnv> {
     #private;
     readonly phase: "mapping";
-    constructor(options?: MappingStageOptions<TState, TCtx>);
-    run: (state: TState, ctx: TCtx) => TState;
+    constructor(options?: MappingStageOptions<TState, TEnv>);
+    run: (state: TState, env: TEnv) => TState;
 }
 export {};