@fundar/data-chart-telling 1.16.0 → 1.18.0

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/axis/rect.d.ts

@@ -1,15 +1,11 @@
-import type { AreaStyle } from '../../plots/styling';
+import type { AreaStyle, PerRow, InsetStyle } from '../../plots/styling';
 import type { CommonMarkerConfigWithArea } from '../channels/commonMarkerConfigWithArea';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
+import type { CommonMarkerConfigWithLabel } from '../channels/commonMarkerConfigWithLabel';
 import type { CommonMarkerConfigWithInterval } from '../channels/commonMarkerConfigWithInterval';
 /** An arbitrary rectangle (svelteplot's `Rect`); `interval` turns `x`/`y` into ranges. */
 export type RectMarkerConfig = {
     type: 'rect';
     interval?: number | string;
-    /** Pixels taken off each side of every rectangle; a bin's default `0.5` on each side leaves a hairline gap. */
-    insetLeft?: number;
-    insetRight?: number;
-    insetTop?: number;
-    insetBottom?: number;
-    styles?: AreaStyle;
-} & CommonMarkerConfigWithArea & CommonMarkerConfigWithColor & CommonMarkerConfigWithInterval;
+    styles?: PerRow<AreaStyle & InsetStyle>;
+} & CommonMarkerConfigWithArea & CommonMarkerConfigWithColor & CommonMarkerConfigWithInterval & CommonMarkerConfigWithLabel;

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

@@ -1,5 +1,5 @@
 import type { AxisValue } from '../../layout/mapping';
-import type { StrokeStyle } from '../../plots/styling';
+import type { StrokeStyle, PerRow, InsetStyle } from '../../plots/styling';
 import type { CommonMarkerConfigWithInterval } from '../channels/commonMarkerConfigWithInterval';
 /**
  * A vertical or horizontal reference line, one line per row when `data` is given, or one per value
@@ -13,19 +13,5 @@ export type RuleMarkerConfig = {
      * a field key or a function of the row gives each row's own.
      */
     value: AxisValue | string | (AxisValue | string)[] | ((d: any) => AxisValue);
-    inset?: number;
-    insetTop?: number;
-    insetBottom?: number;
-    insetLeft?: number;
-    insetRight?: number;
-    /**
-     * A stroke color for each row - a field key or a function of the row - drawn
-     * as it is, not mapped through a color scale. Wins over `styles.stroke`.
-     */
-    stroke?: string | ((d: any) => string | undefined);
-    /** A stroke width for each row - a field key or a function of the row. Wins over `styles.strokeWidth`. */
-    strokeWidth?: string | ((d: any) => number);
-    /** A stroke opacity for each row - a field key or a function of the row - drawn as it is. Wins over `styles.strokeOpacity`. */
-    strokeOpacity?: string | ((d: any) => number);
-    styles?: StrokeStyle;
+    styles?: PerRow<StrokeStyle & InsetStyle>;
 } & CommonMarkerConfigWithInterval;

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

@@ -1,8 +1,8 @@
-import type { StrokeStyle } from '../../plots/styling';
+import type { StrokeStyle, PerRow } from '../../plots/styling';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
 /** A short tick per row along one axis (svelteplot's `TickX`/`TickY`). */
 export type TickMarkerConfig = {
     type: 'tick';
     tickLength?: number | ((d: any) => number);
-    styles?: StrokeStyle;
+    styles?: PerRow<StrokeStyle>;
 } & CommonMarkerConfigWithColor;

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

@@ -1,7 +1,7 @@
-import type { AreaStyle } from '../../plots/styling';
+import type { AreaStyle, PerRow } from '../../plots/styling';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
 /** One polygon per point, its Voronoi cell (svelteplot's `Voronoi`). */
 export type VoronoiMarkerConfig = {
     type: 'voronoi';
-    styles?: AreaStyle;
+    styles?: PerRow<AreaStyle>;
 } & CommonMarkerConfigWithColor;

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

@@ -1,4 +1,5 @@
-import type { AreaStyle } from '../../plots/styling';
+import type { AreaStyle, PerRow } from '../../plots/styling';
+import type { CommonMarkerConfigWithLabel } from '../channels/commonMarkerConfigWithLabel';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
 import type { CommonMarkerConfigWithInterval } from '../channels/commonMarkerConfigWithInterval';
 /** A waffle chart bar: the value as a grid of unit squares (svelteplot's `WaffleX`/`WaffleY`). */
@@ -9,5 +10,5 @@ export type WaffleMarkerConfig = {
     multiple?: number;
     gap?: number;
     round?: boolean;
-    styles?: AreaStyle;
-} & CommonMarkerConfigWithColor & CommonMarkerConfigWithInterval;
+    styles?: PerRow<AreaStyle>;
+} & CommonMarkerConfigWithColor & CommonMarkerConfigWithInterval & CommonMarkerConfigWithLabel;

package/dist/types/markers/basic/dot.d.ts

@@ -1,4 +1,4 @@
-import type { DotStyle } from '../../plots/styling';
+import type { DotStyle, PerRow } from '../../plots/styling';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
 import type { CommonMarkerConfigWithRadius } from '../channels/commonMarkerConfigWithRadius';
 import type { CommonMarkerConfigWithRowOffset } from '../channels/commonMarkerConfigWithRowOffset';
@@ -6,5 +6,5 @@ import type { CommonMarkerConfigWithSymbol } from '../channels/commonMarkerConfi
 /** A point mark (svelteplot's `Dot`), usable on any plot kind. */
 export type DotMarkerConfig = CommonMarkerConfigWithRowOffset<{
     type: 'dot';
-    styles?: DotStyle;
+    styles?: PerRow<DotStyle>;
 } & CommonMarkerConfigWithRadius & CommonMarkerConfigWithColor & CommonMarkerConfigWithSymbol>;

package/dist/types/markers/basic/text.d.ts

@@ -1,9 +1,9 @@
-import type { FontStyle, StrokeStyle } from '../../plots/styling';
+import type { FontStyle, StrokeStyle, PerRow } from '../../plots/styling';
 import type { CommonMarkerConfig } from '../channels/commonMarkerConfig';
 import type { CommonMarkerConfigWithRowOffset } from '../channels/commonMarkerConfigWithRowOffset';
 import type { Margins } from '../../../layout/margins/Margins';
 import type { BandSlice } from '../../layout/hover';
-import type { TextAnchor } from '../../plots/constants';
+import type { LabelAnchor, TextAnchor } from '../../plots/constants';
 import type { NumberDisplay } from '../../layout/numbers';
 /**
  * Spreads labels that would overlap apart vertically, all reaching out to one
@@ -24,7 +24,35 @@ export type TextDeclutterConfig = {
     /** The connectors' stroke. Unset opacity follows each label's own `fillOpacity`. */
     connector?: StrokeStyle;
 };
-/** A text label per row (svelteplot's `Text`), usable on any plot kind. */
+/** Where a row's `x1`, `x2`, `y1` and `y2` are: a field of the rows, the symbol a transform keyed it by, or a function of the row. */
+type FitChannel = string | symbol | ((d: any) => unknown);
+/**
+ * What a label is fitted to: the rectangle its row spans, from `x1` to `x2` along the x axis and from `y1` to `y2`
+ * along the y - a tile of a `treemap` transform, say. A label too big for it is written smaller, down to
+ * `minFontSize`; at that size, broken into as many lines as the box holds and cut short with an ellipsis; and
+ * when almost none of it would show, as its `fallback`. A label with no room for even that is left out.
+ */
+export type TextFitConfig = {
+    /** The edges of a box of your own. A marker that draws a shape for each label gives its own, and these are left out. */
+    x1?: FitChannel;
+    x2?: FitChannel;
+    y1?: FitChannel;
+    y2?: FitChannel;
+    /** Pixels left free inside each edge of the box. Defaults to the configuration's `text.label.padding`, `4`. */
+    padding?: number;
+    /** The smallest size a label is written at, in px. Defaults to the configuration's `text.label.minFontSize`, `8`. */
+    minFontSize?: number;
+    /** The fewest letters worth writing when a text is cut short; under them the `fallback` is written. Defaults to the configuration's `text.label.minLetters`, `3`. */
+    minLetters?: number;
+    /** What to write when the text does not fit, cut short or not - a value alone, say; a number is written as the marker's `decimals` and the rest ask. */
+    fallback?: string | number | ((d: any) => string | number);
+};
+/** The text styles that can be a function of the row. */
+type TextRowStyleKey = 'fill' | 'stroke' | 'strokeWidth' | 'fontWeight' | 'fontStyle';
+/** The text styles that can be a function of the row. */
+type TextRowStyle = Pick<FontStyle, TextRowStyleKey> & {
+    fillOpacity?: number;
+};
 export type TextMarkerConfig = CommonMarkerConfigWithRowOffset<{
     type: 'text';
     /**
@@ -33,15 +61,17 @@ export type TextMarkerConfig = CommonMarkerConfigWithRowOffset<{
      * `decimals`, `prefix`, `suffix` and `signDisplay`, over the configuration's `numbers`.
      */
     text: string | number | ((d: any) => string | number);
-    styles?: FontStyle;
+    /**
+     * How the labels are drawn. `fill`, `fillOpacity`, `stroke`, `strokeWidth`, `fontWeight` and `fontStyle` can each be a function of the row;
+     * the rest place and measure the labels, so they are the same for all of them.
+     */
+    styles?: PerRow<TextRowStyle> & Omit<FontStyle, TextRowStyleKey>;
     /** Which side of its point the text sits on: a value, or a function of the row. Wins over `styles.textAnchor`. */
     textAnchor?: TextAnchor | ((d: any) => TextAnchor);
-    /** Per-row fill, over `styles.fill`. */
-    fill?: string | ((d: any) => string | undefined);
-    /** Per-row fill opacity. */
-    fillOpacity?: number | ((d: any) => number | undefined);
     /** Spreads overlapping labels apart - see {@link TextDeclutterConfig}. `true` takes every default. */
     declutter?: boolean | TextDeclutterConfig;
+    /** Writes each label to fit its box - see {@link TextFitConfig}. `true` takes every default. */
+    fit?: boolean | TextFitConfig;
     /**
      * Flips each label to the other side of its point (or nudges a centred one
      * back in) where its text would cross the plot's edge. `styles.textAnchor`/
@@ -51,16 +81,28 @@ export type TextMarkerConfig = CommonMarkerConfigWithRowOffset<{
     /** The slice of its category band each label sits in (a grouped bar's series); it is drawn off the band's middle, whatever the band's width. */
     bandSlice?: BandSlice;
     /** Where, in the plot's frame, a label sits on an axis it sets no position for: `{ type: 'text', x: 5, frameAnchor: 'top' }` is at the frame's top edge. */
-    frameAnchor?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle';
+    frameAnchor?: LabelAnchor;
     /** Grows the plot's margins, on every side the author left open, so the labels fit. */
     fitMargins?: boolean;
     /** Reports how far the rendered labels reach past the plot's content box, in pixels, on each side. */
-    onOverflow?: (overflow: Margins) => void;
-    /** Fired when the pointer enters a row's label. */
-    onPointerEnter?: (d: any) => void;
-    /** Fired when the pointer leaves a row's label. */
-    onPointerLeave?: (d: any) => void;
+    onoverflow?: (overflow: Margins) => void;
 } & NumberDisplay & CommonMarkerConfig>;
+/** A `text` marker as a shape's `label`: all of it but what the shape sets - its `type`, its rows and the label's position. */
+export type TextLabelConfig = Omit<TextMarkerConfig, 'type' | 'data' | 'x' | 'y' | 'frameAnchor'> & {
+    /**
+     * Where in its shape the label sits: its `'middle'` (the default), against one of its edges (`'top'`, `'bottom'`,
+     * `'left'`, `'right'`) or in one of its corners (`'top-left'`...). The label's `dx` and `dy` move it from there.
+     */
+    anchor?: LabelAnchor;
+    /**
+     * Puts a label anchored to an edge beyond that edge, outside the shape, instead of inside it. A label out there is not
+     * fitted to the shape, and with `fitMargins` the plot's margins grow to hold it.
+     */
+    outside?: boolean;
+    /** Pixels between the label and the edge it is anchored to. Defaults to the configuration's `text.label.gap`, `4`. */
+    gap?: number;
+};
+export type { LabelAnchor };
 /** Where one decluttered label goes - see `Declutter.buildLanes`. */
 export type LabelLane = {
     /** Vertical shift (px) clearing its neighbours and the content box's edges. */

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

@@ -3,8 +3,9 @@ import type { AxisValue } from '../../layout/mapping';
 import type { StatisticConfig } from '../../layout/statistics';
 import type { MarkerTransform } from '../../transforms';
 import type { MarkLegend } from '../../layout/legend';
+import type { CommonMarkerEvents } from './commonMarkerEvents';
 /** Props every marker kind shares: rows, grouping, series scope, position, offset, statistics, transforms. */
-export type CommonMarkerConfig = {
+export type CommonMarkerConfig = CommonMarkerEvents & {
     data?: Record<string, unknown>[];
     grouping?: string | ((d: any) => unknown);
     series?: string;
@@ -27,4 +28,10 @@ export type CommonMarkerConfig = {
     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;
+    /**
+     * 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/channels/commonMarkerConfigWithArea.d.ts

@@ -1,6 +1,5 @@
 import type { CommonMarkerConfig } from './commonMarkerConfig';
-/** Common props plus the fill and opacity channels. */
+/** Common props plus the opacity channel. */
 export type CommonMarkerConfigWithArea = CommonMarkerConfig & {
-    fill?: (d: any) => string;
     opacity?: string | ((d: any) => unknown);
 };

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

@@ -0,0 +1,10 @@
+import type { TextLabelConfig } from '../basic/text';
+/** The markers that draw a shape per row, which can write a label in each one. */
+export type CommonMarkerConfigWithLabel = {
+    /**
+     * A label for each shape, written by a `text` marker: every option of one but `type`, `data`, `x` and `y`,
+     * which the shape sets. The label is centred on its shape, and fitted to it unless `fit` is `false` - see
+     * {@link TextFitConfig}. It never takes the pointer from the shape under it.
+     */
+    label?: TextLabelConfig;
+};

package/dist/types/markers/channels/commonMarkerConfigWithLabel.js

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

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

@@ -0,0 +1,17 @@
+/** The events a mark can be given a handler for, as svelteplot's own marks name them. */
+export declare const MARK_EVENTS: readonly ["onclick", "ondblclick", "oncontextmenu", "onpointerdown", "onpointerup", "onpointerenter", "onpointerleave", "onpointermove", "onmouseenter", "onmouseleave"];
+/** The name of an event a mark takes a handler for. */
+export type MarkEventName = (typeof MARK_EVENTS)[number];
+/**
+ * A handler of an event on one of a mark's shapes: the event, the row the shape draws and
+ * that row's index - as svelteplot's marks call it.
+ */
+export type MarkEventHandler = (event: Event, row: any, index: number) => void;
+/**
+ * Handlers a marker passes on to the shapes svelteplot draws for it. svelteplot documents these props on every
+ * mark (`BaseMarkProps`), and every marker hands them on; svelteplot's code wires them up on some marks only
+ * today (`Rect`, `Bar`, `Cell`, `Area`, `Arrow`, `Dot`, `Trail`, `Vector`, `Geo`, `Line`, `Link`,
+ * `DelaunayLink` and `Voronoi`), so on the others they do nothing yet - they will, whenever svelteplot's code
+ * catches up.
+ */
+export type CommonMarkerEvents = Partial<Record<MarkEventName, MarkEventHandler>>;

package/dist/types/markers/channels/commonMarkerEvents.js

@@ -0,0 +1,13 @@
+/** The events a mark can be given a handler for, as svelteplot's own marks name them. */
+export const MARK_EVENTS = [
+    'onclick',
+    'ondblclick',
+    'oncontextmenu',
+    'onpointerdown',
+    'onpointerup',
+    'onpointerenter',
+    'onpointerleave',
+    'onpointermove',
+    'onmouseenter',
+    'onmouseleave'
+];

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/markers/geo/contour.d.ts

@@ -1,10 +1,11 @@
+import type { CommonMarkerEvents } from '../channels/commonMarkerEvents';
 import type { Accessor } from '../../plots/data/common';
 /**
  * Marching-squares contours from a scalar field (svelteplot's `Contour`).
  * Pass `data` with `x`/`y`/`value` to interpolate samples, or omit `data` and
  * pass `value` as an `(x, y) => number` sampler.
  */
-export type GeoContourMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+export type GeoContourMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = CommonMarkerEvents & {
     type: 'contour';
     data?: TRow[];
     x?: Accessor<TRow, number>;

package/dist/types/markers/geo/graticule.d.ts

@@ -1,6 +1,7 @@
+import type { CommonMarkerEvents } from '../channels/commonMarkerEvents';
 import type { StrokeStyle } from '../../plots/styling';
 /** Longitude and latitude gridlines (svelteplot's `Graticule`). */
-export type GeoGraticuleMarkerConfig = {
+export type GeoGraticuleMarkerConfig = CommonMarkerEvents & {
     type: 'graticule';
     step?: number;
     stepX?: number;

package/dist/types/markers/geo/link.d.ts

@@ -1,7 +1,8 @@
+import type { CommonMarkerEvents } from '../channels/commonMarkerEvents';
 import type { Accessor } from '../../plots/data/common';
 import type { StrokeStyle } from '../../plots/styling';
 /** Lines between point pairs: `curve: 'auto'` traces great-circle arcs, `'linear'` joins their projected positions with a straight line. */
-export type GeoLinkMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+export type GeoLinkMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = CommonMarkerEvents & {
     type: 'link';
     data: TRow[];
     x1: Accessor<TRow, number>;

package/dist/types/markers/geo/sphere.d.ts

@@ -1,6 +1,7 @@
+import type { CommonMarkerEvents } from '../channels/commonMarkerEvents';
 import type { StrokeStyle } from '../../plots/styling';
 /** The outer globe outline (svelteplot's `Sphere`), for orthographic-type projections. */
-export type GeoSphereMarkerConfig = {
+export type GeoSphereMarkerConfig = CommonMarkerEvents & {
     type: 'sphere';
     styles?: StrokeStyle & {
         fill?: string;

package/dist/types/markers/geo/vector.d.ts

@@ -1,6 +1,7 @@
+import type { CommonMarkerEvents } from '../channels/commonMarkerEvents';
 import type { Accessor } from '../../plots/data/common';
 /** Arrows or spikes at points (svelteplot's `Vector`). */
-export type GeoVectorMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+export type GeoVectorMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = CommonMarkerEvents & {
     type: 'vector';
     data: TRow[];
     x: Accessor<TRow, number>;

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. */
@@ -24,6 +24,11 @@ export type DataStageOptions<TState, TCtx> = {
     orderSeries?: (series: Series<any>[], state: TState) => Series<any>[];
     /** The order colors are assigned in. Defaults to the series' own order. */
     colorOrder?: (series: Series<any>[]) => Series<any>[];
+    /**
+     * Whether the kind draws the levels of its `grouping` itself (a treemap's nesting): its series are then
+     * the outermost level's values, not every level's together.
+     */
+    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,14 +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;
     }[];
     /** 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;
 };

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[];
 };