@fundar/data-chart-telling 1.17.0 → 1.18.0

package/dist/layout/styles/ValueLabels.js

@@ -6,6 +6,7 @@ import { seriesIdOf } from '../../utils/grouping';
 import { isGapValue } from '../../plots/utils/gaps';
 import { PlotAxes } from '../../phases/data/PlotAxes';
 import { NumberFormat } from '../../utils/NumberFormat';
+import { RowContext } from '../../phases/context/RowContext';
 /**
  * A plot's value labels: the author's `styles.values` over the plot kind's
  * own defaults, how their text measures, where they are expected to sit
@@ -15,6 +16,11 @@ import { NumberFormat } from '../../utils/NumberFormat';
 export class ValueLabels {
     show;
     anchor;
+    /**
+     * A label's text for `value`: the author's `format`, else the kind's, else the value as the display fields ask.
+     * `row` is the row it labels, whose context the format reads; `series` names its series where there is no row
+     * (a label measured ahead of the rows).
+     */
     format;
     hoverIsolate;
     font;
@@ -33,12 +39,10 @@ export class ValueLabels {
         this.anchor = values?.anchor ?? options.anchor ?? 'outside';
         // The value as the display fields ask (else as it is), which a plot kind's own text builds on.
         const number = NumberFormat.maybe(NumberFormat.displayOf(values), cfg) ?? ((v) => `${v}`);
-        const kindFormat = options.format;
-        this.format = values?.format
-            ? (v, name, row) => values.format(v, name, row, number)
-            : kindFormat
-                ? (v, name) => kindFormat(v, name, number)
-                : (v) => number(v);
+        const own = values?.format ?? options.format;
+        this.format = own
+            ? (v, row, series) => own(v, number, ValueLabels.contextOf(row, series))
+            : (v) => number(v);
         this.hoverIsolate = values?.hoverIsolate ?? false;
         this.font = values?.fontStyle;
         this.fontSize = typeof this.font?.fontSize === 'number' ? this.font.fontSize : 12;
@@ -48,6 +52,11 @@ export class ValueLabels {
         this.#cfg = cfg;
         this.reach = (this.show && reach?.(this)) || [];
     }
+    /** The context a label's `format` reads: its row's, with `series` when the row gives none. */
+    static contextOf(row, series) {
+        const context = RowContext.of(row);
+        return context.series === undefined && series !== undefined ? { ...context, series } : context;
+    }
     /** A plot's value labels: `values` over `options`, the kind's own defaults, their reach read off `state`. */
     static build(values, cfg, options, state) {
         const { reach } = options;
@@ -134,8 +143,8 @@ export class ValueLabels {
      * dims with its row's series, and with `hoverIsolate`, hovering it
      * isolates that series. A row without a series gets the margins only.
      */
-    hooks(ctx) {
-        const interaction = ctx.interaction;
+    hooks(env) {
+        const interaction = env.interaction;
         const seriesOf = (d) => d?.[SERIES_KEY] === undefined ? undefined : String(d[SERIES_KEY]);
         const isolate = this.hoverIsolate && interaction;
         return {
@@ -190,8 +199,8 @@ export class ValueLabels {
      * never reaches out of the plot, so only one `outside` has the margins grow to hold it; and it takes the default
      * `fill` only `outside`, for inside it is written in the color that contrasts with its shape.
      */
-    shapeLabel(ctx, text, defaults = {}) {
-        const { fitMargins, styles: shared, ...events } = this.hooks(ctx);
+    shapeLabel(env, text, defaults = {}) {
+        const { fitMargins, styles: shared, ...events } = this.hooks(env);
         const { font } = this;
         return {
             ...events,
@@ -289,7 +298,7 @@ export class ValueLabels {
             x: (processed.channels.x ?? position.x),
             y: (processed.channels.y2 ?? processed.channels.y ?? topOf),
             grouping: SERIES_ID_KEY,
-            text: (d) => format(Number(valueOf(d)), nameOf(d), d),
+            text: (d) => format(Number(valueOf(d)), d, nameOf(d)),
             styles: {
                 ...font,
                 fill: this.fill ?? ((d) => colorOf(d) ?? 'currentColor'),
@@ -356,7 +365,7 @@ export class ValueLabels {
             const lo = Number(domain[0]);
             const hi = Number(domain[domain.length - 1]);
             for (const s of series)
-                texts.push(format(lo, s.name), format(hi, s.name));
+                texts.push(format(lo, undefined, s.name), format(hi, undefined, s.name));
         }
         else {
             for (const s of series) {
@@ -366,7 +375,7 @@ export class ValueLabels {
                 for (const d of s.data) {
                     const v = Number(y(d));
                     if (!Number.isNaN(v))
-                        texts.push(format(v, s.name));
+                        texts.push(format(v, undefined, s.name));
                 }
             }
         }

package/dist/layout/tooltip/TooltipState.svelte.d.ts

@@ -1,8 +1,8 @@
 import { Box } from '../margins/Box';
-import type { PlotAxes } from '../../phases/data/PlotAxes';
+import { PlotAxes } from '../../phases/data/PlotAxes';
 import type { ProcessedData, ProcessedRow } from '../../types/phases';
-import type { TooltipAnchorX, TooltipAnchorY } from '../../types/layout/tooltip';
 import type { Series } from '../../types/plots/data/common';
+import type { TooltipAnchorX, TooltipAnchorY } from '../../types/layout/tooltip';
 /** What a tooltip is shown from, each read reactively. */
 export type TooltipInputs = {
     /** The point it sits beside. */
@@ -46,16 +46,15 @@ export declare class TooltipState {
     /** A value as plain text: a date as a locale date, a number as `number` writes it (when given), anything else as itself. */
     static value(value: unknown, number?: (value: number) => string): string;
     /**
-     * How a hovered row reads by default, on every plot: its series, when the
-     * plot groups its rows; then where it sits - `category: value` when one
-     * axis is a band of categories (the row's own value, as its series reads
-     * it), else `x: y` as the transforms left them; then the value its color
-     * shows, when that is a number (a heatmap's cells). With `number`, the values - the one on the value axis
-     * (the plot's `y` when neither axis holds categories) and the color's - read as it writes them.
+     * How a hovered row reads by default, on every plot, from its context (see {@link RowContext}): its series,
+     * when the plot groups its rows; then where it sits - `category: value` when one axis is a band of categories,
+     * else `x: y` (an axis the transforms spread into a span, a bin's, as `from-to`); then the value its color
+     * shows, when that is a number (a heatmap's cells). With `number`, the values - the one on the value axis and
+     * the color's - read as it writes them.
      */
     static default(state: {
         processedData?: ProcessedData;
-        resolvedSeries?: Series<Record<string, unknown>>[];
+        resolvedSeries?: Series<any>[];
         channels?: {
             grouping?: unknown;
             color?: {

package/dist/layout/tooltip/TooltipState.svelte.js

@@ -2,7 +2,8 @@ import { Box } from '../margins/Box';
 import { PlotMargins } from '../margins/PlotMargins.svelte';
 import { resolveAccessor } from '../../utils/accessors';
 import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
-import { ValueLabels } from '../styles/ValueLabels';
+import { RowContext } from '../../phases/context/RowContext';
+import { PlotAxes } from '../../phases/data/PlotAxes';
 /** A tooltip anchor as the side of the point the tooltip sits on. */
 const SIDES = {
     left: 'before',
@@ -69,29 +70,33 @@ export class TooltipState {
         return number && typeof value === 'number' ? number(value) : String(value);
     }
     /**
-     * How a hovered row reads by default, on every plot: its series, when the
-     * plot groups its rows; then where it sits - `category: value` when one
-     * axis is a band of categories (the row's own value, as its series reads
-     * it), else `x: y` as the transforms left them; then the value its color
-     * shows, when that is a number (a heatmap's cells). With `number`, the values - the one on the value axis
-     * (the plot's `y` when neither axis holds categories) and the color's - read as it writes them.
+     * How a hovered row reads by default, on every plot, from its context (see {@link RowContext}): its series,
+     * when the plot groups its rows; then where it sits - `category: value` when one axis is a band of categories,
+     * else `x: y` (an axis the transforms spread into a span, a bin's, as `from-to`); then the value its color
+     * shows, when that is a number (a heatmap's cells). With `number`, the values - the one on the value axis and
+     * the color's - read as it writes them.
      */
     static default(state, number) {
         const processed = state.processedData;
         if (!processed)
             return () => '';
-        const x = TooltipState.#axisText(processed, 'x');
-        const y = TooltipState.#axisText(processed, 'y');
-        // With no band axis, the value is the y.
-        const valueY = TooltipState.#axisText(processed, 'y', number);
+        const valueAxis = PlotAxes.valueOf(state);
+        const contextOf = RowContext.reader(state);
         const bandX = state.axes?.bands.includes('x') ?? false;
         const bandY = state.axes?.bands.includes('y') ?? false;
-        const valueOf = ValueLabels.valueOf(state);
+        const along = (axis) => {
+            const span = TooltipState.#spanText(processed, axis, number);
+            const measured = axis === valueAxis && !state.axes?.bands.includes(axis);
+            return (row) => span ? span(row) : TooltipState.value(contextOf(row)[axis], measured ? number : undefined);
+        };
+        const x = along('x');
+        const y = along('y');
+        const valueOf = (row) => TooltipState.value(contextOf(row).value, number);
         const position = bandX && !bandY
-            ? (row) => `${x(row)}: ${TooltipState.value(valueOf(row), number)}`
+            ? (row) => `${x(row)}: ${valueOf(row)}`
             : bandY && !bandX
-                ? (row) => `${y(row)}: ${TooltipState.value(valueOf(row), number)}`
-                : (row) => `${x(row)}: ${valueY(row)}`;
+                ? (row) => `${y(row)}: ${valueOf(row)}`
+                : (row) => `${x(row)}: ${y(row)}`;
         const grouped = state.channels?.grouping !== undefined;
         const color = state.channels?.color;
         const colorName = typeof color?.source === 'string' ? color.source : 'color';
@@ -106,26 +111,20 @@ export class TooltipState {
         };
     }
     /**
-     * How one axis reads on a processed row: its own channel, else the range
-     * the transforms gave it - a stack's own share (`2 - 1`), any other span as `1-2`.
+     * How an axis the transforms spread into a span reads on a processed row - a bin's edges as `from-to` - or
+     * `undefined` when the axis has a value of its own or is a stack's (whose own value the context gives).
      */
-    static #axisText(processed, axis, number) {
+    static #spanText(processed, axis, number) {
         const { channels, transforms } = processed;
-        const read = (channel) => resolveAccessor(channel);
-        const point = channels[axis];
-        if (point !== undefined) {
-            const value = read(point);
-            return (row) => TooltipState.value(value(row), number);
-        }
         const low = channels[`${axis}1`];
         const high = channels[`${axis}2`];
-        if (low === undefined || high === undefined)
-            return () => '';
+        if (channels[axis] !== undefined || low === undefined || high === undefined)
+            return undefined;
+        if (transforms.some((t) => t.type === STACKS[axis]))
+            return undefined;
+        const read = (channel) => resolveAccessor(channel);
         const from = read(low);
         const to = read(high);
-        if (transforms.some((t) => t.type === STACKS[axis])) {
-            return (row) => TooltipState.value(Number(to(row)) - Number(from(row)), number);
-        }
         return (row) => `${TooltipState.value(from(row), number)}-${TooltipState.value(to(row), number)}`;
     }
 }

package/dist/markers/MarkerKinds.d.ts

@@ -14,6 +14,11 @@ export declare class MarkerKinds {
             clip: false;
             drawsRows: true;
         };
+        band: {
+            clip: true;
+            drawsRows: false;
+            legendSymbol: "rect";
+        };
         bar: {
             clip: true;
             drawsRows: true;

package/dist/markers/MarkerKinds.js

@@ -6,6 +6,7 @@ export class MarkerKinds {
     static traits = {
         area: { clip: true, drawsRows: true, legendSymbol: 'area' },
         arrow: { clip: false, drawsRows: true },
+        band: { clip: true, drawsRows: false, legendSymbol: 'rect' },
         bar: { clip: true, drawsRows: true, legendSymbol: 'bar' },
         bollinger: { clip: true, drawsRows: true, legendSymbol: 'line' },
         brush: { clip: false, drawsRows: false },

package/dist/markers/band/BandMarker.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+	import { usePlot } from '../../layout/plot/usePlot';
+	import { getConfiguration } from '../../configuration/config.svelte';
+	import { MarkerEvents } from '../utils/MarkerEvents';
+	import { RowStyle } from '../utils/RowStyle';
+	import { Bands, type Band } from './Bands';
+	import type { BandMarkerConfig } from '../../types/markers/common';
+
+	/**
+	 * Renders one `'band'` marker: a rectangle over the band of each category it names, across the whole of the
+	 * other axis. Nothing on an axis that is not a band scale. It takes the pointer only with a handler of its own,
+	 * so a band behind the plot's shapes does not take their hover.
+	 */
+	const { marker }: { marker: BandMarkerConfig } = $props();
+	const cfg = $derived(getConfiguration());
+	const events = MarkerEvents.use(() => marker);
+	const plot = usePlot().svelteplot;
+
+	const bands = $derived(Bands.of(marker));
+	const rows = $derived(marker.data ?? []);
+	const styles = $derived({ ...cfg.band, ...marker.styles });
+	const scale = $derived(plot.scales[marker.axis]);
+	const across = $derived(plot.scales[marker.axis === 'x' ? 'y' : 'x']);
+
+	/** The pixels the other axis spans, lowest first. */
+	const extent = $derived.by((): [number, number] => {
+		const range = across?.fn?.range?.() as number[] | undefined;
+		if (!range || range.length < 2) return [0, 0];
+		const [a, b] = [Number(range[0]), Number(range[range.length - 1])];
+		return [Math.min(a, b), Math.max(a, b)];
+	});
+
+	/** Where a band is drawn: its slice of the band along the axis, the other axis' whole span across it. */
+	function boxOf(band: Band) {
+		const bandwidth = scale.fn.bandwidth?.() ?? 0;
+		const start = Number(scale.fn(band.category as never));
+		const from = start + band.slice.start * bandwidth;
+		const size = Math.max(0, bandwidth * (1 - band.slice.start - band.slice.end));
+		const [low, high] = extent;
+		return marker.axis === 'x'
+			? { x: from, y: low, width: size, height: high - low }
+			: { x: low, y: from, width: high - low, height: size };
+	}
+
+	/** A color of `styles` for the row: a value, the field of the rows it names, or a function of the row. */
+	const colorOf = (style: unknown, row: unknown) => RowStyle.colorOf(style, rows)?.(row);
+	/** A number of `styles` for the row: a value, the field of the rows it names, or a function of the row. */
+	const numberOf = (style: unknown, row: unknown): number | undefined => {
+		const read = RowStyle.field(style as never) as unknown;
+		const value = typeof read === 'function' ? (read as (row: unknown) => unknown)(row) : read;
+		return value == null ? undefined : Number(value);
+	};
+</script>
+
+{#if scale?.type === 'band'}
+	<g class="band" pointer-events={events.any ? undefined : 'none'}>
+		{#each bands as band (band.category instanceof Date ? +band.category : band.category)}
+			{@const box = boxOf(band)}
+			{@const radius = numberOf(styles.borderRadius, band.row)}
+			<rect
+				{...box}
+				rx={radius}
+				ry={radius}
+				fill={colorOf(styles.fill, band.row)}
+				fill-opacity={numberOf(styles.fillOpacity, band.row)}
+				stroke={colorOf(styles.stroke, band.row)}
+				stroke-width={numberOf(styles.strokeWidth, band.row)}
+				stroke-opacity={numberOf(styles.strokeOpacity, band.row)}
+				stroke-dasharray={colorOf(styles.strokeDasharray, band.row)}
+				{...events.forRow(band.row, band.index)}
+			/>
+		{/each}
+	</g>
+{/if}

package/dist/markers/band/BandMarker.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { BandMarkerConfig } from '../../types/markers/common';
+type $$ComponentProps = {
+    marker: BandMarkerConfig;
+};
+declare const BandMarker: import("svelte").Component<$$ComponentProps, {}, "">;
+type BandMarker = ReturnType<typeof BandMarker>;
+export default BandMarker;

package/dist/markers/band/Bands.d.ts

@@ -0,0 +1,16 @@
+import type { AxisValue } from '../../types/layout/mapping';
+import type { BandSlice } from '../../types/layout/hover';
+import type { BandMarkerConfig } from '../../types/markers/common';
+/** One band to draw: its category, the part of it filled, and the first row that names it. */
+export type Band = {
+    category: AxisValue;
+    slice: BandSlice;
+    row: unknown;
+    index: number;
+};
+/** The bands a `band` marker draws, one per category its rows (or its `value`) name, in the order they first come. */
+export declare class Bands {
+    #private;
+    /** The marker's bands. Rows that share a category share one band, which fills what all of their slices do. */
+    static of(marker: Pick<BandMarkerConfig, 'value' | 'slice' | 'data'>): Band[];
+}

package/dist/markers/band/Bands.js

@@ -0,0 +1,48 @@
+import { resolveAccessor } from '../../utils/accessors';
+/** The bands a `band` marker draws, one per category its rows (or its `value`) name, in the order they first come. */
+export class Bands {
+    static #WHOLE = { start: 0, end: 0 };
+    /** The marker's bands. Rows that share a category share one band, which fills what all of their slices do. */
+    static of(marker) {
+        const { rows, categoryOf } = Bands.#rowsOf(marker);
+        const sliceOf = Bands.#sliceOf(marker.slice);
+        const bands = new Map();
+        rows.forEach((row, index) => {
+            const category = categoryOf(row);
+            if (category == null)
+                return;
+            const key = category instanceof Date ? +category : category;
+            const slice = sliceOf(row);
+            const band = bands.get(key);
+            if (!band) {
+                bands.set(key, { category, slice, row, index });
+                return;
+            }
+            // What either one fills: the least left out at each end.
+            band.slice = {
+                start: Math.min(band.slice.start, slice.start),
+                end: Math.min(band.slice.end, slice.end)
+            };
+        });
+        return [...bands.values()];
+    }
+    /** The rows a marker draws from, and the category of each: its `data` and `value`, or its `value`'s own. */
+    static #rowsOf(marker) {
+        const { value, data } = marker;
+        if (data) {
+            const read = resolveAccessor(value);
+            return { rows: data, categoryOf: read };
+        }
+        const values = (Array.isArray(value) ? value : [value]);
+        return { rows: values, categoryOf: (row) => row };
+    }
+    /** Each row's slice: the marker's own, or a function of the row's; the whole band when it gives none. */
+    static #sliceOf(slice) {
+        const whole = Bands.#WHOLE;
+        const read = typeof slice === 'function' ? slice : () => slice;
+        return (row) => {
+            const own = read(row);
+            return own ? { start: own.start ?? 0, end: own.end ?? 0 } : whole;
+        };
+    }
+}

package/dist/markers/bar/BarMarker.svelte

@@ -9,13 +9,11 @@
 
 	/**
 	 * Renders one `'bar'` marker: `role: 'segment'` (visible bar via
-	 * `<BarX>`/`<BarY>`), `role: 'hitArea'` (invisible hover hit region for
-	 * one segment), or `role: 'highlight'` (visible area highlight).
+	 * `<BarX>`/`<BarY>`) or `role: 'hitArea'` (invisible hover hit region for
+	 * one segment).
 	 */
 	let { marker }: { marker: BarMarkerConfig } = $props();
 	const events = MarkerEvents.use(() => marker);
-	/** The hover band stands for no row, so a style that is a function of one does not apply to it. */
-	const flatStyles = $derived(RowStyle.flat(marker.styles));
 
 	const cfg = $derived(getConfiguration());
 	const data = $derived(marker.data ?? []);
@@ -90,69 +88,28 @@
 		{@const insetRight = (marker.styles?.insetRight ?? 0) * bandwidth}
 		{@const insetTop = (marker.styles?.insetTop ?? 0) * bandwidth}
 		{@const insetBottom = (marker.styles?.insetBottom ?? 0) * bandwidth}
-		{#if marker.role === 'hitArea'}
-			<!-- The band runs the plot's whole value axis, so the pointer needn't be over the bar. -->
-			{@const [rangeMin, rangeMax] = valueExtentFor(marker.isHorizontal)}
-			{#if marker.isHorizontal}
-				<rect
-					class="dct-hit-area"
-					x={rangeMin + insetLeft}
-					y={bandStart + insetBottom}
-					width={Math.max(0, rangeMax - rangeMin - insetLeft - insetRight)}
-					height={Math.max(0, bandwidth - insetTop - insetBottom)}
-					fill="transparent"
-					{...events.forRow(data[0], 0)}
-				/>
-			{:else}
-				<rect
-					class="dct-hit-area"
-					x={bandStart + insetLeft}
-					y={rangeMin + insetBottom}
-					width={Math.max(0, bandwidth - insetLeft - insetRight)}
-					height={Math.max(0, rangeMax - rangeMin - insetTop - insetBottom)}
-					fill="transparent"
-					{...events.forRow(data[0], 0)}
-				/>
-			{/if}
+		<!-- The band runs the plot's whole value axis, so the pointer needn't be over the bar. -->
+		{@const [rangeMin, rangeMax] = valueExtentFor(marker.isHorizontal)}
+		{#if marker.isHorizontal}
+			<rect
+				class="dct-hit-area"
+				x={rangeMin + insetLeft}
+				y={bandStart + insetBottom}
+				width={Math.max(0, rangeMax - rangeMin - insetLeft - insetRight)}
+				height={Math.max(0, bandwidth - insetTop - insetBottom)}
+				fill="transparent"
+				{...events.forRow(data[0], 0)}
+			/>
 		{:else}
-			{@const [valueMin, valueMax] = valueExtentFor(marker.isHorizontal)}
-			{#if marker.isHorizontal}
-				{@const thickness = Math.max(0, bandwidth - insetTop - insetBottom) + 2}
-				{@const center = bandStart + insetBottom + (bandwidth - insetTop - insetBottom) / 2}
-				<rect
-					class="hover-area"
-					x={valueMin}
-					y={center - thickness / 2}
-					width={Math.max(0, valueMax - valueMin)}
-					height={thickness}
-					fill={flatStyles.fill}
-					fill-opacity={flatStyles.fillOpacity}
-					stroke={flatStyles.stroke}
-					stroke-width={flatStyles.strokeWidth}
-					stroke-opacity={flatStyles.strokeOpacity}
-					stroke-dasharray={flatStyles.strokeDasharray}
-					rx={flatStyles.borderRadius}
-					pointer-events="none"
-				/>
-			{:else}
-				{@const thickness = Math.max(0, bandwidth - insetLeft - insetRight) + 2}
-				{@const center = bandStart + insetLeft + (bandwidth - insetLeft - insetRight) / 2}
-				<rect
-					class="hover-area"
-					x={center - thickness / 2}
-					y={valueMin}
-					width={thickness}
-					height={Math.max(0, valueMax - valueMin)}
-					fill={flatStyles.fill}
-					fill-opacity={flatStyles.fillOpacity}
-					stroke={flatStyles.stroke}
-					stroke-width={flatStyles.strokeWidth}
-					stroke-opacity={flatStyles.strokeOpacity}
-					stroke-dasharray={flatStyles.strokeDasharray}
-					ry={flatStyles.borderRadius}
-					pointer-events="none"
-				/>
-			{/if}
+			<rect
+				class="dct-hit-area"
+				x={bandStart + insetLeft}
+				y={rangeMin + insetBottom}
+				width={Math.max(0, bandwidth - insetLeft - insetRight)}
+				height={Math.max(0, rangeMax - rangeMin - insetTop - insetBottom)}
+				fill="transparent"
+				{...events.forRow(data[0], 0)}
+			/>
 		{/if}
 	{/if}
 {/if}