@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/phases/statistics/Statistics.js

@@ -0,0 +1,156 @@
+import { MarkerChannels } from '../../markers/utils/MarkerChannels';
+import { getConfiguration } from '../../configuration/config.svelte';
+import { MovingAverageStatistic } from './methods/MovingAverageStatistic';
+import { DensityStatistic } from './methods/DensityStatistic';
+import { Density2dStatistic } from './methods/Density2dStatistic';
+import { BoxStatistic } from './methods/BoxStatistic';
+import { RegressionStatistic } from './methods/RegressionStatistic';
+import { BollingerStatistic } from './methods/BollingerStatistic';
+/**
+ * The statistics a plot or a marker asks for, as the markers they draw as.
+ * Each statistic type is a class of its own under `methods/`; the same
+ * {@link Statistics.buildMarker} serves plot-level and marker-level attachment.
+ */
+export class Statistics {
+    /**
+     * Builds one {@link StatisticConfig} over a data source into the marker it
+     * renders as - `regression`/`bollinger` construct their marker directly
+     * (svelteplot resolves the curve/band itself, at render time); the others
+     * compute their rows first.
+     */
+    static buildMarker(source, config) {
+        switch (config.type) {
+            case 'movingAverage':
+                return MovingAverageStatistic.build(source, config);
+            case 'density':
+                return DensityStatistic.build(source, config);
+            case 'density2d':
+                return Density2dStatistic.build(source, config);
+            case 'box':
+                return BoxStatistic.build(source, config);
+            case 'regression':
+                return RegressionStatistic.build(source, config);
+            case 'bollinger':
+                return BollingerStatistic.build(source, config);
+        }
+    }
+    /** Narrows a `Series`'s own `Accessor<T,AxisValue>` to a source's field-key-or-function shape - safe in practice, since a real row's field key is always a string. */
+    static #accessor(accessor
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        return accessor;
+    }
+    /**
+     * Resolves a plot's own top-level `statistics` prop against its already-built
+     * `Series<T>[]` (every kind has this before `mapping` runs - see
+     * `buildSeries`) into the derived markers to append alongside the plot's own
+     * default markers. Default (`series` unset, `pooled` unset): one statistic per
+     * series, using that series' own data/accessors/color, so a plot grouped by
+     * `color` gets its statistics grouped the same way. `pooled: true`: one
+     * statistic over every series combined (using the first series' own `x`/`y`,
+     * same convention the shared "mapping" stage uses for a shared
+     * accessor). Named `series`: one statistic per listed series.
+     */
+    static buildForPlot(args) {
+        const { series, statistics, colorFor } = args;
+        if (!statistics?.length || !series.length)
+            return [];
+        return statistics.flatMap((stat) => {
+            if (stat.pooled && stat.series === undefined) {
+                const pooled = series.flatMap((s) => s.data);
+                const source = {
+                    data: pooled,
+                    x: Statistics.#accessor(series[0].x),
+                    y: Statistics.#accessor(series[0].y),
+                    color: colorFor?.(series[0].name)
+                };
+                return [Statistics.buildMarker(source, stat)];
+            }
+            const names = stat.series ?? series.map((s) => s.name);
+            return names.flatMap((name) => {
+                const match = series.find((s) => s.name === name);
+                if (!match)
+                    return [];
+                const source = {
+                    data: match.data,
+                    x: Statistics.#accessor(match.x),
+                    y: Statistics.#accessor(match.y),
+                    color: colorFor?.(name)
+                };
+                return [Statistics.buildMarker(source, stat)];
+            });
+        });
+    }
+    /**
+     * Color a marker's own statistics inherit when its `color` channel is unset:
+     * its flat fill (or stroke), ignoring `none`/`transparent`. Covers both the
+     * plain `styles` keys and the dot-specific `dotFill`/`dotStroke`.
+     */
+    static #markerBaseColor(marker) {
+        const styles = marker.styles;
+        const pick = (key) => {
+            const value = styles?.[key];
+            return typeof value === 'string' && value !== 'none' && value !== 'transparent'
+                ? value
+                : undefined;
+        };
+        return pick('fill') ?? pick('dotFill') ?? pick('stroke') ?? pick('dotStroke');
+    }
+    /** Splits rows into one bucket per distinct `color` value, in first-seen order; rows without a value are skipped. */
+    static #groupRowsByColor(data, color) {
+        const valueOf = typeof color === 'function' ? color : (d) => d[color];
+        const buckets = new Map();
+        for (const row of data) {
+            const value = valueOf(row);
+            if (value == null)
+                continue;
+            const key = String(value);
+            const bucket = buckets.get(key);
+            if (bucket)
+                bucket.push(row);
+            else
+                buckets.set(key, [row]);
+        }
+        return [...buckets.values()];
+    }
+    /**
+     * Expands each marker's own `.statistics` into derived markers, spliced in
+     * right after their source so a derived marker always renders on top of it.
+     * `fallbackData` mirrors `GeometryLayout`'s own `marker.data ?? data` -
+     * applied here too since this runs *before* `GeometryLayout` ever sees these
+     * markers, on a marker that may omit its own `data` to reuse the host plot's.
+     * Generic over the caller's own marker union (e.g. `LinePlot`'s own
+     * `AxisBasedMarkersConfig`, which adds a `delta` kind on top of
+     * {@link AxisBasedMarkersConfig}) - untouched markers pass through as
+     * `TMarker`. Eligibility is structural, not a hardcoded list of `type`s: any
+     * marker mixing in `CommonMarkerConfig` (the "common" family) has `.x`/`.y`
+     * and an optional `.statistics`, so a `rule`/`hover`/`component` marker
+     * (neither field) always falls through the guard below untouched, and a
+     * future "common" marker kind is eligible with no extra bookkeeping here.
+     */
+    static expandMarkers(markers, fallbackData) {
+        return markers.flatMap((marker) => {
+            const statable = marker;
+            const { x, y } = statable;
+            // A literal position (number/Date) has no per-row values to derive statistics from.
+            const isAccessor = (v) => typeof v === 'string' || typeof v === 'function';
+            if (!statable.statistics?.length || !isAccessor(x) || !isAccessor(y))
+                return [marker];
+            const data = statable.data ?? fallbackData;
+            const accessors = { x: x, y: y };
+            // A marker's `color` channel groups it: each statistic is then derived per
+            // group, in that group's own color - same as a plot's statistics per series.
+            const colorFn = statable.color
+                ? MarkerChannels.buildFill(data, statable.color, statable.scales, getConfiguration())
+                : undefined;
+            const flatColor = Statistics.#markerBaseColor(statable);
+            const derived = statable.statistics.flatMap((stat) => {
+                if (!colorFn || !statable.color || stat.pooled) {
+                    return [Statistics.buildMarker({ data, ...accessors, color: flatColor }, stat)];
+                }
+                return Statistics.#groupRowsByColor(data, statable.color).flatMap((rows) => Statistics.buildMarker({ data: rows, ...accessors, color: colorFn(rows[0]) }, stat));
+            });
+            return [marker, ...derived];
+        });
+    }
+}

package/dist/phases/statistics/StatisticsPhase.d.ts

@@ -0,0 +1,18 @@
+import type { PhaseStage, StatisticsStageOptions, StatisticsStageState } from '../../types/phases';
+/**
+ * The "statistics" phase every axis-based plot shares: seeds `state.markers`
+ * with the plot-level `statistics` resolved against every series, followed by
+ * the author's own markers, each one inheriting the plot's grouping and color,
+ * drawing the plot's processed rows when it has none of its own (see
+ * `withProcessedRows`), running its own `transforms`, and expanding its own
+ * `.statistics` in place.
+ * Authored markers render on top of the plot-level ones. Later phases build
+ * onto `state.markers`. With facet panels, all of it resolves once per panel,
+ * over that panel's series and rows, and each marker is tagged with its panel.
+ */
+export declare class StatisticsPhase<TState extends StatisticsStageState> implements PhaseStage<TState> {
+    #private;
+    readonly phase: "statistics";
+    constructor(options?: StatisticsStageOptions<TState>);
+    run: (state: TState) => TState;
+}

package/dist/phases/statistics/StatisticsPhase.js

@@ -0,0 +1,67 @@
+import { AuthorMarkers } from './AuthorMarkers';
+import { Statistics } from './Statistics';
+import { PANEL_KEY, FacetPanels } from '../facet/FacetPanels';
+import { PlotAxes } from '../data/PlotAxes';
+/** Marker kinds that draw from a channel pair, so they take the plot's `x`/`y` when the author leaves one out. */
+const POSITIONED_KINDS = new Set(['line', 'area', 'dot']);
+/**
+ * The "statistics" phase every axis-based plot shares: seeds `state.markers`
+ * with the plot-level `statistics` resolved against every series, followed by
+ * the author's own markers, each one inheriting the plot's grouping and color,
+ * drawing the plot's processed rows when it has none of its own (see
+ * `withProcessedRows`), running its own `transforms`, and expanding its own
+ * `.statistics` in place.
+ * Authored markers render on top of the plot-level ones. Later phases build
+ * onto `state.markers`. With facet panels, all of it resolves once per panel,
+ * over that panel's series and rows, and each marker is tagged with its panel.
+ */
+export class StatisticsPhase {
+    phase = 'statistics';
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    run = (state) => {
+        if (!state.panels)
+            return { ...state, markers: this.#resolve(state) };
+        const markers = state.panels.flatMap((panel) => this.#resolve(FacetPanels.narrowToPanel(state, panel.key)).map((marker) => ({ ...marker, [PANEL_KEY]: panel.key })));
+        return { ...state, markers };
+    };
+    #resolve(state) {
+        const options = this.#options;
+        const { resolvedSeries = [], flat = [], colorForSeries, statistics, authorMarkers = [] } = state;
+        const { inheritGrouping = true, inheritPositions = false } = options;
+        const defaultColor = options.defaultColor
+            ? options.defaultColor(state)
+            : resolvedSeries[0] && colorForSeries?.(resolvedSeries[0].name);
+        const onProcessed = authorMarkers.map((marker) => AuthorMarkers.withProcessedRows(marker, state.processedData));
+        const positioned = inheritPositions
+            ? onProcessed.map((marker) => {
+                if (!POSITIONED_KINDS.has(marker.type))
+                    return marker;
+                const own = marker;
+                return {
+                    ...own,
+                    x: own.x ?? resolvedSeries[0]?.x ?? state.x,
+                    y: own.y ?? resolvedSeries[0]?.y ?? state.y
+                };
+            })
+            : onProcessed;
+        // A series setting no value of its own (a histogram's) measures its processed rows: its bins.
+        const valueAxis = PlotAxes.valueOf(state);
+        const measured = state.processedData && resolvedSeries.some((s) => s[valueAxis] === undefined)
+            ? (state.processedGroups ?? []).map((group) => group.series)
+            : resolvedSeries;
+        return [
+            ...Statistics.buildForPlot({ series: measured, statistics, colorFor: colorForSeries }),
+            ...Statistics.expandMarkers(AuthorMarkers.prepare(positioned, {
+                grouping: inheritGrouping ? state.grouping : undefined,
+                color: inheritGrouping ? state.color : undefined,
+                defaultColor,
+                flat,
+                resolvedSeries,
+                scopedGroups: state.scopedGroups
+            }), flat)
+        ];
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { StatisticConfig } from '../../../types/layout/statistics';
+import type { BollingerMarkerConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** Bollinger bands over the source, drawn as a `bollinger` marker (svelteplot computes them at render time). */
+export declare class BollingerStatistic {
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: Extract<StatisticConfig, {
+        type: 'bollinger';
+    }>): BollingerMarkerConfig;
+}

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

@@ -0,0 +1,18 @@
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** Bollinger bands over the source, drawn as a `bollinger` marker (svelteplot computes them at render time). */
+export class BollingerStatistic {
+    static build(source, config) {
+        return {
+            type: 'bollinger',
+            data: source.data,
+            x: source.x,
+            y: source.y,
+            n: config.n,
+            k: config.k,
+            styles: {
+                ...config.styles,
+                stroke: config.styles?.stroke ?? source.color ?? STATISTIC_FALLBACK_COLOR
+            }
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { StatisticConfig } from '../../../types/layout/statistics';
+import type { BoxMarkerConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** Box-and-whisker summary of the source, drawn as a `box` marker. */
+export declare class BoxStatistic {
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: Extract<StatisticConfig, {
+        type: 'box';
+    }>): BoxMarkerConfig;
+}

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

@@ -0,0 +1,18 @@
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** Box-and-whisker summary of the source, drawn as a `box` marker. */
+export class BoxStatistic {
+    static build(source, config) {
+        return {
+            type: 'box',
+            data: source.data,
+            x: source.x,
+            y: source.y,
+            sort: config.sort,
+            bar: { fill: source.color ?? STATISTIC_FALLBACK_COLOR, ...config.bar },
+            rule: config.rule,
+            dot: config.dot,
+            tickMedian: config.tickMedian,
+            tickMinMax: config.tickMinMax
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { StatisticConfig } from '../../../types/layout/statistics';
+import type { DensityMarkerConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** 2D kernel density over the source's `x` and `y`, drawn as a `density` marker. */
+export declare class Density2dStatistic {
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: Extract<StatisticConfig, {
+        type: 'density2d';
+    }>): DensityMarkerConfig;
+}

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

@@ -0,0 +1,18 @@
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** 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
+            }
+        };
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { DensityStatisticOptions } from '../../../types/layout/statistics';
+import type { AreaMarkerConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** 1D kernel density over the source's `x` values, drawn as an `area` marker. */
+export declare class DensityStatistic {
+    /**
+     * The `densityX` transform, wrapped into an `area` marker - the curve's own
+     * `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;
+}

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

@@ -0,0 +1,29 @@
+import { Transforms } from '../../transforms/Transforms';
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** 1D kernel density over the source's `x` values, drawn as an `area` marker. */
+export class DensityStatistic {
+    /**
+     * The `densityX` transform, wrapped into an `area` marker - the curve's own
+     * `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(source, config) {
+        const result = Transforms.run({
+            type: 'densityX',
+            data: source.data,
+            x: source.x,
+            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
+            }
+        };
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { MovingAverageStatisticOptions } from '../../../types/layout/statistics';
+import type { LineMarkerConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** Sliding-window reducer (mean/median/sum/...) drawn as a `line` marker. */
+export declare class MovingAverageStatistic {
+    /**
+     * The `windowY` transform, wrapped into our own `line` marker - svelteplot has
+     * 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;
+}

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

@@ -0,0 +1,30 @@
+import { Transforms } from '../../transforms/Transforms';
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** Sliding-window reducer (mean/median/sum/...) drawn as a `line` marker. */
+export class MovingAverageStatistic {
+    /**
+     * The `windowY` transform, wrapped into our own `line` marker - svelteplot has
+     * no dedicated mark for this (unlike `regression`/`bollinger`). `windowY`
+     * keeps one output row per input row, so `x` passes straight through.
+     */
+    static build(source, config) {
+        const result = Transforms.run({
+            type: 'windowY',
+            data: source.data,
+            x: source.x,
+            y: source.y,
+            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
+            }
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { StatisticConfig } from '../../../types/layout/statistics';
+import type { RegressionMarkerConfig } from '../../../types/markers/common';
+import { type StatisticSource } from '../../../types/phases/statistics/source';
+/** A regression curve over the source, drawn as a `regression` marker (svelteplot fits it at render time). */
+export declare class RegressionStatistic {
+    static build<T extends Record<string, unknown>>(source: StatisticSource<T>, config: Extract<StatisticConfig, {
+        type: 'regression';
+    }>): RegressionMarkerConfig;
+}

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

@@ -0,0 +1,21 @@
+import { STATISTIC_FALLBACK_COLOR } from '../../../types/phases/statistics/source';
+/** 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
+            }
+        };
+    }
+}

package/dist/phases/styles/StylesPhase.d.ts

@@ -0,0 +1,13 @@
+import type { AxisPlotState, AxisPlotCtx, PhaseStage } from '../../types/phases';
+import type { StylesStageOptions } from '../../types/phases/styles/phase';
+/**
+ * The shared "styles" phase: resolves the plot's `styles` against the plot
+ * kind's own defaults - its value labels (`valueLabels`), with how far they
+ * are expected to reach out, which its margins start from.
+ */
+export declare class StylesPhase<TState extends AxisPlotState<any, any, any, any>, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "styles";
+    constructor(options?: StylesStageOptions<TState>);
+    run: (state: TState, ctx: TCtx) => TState;
+}

package/dist/phases/styles/StylesPhase.js

@@ -0,0 +1,17 @@
+import { ValueLabels } from '../../layout/styles/ValueLabels';
+/**
+ * The shared "styles" phase: resolves the plot's `styles` against the plot
+ * kind's own defaults - its value labels (`valueLabels`), with how far they
+ * are expected to reach out, which its margins start from.
+ */
+export class StylesPhase {
+    phase = 'styles';
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    run = (state, ctx) => ({
+        ...state,
+        valueLabels: ValueLabels.build(state.values, ctx.cfg, this.#options.values ?? {}, state)
+    });
+}

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

@@ -0,0 +1,14 @@
+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} -
+ * 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";
+    run: (state: TState) => TState;
+}
+export {};

package/dist/phases/tooltip/TooltipPhase.js

@@ -0,0 +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} -
+ * 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),
+        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 '../../plots/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));
+        });
+    }
+}