@fundar/data-chart-telling 1.17.0 → 1.18.0

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

@@ -1,13 +1,13 @@
 import type { ValueLabels } from '../../../layout/styles/ValueLabels';
 import type { AxisBasedMarkersConfig, TextMarkerConfig } from '../../markers/common';
 /** What a plot kind adds to the shared "markers" stage. */
-export type MarkersStageOptions<TState, TCtx> = {
+export type MarkersStageOptions<TState, TEnv> = {
     /** The plot's own marks - its bars, lines, dots... - drawn under every other marker. */
-    marks: (state: TState, ctx: TCtx) => AxisBasedMarkersConfig[];
+    marks: (state: TState, env: TEnv) => AxisBasedMarkersConfig[];
     /**
      * Its value labels, once they show: `text` markers drawn over everything.
      * The stage adds what every label shares - see {@link ValueLabels.hooks}.
      * Without it, the plot draws none.
      */
-    valueLabels?: (labels: ValueLabels, state: TState, ctx: TCtx) => TextMarkerConfig[];
+    valueLabels?: (labels: ValueLabels, state: TState, env: TEnv) => TextMarkerConfig[];
 };

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

@@ -13,7 +13,7 @@ export type AxisFit = Partial<AnyAxisScale> & {
  * numeric axis to cover derived markers and transformed ranges; these say
  * where a kind goes beyond that.
  */
-export type ScalesStageOptions<TState, TCtx> = {
+export type ScalesStageOptions<TState, TEnv> = {
     /** Axes whose marks grow from zero, so a domain this stage sets still reaches it - by name or by role (`'value'`). */
     zero?: AxisRef[];
     /** Axes that reach as far below zero as above it, to the largest magnitude - by name or by role. */
@@ -21,10 +21,10 @@ export type ScalesStageOptions<TState, TCtx> = {
     /** Keeps a category axis in the order the data gives it. Without it, categories sort ascending, as svelteplot does. */
     bandOrder?: 'data';
     /** The kind's own options for an axis, by name or by role, under the author's `scales`: padding, label anchor, tick format. */
-    defaults?: (state: TState, ctx: TCtx) => Partial<Record<AxisRef, AnyAxisScale>>;
+    defaults?: (state: TState, env: TEnv) => Partial<Record<AxisRef, AnyAxisScale>>;
     /** The options the kind fits to its own marks on an axis the author left unpinned - a niced value axis, a domain padded for its dots. */
-    fit?: (state: TState, ctx: TCtx) => Partial<Record<AxisChannelName, AxisFit>>;
+    fit?: (state: TState, env: TEnv) => Partial<Record<AxisChannelName, AxisFit>>;
     /** The kind's own extra "scales" output, once every scale is in place. */
-    extend?: (state: TState, ctx: TCtx) => TState;
+    extend?: (state: TState, env: TEnv) => TState;
 };
 export {};

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

@@ -4,9 +4,9 @@
  * of a plot shares, `tooltip`, how a hovered row reads once
  * everything it reads from is placed, and `hover`, what the pointer can match.
  */
-export type PlotPhase = 'facet' | 'data' | 'mapping' | 'transforms' | 'statistics' | 'sharedScales' | 'scales' | 'styles' | 'markers' | 'coordinates' | 'tooltip' | 'hover';
+export type PlotPhase = 'facet' | 'data' | 'mapping' | 'transforms' | 'context' | 'statistics' | 'sharedScales' | 'scales' | 'styles' | 'markers' | 'coordinates' | 'tooltip' | 'hover';
 /** A resolution step for one {@link PlotPhase} - same state shape in and out. Each shared phase is a class (`DataPhase`, `HoverPhase`...) that implements it. */
-export type PhaseStage<TState, TCtx = unknown> = {
+export type PhaseStage<TState, TEnv = unknown> = {
     phase: PlotPhase;
-    run: (state: TState, ctx: TCtx) => TState;
+    run: (state: TState, env: TEnv) => TState;
 };

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

@@ -91,7 +91,7 @@ export type AxisPlotState<TData extends Record<string, unknown>, TStyle extends
     hoverRows?: unknown[];
 };
 /** The environment every axis-based plot's phases read from, alongside the growing state. */
-export type AxisPlotCtx = {
+export type AxisPlotEnv = {
     cfg: PlotStylesConfig;
     /** The legend's toggles and the figure's hover, read for one plot: which series show and how each dims. */
     interaction?: PlotInteraction;

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

@@ -1,3 +1,4 @@
+import type { PlotRowContext } from '../../layout/context';
 import type { EdgeBox } from '../../layout/box';
 import type { ValueLabels } from '../../../layout/styles/ValueLabels';
 import type { ValueAnchor } from '../../plots/constants';
@@ -7,8 +8,8 @@ export type ValueLabelsOptions<TState> = {
     show?: boolean;
     /** Where a label sits when `styles.values.anchor` is unset. Defaults to `'outside'`. */
     anchor?: ValueAnchor;
-    /** A label's text when `styles.values.format` is unset. Defaults to the bare value. `number` writes a value as the plot's `styles.values` display fields (`decimals`, `prefix`, `suffix`, `signDisplay`) ask. */
-    format?: (value: number, seriesName: string, number: (value: number) => string) => string;
+    /** A label's text when `styles.values.format` is unset. Defaults to the bare value. `number` writes a value as the plot's `styles.values` display fields (`decimals`, `prefix`, `suffix`, `signDisplay`) ask, and `context` is what the plot knows of the labelled row. */
+    format?: (value: number, number: (value: number) => string, context: PlotRowContext) => string;
     /**
      * Where the labels are expected to sit, from the whole data: boxes around
      * the points they label, on the plot edges those points can reach (see

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

@@ -51,9 +51,9 @@ export type TransformsStageState = {
     processedGroups?: VisualGroup<Series<ProcessedRow>, any>[];
 };
 /** What differs between plots in the shared "transforms" stage. */
-export type TransformsStageOptions<TState extends TransformsStageState, TCtx> = {
+export type TransformsStageOptions<TState extends TransformsStageState, TEnv> = {
     /** The transforms to run. Defaults to the plot's own `transforms`. */
-    transforms?: (state: TState, ctx: TCtx) => MarkerTransform[];
+    transforms?: (state: TState, env: TEnv) => MarkerTransform[];
     /**
      * Whether a series the legend omits keeps its part of the whole (a treemap's tile): the transforms run over
      * its rows too, so every other part keeps its share and its place, and its own rows are dropped after.

package/dist/types/plots/constants.d.ts

@@ -32,11 +32,9 @@ export type FontWeight = 'normal' | 'bold' | number;
 /** `font-style` keyword accepted by any text styling. */
 export type FontStyleKeyword = 'normal' | 'italic';
 /**
- * Horizontal text anchor. `'outside'` is only meaningful where the consuming
- * mark resolves it per-point from a signed x value (currently `HoverMarker`
- * only) - it anchors the label away from zero: `'start'` (extending right)
- * for a positive x, `'end'` (extending left) for negative. Elsewhere it's
- * treated the same as `'start'`.
+ * Horizontal text anchor. `'outside'` leaves the side to the mark that writes
+ * the label, where it picks one per point (a Cleveland plot's labels take
+ * their own); elsewhere it's treated the same as `'start'`.
  */
 export type TextAnchor = 'start' | 'middle' | 'end' | 'outside';
 /** Vertical text anchor. */

package/dist/types/plots/correlation/heatmap/state.d.ts

@@ -1,7 +1,7 @@
 import type { CellSegmentStyle } from '../../segments/common';
 import type { ResolvedChannel, ResolvedChannels } from '../../../layout/mapping';
 import type { LegendRange } from '../../../layout/legend';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /**
  * The active continuous-legend range filter, if any - narrows which cells
  * render at full opacity, and in `'rescale'` mode, the color domain itself.
@@ -23,6 +23,6 @@ export type HeatmapPlotState<TData extends Record<string, unknown>> = AxisPlotSt
     resolveOpacity?: (row: TData) => number;
 };
 /** The environment every HeatmapPlot phase reads from, alongside the growing state. */
-export type HeatmapPlotCtx = AxisPlotCtx & {
+export type HeatmapPlotEnv = AxisPlotEnv & {
     range: HeatmapRangeFilter | null | undefined;
 };

package/dist/types/plots/correlation/scatter/state.d.ts

@@ -1,6 +1,6 @@
 import type { ScatterSegmentStyle } from '../../segments/common';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** ScatterPlot's pipeline state: the shared axis-based state, with no extras of its own. */
 export type ScatterPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, ScatterSegmentStyle>;
 /** The environment every ScatterPlot phase reads from, alongside the growing state. */
-export type ScatterPlotCtx = AxisPlotCtx;
+export type ScatterPlotEnv = AxisPlotEnv;

package/dist/types/plots/distribution/box/props.d.ts

@@ -1,10 +1,32 @@
+import type { KindRowContext } from '../../../layout/context';
+import type { AxisValue } from '../../../layout/mapping';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
 import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { AxisBasedStylesConfig } from '../../../layout/styles';
 import type { AreaStyle } from '../../styling';
+/**
+ * One box's summary: its category, its quartiles, the whisker ends (the farthest values within 1.5 IQR of the box),
+ * how many values it has and the ones past the whiskers.
+ */
+export type BoxSummary = {
+    category: AxisValue;
+    min: number;
+    p25: number;
+    median: number;
+    p75: number;
+    max: number;
+    count: number;
+    outliers: number[];
+};
+/**
+ * What a `BoxPlot` or a `ViolinPlot` knows of a row, which its tooltip's and value labels' `format`, its hover and
+ * `usePlot().contextOf` read: the summary of the box (or violin) it is in. A value's own `value` stays its own; a
+ * hovered box's is its median.
+ */
+export type BoxRowContext = KindRowContext<BoxSummary>;
 /** `BoxPlot`'s public props. */
-export type BoxPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type BoxPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>, undefined, BoxRowContext>;
 /** What `BoxPlot`'s core draws from. */
 export type BoxPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/distribution/box/state.d.ts

@@ -1,23 +1,12 @@
 import type { AreaStyle } from '../../styling';
-import type { AxisPlotState, AxisPlotCtx, ProcessedRow } from '../../../phases';
-import type { AxisValue } from '../../../layout/mapping';
+import type { AxisPlotState, AxisPlotEnv, ProcessedRow } from '../../../phases';
+import type { BoxSummary } from './props';
 /** BoxPlot's pipeline state: the shared axis-based state, with no extras of its own. */
 export type BoxPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
 /** The environment every BoxPlot phase reads from, alongside the growing state. */
-export type BoxPlotCtx = AxisPlotCtx;
+export type BoxPlotEnv = AxisPlotEnv;
 /**
- * One box's summary - what a hovered box reads as: its category, its
- * quartiles, the whisker ends (the farthest values within 1.5 IQR of the
- * box) and the values past them. It also keeps the series tags and, when the
- * category channel is a field key, the category under that field.
+ * One box's summary as a row - what a hovered box reads as. It also keeps the series tags and, when the category
+ * channel is a field key, the category under that field.
  */
-export type BoxSummaryRow = ProcessedRow & {
-    category: AxisValue;
-    min: number;
-    p25: number;
-    median: number;
-    p75: number;
-    max: number;
-    count: number;
-    outliers: number[];
-};
+export type BoxSummaryRow = ProcessedRow & BoxSummary;

package/dist/types/plots/distribution/density/state.d.ts

@@ -1,6 +1,6 @@
 import type { AreaStyle } from '../../styling';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** DensityPlot's pipeline state: the shared axis-based state, with no extras of its own. */
 export type DensityPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
 /** The environment every DensityPlot phase reads from, alongside the growing state. */
-export type DensityPlotCtx = AxisPlotCtx;
+export type DensityPlotEnv = AxisPlotEnv;

package/dist/types/plots/distribution/histogram/props.d.ts

@@ -1,10 +1,23 @@
+import type { KindRowContext } from '../../../layout/context';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
 import type { SeriesProps, SingleAxisDataProps } from '../../data/common';
 import type { AxisBasedStylesConfig } from '../../../layout/styles';
 import type { AreaStyle } from '../../styling';
+/**
+ * What a `HistogramPlot` knows of a bin, which its tooltip's and value labels' `format`, its hover and
+ * `usePlot().contextOf` read: its `count` (also its `value`) and the edges it spans.
+ */
+export type HistogramRowContext = KindRowContext<{
+    /** How many values fall in the bin. */
+    count: number;
+    /** The bin's lower edge. */
+    from: number;
+    /** The bin's upper edge. */
+    to: number;
+}>;
 /** `HistogramPlot`'s public props. */
-export type HistogramPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | SingleAxisDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type HistogramPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | SingleAxisDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>, undefined, HistogramRowContext>;
 /** What `HistogramPlot`'s core draws from. */
 export type HistogramPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | SingleAxisDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/distribution/histogram/state.d.ts

@@ -1,6 +1,6 @@
 import type { AreaStyle } from '../../styling';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** HistogramPlot's pipeline state: the shared axis-based state, with no extras of its own. */
 export type HistogramPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
 /** The environment every HistogramPlot phase reads from, alongside the growing state. */
-export type HistogramPlotCtx = AxisPlotCtx;
+export type HistogramPlotEnv = AxisPlotEnv;

package/dist/types/plots/distribution/pyramid/state.d.ts

@@ -1,6 +1,6 @@
 import type { Series } from '../../data/common';
 import type { BarSegmentStyle } from '../../segments/common';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 export type PyramidSide = 'left' | 'right';
 /** A resolved series tagged with which side of the shared zero baseline it renders on. */
 export type PyramidSeries<TData extends Record<string, unknown>> = Series<TData> & {
@@ -13,4 +13,4 @@ export type PyramidSeries<TData extends Record<string, unknown>> = Series<TData>
  */
 export type PyramidPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, BarSegmentStyle, PyramidSeries<TData>>;
 /** The environment every PyramidPlot phase reads from, alongside the growing state. */
-export type PyramidPlotCtx = AxisPlotCtx;
+export type PyramidPlotEnv = AxisPlotEnv;

package/dist/types/plots/distribution/violin/props.d.ts

@@ -1,3 +1,4 @@
+import type { BoxRowContext } from '../box/props';
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
@@ -18,6 +19,6 @@ export type ViolinPlotStylesConfig = AxisBasedStylesConfig & {
     box?: boolean | number;
 };
 /** `ViolinPlot`'s public props. */
-export type ViolinPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ViolinPlotStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type ViolinPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ViolinPlotStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>, undefined, BoxRowContext>;
 /** What `ViolinPlot`'s core draws from. */
 export type ViolinPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ViolinPlotStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/distribution/violin/state.d.ts

@@ -1,6 +1,6 @@
 import type { AreaStyle } from '../../styling';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** ViolinPlot's pipeline state: the shared axis-based state, with no extras of its own. */
 export type ViolinPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
 /** The environment every ViolinPlot phase reads from, alongside the growing state. */
-export type ViolinPlotCtx = AxisPlotCtx;
+export type ViolinPlotEnv = AxisPlotEnv;

package/dist/types/plots/evolution/area/state.d.ts

@@ -1,6 +1,6 @@
 import type { AreaStyle } from '../../styling';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** AreaPlot's pipeline state: the shared axis-based state, with no extras of its own. */
 export type AreaPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
 /** The environment every AreaPlot phase reads from, alongside the growing state. */
-export type AreaPlotCtx = AxisPlotCtx;
+export type AreaPlotEnv = AxisPlotEnv;

package/dist/types/plots/evolution/line/state.d.ts

@@ -1,9 +1,9 @@
 import type { GapsConfig } from '../../gaps';
 import type { LineSegmentStyle } from '../../segments/common';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** LinePlot's pipeline state: the shared axis-based state plus its gaps. */
 export type LinePlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, LineSegmentStyle> & {
     gaps?: GapsConfig<LineSegmentStyle>;
 };
 /** The environment every LinePlot phase reads from, alongside the growing state. */
-export type LinePlotCtx = AxisPlotCtx;
+export type LinePlotEnv = AxisPlotEnv;

package/dist/types/plots/evolution/slope/state.d.ts

@@ -1,5 +1,5 @@
-import type { LinePlotState, LinePlotCtx } from '../line/state';
+import type { LinePlotState, LinePlotEnv } from '../line/state';
 /** SlopePlot's pipeline state: a LinePlot's. */
 export type SlopePlotState<TData extends Record<string, unknown>> = LinePlotState<TData>;
 /** The environment every SlopePlot phase reads from, alongside the growing state. */
-export type SlopePlotCtx = LinePlotCtx;
+export type SlopePlotEnv = LinePlotEnv;

package/dist/types/plots/evolution/sparkline/state.d.ts

@@ -1,5 +1,5 @@
-import type { LinePlotState, LinePlotCtx } from '../line/state';
+import type { LinePlotState, LinePlotEnv } from '../line/state';
 /** SparklinePlot's pipeline state: a LinePlot's. */
 export type SparklinePlotState<TData extends Record<string, unknown>> = LinePlotState<TData>;
 /** The environment every SparklinePlot phase reads from, alongside the growing state. */
-export type SparklinePlotCtx = LinePlotCtx;
+export type SparklinePlotEnv = LinePlotEnv;

package/dist/types/plots/map/geo/state.d.ts

@@ -78,7 +78,7 @@ export type GeoPlotState<TProps extends Record<string, unknown>> = {
     hoverRows?: TaggedGeoFeature<TProps>[];
 };
 /** The environment every GeoPlot phase reads from, alongside the growing state. */
-export type GeoPlotCtx<TProps extends Record<string, unknown>> = {
+export type GeoPlotEnv<TProps extends Record<string, unknown>> = {
     cfg: PlotStylesConfig;
     range: GeoRangeFilter | null | undefined;
     fill?: string;

package/dist/types/plots/part-of-a-whole/treemap/props.d.ts

@@ -3,13 +3,23 @@ import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
 import type { NonAxisDataProps } from '../../data/common';
 import type { AxisBasedStylesConfig } from '../../../layout/styles';
-import type { TooltipContext } from '../../../layout/tooltip';
+import type { KindRowContext } from '../../../layout/context';
 import type { BarSegmentStyle } from '../../segments/common';
-/** What a `TreemapPlot` knows of a hovered tile beyond its row, the third argument of `tooltip.format`. */
-export type TreemapTooltipContext = TooltipContext & {
+/**
+ * What a `TreemapPlot` knows of a tile, which its tooltip's and value labels' `format`, its hover and
+ * `usePlot().contextOf` read: its series (the outermost level), and what the plot works out for it. Its `value`
+ * is the tile's summed value, and it has no `x` or `y`.
+ */
+export type TreemapRowContext = KindRowContext<{
+    /** The tile's name: the value at its innermost level. */
+    name: string;
+    /** The value at every level of the tile, outermost first. */
+    path: string[];
     /** The tile's part of the whole, from `0` to `100`, worked out from the values in whatever unit they are. */
     share: number;
-};
+}>;
+/** What a `TreemapPlot`'s `tooltip.format` gets in its third argument - see {@link TreemapRowContext}. */
+export type TreemapTooltipContext = TreemapRowContext;
 /**
  * `TreemapPlot`'s public props: flat rows, a tile each, on no axes. `value` is a tile's area, and `grouping` what
  * the tiles nest by (`'sector.branch'`, outermost first), whose outermost level colors them.

package/dist/types/plots/part-of-a-whole/treemap/state.d.ts

@@ -1,6 +1,6 @@
 import type { BarSegmentStyle } from '../../segments/common';
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 /** TreemapPlot's pipeline state: the shared axis-based state, over a unit square its tiles are laid out in. */
 export type TreemapPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, BarSegmentStyle>;
 /** The environment every TreemapPlot phase reads from, alongside the growing state. */
-export type TreemapPlotCtx = AxisPlotCtx;
+export type TreemapPlotEnv = AxisPlotEnv;

package/dist/types/plots/props.d.ts

@@ -1,3 +1,4 @@
+import type { HoverLook } from '../markers/common';
 import type { Pipeline } from '../../phases/Pipeline';
 import type { Snippet } from 'svelte';
 import type { TooltipContext, TooltipOptions, TooltipProp } from '../layout/tooltip';
@@ -62,6 +63,8 @@ export type HoverConfig<TRow extends Record<string, unknown>> = {
     pointMatching?: PointMatchingStrategy;
     /** Forces the crosshair rule(s) a `hover` marker draws off entirely, overriding whatever `strategy` implies. */
     crosshair?: boolean;
+    /** The plot kind's own hover under the strategy in force, which an author's `hover` marker is laid over as it is drawn. */
+    look?: (strategy: HoverStrategy) => HoverLook;
 };
 /** The `scales` prop of any plot kind. */
 export type ScalesConfig<TData = Record<string, unknown>> = AxisBasedScalesConfig<TData> | GeoScalesConfig;

package/dist/types/plots/ranking/bar/state.d.ts

@@ -1,6 +1,6 @@
-import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv } from '../../../phases';
 import type { BarSegmentStyle } from '../../segments/common';
 /** BarPlot's pipeline state: the shared axis-based state. */
 export type BarPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, BarSegmentStyle>;
 /** The environment every BarPlot phase reads from, alongside the growing state. */
-export type BarPlotCtx = AxisPlotCtx;
+export type BarPlotEnv = AxisPlotEnv;

package/dist/types/plots/ranking/bullet/state.d.ts

@@ -1,5 +1,5 @@
-import type { BarPlotState, BarPlotCtx } from '../bar/state';
+import type { BarPlotState, BarPlotEnv } from '../bar/state';
 /** BulletPlot's pipeline state: a bar plot's, which already carries the `target` and `ranges` it measures against. */
 export type BulletPlotState<TData extends Record<string, unknown>> = BarPlotState<TData>;
 /** The environment every BulletPlot phase reads from. */
-export type BulletPlotCtx = BarPlotCtx;
+export type BulletPlotEnv = BarPlotEnv;

package/dist/types/plots/ranking/cleveland/state.d.ts

@@ -1,9 +1,9 @@
-import type { AxisPlotState, AxisPlotCtx, ProcessedRow } from '../../../phases';
+import type { AxisPlotState, AxisPlotEnv, ProcessedRow } from '../../../phases';
 import type { LineSegmentStyle } from '../../segments/common';
 /** ClevelandPlot's pipeline state (shared by its wrappers): the shared axis-based state, with no extras of its own. */
 export type ClevelandPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, LineSegmentStyle>;
 /** The environment every ClevelandPlot phase reads from, alongside the growing state. */
-export type ClevelandPlotCtx = AxisPlotCtx;
+export type ClevelandPlotEnv = AxisPlotEnv;
 /** The configuration blocks the Cleveland-style plots draw their defaults from: one per plot. */
 export type ClevelandConfigKey = 'lollipop' | 'dumbbell' | 'cleveland' | 'forest';
 /** One category's dots along the value axis: the row each one draws, and the range they span. */

package/dist/types/plots/ranking/dumbbell/state.d.ts

@@ -1,5 +1,5 @@
-import type { ClevelandPlotState, ClevelandPlotCtx } from '../cleveland/state';
+import type { ClevelandPlotState, ClevelandPlotEnv } from '../cleveland/state';
 /** DumbbellPlot's pipeline state: a ClevelandPlot's. */
 export type DumbbellPlotState<TData extends Record<string, unknown>> = ClevelandPlotState<TData>;
 /** The environment every DumbbellPlot phase reads from, alongside the growing state. */
-export type DumbbellPlotCtx = ClevelandPlotCtx;
+export type DumbbellPlotEnv = ClevelandPlotEnv;

package/dist/types/plots/ranking/forest/state.d.ts

@@ -1,5 +1,5 @@
-import type { ClevelandPlotState, ClevelandPlotCtx } from '../cleveland/state';
+import type { ClevelandPlotState, ClevelandPlotEnv } from '../cleveland/state';
 /** ForestPlot's pipeline state: a ClevelandPlot's. */
 export type ForestPlotState<TData extends Record<string, unknown>> = ClevelandPlotState<TData>;
 /** The environment every ForestPlot phase reads from, alongside the growing state. */
-export type ForestPlotCtx = ClevelandPlotCtx;
+export type ForestPlotEnv = ClevelandPlotEnv;

package/dist/types/plots/ranking/lollipop/state.d.ts

@@ -1,5 +1,5 @@
-import type { ClevelandPlotState, ClevelandPlotCtx } from '../cleveland/state';
+import type { ClevelandPlotState, ClevelandPlotEnv } from '../cleveland/state';
 /** LollipopPlot's pipeline state: a ClevelandPlot's. */
 export type LollipopPlotState<TData extends Record<string, unknown>> = ClevelandPlotState<TData>;
 /** The environment every LollipopPlot phase reads from, alongside the growing state. */
-export type LollipopPlotCtx = ClevelandPlotCtx;
+export type LollipopPlotEnv = ClevelandPlotEnv;

package/docs/markers.md

@@ -74,6 +74,7 @@ Many markers also take channel fields (`color`, `fill`, `opacity`, `r`, `symbol`
 | `text`                                                   | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins`, `fit`                                                                                 |
 | `line`                                                   | A line through the rows                                                                                                                                                                             |
 | `rule`                                                   | A reference line: `axis: 'x' \| 'y'`, `value` (a list draws a line at each, or a function with `data`), `styles` (`StrokeStyle`, and `inset`, `insetTop`, ... to pull it in from its ends)          |
+| `band`                                                   | The band of a category across the whole other axis: `axis: 'x' \| 'y'`, `value` (a list, or a function with `data`), `slice`, `styles` (`AreaStyle`). Only on a band scale                          |
 | `tick`                                                   | A short tick per row along one axis                                                                                                                                                                 |
 | `bar`                                                    | A bar; `rect`, `cell`: rectangles and heatmap cells                                                                                                                                                 |
 | `rect`                                                   | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges; `styles` (`AreaStyle`, and `inset`, `insetLeft`, ...); `label`, a text in each (`cell`, `bar` and `waffle` take it too) |
@@ -101,7 +102,7 @@ On a plot with a [`facet`](facets.md#markers-and-segments-in-some-panels), every
 
 ## Several positions at once
 
-A `rule` takes a list as its `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
+A `rule` and a `band` take a list as their `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
 
 ```ts
 markers={[
@@ -123,9 +124,40 @@ A delta's `stroke`, `text` and `dot` can be functions of the position, to style
 
 Every other marker draws from `data` rows, one mark per row, so it already takes many positions.
 
+## Bands
+
+`{ type: 'band', axis: 'x', value: 'Salta' }` fills the band of a category on a band scale, across the whole of the other axis: a column behind a bar plot's bars, a row across a horizontal one. With `data`, `value` is a field key or a function of the row, and the rows that name the same category draw one band. `slice` fills part of the band, as the fractions of its width left out at its start and its end (`{ start: 0.5, end: 0 }` is its second half), or a function of the row for each one's; a band several rows share fills what all of their slices do. `styles` take `AreaStyle`, each field a value or a function of the row, over `band` in the [configuration](theming.md). A band takes the pointer only with a handler of its own (`onclick`...), so one behind a plot's shapes leaves them their hover. On an axis that is not a band scale it draws nothing.
+
+```ts
+markers={[
+	// The two provinces of the story, behind their bars.
+	{ type: 'band', axis: 'x', value: ['Salta', 'Jujuy'], styles: { fill: '#fde68a', fillOpacity: 0.5 } }
+]}
+```
+
 ## Hover highlight
 
-`{ type: 'hover' }` draws a crosshair, a dot and a label at the hovered point. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `ruleX`, `ruleY`, `areaX`, `areaY` (a band highlight on band scales), `showLabels`, `format`, the number fields `decimals`, `prefix`, `suffix` and `signDisplay` (they write the label's value; `format` gets a `number` function that does the same), and the styles `rule`, `area`, `dot`, `text`. See [Tooltip and hover](tooltip-and-hover.md).
+`{ type: 'hover' }` draws the plot's own hover: a crosshair, a dot and a label at the hovered point on most plots, the hovered category's band on a bar plot. It makes the plot hoverable on its own; add `tooltip` for a floating box too. Fields: `strategy`, `sync`, `series`, `scope`; `back` and `front`, the markers it draws behind the plot's shapes and in front of them, over the hovered points (they replace the plot's); `active` and `others`, which restyle the hovered shapes and the rest; and `format` and the number fields `decimals`, `prefix`, `suffix` and `signDisplay`, which write each point's label. See [Tooltip and hover](tooltip-and-hover.md#in-plot-hover).
+
+```ts
+// A crosshair only at the hovered point, and its value in bold, without a dot.
+{ type: 'hover', back: [{ type: 'rule', axis: 'x', points: 'active' }], front: [{ type: 'text', styles: { fontWeight: 'bold' } }] }
+```
+
+Every marker takes `hover`, which links it to the plot's hover:
+
+- `'trigger'` makes it a hit area: the pointer over one of its shapes hovers that shape's row.
+- `'style'` has its shapes take the hover marker's `active` and `others`.
+- `true` does both.
+
+```ts
+markers={[
+	{ type: 'hover', active: { stroke: 'black', strokeWidth: 2 }, others: { fillOpacity: 0.3 } },
+	{ type: 'rect', data: eras, x1: 'from', x2: 'to', y1: 0, y2: 100, hover: true }
+]}
+```
+
+A plot's own shapes are linked already where its kind does it: the tiles, cells, bars, bins and dots of `TreemapPlot`, `HeatmapPlot`, `BarPlot`, `BulletPlot`, `PyramidPlot`, `HistogramPlot`, `ScatterPlot` and the Cleveland family. The `Layout/Hover` stories show every feature of the hover on every plot kind.
 
 ## Styles that depend on the row
 

package/docs/plots/evolution/line.md

@@ -20,7 +20,7 @@ One line per series. Rows with a missing value (`null`, `undefined`, `NaN`) brea
 	x="date"
 	y="index"
 	color="commodity"
-	styles={{ values: { show: true, format: (v, name) => `${name}: ${v}` } }}
+	styles={{ values: { show: true, format: (v, _number, context) => `${context.series}: ${v}` } }}
 />
 ```
 

package/docs/plots/evolution/slope.md

@@ -32,7 +32,7 @@ A line per series between two positions of a category axis, a dot on each end, t
 
 - `x` is always a category axis (a point scale, so the first and last positions reach the plot's edges), even for numbers or dates: each distinct value is a position, in the order the data gives them (`scales.x.domain` sets it).
 - `grouping` (or `color`) names the series; the legend toggles them like any other.
-- `styles.values` writes each series' first and last value (`select` picks others: `'first'`, `'last'`, `'min'`, `'max'`). Each label sits out in the margin on a lane, joined to its dot by a connector. The text is `format` of the value and series name.
+- `styles.values` writes each series' first and last value (`select` picks others: `'first'`, `'last'`, `'min'`, `'max'`). Each label sits out in the margin on a lane, joined to its dot by a connector. The text is `format` of the value, `number` and the row's context, with its `series`.
 - The value axis is hidden, since the labels carry the values; `scales.y.axisDisplay: 'visible'` brings it back. It fits the values without reaching for zero; pin `scales.y.domain` to start it there.
 - The stroke width, dot radius and padding come from `slope` in the [configuration](../../theming.md); `padding` leaves room outside the first and last position. The positions sit at the plot's edges, and the margins grow to fit the labels.
 - `segments` restyle chosen series (`styles: { stroke: { strokeWidth: 4 } }`), as in a line plot.

package/docs/plots/part-of-a-whole/treemap.md

@@ -40,7 +40,7 @@ Each tile is labelled with its name and its **share of the whole**, in percent,
 3. The value alone, when almost none of the name would show.
 4. Nothing, when not even the value fits.
 
-`styles.values.format(value, group, row, number)` writes the tile's whole text instead (`value` is the share, in percent; `number` writes it as the display fields ask), and `styles.values.show: false` leaves the tiles bare. The label's `fontStyle` sets `fontSize` (the biggest it takes), `fontWeight` and `fill`; `treemap` in the [configuration](../../theming.md) sets the lines between tiles, the label color and the room kept around it.
+`styles.values.format(value, number, context)` writes the tile's whole text instead (`value` is the share, in percent; `number` writes it as the display fields ask; `context` holds the tile's `series`, `name`, `path` and `share`), and `styles.values.show: false` leaves the tiles bare. The label's `fontStyle` sets `fontSize` (the biggest it takes), `fontWeight` and `fill`; `treemap` in the [configuration](../../theming.md) sets the lines between tiles, the label color and the room kept around it.
 
 ## Style
 
@@ -66,4 +66,38 @@ Each tile is labelled with its name and its **share of the whole**, in percent,
 
 ## Hover and tooltip
 
-Hovering a tile matches it alone - an invisible `rect` over each tile drives the plot's hover - and `tooltip` shows its name and share. `tooltip.format(row, number, context)` writes it by hand: `row` is the tile's row, with the fields of every level and its summed `value`, and `context` what the library works out about it - its `series` (the outermost level) and its `share` of the whole, from 0 to 100. The share is worked out from the values, in whatever unit they are, so a dataset whose `value` is a percentage already reads the same.
+Hovering a tile matches it alone - an invisible `rect` over each tile drives the plot's hover - and `tooltip` shows its name and share. `tooltip.format(row, number, context)` writes it by hand: `row` is the tile's row, with the fields of every level and its summed `value`, and `context` what the library works out about it - its `series` (the outermost level), its `name`, `path`, summed `value` and `share` of the whole, from 0 to 100 (see [Row context](../../state.md#row-context)). The share is worked out from the values, in whatever unit they are, so a dataset whose `value` is a percentage already reads the same.
+
+A `hover` marker draws no crosshair, dot or label over a treemap, since a tile has no axes and writes its own label: it outlines the hovered tile, in the configuration's `hover.active`. The tiles are linked to the hover, so its `active` and `others` restyle them: the hovered tile lightened and outlined, the rest faded, each label still on its tile and written in the color that reads best on its new one. A tile the legend dims stays hoverable and keeps its dimmed fill; one it hides, omits or rescales away is never hovered. See [Tooltip and hover](../../tooltip-and-hover.md#restyling-the-hovered-shapes).
+
+<!-- example: examples/TreemapHover.svelte -->
+
+```svelte
+<script lang="ts">
+	import { TreemapPlot } from '@fundar/data-chart-telling';
+	import { ACTIVITY_BRANCHES } from './datasets';
+</script>
+
+<!--
+	The hover marker restyles the tiles themselves: the hovered one at full strength and outlined, every other
+	faded. Each label is still written on its tile, in the color that reads best on it.
+-->
+<TreemapPlot
+	width={760}
+	height={440}
+	data={ACTIVITY_BRANCHES}
+	value="value"
+	grouping="sector.branch"
+	styles={{ area: { fillOpacity: 0.85 } }}
+	tooltip
+	markers={[
+		{
+			type: 'hover',
+			active: { fillOpacity: 1, stroke: '#111827', strokeWidth: 2 },
+			others: { fillOpacity: 0.35 }
+		}
+	]}
+/>
+```
+
+<!-- /example -->