@fundar/data-chart-telling 1.17.0 → 1.19.0

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

@@ -1,4 +1,4 @@
-import type { MarkerTraits } from '../types/markers/traits';
+import type { InheritedChannel, MarkerTraits } from '../types/markers/traits';
 /**
  * Every marker kind's traits, in one row each. Typed over every kind, so a
  * new kind can't be added without declaring all of its traits here.
@@ -6,20 +6,42 @@ import type { MarkerTraits } from '../types/markers/traits';
 export declare class MarkerKinds {
     static readonly traits: {
         area: {
+            oriented: true;
+            inherits: ("grouping" | "x" | "y" | "color" | "opacity")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
+            labels: {
+                default: "point";
+                path: "area";
+                point: "top";
+            };
         };
         arrow: {
             clip: false;
             drawsRows: true;
         };
+        band: {
+            clip: true;
+            drawsRows: false;
+            legendSymbol: "rect";
+        };
         bar: {
+            oriented: true;
+            inherits: ("x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "bar";
+            labels: {
+                default: "box";
+                box: "band";
+                path: "box";
+                point: "box";
+            };
         };
         bollinger: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
@@ -29,14 +51,23 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         box: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "bar";
         };
         cell: {
+            inherits: ("x" | "y" | "color" | "opacity")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "cell";
+            labels: {
+                default: "box";
+                box: "cell";
+                path: "box";
+                point: "box";
+            };
         };
         component: {
             clip: false;
@@ -47,10 +78,12 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         delaunayLink: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
         delaunayMesh: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
@@ -59,19 +92,27 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         density: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         difference: {
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         dot: {
+            inherits: ("symbol" | "x" | "y" | "color" | "opacity" | "r")[];
             clip: false;
             drawsRows: true;
             legendSymbol: "dot";
+            labels: {
+                default: "point";
+                path: "rim";
+                point: "dot";
+            };
         };
         geo: {
             clip: false;
@@ -94,11 +135,13 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         hull: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         image: {
+            inherits: ("x" | "y")[];
             clip: false;
             drawsRows: true;
         };
@@ -107,9 +150,15 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         line: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
+            labels: {
+                default: "point";
+                path: "stroke";
+                point: "row";
+            };
         };
         link: {
             clip: false;
@@ -120,11 +169,20 @@ export declare class MarkerKinds {
             drawsRows: true;
         };
         rect: {
+            inherits: ("x" | "y" | "color" | "opacity")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "rect";
+            labels: {
+                default: "box";
+                box: "edges";
+                path: "box";
+                point: "box";
+            };
         };
         regression: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
@@ -139,40 +197,65 @@ export declare class MarkerKinds {
             drawsRows: false;
         };
         text: {
+            inherits: ("x" | "y")[];
             clip: false;
             drawsRows: true;
         };
         tick: {
+            oriented: true;
+            inherits: "color"[];
             clip: true;
             drawsRows: true;
         };
         trail: {
+            inherits: ("grouping" | "x" | "y" | "color" | "opacity" | "r")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "line";
+            labels: {
+                default: "point";
+                path: "stroke";
+                point: "row";
+            };
         };
         vector: {
+            inherits: "length"[];
             clip: false;
             drawsRows: false;
         };
         violin: {
+            oriented: true;
+            inherits: ("x" | "y")[];
             clip: true;
             drawsRows: true;
             legendSymbol: "area";
         };
         voronoi: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
         voronoiMesh: {
+            inherits: ("grouping" | "x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
         };
         waffle: {
+            oriented: true;
+            inherits: ("x" | "y" | "color")[];
             clip: true;
             drawsRows: true;
+            labels: {
+                default: "box";
+                box: "band";
+                path: "box";
+                point: "box";
+            };
         };
     };
     /** The traits of a marker kind, or `undefined` for a type no kind declares. */
     static of(type: string | undefined): MarkerTraits | undefined;
+    static inherits(type: string | undefined, channel: InheritedChannel): boolean;
+    /** Whether the kind takes the plot's scales: it inherits a channel that has one. */
+    static inheritsScales(type: string | undefined): boolean;
 }

package/dist/markers/MarkerKinds.js

@@ -1,47 +1,167 @@
+const SCALED = ['color', 'opacity', 'symbol', 'r', 'length'];
 /**
  * Every marker kind's traits, in one row each. Typed over every kind, so a
  * new kind can't be added without declaring all of its traits here.
  */
 export class MarkerKinds {
     static traits = {
-        area: { clip: true, drawsRows: true, legendSymbol: 'area' },
+        area: {
+            oriented: true,
+            inherits: ['x', 'y', 'grouping', 'color', 'opacity'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area',
+            labels: { default: 'point', path: 'area', point: 'top' }
+        },
         arrow: { clip: false, drawsRows: true },
-        bar: { clip: true, drawsRows: true, legendSymbol: 'bar' },
-        bollinger: { clip: true, drawsRows: true, legendSymbol: 'line' },
+        band: { clip: true, drawsRows: false, legendSymbol: 'rect' },
+        bar: {
+            oriented: true,
+            inherits: ['x', 'y', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'bar',
+            labels: { default: 'box', box: 'band', path: 'box', point: 'box' }
+        },
+        bollinger: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line'
+        },
         brush: { clip: false, drawsRows: false },
-        box: { clip: true, drawsRows: true, legendSymbol: 'bar' },
-        cell: { clip: true, drawsRows: true, legendSymbol: 'cell' },
+        box: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'bar'
+        },
+        cell: {
+            inherits: ['x', 'y', 'color', 'opacity'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'cell',
+            labels: { default: 'box', box: 'cell', path: 'box', point: 'box' }
+        },
         component: { clip: false, drawsRows: false },
         contour: { clip: false, drawsRows: false },
-        delaunayLink: { clip: true, drawsRows: true },
-        delaunayMesh: { clip: true, drawsRows: true },
+        delaunayLink: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
+        delaunayMesh: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
         delta: { clip: false, drawsRows: false },
-        density: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        difference: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        dot: { clip: false, drawsRows: true, legendSymbol: 'dot' },
+        density: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        difference: {
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        dot: {
+            inherits: ['x', 'y', 'color', 'opacity', 'symbol', 'r'],
+            clip: false,
+            drawsRows: true,
+            legendSymbol: 'dot',
+            labels: { default: 'point', path: 'rim', point: 'dot' }
+        },
         geo: { clip: false, drawsRows: false },
         'geo-component': { clip: false, drawsRows: true },
         'geo-hover': { clip: false, drawsRows: false },
         graticule: { clip: false, drawsRows: false },
         hover: { clip: false, drawsRows: false },
-        hull: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        image: { clip: false, drawsRows: true },
+        hull: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        image: {
+            inherits: ['x', 'y'],
+            clip: false,
+            drawsRows: true
+        },
         inset: { clip: false, drawsRows: false },
-        line: { clip: true, drawsRows: true, legendSymbol: 'line' },
+        line: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line',
+            labels: { default: 'point', path: 'stroke', point: 'row' }
+        },
         link: { clip: false, drawsRows: false },
         raster: { clip: true, drawsRows: true },
-        rect: { clip: true, drawsRows: true, legendSymbol: 'rect' },
-        regression: { clip: true, drawsRows: true, legendSymbol: 'line' },
+        rect: {
+            inherits: ['x', 'y', 'color', 'opacity'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'rect',
+            labels: { default: 'box', box: 'edges', path: 'box', point: 'box' }
+        },
+        regression: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line'
+        },
         rule: { clip: true, drawsRows: false, legendSymbol: 'line' },
         sphere: { clip: false, drawsRows: false },
-        text: { clip: false, drawsRows: true },
-        tick: { clip: true, drawsRows: true },
-        trail: { clip: true, drawsRows: true, legendSymbol: 'line' },
-        vector: { clip: false, drawsRows: false },
-        violin: { clip: true, drawsRows: true, legendSymbol: 'area' },
-        voronoi: { clip: true, drawsRows: true },
-        voronoiMesh: { clip: true, drawsRows: true },
-        waffle: { clip: true, drawsRows: true }
+        text: {
+            inherits: ['x', 'y'],
+            clip: false,
+            drawsRows: true
+        },
+        tick: {
+            oriented: true,
+            inherits: ['color'],
+            clip: true,
+            drawsRows: true
+        },
+        trail: {
+            inherits: ['x', 'y', 'grouping', 'color', 'opacity', 'r'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'line',
+            labels: { default: 'point', path: 'stroke', point: 'row' }
+        },
+        vector: { inherits: ['length'], clip: false, drawsRows: false },
+        violin: {
+            oriented: true,
+            inherits: ['x', 'y'],
+            clip: true,
+            drawsRows: true,
+            legendSymbol: 'area'
+        },
+        voronoi: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
+        voronoiMesh: {
+            inherits: ['x', 'y', 'grouping', 'color'],
+            clip: true,
+            drawsRows: true
+        },
+        waffle: {
+            oriented: true,
+            inherits: ['x', 'y', 'color'],
+            clip: true,
+            drawsRows: true,
+            labels: { default: 'box', box: 'band', path: 'box', point: 'box' }
+        }
     };
     /** The traits of a marker kind, or `undefined` for a type no kind declares. */
     static of(type) {
@@ -49,4 +169,11 @@ export class MarkerKinds {
             ? MarkerKinds.traits[type]
             : undefined;
     }
+    static inherits(type, channel) {
+        return MarkerKinds.of(type)?.inherits?.includes(channel) ?? false;
+    }
+    /** Whether the kind takes the plot's scales: it inherits a channel that has one. */
+    static inheritsScales(type) {
+        return SCALED.some((channel) => MarkerKinds.inherits(type, channel));
+    }
 }

package/dist/markers/area/AreaMarker.svelte

@@ -16,7 +16,7 @@
 	const events = MarkerEvents.use(() => marker);
 
 	const plot = usePlot();
-	const isHorizontal = $derived(plot.axes?.isHorizontal ?? false);
+	const isHorizontal = $derived(marker.isHorizontal ?? plot.axes?.isHorizontal ?? false);
 	const AreaMark = $derived(isHorizontal ? AreaX : AreaY);
 
 	const cfg = $derived(getConfiguration());

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