@fundar/data-chart-telling 1.16.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);
@@ -45,7 +45,7 @@ export class ClevelandMarkers {
         // color and its segment's style; the legend dims it with the series.
         const size = state.channels?.r;
         const dotRadius = typeof size === 'number' ? size : style.dotRadius;
-        const neutral = style.connectorColor ?? cfg.axis.color;
+        const neutral = style.connectorColor ?? 'currentColor';
         // `styles.stroke` is the connectors' look below everything the author sets for them: a segment's
         // stroke wins over `styles.connector`, which wins over it. A function of the series styles only
         // the connector of a lone dot, which has a series; the connector of several dots has none.
@@ -135,10 +135,12 @@ export class ClevelandMarkers {
             data: group.flatMap((look) => look.rows),
             value: 'category',
             ...(isHorizontal ? { x1: 'from', x2: 'to' } : { y1: 'from', y2: 'to' }),
-            stroke: 'stroke',
-            strokeWidth: 'strokeWidth',
-            strokeOpacity: 'strokeOpacity',
-            ...(Object.keys(pattern).length > 0 ? { styles: pattern } : {})
+            styles: {
+                ...pattern,
+                stroke: 'stroke',
+                strokeWidth: 'strokeWidth',
+                strokeOpacity: 'strokeOpacity'
+            }
         }));
         // The arrows, one marker per pattern like the lines, each from its `from` dot to its `to` dot.
         const head = connector.arrow;
@@ -157,12 +159,14 @@ export class ClevelandMarkers {
                     headLength: head.headLength,
                     headAngle: head.headAngle,
                     // The shaft starts and ends at the edge of its dots, not under them.
-                    insetStart: dotRadius,
-                    insetEnd: dotRadius,
-                    stroke: 'stroke',
-                    strokeWidth: 'strokeWidth',
-                    strokeOpacity: 'strokeOpacity',
-                    ...(Object.keys(pattern).length > 0 ? { styles: pattern } : {})
+                    styles: {
+                        ...pattern,
+                        insetStart: dotRadius,
+                        insetEnd: dotRadius,
+                        stroke: 'stroke',
+                        strokeWidth: 'strokeWidth',
+                        strokeOpacity: 'strokeOpacity'
+                    }
                 }
             ];
         });
@@ -183,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: {
@@ -202,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. */
@@ -239,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 [];
@@ -251,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' }
@@ -266,8 +271,8 @@ export class ClevelandMarkers {
                 text: 'text',
                 styles: {
                     ...font,
-                    fill: font?.fill ?? ctx.cfg.axis.color,
-                    fontSize: font?.fontSize ?? ctx.cfg.connector.labelFontSize,
+                    fill: font?.fill ?? 'currentColor',
+                    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,
@@ -282,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);
@@ -290,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).
@@ -308,7 +313,7 @@ export class ClevelandMarkers {
         // What fills the labels of a series: the one fill all share, its own color, or the axis'.
         const fillOf = (series) => labels.fill ??
             (labels.color === 'series' ? state.colorForSeries(series) : undefined) ??
-            ctx.cfg.axis.color;
+            'currentColor';
         const names = labels.color === 'series' && !labels.fill
             ? (state.resolvedSeries ?? []).map((s) => s.name)
             : [''];
@@ -325,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),
@@ -354,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

@@ -70,7 +70,7 @@ export type PlotStylesConfig = {
     palette: string[];
     /** Default shape cycle for the `symbol` channel, in order. */
     symbols: SymbolType[];
-    /** The default continuous ramp, the on-cell label colour and the default opacity-channel range. */
+    /** The default continuous ramp and the default opacity-channel range. */
     continuous: {
         /** The ramp's first color, when it is not a named `scheme`. */
         min: string;
@@ -80,7 +80,6 @@ export type PlotStylesConfig = {
         scheme?: string;
         /** The part of `scheme` to use, as `[from, to]` fractions of it: `[0.2, 1]` skips the near-white start of `'blues'`. */
         schemeRange?: [number, number];
-        labelColor: string;
         opacityRange: [number, number];
     };
     /**
@@ -244,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. */
@@ -264,6 +265,19 @@ export type PlotStylesConfig = {
             disabledOpacity: number;
         };
     };
+    /** The tiles of a `TreemapPlot` and the labels written on them. */
+    treemap: {
+        /** The line between tiles. */
+        stroke: string;
+        /** Its width, in px. */
+        strokeWidth: number;
+        /** Font size of a tile's label, in px. */
+        fontSize: number;
+        /** The room kept between a tile's edge and its label, in px. */
+        padding: number;
+        /** Line height of a tile's label, as a multiple of its font size. */
+        lineHeight: number;
+    };
     /** Timeline gutter styling. */
     timeline: {
         axisColor: string;
@@ -367,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', {
@@ -378,6 +394,19 @@ export type PlotStylesConfig = {
     };
     /** Default text-marker behavior. */
     text: {
+        /** Defaults of the `label` a shape writes in itself (`rect`, `cell`, `bar`, `waffle`), each overridden by the label's own `gap` and `fit`. */
+        label: {
+            /** Pixels between a label and the edge it is anchored to. */
+            gap: number;
+            /** Pixels a fitted label keeps free inside each edge of its shape. */
+            padding: number;
+            /** The smallest size a fitted label is written at, in px. */
+            minFontSize: number;
+            /** The fewest letters worth writing when a fitted label is cut short; under them its `fallback` is written. */
+            minLetters: number;
+            /** The colors a label inside its shape is written in: the one that reads best on the shape's color. A label's own `fill` wins. */
+            contrast: string[];
+        };
         /** Geometry and connector of a decluttered text marker (`declutter`) - e.g. LinePlot's end-of-line value labels. */
         declutter: {
             /** Shortest lane's distance (px) from the point before a connector bends. */

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

@@ -20,7 +20,12 @@ export type LegendDisabledStyle = {
  * What a legend toggle does to a series once it's off: `'dim'` dims it in
  * place (styled by `style`), `'hide'` makes it fully transparent while the
  * axes keep its range, `'omit'` removes it from the plot entirely, rescaling
- * the axes to what's left.
+ * the axes to what's left - the other series keep their values, and a part of
+ * a whole (a treemap's tile) its share and its place. `'rescale'` removes it
+ * too, and the parts left make the whole again: a stack's visible parts are
+ * scaled up to the total each category had, and a treemap's tiles are laid out
+ * and given their shares anew, as the new 100%. On a plot of no parts it is an
+ * `'omit'`.
  */
 export type LegendDisabledAction = {
     mode: 'dim';
@@ -29,6 +34,8 @@ export type LegendDisabledAction = {
     mode: 'hide';
 } | {
     mode: 'omit';
+} | {
+    mode: 'rescale';
 };
 export type LegendItem = {
     name: string;

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

@@ -14,7 +14,9 @@ export type ChannelValue = {
      * Splits `data` into one series per distinct value - the structural
      * grouping key. Defaults to `color` when omitted, so a single `color`
      * accessor groups *and* colors series; pass both to split by one field
-     * while coloring by another.
+     * while coloring by another. A dotted name (`'sector.branch'`) groups by several
+     * levels, outermost first: a plot that nests (a treemap) nests by them, any other
+     * splits by their combination - see {@link GroupingAccessor}.
      */
     grouping: unknown;
     /**
@@ -34,6 +36,8 @@ export type ChannelValue = {
     r: number;
     /** Vector/spike magnitude - a literal number is a fixed pixel length. Configure via `scales.length`. */
     length: number;
+    /** What a row amounts to as a part of a whole: a treemap tile's area. A plot without parts ignores it. */
+    value: number;
 };
 /** Every channel a plot maps from its rows. */
 export type ChannelName = keyof ChannelValue;
@@ -46,9 +50,14 @@ export type AxisChannelName = 'x' | 'y';
 export type IndependentChannelName = 'color' | 'grouping' | 'opacity' | 'symbol';
 /** The size channels, which also take a literal number as a fixed pixel size that bypasses their scale. */
 export type SizeChannelName = 'r' | 'length';
-/** Every channel as a plot prop: a field key or accessor function (or a literal size, for a size channel). */
+/**
+ * What a plot's rows group by: a field, the fields of several levels joined by dots (`'sector.branch'`,
+ * outermost first), or a function of the row. A dotted name is a field when the rows have one by that name.
+ */
+export type GroupingAccessor<TData> = (keyof TData & string) | `${keyof TData & string}.${string}` | ((row: TData) => unknown);
+/** Every channel as a plot prop: a field key or accessor function (or a literal size, for a size channel); `grouping` also takes levels - see {@link GroupingAccessor}. */
 export type ChannelAccessors<TData extends Record<string, unknown>> = {
-    [K in keyof ChannelValue]?: Accessor<TData, ChannelValue[K]> | (K extends SizeChannelName ? number : never);
+    [K in keyof ChannelValue]?: K extends 'grouping' ? GroupingAccessor<TData> : Accessor<TData, ChannelValue[K]> | (K extends SizeChannelName ? number : never);
 };
 /** One channel's own resolved data accessor - mirrors svelteplot's own `ChannelAccessor`. */
 export type ResolvedChannel<TData, TValue = AxisValue> = {

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

@@ -19,6 +19,12 @@ export type ColorScaleConfig = {
     pivot?: number;
     /** Fallback color for a missing/unmapped value. Defaults to `'#ccc'`. */
     unknown?: string;
+    /**
+     * With a `grouping` of several levels (`'sector.kind.branch'`), the level its colors reach: `1` (the default)
+     * gives each outermost value its color, and a deeper one gives each value down to that level a tone of its
+     * outermost value's color - `2` a tone per kind within its sector's color. Ignored by a continuous ramp.
+     */
+    depth?: number;
 };
 /** How groups sharing the same `grouping`/`color` value are ordered: `reverse` flips which sorts first (e.g. PyramidPlot's left/right sides). */
 export type GroupingScaleConfig = {

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,18 +13,24 @@ export type TooltipAnchorY = 'top' | 'middle' | 'bottom';
 export type TooltipRow<TRow> = TRow & {
     seriesColor?: 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
  * x of a horizontal bar chart), and a heatmap's color value - and the numbers a custom `format` writes with its `number`.
  */
-export type TooltipOptions<TRow extends Record<string, unknown>> = NumberDisplay & {
+export type TooltipOptions<TRow extends Record<string, unknown>, TContext extends TooltipContext = TooltipContext> = NumberDisplay & {
     /** Matching strategy. Defaults to the chart kind's own default. */
     strategy?: HoverStrategy;
     /** Highlight the hovered point in every synced plot too. Defaults to `false`. */
     sync?: boolean;
-    /** Custom tooltip text for a row (supports `\n`). Defaults per chart kind. `number` writes a value as the display fields above ask. */
-    format?: (row: TRow, number: (value: number) => string) => string;
+    /**
+     * 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: 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. */
     series?: string[];
     /** Custom tooltip body; replaces `format` when given. Its rows carry a `seriesColor` - see {@link TooltipRow}. */
@@ -36,4 +43,4 @@ export type TooltipOptions<TRow extends Record<string, unknown>> = NumberDisplay
     anchorY?: TooltipAnchorY;
 };
 /** Either a bare on/off flag or the full option object. */
-export type TooltipProp<TRow extends Record<string, unknown>> = boolean | TooltipOptions<TRow>;
+export type TooltipProp<TRow extends Record<string, unknown>, TContext extends TooltipContext = TooltipContext> = boolean | TooltipOptions<TRow, TContext>;

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

@@ -1,4 +1,4 @@
-import type { StrokeStyle } from '../../plots/styling';
+import type { StrokeStyle, PerRow, DirectedInsetStyle } from '../../plots/styling';
 import type { CommonMarkerConfigWithInterval } from '../channels/commonMarkerConfigWithInterval';
 /** A point-to-point arrow (svelteplot's `Arrow`), from `x1`/`y1` to `x2`/`y2`. */
 export type ArrowMarkerConfig = {
@@ -7,12 +7,6 @@ export type ArrowMarkerConfig = {
     bend?: number | true;
     headAngle?: number;
     headLength?: number;
-    inset?: number;
-    insetStart?: number;
-    insetEnd?: number;
     sweep?: 1 | 0 | -1 | '+x' | '-x' | '+y' | '-y';
-    stroke?: string | ((d: any) => string | undefined);
-    strokeWidth?: string | ((d: any) => number);
-    strokeOpacity?: string | ((d: any) => number);
-    styles?: StrokeStyle;
+    styles?: PerRow<StrokeStyle & DirectedInsetStyle>;
 } & CommonMarkerConfigWithInterval;

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

@@ -1,18 +1,14 @@
 import type { AxisValue } from '../../layout/mapping';
-import type { AreaStyle } from '../../plots/styling';
+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;
-    insetTop?: number;
-    insetBottom?: number;
-    insetLeft?: number;
-    insetRight?: number;
     thickness?: number;
-    styles?: AreaStyle;
+    styles?: PerRow<AreaStyle> & InsetStyle;
     category?: AxisValue;
-    hover?: boolean;
-} & CommonMarkerConfigWithColor & CommonMarkerConfigWithInterval;
+} & CommonMarkerConfigWithColor & CommonMarkerConfigWithInterval & CommonMarkerConfigWithLabel;

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

@@ -1,9 +1,9 @@
-import type { AreaStyle } from '../../plots/styling';
+import type { AreaStyle, PerRow, InsetStyle } from '../../plots/styling';
 import type { CommonMarkerConfigWithArea } from '../channels/commonMarkerConfigWithArea';
+import type { CommonMarkerConfigWithLabel } from '../channels/commonMarkerConfigWithLabel';
 import type { CommonMarkerConfigWithColor } from '../channels/commonMarkerConfigWithColor';
-/** A heatmap cell mark; `fill` is always set per row. */
+/** A heatmap cell mark; its `fill` is set per row, by `color` or `styles.fill`. */
 export type CellMarkerConfig = {
     type: 'cell';
-    styles?: AreaStyle;
-    inset?: number;
-} & CommonMarkerConfigWithColor & Required<Pick<CommonMarkerConfigWithArea, 'fill'>>;
+    styles?: PerRow<AreaStyle & Pick<InsetStyle, 'inset'>>;
+} & CommonMarkerConfigWithColor & CommonMarkerConfigWithArea & CommonMarkerConfigWithLabel;

package/dist/types/markers/axis/delaunayLink.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 line per Delaunay triangulation edge (svelteplot's `DelaunayLink`). */
 export type DelaunayLinkMarkerConfig = {
     type: 'delaunayLink';
-    styles?: AreaStyle;
+    styles?: PerRow<AreaStyle>;
 } & CommonMarkerConfigWithColor;