@fundar/data-chart-telling 1.17.0 → 1.18.0

package/dist/plots/ranking/cleveland/ClevelandMarkers.js

@@ -25,8 +25,8 @@ export class ClevelandMarkers {
         warned.clear();
     }
     /** The plot's connectors, then its dots, which draw on top of them. */
-    marks = (state, ctx) => {
-        const { cfg, interaction } = ctx;
+    marks = (state, env) => {
+        const { cfg, interaction } = env;
         const style = cfg[this.#options.config];
         const { isHorizontal } = ClevelandMarkers.#geometry(state);
         const ranges = ClevelandRanges.of(state, this.#options.fromBaseline ?? false, ClevelandConnector.ends(state), this.#options.interval ?? false);
@@ -187,6 +187,7 @@ export class ClevelandMarkers {
                     type: 'dot',
                     series: name,
                     data: segment.data,
+                    hover: 'style',
                     ...(isHorizontal ? { x: value, y: category } : { x: category, y: value }),
                     r,
                     styles: {
@@ -206,7 +207,7 @@ export class ClevelandMarkers {
             ...caps,
             ...arrows,
             ...dots,
-            ...this.#connectorLabels(state, ctx, connector, looks, isHorizontal)
+            ...this.#connectorLabels(state, env, connector, looks, isHorizontal)
         ];
     };
     /** The dash, cap and join a connector is drawn with, leaving out what is not set. */
@@ -243,7 +244,7 @@ export class ClevelandMarkers {
         }));
     }
     /** The label on each connector, when `styles.connector.label` asks for one: written at its middle, beside it or on it. */
-    #connectorLabels(state, ctx, connector, looks, isHorizontal) {
+    #connectorLabels(state, env, connector, looks, isHorizontal) {
         const label = connector.label;
         if (!label)
             return [];
@@ -255,7 +256,7 @@ export class ClevelandMarkers {
             return [];
         const font = label.fontStyle;
         // Beside a connector: clear of half its thickest, and a few px.
-        const clear = Math.max(...data.map((row) => Number(row.strokeWidth))) / 2 + ctx.cfg.connector.labelGap;
+        const clear = Math.max(...data.map((row) => Number(row.strokeWidth))) / 2 + env.cfg.connector.labelGap;
         const inside = label.anchor === 'middle';
         const at = inside
             ? { dx: 0, dy: 0, textAnchor: 'middle', lineAnchor: 'middle' }
@@ -271,7 +272,7 @@ export class ClevelandMarkers {
                 styles: {
                     ...font,
                     fill: font?.fill ?? 'currentColor',
-                    fontSize: font?.fontSize ?? ctx.cfg.connector.labelFontSize,
+                    fontSize: font?.fontSize ?? env.cfg.connector.labelFontSize,
                     dx: font?.dx ?? at.dx,
                     dy: font?.dy ?? at.dy,
                     textAnchor: font?.textAnchor && font.textAnchor !== 'outside' ? font.textAnchor : at.textAnchor,
@@ -286,7 +287,7 @@ export class ClevelandMarkers {
      * of it), past the bottom end (below, or left of it) and, for the dots
      * between, beside it - and per series, when they take their series' color.
      */
-    valueLabels = (labels, state, ctx) => {
+    valueLabels = (labels, state, env) => {
         if (!state.processedData?.data.length)
             return [];
         const { isHorizontal } = ClevelandMarkers.#geometry(state);
@@ -294,7 +295,7 @@ export class ClevelandMarkers {
         const { font, format } = labels;
         const read = ValueLabels.valueOf(state);
         const valueOf = ProcessedPositions.of(state.processedData, PlotAxes.valueOf(state))[PlotAxes.valueOf(state)];
-        const gap = labels.offset(isHorizontal ? 'x' : 'y', ctx.cfg[this.#options.config].labelGap);
+        const gap = labels.offset(isHorizontal ? 'x' : 'y', env.cfg[this.#options.config].labelGap);
         const nameOf = (d) => String(d[SERIES_KEY]);
         const picked = this.#picked(state);
         // Where a label sits from its dot, by role: along the range (past an end) or across it (between).
@@ -329,7 +330,7 @@ export class ClevelandMarkers {
                     type: 'text',
                     data,
                     ...(isHorizontal ? { x: value, y: category } : { x: category, y: value }),
-                    text: (d) => format(Number(read(d) ?? valueOf(d)), nameOf(d), d),
+                    text: (d) => format(Number(read(d) ?? valueOf(d)), d, nameOf(d)),
                     styles: {
                         ...font,
                         fill: fillOf(name),
@@ -358,7 +359,7 @@ export class ClevelandMarkers {
             return [labels.edgeBox('0', { x: 'middle', y: 'before' }, at, ['top'])];
         }
         const at = { x: labels.offset('x', gap) };
-        const texts = new Set(top.map(({ dot }) => labels.format(dot.value, dot.series, dot.row)));
+        const texts = new Set(top.map(({ dot }) => labels.format(dot.value, dot.row, dot.series)));
         return [...texts].map((text) => labels.edgeBox(text, { x: 'after', y: 'middle' }, at, ['right']));
     };
     /**

package/dist/plots/ranking/cleveland/defaults.d.ts

@@ -1,5 +1,5 @@
 import type { AxisPlotDefaults } from '../../../types/phases';
-import type { ClevelandOptions, ClevelandPlotState, ClevelandPlotCtx } from '../../../types/plots/ranking/cleveland/state';
+import type { ClevelandOptions, ClevelandPlotState, ClevelandPlotEnv } from '../../../types/plots/ranking/cleveland/state';
 /**
  * ClevelandPlot on the shared pipeline, and the base of its wrappers: per
  * category along one category axis - `x`, or `y` for sideways rows, as the
@@ -10,4 +10,4 @@ import type { ClevelandOptions, ClevelandPlotState, ClevelandPlotCtx } from '../
  * what it checks about the series before drawing. Its plot defaults to hover
  * along the category axis.
  */
-export declare function buildClevelandDefaults<TData extends Record<string, unknown>>(options?: ClevelandOptions): AxisPlotDefaults<ClevelandPlotState<TData>, ClevelandPlotCtx>;
+export declare function buildClevelandDefaults<TData extends Record<string, unknown>>(options?: ClevelandOptions): AxisPlotDefaults<ClevelandPlotState<TData>, ClevelandPlotEnv>;

package/dist/plots/ranking/cleveland/defaults.js

@@ -1,4 +1,5 @@
 import { ClevelandMarkers } from './ClevelandMarkers';
+import { HoverDefaults } from '../../../layout/hover/HoverDefaults';
 import { ClevelandRanges } from './ClevelandRanges';
 import { NiceTicks } from '../../../layout/scales/NiceTicks';
 import { PlotAxes } from '../../../phases/data/PlotAxes';
@@ -53,16 +54,18 @@ export function buildClevelandDefaults(options = { name: 'ClevelandPlot', config
             fit: options.interval
                 ? (state) => fitInterval(state, options.fromBaseline ?? false)
                 : undefined,
-            defaults: (_state, ctx) => ({
+            defaults: (_state, env) => ({
                 category: {
-                    paddingInner: ctx.cfg[options.config].paddingInner,
-                    paddingOuter: ctx.cfg[options.config].paddingOuter
+                    paddingInner: env.cfg[options.config].paddingInner,
+                    paddingOuter: env.cfg[options.config].paddingOuter
                 }
             })
         },
         // A dot is labelled by what its category's dots say: the first, the highest... of each.
         transforms: { labels: { group: 'category', skip: ClevelandRanges.skipGaps } },
         styles: { values: { reach: markers.reach } },
-        markers: { marks: markers.marks, valueLabels: markers.valueLabels }
+        markers: { marks: markers.marks, valueLabels: markers.valueLabels },
+        // A rule along the value axis at the hovered dot, and a dot and a label on each one of its category.
+        hover: { marker: (state) => HoverDefaults.valueRule(PlotAxes.valueOf(state)) }
     };
 }

package/dist/plots/ranking/dumbbell/defaults.d.ts

@@ -1,9 +1,9 @@
 import type { AxisPlotDefaults } from '../../../types/phases';
-import type { DumbbellPlotState, DumbbellPlotCtx } from '../../../types/plots/ranking/dumbbell/state';
+import type { DumbbellPlotState, DumbbellPlotEnv } from '../../../types/plots/ranking/dumbbell/state';
 /**
  * DumbbellPlot on the shared pipeline: a ClevelandPlot of exactly two series,
  * so every category is two dots joined by a connector - the change, or the gap,
  * between them. It warns when it has another number of series, which
  * `LollipopPlot` (one) and `ClevelandPlot` (any) are for.
  */
-export declare function buildDumbbellDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<DumbbellPlotState<TData>, DumbbellPlotCtx>;
+export declare function buildDumbbellDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<DumbbellPlotState<TData>, DumbbellPlotEnv>;

package/dist/plots/ranking/forest/defaults.d.ts

@@ -1,5 +1,5 @@
 import type { AxisPlotDefaults } from '../../../types/phases';
-import type { ForestPlotState, ForestPlotCtx } from '../../../types/plots/ranking/forest/state';
+import type { ForestPlotState, ForestPlotEnv } from '../../../types/plots/ranking/forest/state';
 /**
  * ForestPlot on the shared pipeline: a ClevelandPlot whose dot is an estimate
  * and whose stem is its interval - each row's `lower` and `upper`, or `error`
@@ -8,4 +8,4 @@ import type { ForestPlotState, ForestPlotCtx } from '../../../types/plots/rankin
  * for - or `facet`, to compare the series side by side. The value axis fits the
  * intervals' ends.
  */
-export declare function buildForestDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<ForestPlotState<TData>, ForestPlotCtx>;
+export declare function buildForestDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<ForestPlotState<TData>, ForestPlotEnv>;

package/dist/plots/ranking/lollipop/defaults.d.ts

@@ -1,9 +1,9 @@
 import type { AxisPlotDefaults } from '../../../types/phases';
-import type { LollipopPlotState, LollipopPlotCtx } from '../../../types/plots/ranking/lollipop/state';
+import type { LollipopPlotState, LollipopPlotEnv } from '../../../types/plots/ranking/lollipop/state';
 /**
  * LollipopPlot on the shared pipeline: a ClevelandPlot of one value per
  * category, whose stem rises from the baseline - zero, or the nearest end of a
  * pinned value domain - to the dot. It warns when a category has values in
  * several series, which `DumbbellPlot` and `ClevelandPlot` are for.
  */
-export declare function buildLollipopDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<LollipopPlotState<TData>, LollipopPlotCtx>;
+export declare function buildLollipopDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<LollipopPlotState<TData>, LollipopPlotEnv>;

package/dist/types/configuration/styling.d.ts

@@ -243,6 +243,8 @@ export type PlotStylesConfig = {
         dot: DotStyle;
         font: FontStyle;
         area: AreaStyle;
+        /** How a hovered shape looks on a plot whose hover only restyles its shapes (a treemap's tile, a heatmap's cell). */
+        active: StrokeStyle;
     };
     facet: {
         /** Position badge shown in `carousel`/`paginated` facet modes. */
@@ -379,6 +381,8 @@ export type PlotStylesConfig = {
         /** Gap, in px, between a connector and its label when it is written beside it. */
         labelGap: number;
     };
+    /** The `band` marker's style, under its own `styles`. */
+    band: AreaStyle;
     /** The `delta` marker's label offset and anchor, per axis the delta is taken on. A marker's own `text` wins. */
     delta: {
         text: Record<'x' | 'y', {

package/dist/types/layout/context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a plot knows of one of the rows it draws: the series it is drawn in, where it sits, and the value it shows
+ * - the dataset's own, or the one the plot works out for it (a density's estimate, a bin's count). It is worked
+ * out once per row, as the plot reads its data, and every place that writes about a row reads it: a tooltip's
+ * `format`, a hover's points and labels, the value labels, and an author's own markers (see `RowContext.of`).
+ * A plot kind that works out more about a row gives a type that extends this one.
+ */
+export type PlotRowContext<TRow = Record<string, unknown>> = {
+    /** The name of the series the row is drawn in, on the plots that have series. */
+    series?: string;
+    /** The row's value on `x`: its own (not a stack's running total), else where the plot's transforms put it. */
+    x?: unknown;
+    /** The row's value on `y`, as `x`. */
+    y?: unknown;
+    /** The value the row shows, on the plot's value axis, when it is a number. */
+    value?: number;
+    /** The row itself, as the plot drew it: the data's fields, plus whatever its transforms added. */
+    row?: TRow;
+};
+/** A plot kind's own context of a row: the shared one, with what the kind works out for it. */
+export type KindRowContext<TExtra extends object, TRow = Record<string, unknown>> = PlotRowContext<TRow> & TExtra;

package/dist/types/layout/context.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,3 +1,4 @@
+import type { PlotRowContext } from './context';
 import type { AxisValue } from './mapping';
 /**
  * How the hover highlight finds related points within a facet.
@@ -41,6 +42,8 @@ export type HoverDisplayPoint = {
     color?: string;
     /** A 'grouped' series' own slice of the category band, as start/end fractions (0-1) of the whole band. `undefined` means the whole band. */
     areaInset?: BandSlice;
+    /** What the plot knows of the point's row: its series, where it sits, its value and whatever its kind works out - see {@link PlotRowContext}. */
+    context?: PlotRowContext;
 };
 /** A candidate point for hover matching/highlighting - also carries its source row. */
 export type HoverPoint<T> = HoverDisplayPoint & {

package/dist/types/layout/styles/values.d.ts

@@ -1,6 +1,7 @@
 import type { ValueAnchor } from '../../plots/constants';
 import type { FontStyle, StrokeStyle } from '../../plots/styling';
 import type { NumberDisplay } from '../numbers';
+import type { PlotRowContext } from '../context';
 /**
  * Which of a group's rows get a value label: its first or last, or the one
  * with the lowest or highest value (read on the plot's value axis). The group
@@ -38,8 +39,13 @@ export type ValuesStyle = NumberDisplay & {
      * CSS color writes them all in it. `fontStyle.fill` wins when it is set.
      */
     color?: 'series' | (string & {});
-    /** A label's text, in place of the value as `decimals`, `prefix`, `suffix` and `signDisplay` write it, from its row's own value (a histogram bin's count) and its series - and, on the plots that label one row each, that row, for the other fields of the data. */
-    format?: (value: number, seriesName: string, row?: Record<string, unknown>, number?: (value: number) => string) => string;
+    /**
+     * A label's text, in place of the value as `decimals`, `prefix`, `suffix` and `signDisplay` write it: from the
+     * value it shows (a histogram bin's count, a tile's share), `number`, which writes a value as those fields ask,
+     * and `context`, what the plot knows of the labelled row - its `series`, `x`, `y`, whatever its kind works out
+     * and, where the label has one, the `row` itself, for the other fields of the data (see {@link PlotRowContext}).
+     */
+    format?: (value: number, number: (value: number) => string, context: PlotRowContext) => string;
     /** Hovering a label dims every other series, like toggling them off in the legend. */
     hoverIsolate?: boolean;
     fontStyle?: FontStyle;

package/dist/types/layout/tooltip.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HoverStrategy } from './hover';
 import type { NumberDisplay } from './numbers';
+import type { PlotRowContext } from './context';
 /**
  * Preferred horizontal placement of the tooltip beside the cursor; it moves
  * to the other side when it would overflow. Defaults to `'right'`.
@@ -12,15 +13,8 @@ export type TooltipAnchorY = 'top' | 'middle' | 'bottom';
 export type TooltipRow<TRow> = TRow & {
     seriesColor?: string;
 };
-/**
- * What a plot knows of a hovered row beyond its own fields, the third argument of a tooltip's `format`:
- * the series it is drawn in, on the plots that have series. A plot kind that works out more about a row
- * gives a type that extends this one.
- */
-export type TooltipContext = {
-    /** The name of the series the row is drawn in. */
-    series?: string;
-};
+/** What a plot knows of a hovered row, the third argument of a tooltip's `format` - see {@link PlotRowContext}. */
+export type TooltipContext = PlotRowContext;
 /**
  * Author-facing tooltip option on the chart kinds. `true` = enable with defaults. `decimals`, `prefix`,
  * `suffix` and `signDisplay` write the value the default text shows - the one on the plot's value axis (the
@@ -33,7 +27,8 @@ export type TooltipOptions<TRow extends Record<string, unknown>, TContext extend
     sync?: boolean;
     /**
      * Custom tooltip text for a row (supports `\n`). Defaults per chart kind. `number` writes a value as the display
-     * fields above ask, and `context` is what the plot knows of the row - see {@link TooltipContext}.
+     * fields above ask, and `context` is what the plot knows of the row: its series, `x`, `y`, the value it shows and
+     * whatever its kind works out (a tile's share, a box's quartiles) - see {@link PlotRowContext}.
      */
     format?: (row: TRow, number: (value: number) => string, context: TContext) => string;
     /** Named subset of crossing series to include. Omitted = all matched. */

package/dist/types/markers/axis/axisBasedMarkersConfig.d.ts

@@ -23,8 +23,9 @@ import type { TrailMarkerConfig } from './trail';
 import type { WaffleMarkerConfig } from './waffle';
 import type { ViolinMarkerConfig } from './violin';
 import type { RuleMarkerConfig } from './rule';
+import type { BandMarkerConfig } from './band';
 import type { HoverMarkerConfig } from './hover';
 import type { CustomComponentMarkerConfig } from './component';
 import type { DeltaMarkerConfig } from './delta';
 /** Every marker kind an axis-based plot can render. */
-export type AxisBasedMarkersConfig = BasicMarkersConfig | LineMarkerConfig | BarMarkerConfig | CellMarkerConfig | RectMarkerConfig | RegressionMarkerConfig | BollingerMarkerConfig | AreaMarkerConfig | DensityMarkerConfig | BoxMarkerConfig | HullMarkerConfig | DifferenceMarkerConfig | ArrowMarkerConfig | BrushMarkerConfig | DelaunayLinkMarkerConfig | DelaunayMeshMarkerConfig | VoronoiMarkerConfig | VoronoiMeshMarkerConfig | ImageMarkerConfig | RasterMarkerConfig | TickMarkerConfig | TrailMarkerConfig | WaffleMarkerConfig | ViolinMarkerConfig | RuleMarkerConfig | HoverMarkerConfig | CustomComponentMarkerConfig | DeltaMarkerConfig;
+export type AxisBasedMarkersConfig = BasicMarkersConfig | LineMarkerConfig | BarMarkerConfig | CellMarkerConfig | RectMarkerConfig | RegressionMarkerConfig | BollingerMarkerConfig | AreaMarkerConfig | DensityMarkerConfig | BoxMarkerConfig | HullMarkerConfig | DifferenceMarkerConfig | ArrowMarkerConfig | BrushMarkerConfig | DelaunayLinkMarkerConfig | DelaunayMeshMarkerConfig | VoronoiMarkerConfig | VoronoiMeshMarkerConfig | ImageMarkerConfig | RasterMarkerConfig | TickMarkerConfig | TrailMarkerConfig | WaffleMarkerConfig | ViolinMarkerConfig | RuleMarkerConfig | BandMarkerConfig | HoverMarkerConfig | CustomComponentMarkerConfig | DeltaMarkerConfig;

package/dist/types/markers/axis/band.d.ts

@@ -0,0 +1,24 @@
+import type { AxisValue } from '../../layout/mapping';
+import type { BandSlice } from '../../layout/hover';
+import type { AreaStyle, PerRow } from '../../plots/styling';
+import type { CommonMarkerConfig } from '../channels/commonMarkerConfig';
+/**
+ * The band of a category on a band axis, across the whole of the other axis: one per category, however many rows
+ * name it. On an axis that is not a band scale it draws nothing.
+ */
+export type BandMarkerConfig = {
+    type: 'band';
+    axis: 'x' | 'y';
+    /**
+     * Which band. A list draws one at each category (without `data`); with `data`, a field key or a function of the
+     * row gives each row's own.
+     */
+    value: AxisValue | string | (AxisValue | string)[] | ((d: any) => AxisValue);
+    /**
+     * The part of the band it fills, as the fractions of its width left out at its start and its end (a grouped
+     * bar's series' slice). A function of the row gives each row's own; a band several rows share fills what all of
+     * them do. Unset, the whole band.
+     */
+    slice?: BandSlice | ((d: any) => BandSlice | undefined);
+    styles?: PerRow<AreaStyle>;
+} & Omit<CommonMarkerConfig, 'x' | 'y'>;

package/dist/types/markers/axis/band.js

@@ -0,0 +1 @@
+export {};

package/dist/types/markers/axis/bar.d.ts

@@ -3,10 +3,10 @@ import type { AreaStyle, PerRow, InsetStyle } from '../../plots/styling';
 import type { CommonMarkerConfigWithLabel } from '../channels/commonMarkerConfigWithLabel';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
 import type { CommonMarkerConfigWithInterval } from '../channels/commonMarkerConfigWithInterval';
-/** A bar mark; `role` tells a visible segment from the hover hit area and highlight. */
+/** A bar mark; `role` tells a visible segment from the hover hit area. */
 export type BarMarkerConfig = {
     type: 'bar';
-    role: 'segment' | 'hitArea' | 'highlight';
+    role: 'segment' | 'hitArea';
     isHorizontal: boolean;
     thickness?: number;
     styles?: PerRow<AreaStyle> & InsetStyle;

package/dist/types/markers/axis/hover.d.ts

@@ -1,10 +1,54 @@
-import type { AreaStyle, DotStyle, FontStyle, StrokeStyle } from '../../plots/styling';
+import type { AxisBasedMarkersConfig } from './axisBasedMarkersConfig';
 import type { HoverDisplayPoint, HoverStrategy } from '../../layout/hover';
 import type { NumberDisplay } from '../../layout/numbers';
+import type { LineStyle } from '../../plots/constants';
+/** A style value: the same for every shape, or a function of the row a shape draws. */
+type ShapeStyleValue<T> = T | ((row: any) => T);
 /**
- * In-SVG hover highlight: crosshair, dot and label. The label is the hovered value as `decimals`, `prefix`,
- * `suffix` and `signDisplay` write it - as the plot writes it while none of them (nor `numbers.decimals`) is set -
- * unless `format` writes it.
+ * How the shapes of a marker linked to the hover (`hover: true` or `'style'`) look while the hover is on: the
+ * hovered ones under `active`, the rest under `others`. Each value replaces the shape's own, and may be a
+ * function of its row.
+ */
+export type HoverShapeStyle = {
+    fill?: ShapeStyleValue<string>;
+    fillOpacity?: ShapeStyleValue<number>;
+    stroke?: ShapeStyleValue<string>;
+    strokeWidth?: ShapeStyleValue<number>;
+    strokeOpacity?: ShapeStyleValue<number>;
+    strokeDasharray?: string | LineStyle;
+};
+/** `T` with its `K` fields left to be set. */
+type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/** A marker as the hover takes it: a `rule`'s and a `band`'s `value` and a `text`'s `text` default to the point's. */
+type InHover<T> = T extends {
+    type: 'rule' | 'band';
+} ? Optional<T, 'value' & keyof T> : T extends {
+    type: 'text';
+} ? Optional<T, 'text' & keyof T> : T;
+/**
+ * A marker the hover draws: any marker but another hover, over the hovered points. Without `data` of its own its
+ * rows are the points - each its `x`, `y`, `label` (written as the hover marker's number fields ask), `series`,
+ * `color` (its series'), `areaInset` (its slice of the band) and `row` (the row it stands for) - and its `x` and
+ * `y` default to the point's. What it leaves unset comes from the hover: a `rule` sits at each point along its
+ * `axis`, a `band` around it (in its series' slice), a `text` writes its label; each in the configuration's `hover`
+ * look (a `rect` in its `area`), and a `dot` and a `text` in the point's series color.
+ */
+export type HoverLayerMarker = InHover<Exclude<AxisBasedMarkersConfig, {
+    type: 'hover';
+}>> & {
+    /**
+     * Which points it draws: every one the hover matches (the default), only the one under the pointer, or those a
+     * function of the point keeps.
+     */
+    points?: 'all' | 'active' | ((point: HoverDisplayPoint) => boolean);
+};
+/**
+ * The plot's hover, inside the plot: how the hovered shapes look (`active`) and the rest (`others`), and the
+ * markers it draws behind the plot's shapes (`back`) and in front of them (`front`) - a rule, a band, a dot, a
+ * label, a component. Each plot kind has a hover of its own that this one is laid over: `active` and `others`
+ * field by field, `back` and `front` replacing the kind's lists when set (`back: []` draws nothing behind).
+ * The points' label is the hovered value as `decimals`, `prefix`, `suffix` and `signDisplay` write it - as the
+ * plot writes it while none of them (nor `numbers.decimals`) is set - unless `format` writes it.
  */
 export type HoverMarkerConfig = NumberDisplay & {
     type: 'hover';
@@ -12,16 +56,17 @@ export type HoverMarkerConfig = NumberDisplay & {
     scope?: 'series' | 'segment';
     strategy?: HoverStrategy;
     sync?: boolean;
-    ruleX?: boolean;
-    ruleY?: boolean;
-    /** A thickened highlight area in place of a thin crosshair; meaningful on band scales only. */
-    areaX?: boolean;
-    areaY?: boolean;
-    showLabels?: boolean;
-    /** The label's text for a point, in place of the value. `number` writes a value as the display fields above ask. */
+    /** How the hovered shapes of every marker linked to the hover look - the plot's own tiles, bars and cells among them. */
+    active?: HoverShapeStyle;
+    /** How the shapes the hover does not reach look, while it is on. */
+    others?: HoverShapeStyle;
+    /** The markers drawn behind every other one of the plot, over the hovered points. */
+    back?: HoverLayerMarker[];
+    /** The markers drawn in front of the plot's shapes, over the hovered points. */
+    front?: HoverLayerMarker[];
+    /** A point's label, in place of its value. `number` writes a value as the display fields above ask. */
     format?: (point: HoverDisplayPoint, number: (value: number) => string) => string;
-    rule?: StrokeStyle;
-    area?: AreaStyle;
-    dot?: DotStyle;
-    text?: FontStyle;
 };
+/** What a plot kind's own hover is made of, which an author's `hover` marker is laid over. */
+export type HoverLook = Pick<HoverMarkerConfig, 'active' | 'others' | 'back' | 'front'>;
+export {};

package/dist/types/markers/channels/commonMarkerConfig.d.ts

@@ -28,6 +28,10 @@ export type CommonMarkerConfig = CommonMarkerEvents & {
     clip?: boolean;
     /** Names the marker on its plot's automatic legend - see {@link MarkLegend}. `false` keeps a decorative marker out of it, and out of how the plot's series look there. */
     legend?: MarkLegend | false;
-    /** Makes the marker a hit area of the plot's hover: the pointer entering any of its shapes hovers its `data` rows. */
-    hover?: boolean;
+    /**
+     * Links the marker to the plot's hover. `'trigger'` makes it a hit area: the pointer entering any of its shapes
+     * hovers its `data` rows. `'style'` has its shapes take the hover marker's `active` and `others` styles.
+     * `true` does both.
+     */
+    hover?: boolean | 'trigger' | 'style';
 };

package/dist/types/markers/common.d.ts

@@ -22,6 +22,7 @@ export * from './axis/trail';
 export * from './axis/waffle';
 export * from './axis/violin';
 export * from './axis/rule';
+export * from './axis/band';
 export * from './axis/hover';
 export * from './axis/component';
 export * from './axis/axisBasedMarkersConfig';

package/dist/types/markers/common.js

@@ -22,6 +22,7 @@ export * from './axis/trail';
 export * from './axis/waffle';
 export * from './axis/violin';
 export * from './axis/rule';
+export * from './axis/band';
 export * from './axis/hover';
 export * from './axis/component';
 export * from './axis/axisBasedMarkersConfig';

package/dist/types/phases/context/phase.d.ts

@@ -0,0 +1,7 @@
+/**
+ * What a plot kind works out for each of its processed rows beyond the shared context (its series, `x`, `y` and
+ * value): a tile's share, a bin's edges, a box's quartiles. Given the state once, it returns a function of a row,
+ * so whatever the rows share (a total, a box's summary) is worked out once. What it returns is laid over the
+ * shared context, so it can also replace the `value` a row shows.
+ */
+export type ContextStageOptions<TState, TEnv = unknown> = (state: TState, env: TEnv) => (row: never) => object | undefined;

package/dist/types/phases/context/phase.js

@@ -0,0 +1 @@
+export {};

package/dist/types/phases/data/phase.d.ts

@@ -15,7 +15,7 @@ export type SegmentsStageOptions = {
  * which channels the author set, what each axis is, which way the plot runs,
  * whether `color` groups - the stage reads off the data itself.
  */
-export type DataStageOptions<TState, TCtx> = {
+export type DataStageOptions<TState, TEnv> = {
     /** How many axes the kind lays out as categories: 0 (line), 1 (bar) or 2 (heatmap). Defaults to 0. */
     discreteAxes?: DiscreteAxesCount;
     /** How the kind's own mark splits into visual segments. */
@@ -30,5 +30,5 @@ export type DataStageOptions<TState, TCtx> = {
      */
     nested?: boolean;
     /** The plot's own extra "data" output, once the shared one is in place. */
-    extend?: (state: TState, ctx: TCtx) => TState;
+    extend?: (state: TState, env: TEnv) => TState;
 };

package/dist/types/phases/hover/phase.d.ts

@@ -1,5 +1,6 @@
 import type { HoverDisplayPoint, HoverStrategy } from '../../layout/hover';
 import type { HoverConfig, PointMatchingStrategy } from '../../plots/props';
+import type { HoverLook } from '../../markers/common';
 /** Where a row sits for hover matching and the hover controller: its `x` and `y`. */
 export type HoverPosition = {
     x: (row: never) => unknown;
@@ -11,7 +12,7 @@ export type HoverPosition = {
  * row or a cell outside the legend's range can't), the rows themselves and
  * their series' colors - the stage reads off the plot's own state.
  */
-export type HoverStageOptions<TState, TCtx = unknown> = {
+export type HoverStageOptions<TState, TEnv = unknown> = {
     /**
      * The hover strategy, when the plot's axes don't say it: along the axis
      * that isn't measured, or `'punctual'` with both axes holding categories.
@@ -27,16 +28,18 @@ export type HoverStageOptions<TState, TCtx = unknown> = {
     position?: (state: TState) => HoverPosition;
     /** The short label drawn next to a hovered row. Defaults to its value. */
     label?: (state: TState) => (row: never) => string;
-    /** What a hovered row reads as, e.g. with derived fields added. Defaults to the processed row. */
-    row?: (state: TState) => (row: never) => unknown;
     /** Fields a candidate carries besides its place, label and series color (a grouped bar's `dx`/`dy`). */
-    decorate?: (state: TState, ctx: TCtx) => (row: never) => Partial<Omit<HoverDisplayPoint, 'x' | 'y' | 'label'>>;
+    decorate?: (state: TState, env: TEnv) => (row: never) => Partial<Omit<HoverDisplayPoint, 'x' | 'y' | 'label'>>;
     /** Invisible markers that drive the plot's hover themselves (a bar's band), given its resolved hover config. */
-    hitAreas?: (state: TState, hover: HoverConfig<any>, ctx: TCtx) => {
+    hitAreas?: (state: TState, hover: HoverConfig<any>, env: TEnv) => {
         type: string;
     }[];
-    /** What the kind knows of a row beyond its series, which an author's own tooltip `format` gets in its third argument. */
-    context?: (state: TState) => (row: never) => object;
     /** How a pointer event resolves to a candidate. Defaults to the nearest one. */
     pointMatching?: PointMatchingStrategy;
+    /**
+     * The kind's own hover, which an author's `hover` marker is laid over - one look, or one for each strategy, as
+     * the strategy in force can change while the plot is shown (a composer's, a scrolly step's). Defaults to a
+     * crosshair along the axes the strategy matches along, and a dot and a label on each point.
+     */
+    marker?: (state: TState, env: TEnv) => HoverLook | ((strategy: HoverStrategy) => HoverLook);
 };

package/dist/types/phases/index.d.ts

@@ -1,10 +1,11 @@
 export type { PlotPhase, PhaseStage } from './stage';
-export type { AxisPlotState, AxisPlotCtx } from './state';
+export type { AxisPlotState, AxisPlotEnv } from './state';
 export type { AxisPlotKind, AxisPlotDefaults, SharedScalesOptions } from './kind';
 export type { DataRunState } from './pipeline';
 export type { DataStageOptions } from './data/phase';
 export type { MappingStageOptions } from './mapping/phase';
 export type { ProcessedRow, ProcessedChannel, ProcessedChannelName, ProcessedData, TransformsStageState, TransformsStageOptions } from './transforms/phase';
+export type { ContextStageOptions } from './context/phase';
 export type { StatisticsStageState, StatisticsStageOptions } from './statistics/phase';
 export type { SharedAxisValues } from './sharedScales/phase';
 export type { AxisFit, ScalesStageOptions } from './scales/phase';

package/dist/types/phases/kind.d.ts

@@ -4,6 +4,7 @@ import type { TransformsStageOptions, TransformsStageState } from './transforms/
 import type { StatisticsStageOptions, StatisticsStageState } from './statistics/phase';
 import type { ScalesStageOptions } from './scales/phase';
 import type { HoverStageOptions } from './hover/phase';
+import type { ContextStageOptions } from './context/phase';
 import type { StylesStageOptions } from './styles/phase';
 import type { MarkersStageOptions } from './markers/phase';
 import type { AxisChannelName, ChannelName } from '../layout/mapping';
@@ -12,15 +13,17 @@ import type { AxisRole } from './data/axes';
  * What one axis-based plot kind adds to the shared pipeline: options for each
  * shared stage - its own marks and value labels among them.
  */
-export type AxisPlotKind<TState extends TransformsStageState & StatisticsStageState, TCtx> = {
-    data?: DataStageOptions<TState, TCtx>;
-    mapping?: MappingStageOptions<TState, TCtx>;
-    transforms?: TransformsStageOptions<TState, TCtx>;
+export type AxisPlotKind<TState extends TransformsStageState & StatisticsStageState, TEnv> = {
+    data?: DataStageOptions<TState, TEnv>;
+    mapping?: MappingStageOptions<TState, TEnv>;
+    transforms?: TransformsStageOptions<TState, TEnv>;
+    /** What the kind works out for each of its rows, for everything that writes about a row to read - see `RowContext`. */
+    context?: ContextStageOptions<TState, TEnv>;
     statistics?: StatisticsStageOptions<TState>;
-    scales?: ScalesStageOptions<TState, TCtx>;
+    scales?: ScalesStageOptions<TState, TEnv>;
     styles?: StylesStageOptions<TState>;
-    markers: MarkersStageOptions<TState, TCtx>;
-    hover?: HoverStageOptions<TState, TCtx>;
+    markers: MarkersStageOptions<TState, TEnv>;
+    hover?: HoverStageOptions<TState, TEnv>;
     /**
      * How the slices of a plot (facet panels, timeline steps) share their
      * domains. Every axis kind shares them - bands from its axes, zero from its
@@ -42,7 +45,7 @@ export type SharedScalesOptions = {
  * runs with: the options for each pipeline phase (its hover among them),
  * plus how its plot tweens a timeline unless the author says otherwise.
  */
-export type AxisPlotDefaults<TState extends TransformsStageState & StatisticsStageState, TCtx> = AxisPlotKind<TState, TCtx> & {
+export type AxisPlotDefaults<TState extends TransformsStageState & StatisticsStageState, TEnv> = AxisPlotKind<TState, TEnv> & {
     timeline?: {
         /** Default for `timeline.filterMode`. */
         filterMode?: 'exact' | 'upTo';

package/dist/types/phases/mapping/phase.d.ts

@@ -1,5 +1,5 @@
 /** What differs between plots in the shared "mapping" stage. */
-export type MappingStageOptions<TState, TCtx> = {
+export type MappingStageOptions<TState, TEnv> = {
     /** The plot's own extra "mapping" output, once every channel is resolved. */
-    extend?: (state: TState, ctx: TCtx) => TState;
+    extend?: (state: TState, env: TEnv) => TState;
 };