@fundar/data-chart-telling 1.0.0 → 1.2.0

package/dist/phases/statistics/methods/Density2dStatistic.js

@@ -2,17 +2,19 @@ import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/sourc
 /** 2D kernel density over the source's `x` and `y`, drawn as a `density` marker. */
 export class Density2dStatistic {
     static build(source, config) {
-        return {
-            type: 'density',
-            data: source.data,
-            x: source.x,
-            y: source.y,
-            bandwidth: config.bandwidth,
-            thresholds: config.thresholds,
-            styles: {
-                ...config.styles,
-                stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+        return [
+            {
+                type: 'density',
+                data: source.data,
+                x: source.x,
+                y: source.y,
+                bandwidth: config.bandwidth,
+                thresholds: config.thresholds,
+                styles: {
+                    ...config.styles,
+                    stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+                }
             }
-        };
+        ];
     }
 }

package/dist/phases/statistics/methods/DensityStatistic.d.ts

@@ -8,5 +8,5 @@ export declare class DensityStatistic {
      * `x` is the value and `y` the density, so it draws on the plot's axes as-is.
      * The output is one derived row per estimate point rather than one per input row.
      */
-    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: DensityStatisticOptions): AreaMarkerConfig;
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: DensityStatisticOptions): AreaMarkerConfig[];
 }

package/dist/phases/statistics/methods/DensityStatistic.js

@@ -15,15 +15,17 @@ export class DensityStatistic {
             kernel: config.kernel,
             bandwidth: config.bandwidth
         });
-        return {
-            type: 'area',
-            data: result.data,
-            x: result.x,
-            y: result.y,
-            styles: {
-                ...config.styles,
-                fill: config.styles?.fill ?? source.color ?? STATISTIC_FALLBACK_COLOR
+        return [
+            {
+                type: 'area',
+                data: result.data,
+                x: result.x,
+                y: result.y,
+                styles: {
+                    ...config.styles,
+                    fill: config.styles?.fill ?? source.color ?? STATISTIC_FALLBACK_COLOR
+                }
             }
-        };
+        ];
     }
 }

package/dist/phases/statistics/methods/DeviationStatistic.d.ts

@@ -0,0 +1,8 @@
+import type { DeviationStatisticOptions } from '../../../types/layout/statistics';
+import type { AxisBasedMarkersConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** An estimator of the source's values along the plot's value axis and a band around it, drawn as a `rect` and a `rule` marker, each optionally labelled by a `text` marker. */
+export declare class DeviationStatistic {
+    #private;
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: DeviationStatisticOptions): AxisBasedMarkersConfig[];
+}

package/dist/phases/statistics/methods/DeviationStatistic.js

@@ -0,0 +1,111 @@
+import { deviation, extent, mean, median } from 'd3-array';
+import { resolveAccessor } from '../../../utils/accessors';
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** Scales a median absolute deviation to the standard deviation of a normal distribution. */
+const MAD_SCALE = 1.4826;
+const DEFAULT_BAND_OPACITY = 0.15;
+const LABEL_FONT_SIZE = 10;
+/** Pixels between a label and the line it names, and between it and the plot's edge. */
+const LABEL_GAP = 4;
+/** An estimator of the source's values along the plot's value axis and a band around it, drawn as a `rect` and a `rule` marker, each optionally labelled by a `text` marker. */
+export class DeviationStatistic {
+    static build(source, config) {
+        const axis = source.axis ?? 'y';
+        const read = resolveAccessor(source[axis]);
+        const values = source.data
+            .map((d) => {
+            const v = read(d);
+            return v instanceof Date ? v.getTime() : typeof v === 'number' ? v : NaN;
+        })
+            .filter(Number.isFinite);
+        if (!values.length)
+            return [];
+        const center = DeviationStatistic.#estimate(values, config.estimator ?? 'mean');
+        const spread = DeviationStatistic.#spread(values, config.spread ?? 'stdev');
+        const half = (config.k ?? 1) * spread;
+        const color = source.color ?? STATISTIC_FALLBACK_COLOR;
+        const markers = [];
+        if (config.band !== false) {
+            const { label, ...style } = config.band ?? {};
+            const [lo, hi] = [center - half, center + half];
+            markers.push({
+                type: 'rect',
+                data: [{ lo, hi }],
+                ...(axis === 'x' ? { x1: 'lo', x2: 'hi' } : { y1: 'lo', y2: 'hi' }),
+                styles: { fillOpacity: DEFAULT_BAND_OPACITY, ...style, fill: style.fill ?? color }
+            });
+            if (label) {
+                const own = label === true ? {} : label;
+                const lower = own.edge === 'lower';
+                const outside = own.position === 'outside';
+                markers.push(DeviationStatistic.#label(axis, lower ? lo : hi, color, lower === outside, {
+                    text: own.text ?? (config.spread === 'mad' ? 'MAD' : 'STDEV'),
+                    styles: own.styles
+                }));
+            }
+        }
+        if (config.rule !== false) {
+            const { label, ...style } = config.rule ?? {};
+            markers.push({
+                type: 'rule',
+                axis,
+                value: center,
+                styles: { ...style, stroke: style.stroke ?? color }
+            });
+            if (label) {
+                const own = label === true ? {} : label;
+                markers.push(DeviationStatistic.#label(axis, center, color, axis === 'x', {
+                    text: own.text ?? (config.estimator ?? 'mean').toUpperCase(),
+                    styles: own.styles
+                }));
+            }
+        }
+        return markers;
+    }
+    /**
+     * A label beside the line at `position`, against the plot's start edge: a
+     * vertical line's reads down from the top, a horizontal line's ends at the
+     * right. `towardLower` puts its body on the side of lower values (left of a
+     * vertical line, below a horizontal one).
+     */
+    static #label(axis, position, color, towardLower, label) {
+        const vertical = axis === 'x';
+        const fontSize = label.styles?.fontSize ?? LABEL_FONT_SIZE;
+        const sign = towardLower ? -1 : 1;
+        // A vertical line's text is centred on its own point, so its half-height plus the gap clears the line.
+        const gap = LABEL_GAP + (vertical ? fontSize / 2 : 0);
+        const [dx, dy] = vertical ? [sign * gap, LABEL_GAP] : [-LABEL_GAP, -sign * gap];
+        return {
+            type: 'text',
+            text: label.text,
+            ...(vertical ? { x: position } : { y: position }),
+            frameAnchor: vertical ? 'top' : 'right',
+            styles: {
+                fill: color,
+                fontSize,
+                ...(vertical
+                    ? { rotate: 90, textAnchor: 'start', lineAnchor: 'middle' }
+                    : { textAnchor: 'end', lineAnchor: towardLower ? 'top' : 'bottom' }),
+                ...label.styles,
+                dx: dx + (label.styles?.dx ?? 0),
+                dy: dy + (label.styles?.dy ?? 0)
+            }
+        };
+    }
+    static #estimate(values, estimator) {
+        if (estimator === 'median')
+            return median(values);
+        if (estimator === 'midrange') {
+            const [lo, hi] = extent(values);
+            return (lo + hi) / 2;
+        }
+        return mean(values);
+    }
+    static #spread(values, spread) {
+        if (spread === 'mad') {
+            const mid = median(values);
+            return MAD_SCALE * median(values.map((v) => Math.abs(v - mid)));
+        }
+        return deviation(values) ?? 0;
+    }
+}

package/dist/phases/statistics/methods/MovingAverageStatistic.d.ts

@@ -8,5 +8,5 @@ export declare class MovingAverageStatistic {
      * no dedicated mark for this (unlike `regression`/`bollinger`). `windowY`
      * keeps one output row per input row, so `x` passes straight through.
      */
-    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: MovingAverageStatisticOptions): LineMarkerConfig;
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: MovingAverageStatisticOptions): LineMarkerConfig[];
 }

package/dist/phases/statistics/methods/MovingAverageStatistic.js

@@ -16,15 +16,17 @@ export class MovingAverageStatistic {
             k: config.k,
             reduce: config.reduce ?? 'mean'
         });
-        return {
-            type: 'line',
-            data: result.data,
-            x: result.x,
-            y: result.y,
-            styles: {
-                ...config.styles,
-                stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+        return [
+            {
+                type: 'line',
+                data: result.data,
+                x: result.x,
+                y: result.y,
+                styles: {
+                    ...config.styles,
+                    stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+                }
             }
-        };
+        ];
     }
 }

package/dist/phases/statistics/methods/RegressionStatistic.d.ts

@@ -5,5 +5,5 @@ import { type StatisticSource } from '../../../types/phases/statistics/source';
 export declare class RegressionStatistic {
     static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: Extract<StatisticConfig, {
         type: 'regression';
-    }>): RegressionMarkerConfig;
+    }>): RegressionMarkerConfig[];
 }

package/dist/phases/statistics/methods/RegressionStatistic.js

@@ -2,20 +2,22 @@ import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/sourc
 /** A regression curve over the source, drawn as a `regression` marker (svelteplot fits it at render time). */
 export class RegressionStatistic {
     static build(source, config) {
-        return {
-            type: 'regression',
-            data: source.data,
-            x: source.x,
-            y: source.y,
-            regressionType: config.regressionType,
-            order: config.order,
-            base: config.base,
-            span: config.span,
-            confidence: config.confidence,
-            styles: {
-                ...config.styles,
-                stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+        return [
+            {
+                type: 'regression',
+                data: source.data,
+                x: source.x,
+                y: source.y,
+                regressionType: config.regressionType,
+                order: config.order,
+                base: config.base,
+                span: config.span,
+                confidence: config.confidence,
+                styles: {
+                    ...config.styles,
+                    stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+                }
             }
-        };
+        ];
     }
 }

package/dist/phases/tooltip/TooltipPhase.d.ts

@@ -2,8 +2,10 @@ import type { AxisPlotState, PhaseStage } from '../../types/phases';
 type AnyAxisState = AxisPlotState<any, any, any, any>;
 /**
  * The "tooltip" phase every axis-based plot shares: how a hovered row reads,
- * as `tooltipFormat` - the same default on every plot, {@link TooltipState.default}.
- * It runs after the scales, which say which axis holds categories.
+ * as `tooltipFormat` - the same default on every plot, {@link TooltipState.default} -
+ * and the order its rows read in, as `tooltipSort`: highest value first, by
+ * each row's own value (a stacked row's share, not its running total). It
+ * runs after the scales, which say which axis holds categories.
  */
 export declare class TooltipPhase<TState extends AnyAxisState> implements PhaseStage<TState> {
     readonly phase: "tooltip";

package/dist/phases/tooltip/TooltipPhase.js

@@ -1,10 +1,17 @@
 import { TooltipState } from '../../layout/tooltip/TooltipState.svelte';
+import { ValueLabels } from '../../layout/styles/ValueLabels';
 /**
  * The "tooltip" phase every axis-based plot shares: how a hovered row reads,
- * as `tooltipFormat` - the same default on every plot, {@link TooltipState.default}.
- * It runs after the scales, which say which axis holds categories.
+ * as `tooltipFormat` - the same default on every plot, {@link TooltipState.default} -
+ * and the order its rows read in, as `tooltipSort`: highest value first, by
+ * each row's own value (a stacked row's share, not its running total). It
+ * runs after the scales, which say which axis holds categories.
  */
 export class TooltipPhase {
     phase = 'tooltip';
-    run = (state) => ({ ...state, tooltipFormat: TooltipState.default(state) });
+    run = (state) => ({
+        ...state,
+        tooltipFormat: TooltipState.default(state),
+        tooltipSort: TooltipState.descending(ValueLabels.valueOf(state))
+    });
 }

package/dist/phases/transforms/ProcessedPositions.d.ts

@@ -0,0 +1,30 @@
+import type { AxisChannelName } from '../../types/layout/mapping';
+import type { ProcessedData, ProcessedRow } from '../../types/phases';
+/**
+ * Where the "transforms" phase's processed rows sit, read off its output
+ * (`state.processedData`) - by whichever channels the transforms left: a
+ * row's own value, a stack's `1`-`2` span, a bin's edges. Every later phase
+ * reads positions through it instead of telling those channels apart itself.
+ */
+export declare class ProcessedPositions {
+    /**
+     * Where a processed row sits: the top of its value (`y2`, or `y` - `x2`/`x`
+     * when `valueAxis` is `x`) and, on the other axis, its own position (or the
+     * middle of its `1`-`2` span, a bin's centre).
+     */
+    static of(processed: ProcessedData, valueAxis?: 'x' | 'y'): {
+        x: (row: ProcessedRow) => unknown;
+        y: (row: ProcessedRow) => unknown;
+    };
+    /**
+     * A processed row's span along `valueAxis`: from its `1` channel (a stack's
+     * bottom) or, with none, from `baseline`, to its top. `undefined` when the
+     * row has no value there. `stacked` tells a stack from plain values.
+     */
+    static span(processed: ProcessedData, valueAxis: 'x' | 'y', baseline?: number): {
+        stacked: boolean;
+        of: (row: ProcessedRow) => [number, number] | undefined;
+    };
+    /** Every value the processed rows sit at on one axis, through each of its channels. */
+    static values(processed: ProcessedData | undefined, axis: AxisChannelName): unknown[];
+}

package/dist/phases/transforms/ProcessedPositions.js

@@ -0,0 +1,74 @@
+import { resolveAccessor } from '../../utils/accessors';
+import { isGapValue } from '../../plots/utils/gaps';
+const POSITION_CHANNELS = {
+    x: ['x', 'x1', 'x2'],
+    y: ['y', 'y1', 'y2']
+};
+/**
+ * Where the "transforms" phase's processed rows sit, read off its output
+ * (`state.processedData`) - by whichever channels the transforms left: a
+ * row's own value, a stack's `1`-`2` span, a bin's edges. Every later phase
+ * reads positions through it instead of telling those channels apart itself.
+ */
+export class ProcessedPositions {
+    /**
+     * Where a processed row sits: the top of its value (`y2`, or `y` - `x2`/`x`
+     * when `valueAxis` is `x`) and, on the other axis, its own position (or the
+     * middle of its `1`-`2` span, a bin's centre).
+     */
+    static of(processed, valueAxis = 'y') {
+        const { channels } = processed;
+        const read = (channel) => resolveAccessor(channel);
+        const along = (axis) => {
+            const own = channels[axis];
+            const from = channels[`${axis}1`];
+            const to = channels[`${axis}2`];
+            if (axis === valueAxis) {
+                const top = to ?? own;
+                return top !== undefined ? read(top) : () => undefined;
+            }
+            if (own !== undefined)
+                return read(own);
+            if (from === undefined || to === undefined)
+                return () => undefined;
+            return (row) => (Number(read(from)(row)) + Number(read(to)(row))) / 2;
+        };
+        return { x: along('x'), y: along('y') };
+    }
+    /**
+     * A processed row's span along `valueAxis`: from its `1` channel (a stack's
+     * bottom) or, with none, from `baseline`, to its top. `undefined` when the
+     * row has no value there. `stacked` tells a stack from plain values.
+     */
+    static span(processed, valueAxis, baseline = 0) {
+        const from = processed.channels[`${valueAxis}1`];
+        const stacked = from !== undefined && processed.channels[`${valueAxis}2`] !== undefined;
+        const top = ProcessedPositions.of(processed, valueAxis)[valueAxis];
+        const bottom = stacked
+            ? resolveAccessor(from)
+            : () => baseline;
+        return {
+            stacked,
+            of: (row) => {
+                const end = top(row);
+                const start = bottom(row);
+                if (isGapValue(end) || isGapValue(start))
+                    return undefined;
+                const span = [Number(start), Number(end)];
+                return Number.isFinite(span[0]) && Number.isFinite(span[1]) ? span : undefined;
+            }
+        };
+    }
+    /** Every value the processed rows sit at on one axis, through each of its channels. */
+    static values(processed, axis) {
+        if (!processed)
+            return [];
+        return POSITION_CHANNELS[axis].flatMap((name) => {
+            const channel = processed.channels[name];
+            if (channel === undefined)
+                return [];
+            const read = resolveAccessor(channel);
+            return processed.data.map((row) => read(row));
+        });
+    }
+}

package/dist/phases/transforms/TransformsPhase.d.ts

@@ -1,7 +1,4 @@
-import type { Series } from '../../types/plots/data/common';
-import type { SegmentsConfig } from '../../types/plots/props';
-import type { VisualGroup } from '../../types/plots/segments/config';
-import type { PhaseStage, ProcessedData, ProcessedRow, TransformsStageOptions, TransformsStageState } from '../../types/phases';
+import type { PhaseStage, TransformsStageOptions, TransformsStageState } from '../../types/phases';
 /** The field each processed row carries its series name under, for its color, legend and labels. */
 export declare const SERIES_KEY = "__series";
 /** The field each processed row carries its series id under - the transforms' `z`, so a stack or bin keeps series apart. */
@@ -14,7 +11,8 @@ export declare const GAP_KIND = "__gapKind";
  * The "transforms" phase every axis-based plot shares: runs the plot-level
  * transforms once over every visible series' rows together, so a stack sees
  * every series and a bin keeps each series apart (both group by series), and
- * leaves the result in `state.processedData` for the plot's own marks. With
+ * leaves the result in `state.processedData` for the plot's own marks - and
+ * in `state.processedGroups`, split back into the visual groups they draw. With
  * facet panels, the transforms run once per panel's rows, so a stack never
  * combines two panels, and every row they return keeps its panel. A gap that
  * `styles.gaps` fills is read at its interpolated value, so it takes its place
@@ -23,42 +21,7 @@ export declare const GAP_KIND = "__gapKind";
 export declare class TransformsPhase<TState extends TransformsStageState, TCtx = unknown> implements PhaseStage<TState, TCtx> {
     #private;
     readonly phase: "transforms";
-    constructor(options?: TransformsStageOptions<TState, TCtx>);
+    /** `connect`: whether a series' visual segments bridge into each other, as the kind's "data" phase splits them. */
+    constructor(options?: TransformsStageOptions<TState, TCtx>, connect?: boolean);
     run: (state: TState, ctx: TCtx) => TState;
-    /**
-     * The processed rows split back into one group per visible series, each cut
-     * into its styled visual segments by `segments`, matched on the processed `x`.
-     * Each series reads its rows through its value axis: a stack's top, a bin's start.
-     */
-    static buildProcessedGroups<TStyle>(state: TransformsStageState & {
-        segments?: SegmentsConfig<TStyle>;
-    }, connect?: boolean): VisualGroup<Series<ProcessedRow>, TStyle>[];
-    /**
-     * The processed rows in their own order, split into runs of consecutive rows
-     * from the same visible series, each cut into its styled visual segments like
-     * {@link TransformsPhase.buildProcessedGroups}. Drawn in turn, the runs keep the rows' order
-     * across series, so a transform that reorders rows (`sort`, `reverse`,
-     * `shuffle`) decides which rows paint on top. Unreordered, each series is one run.
-     */
-    static buildProcessedRuns<TStyle>(state: TransformsStageState & {
-        segments?: SegmentsConfig<TStyle>;
-    }): VisualGroup<Series<ProcessedRow>, TStyle>[];
-    /**
-     * Where a processed row sits: the top of its value (`y2`, or `y` - `x2`/`x`
-     * when `valueAxis` is `x`) and, on the other axis, its own position (or the
-     * middle of its `1`-`2` span, a bin's centre).
-     */
-    static processedPosition(processed: ProcessedData, valueAxis?: 'x' | 'y'): {
-        x: (row: ProcessedRow) => unknown;
-        y: (row: ProcessedRow) => unknown;
-    };
-    /**
-     * A processed row's span along `valueAxis`: from its `1` channel (a stack's
-     * bottom) or, with none, from `baseline`, to its top. `undefined` when the
-     * row has no value there. `stacked` tells a stack from plain values.
-     */
-    static processedSpan(processed: ProcessedData, valueAxis: 'x' | 'y', baseline?: number): {
-        stacked: boolean;
-        of: (row: ProcessedRow) => [number, number] | undefined;
-    };
 }