@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/phases/Pipeline.js

@@ -0,0 +1,226 @@
+import { FacetPhase } from './facet/FacetPhase';
+import { DataPhase } from './data/DataPhase';
+import { MappingPhase } from './mapping/MappingPhase';
+import { TransformsPhase } from './transforms/TransformsPhase';
+import { StatisticsPhase } from './statistics/StatisticsPhase';
+import { ScalesPhase } from './scales/ScalesPhase';
+import { SharedScalesPhase } from './sharedScales/SharedScalesPhase';
+import { StylesPhase } from './styles/StylesPhase';
+import { MarkersPhase } from './markers/MarkersPhase';
+import { TooltipPhase } from './tooltip/TooltipPhase';
+import { HoverPhase } from './hover/HoverPhase';
+import { PlotInteraction } from '../layout/interaction/PlotInteraction.svelte';
+import { DEFAULT_CONFIG } from '../configuration/config.svelte';
+/**
+ * A plot's pipeline: its stages, one per phase, in {@link Pipeline.ORDER},
+ * and what its plot needs before any of them run - its hover strategy and
+ * timeline defaults. Every core of the plot runs it ({@link run}); with a
+ * facet, the plot first runs its data phases once over every panel
+ * ({@link runData}), and each panel's core runs only the rest.
+ *
+ * Stages declared out of phase order still run in it - with a warning, once,
+ * since the declared order would otherwise read as the one that runs.
+ */
+export class Pipeline {
+    /**
+     * The phases that work on the plot's rows - everything before its scales,
+     * plus the domains its slices share - in order. They run once over every
+     * facet panel; the rest depend on each panel's own box.
+     */
+    static DATA_PHASES = [
+        'facet',
+        'data',
+        'mapping',
+        'transforms',
+        'statistics',
+        'sharedScales'
+    ];
+    /** Every {@link PlotPhase}, in the order they run: the data phases, then each panel's own. */
+    static ORDER = [
+        ...Pipeline.DATA_PHASES,
+        'scales',
+        'styles',
+        'markers',
+        'coordinates',
+        'tooltip',
+        'hover'
+    ];
+    // Every axis kind's pipeline, built once per kind object.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static #axisKinds = new WeakMap();
+    stages;
+    #options;
+    #data;
+    #panel;
+    constructor(stages, options = {}) {
+        const rank = (phase) => Pipeline.ORDER.indexOf(phase);
+        const ordered = [...stages].sort((a, b) => rank(a.phase) - rank(b.phase));
+        if (ordered.some((stage, i) => stage !== stages[i])) {
+            console.warn(`Pipeline: stages declared as [${stages.map((s) => s.phase).join(', ')}] run in phase order: [${ordered.map((s) => s.phase).join(', ')}].`);
+        }
+        this.stages = ordered;
+        this.#options = options;
+    }
+    /**
+     * An axis-based plot kind's pipeline: the shared stages, each set up with
+     * the kind's own options - its marks and value labels among them - started
+     * from a core's props. Built once per kind object.
+     */
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    static ofAxisKind(kind) {
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+        const cached = Pipeline.#axisKinds.get(kind);
+        if (cached)
+            return cached;
+        const scales = new ScalesPhase(kind.scales);
+        const pipeline = new Pipeline([
+            new FacetPhase(),
+            new DataPhase(kind.data),
+            new MappingPhase(kind.mapping),
+            new TransformsPhase(kind.transforms),
+            new StatisticsPhase(kind.statistics),
+            new SharedScalesPhase(kind.sharedScales, scales),
+            scales,
+            new StylesPhase(kind.styles),
+            new MarkersPhase(kind.markers),
+            new TooltipPhase(),
+            new HoverPhase(kind.hover)
+        ], {
+            seed: (props, rows) => Pipeline.#axisSeed(props, rows),
+            hoverStrategy: kind.hover?.strategy,
+            timeline: kind.timeline
+        });
+        Pipeline.#axisKinds.set(kind, pipeline);
+        return pipeline;
+    }
+    /** A plot's pipeline from what its kind gives: its axis-kind defaults, or a pipeline of its own. */
+    static of(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    defaults
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        return defaults instanceof Pipeline ? defaults : Pipeline.ofAxisKind(defaults);
+    }
+    /** The stage of `phase`, if the pipeline has one. */
+    stage(phase) {
+        return this.stages.find((stage) => stage.phase === phase);
+    }
+    /**
+     * A core's run: every stage over the state its `input` (an axis core's
+     * props) seeds - or, given `panelState` (one facet panel's part of
+     * {@link runData}), only the stages after the data phases, over that state
+     * with the input's own props (its box, margins and scales) on top.
+     */
+    run = (input, ctx, panelState) => {
+        const seed = this.#seed(input);
+        if (!panelState)
+            return Pipeline.#through(this.stages, seed, ctx);
+        this.#panel ??= this.stages.filter((stage) => !Pipeline.DATA_PHASES.includes(stage.phase));
+        return Pipeline.#through(this.#panel, { ...panelState, ...seed }, ctx);
+    };
+    /** Whether the pipeline has data phases to run once over every facet panel ({@link runData}). */
+    get facets() {
+        return this.stage('facet') !== undefined;
+    }
+    /**
+     * The data phases over `rows`, seeded from a core's `props`, with the
+     * plot's `facet`: one run that every facet panel then reads its part of,
+     * including the domains its slices share (its "sharedScales" phase).
+     */
+    runData(props, rows, facet, legendInteraction, cfg) {
+        this.#data ??= this.stages.filter((stage) => Pipeline.DATA_PHASES.includes(stage.phase));
+        const seed = { ...this.#seed(props, rows), facet };
+        return Pipeline.#through(this.#data, seed, Pipeline.#ctxFor(cfg, legendInteraction));
+    }
+    /**
+     * The plot's hover strategy when neither its `tooltip` nor a hover marker
+     * sets one, given its props: the kind's own, or the one its axes ask for,
+     * read after the "data" phase tells them apart.
+     */
+    hoverStrategy(props, cfg = DEFAULT_CONFIG) {
+        const fixed = this.#options.hoverStrategy;
+        if (fixed !== undefined)
+            return fixed;
+        const upToData = this.stages.filter((s) => s.phase === 'data');
+        const state = Pipeline.#through(upToData, this.#seed(props), Pipeline.#ctxFor(cfg, null));
+        return HoverPhase.strategyOf(state);
+    }
+    /** The plot's default `timeline.filterMode`. */
+    get filterMode() {
+        return this.#options.timeline?.filterMode;
+    }
+    /**
+     * How the plot tweens its timeline unless `timeline.interpolate` says
+     * otherwise, from the channels its "mapping" phase resolves over
+     * `props.data`: rows matched by the values of whichever `key` channels are
+     * set, `value` tweened. `undefined` when its kind tweens nothing.
+     */
+    interpolation(props, cfg) {
+        const channels = this.#options.timeline?.interpolation;
+        if (!channels || !props.data)
+            return undefined;
+        const upToMapping = this.stages.filter((s) => s.phase === 'data' || s.phase === 'mapping');
+        // Without a legend: the channels read the same whatever it turns off.
+        const state = Pipeline.#through(upToMapping, this.#seed(props), Pipeline.#ctxFor(cfg, null));
+        const channel = (ref) => {
+            const name = ref === 'value' || ref === 'category' ? state.axes?.[ref] : ref;
+            if (name === undefined)
+                return undefined;
+            const c = state.channels?.[name];
+            return typeof c === 'object' ? c : undefined;
+        };
+        const value = channel(channels.value)?.source;
+        if (value === undefined)
+            return undefined;
+        const keys = channels.key
+            .map(channel)
+            .filter((c) => c?.source !== undefined);
+        const key = keys.length > 1
+            ? (row) => keys.map((c) => String(c.accessor(row))).join('::')
+            : keys[0]?.source;
+        return { value: value, key };
+    }
+    /** The state a run starts from. */
+    #seed(input, rows) {
+        return this.#options.seed ? this.#options.seed(input, rows) : input;
+    }
+    /** `stages` over `state`, in order. */
+    static #through(stages, state, ctx) {
+        return stages.reduce((acc, stage) => stage.run(acc, ctx), state);
+    }
+    /** The context a plot-level run reads, outside any core: the configuration and the legend. */
+    static #ctxFor(cfg, legendInteraction) {
+        const interaction = new PlotInteraction(() => cfg, { legend: legendInteraction });
+        return { cfg, interaction };
+    }
+    /**
+     * The state an axis plot's pipeline starts from: its core props, drawing
+     * `rows`. Every kind starts from the same shape; a prop its phases don't
+     * read is simply carried along.
+     */
+    static #axisSeed(props, rows = props.data) {
+        return {
+            series: props.series,
+            data: rows,
+            x: props.x,
+            y: props.y,
+            grouping: props.grouping,
+            color: props.color,
+            opacity: props.opacity,
+            r: props.r,
+            symbol: props.symbol,
+            segments: props.segments ?? {},
+            styles: props.styles,
+            gaps: props.styles?.gaps,
+            values: props.styles?.values,
+            scales: (props.scales ?? {}),
+            width: props.width,
+            height: props.height,
+            margins: props.margins,
+            tooltip: props.tooltip,
+            authorMarkers: props.markers ?? [],
+            statistics: props.statistics ?? [],
+            transforms: props.transforms ?? []
+        };
+    }
+}

package/dist/phases/data/DataPhase.d.ts

@@ -0,0 +1,25 @@
+import type { Accessor } from '../../types/plots/data/common';
+import type { AxisPlotState, AxisPlotCtx, DataStageOptions, PhaseStage } from '../../types/phases';
+type AnyAxisState = AxisPlotState<any, any, any, any>;
+/**
+ * The "data" phase every axis-based plot shares: its series (from `series`,
+ * or flat rows split by {@link DataPhase.buildGrouping}), what each position
+ * channel is and which way the plot runs ({@link PlotAxes}), each series'
+ * color, the series a legend omits dropped, each series cut into its styled
+ * visual segments, and - for a discrete mark - the values its gaps fill in.
+ * Colors and axes come from every series, before any is omitted or split by
+ * facet panel, so they stay put and every panel agrees.
+ */
+export declare class DataPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "data";
+    constructor(options?: DataStageOptions<TState, TCtx>);
+    run: (state: TState, ctx: TCtx) => TState;
+    /**
+     * The key a plot's rows split into series by: its `grouping`, or its `color`
+     * when that names categories. A numeric `color` is a continuous value (a
+     * heatmap's cells), so it colors rows without grouping them.
+     */
+    static buildGrouping(state: Pick<AnyAxisState, 'grouping' | 'color' | 'data'>): Accessor<any, unknown> | undefined;
+}
+export {};

package/dist/phases/data/DataPhase.js

@@ -0,0 +1,82 @@
+import { buildSeries } from '../../utils/grouping';
+import { resolveColorScale } from '../../utils/color';
+import { resolveAccessor } from '../../plots/utils/accessors';
+import { buildGroupedSeries, buildScopedMarkerGroups } from '../../plots/utils/segments';
+import { buildGapFillMaps, isGapValue } from '../../plots/utils/gaps';
+import { FacetPhase } from '../facet/FacetPhase';
+import { PlotAxes } from './PlotAxes';
+/**
+ * The "data" phase every axis-based plot shares: its series (from `series`,
+ * or flat rows split by {@link DataPhase.buildGrouping}), what each position
+ * channel is and which way the plot runs ({@link PlotAxes}), each series'
+ * color, the series a legend omits dropped, each series cut into its styled
+ * visual segments, and - for a discrete mark - the values its gaps fill in.
+ * Colors and axes come from every series, before any is omitted or split by
+ * facet panel, so they stay put and every panel agrees.
+ */
+export class DataPhase {
+    phase = 'data';
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    run = (state, ctx) => {
+        const options = this.#options;
+        const { series, data, segments, scales } = state;
+        const { connect = true, color: segmentColor } = options.segments ?? {};
+        const built = series ?? buildSeries(data ?? [], state.x, state.y, DataPhase.buildGrouping(state));
+        const fullSeries = options.orderSeries ? options.orderSeries(built, state) : built;
+        const axes = PlotAxes.build({
+            series: fullSeries,
+            scales,
+            given: { x: state.x !== undefined, y: state.y !== undefined },
+            discrete: options.discreteAxes
+        });
+        const colorForSeries = resolveColorScale(scales.color, (options.colorOrder ? options.colorOrder(fullSeries) : fullSeries).map((s) => s.name), ctx.cfg.palette);
+        const panelSeries = state.panels && state.panelOf && !series
+            ? FacetPhase.splitSeriesByPanel(fullSeries, state.panels, state.panelOf)
+            : fullSeries;
+        const resolvedSeries = ctx.interaction?.legend?.withoutOmitted(panelSeries) ?? panelSeries;
+        const groupedSeries = buildGroupedSeries(resolvedSeries, segments, connect);
+        const scopedGroups = buildScopedMarkerGroups({
+            groupedSeries,
+            segments,
+            colorFor: (s) => colorForSeries(s.name),
+            segmentColorFor: (style, defaultColor) => segmentColor?.(style) ?? defaultColor
+        });
+        // A continuous mark bridges its gaps instead (see `buildGapMarkers`).
+        const gapFillMaps = connect
+            ? undefined
+            : buildGapFillMaps(resolvedSeries, state.gaps, axes.value);
+        const next = {
+            ...state,
+            axes,
+            resolvedSeries,
+            allSeriesNames: fullSeries.map((s) => s.name),
+            groupedSeries,
+            flat: resolvedSeries.flatMap((s) => s.data),
+            scopedGroups,
+            colorForSeries,
+            ...(gapFillMaps ? { gapFillMaps } : {})
+        };
+        return options.extend ? options.extend(next, ctx) : next;
+    };
+    /**
+     * The key a plot's rows split into series by: its `grouping`, or its `color`
+     * when that names categories. A numeric `color` is a continuous value (a
+     * heatmap's cells), so it colors rows without grouping them.
+     */
+    static buildGrouping(state
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        if (state.grouping !== undefined)
+            return state.grouping;
+        const color = state.color;
+        if (color === undefined || !state.data)
+            return color;
+        const read = resolveAccessor(color);
+        const values = state.data.map(read).filter((v) => !isGapValue(v));
+        const continuous = values.length > 0 && values.every((v) => typeof v === 'number');
+        return continuous ? undefined : color;
+    }
+}

package/dist/phases/data/PlotAxes.d.ts

@@ -0,0 +1,75 @@
+import type { AxisChannelName } from '../../types/layout/mapping';
+import type { AxisRef, DiscreteAxesCount, InferredAxis, Orientation } from '../../types/phases/data/axes';
+/** What {@link PlotAxes.build} reads: the series' own channels and the author's axis scales. */
+type PlotAxesSource = {
+    series: {
+        x?: unknown;
+        y?: unknown;
+        data: unknown[];
+    }[];
+    scales?: {
+        x?: {
+            type?: string;
+        };
+        y?: {
+            type?: string;
+        };
+    };
+    /** Channels the plot sets itself, which count as active even when no series carries them (an empty one). */
+    given?: Partial<Record<AxisChannelName, boolean>>;
+    /** How many axes the plot kind lays out as categories. */
+    discrete?: DiscreteAxesCount;
+};
+/**
+ * What a plot's position channels are, read once from its series: which
+ * channels the author set, how each axis lays out its values, which one holds
+ * the categories and which the measured values, and so which way the marks
+ * run. Every later phase reads it instead of telling axes apart on its own.
+ */
+export declare class PlotAxes {
+    #private;
+    readonly x?: InferredAxis;
+    readonly y?: InferredAxis;
+    /** The axis whose values the plot sorts into, when it has exactly one. */
+    readonly category?: AxisChannelName;
+    /** The axis the plot measures along. */
+    readonly value?: AxisChannelName;
+    readonly orientation: Orientation;
+    /** The axes the plot kind lays out as bands: its category axes, none for a kind that needs none. */
+    readonly bands: readonly AxisChannelName[];
+    constructor(fields: {
+        x?: InferredAxis;
+        y?: InferredAxis;
+        category?: AxisChannelName;
+        value?: AxisChannelName;
+        orientation: Orientation;
+        bands?: readonly AxisChannelName[];
+    });
+    get isHorizontal(): boolean;
+    /** The axis `ref` names: itself, or whichever axis plays that role. */
+    resolve(ref: AxisRef): AxisChannelName | undefined;
+    /** Whether `axis` lays out distinct categories. */
+    isDiscrete(axis: AxisChannelName): boolean;
+    /** The axis a plot without inferred axes measures along: `y`. */
+    static valueOf(state: {
+        axes?: PlotAxes;
+    }): AxisChannelName;
+    /** The axis a plot without inferred axes sorts into: `x`. */
+    static categoryOf(state: {
+        axes?: PlotAxes;
+    }): AxisChannelName;
+    /** The other position axis. */
+    static other(axis: AxisChannelName): AxisChannelName;
+    /**
+     * A plot's axes from its series and `scales`. An author's `scales.*.type`
+     * always wins; otherwise each axis' values decide (strings are categories,
+     * dates are time, numbers a range). A kind needing more category axes than
+     * that gives promotes the likeliest ones - time first, then `x` before `y` -
+     * so bars over years stay bars. With one category axis, the other is the
+     * value, and the plot is horizontal when the categories run along `y`; a
+     * plot with a single channel (a histogram) is horizontal when that channel
+     * is `y`.
+     */
+    static build({ series, scales, given, discrete }: PlotAxesSource): PlotAxes;
+}
+export {};

package/dist/phases/data/PlotAxes.js

@@ -0,0 +1,151 @@
+import { resolveAccessor } from '../../plots/utils/accessors';
+import { isGapValue } from '../../plots/utils/gaps';
+import { DISCRETE_SCALE_TYPES, TEMPORAL_SCALE_TYPES } from '../../types/layout/scales';
+const AXES = ['x', 'y'];
+const DISCRETE_TYPES = new Set(DISCRETE_SCALE_TYPES);
+const TEMPORAL_TYPES = new Set(TEMPORAL_SCALE_TYPES);
+/**
+ * What a plot's position channels are, read once from its series: which
+ * channels the author set, how each axis lays out its values, which one holds
+ * the categories and which the measured values, and so which way the marks
+ * run. Every later phase reads it instead of telling axes apart on its own.
+ */
+export class PlotAxes {
+    x;
+    y;
+    /** The axis whose values the plot sorts into, when it has exactly one. */
+    category;
+    /** The axis the plot measures along. */
+    value;
+    orientation;
+    /** The axes the plot kind lays out as bands: its category axes, none for a kind that needs none. */
+    bands;
+    constructor(fields) {
+        this.x = fields.x;
+        this.y = fields.y;
+        this.category = fields.category;
+        this.value = fields.value;
+        this.orientation = fields.orientation;
+        this.bands = fields.bands ?? [];
+    }
+    get isHorizontal() {
+        return this.orientation === 'horizontal';
+    }
+    /** The axis `ref` names: itself, or whichever axis plays that role. */
+    resolve(ref) {
+        return ref === 'x' || ref === 'y' ? ref : this[ref];
+    }
+    /** Whether `axis` lays out distinct categories. */
+    isDiscrete(axis) {
+        return this[axis]?.kind === 'discrete';
+    }
+    /** The axis a plot without inferred axes measures along: `y`. */
+    static valueOf(state) {
+        return state.axes?.value ?? 'y';
+    }
+    /** The axis a plot without inferred axes sorts into: `x`. */
+    static categoryOf(state) {
+        return state.axes?.category ?? 'x';
+    }
+    /** The other position axis. */
+    static other(axis) {
+        return axis === 'x' ? 'y' : 'x';
+    }
+    /**
+     * A plot's axes from its series and `scales`. An author's `scales.*.type`
+     * always wins; otherwise each axis' values decide (strings are categories,
+     * dates are time, numbers a range). A kind needing more category axes than
+     * that gives promotes the likeliest ones - time first, then `x` before `y` -
+     * so bars over years stay bars. With one category axis, the other is the
+     * value, and the plot is horizontal when the categories run along `y`; a
+     * plot with a single channel (a histogram) is horizontal when that channel
+     * is `y`.
+     */
+    static build({ series, scales, given, discrete = 0 }) {
+        const axes = {};
+        for (const axis of AXES) {
+            if (!given?.[axis] && !series.some((s) => s[axis] !== undefined))
+                continue;
+            const explicit = PlotAxes.#kindOfType(scales?.[axis]?.type);
+            axes[axis] = explicit
+                ? { kind: explicit, origin: 'explicit' }
+                : { kind: PlotAxes.#kindOfValues(series, axis), origin: 'inferred' };
+        }
+        const active = AXES.filter((axis) => axes[axis] !== undefined);
+        const discreteAxes = () => active.filter((axis) => axes[axis].kind === 'discrete');
+        const candidates = active
+            .filter((axis) => axes[axis].kind !== 'discrete' && axes[axis].origin !== 'explicit')
+            .sort((a, b) => Number(axes[b].kind === 'temporal') - Number(axes[a].kind === 'temporal'));
+        while (discreteAxes().length < discrete && candidates.length) {
+            axes[candidates.shift()] = { kind: 'discrete', origin: 'promoted' };
+        }
+        const found = discreteAxes();
+        const fields = { x: axes.x, y: axes.y };
+        if (discrete === 2)
+            return new PlotAxes({ ...fields, orientation: 'vertical', bands: active });
+        if (discrete === 1) {
+            if (found.length > 1) {
+                console.warn('Plot: both axes lay out categories, but this plot measures along one of them - ' +
+                    'mark the value axis with a numeric scales type or pass numeric values. Defaulting the categories to x.');
+            }
+            const category = found.length === 1 ? found[0] : 'x';
+            return new PlotAxes({
+                ...fields,
+                category,
+                value: PlotAxes.other(category),
+                orientation: category === 'y' ? 'horizontal' : 'vertical',
+                bands: [category]
+            });
+        }
+        if (active.length === 1) {
+            const [only] = active;
+            return new PlotAxes({
+                ...fields,
+                value: PlotAxes.other(only),
+                orientation: only === 'y' ? 'horizontal' : 'vertical'
+            });
+        }
+        // Two free axes: horizontal only when `y` holds positions (categories or time) and `x` a range.
+        const horizontal = axes.x?.kind === 'continuous' && axes.y !== undefined && axes.y.kind !== 'continuous';
+        const value = horizontal ? 'x' : 'y';
+        return new PlotAxes({
+            ...fields,
+            value,
+            category: found.length === 1 ? found[0] : undefined,
+            orientation: horizontal ? 'horizontal' : 'vertical'
+        });
+    }
+    /** The kind an author's scale type sets, or `undefined` when it leaves it to the values. */
+    static #kindOfType(type) {
+        if (type === undefined || type === 'auto')
+            return undefined;
+        if (DISCRETE_TYPES.has(type))
+            return 'discrete';
+        if (TEMPORAL_TYPES.has(type))
+            return 'temporal';
+        return 'continuous';
+    }
+    /** The kind one axis' values read as: any non-number makes it discrete, all dates temporal. */
+    static #kindOfValues(series, axis) {
+        let dates = 0;
+        let numbers = 0;
+        for (const s of series) {
+            const accessor = s[axis];
+            if (accessor === undefined)
+                continue;
+            const read = resolveAccessor(accessor);
+            for (const row of s.data) {
+                const v = read(row);
+                if (isGapValue(v) || v === '')
+                    continue;
+                if (typeof v === 'number')
+                    numbers++;
+                else if (v instanceof Date)
+                    dates++;
+                else
+                    return 'discrete';
+            }
+        }
+        return dates > 0 && numbers === 0 ? 'temporal' : 'continuous';
+    }
+}

package/dist/phases/facet/FacetPhase.d.ts

@@ -0,0 +1,52 @@
+import type { Series } from '../../types/plots/data/common';
+import type { FacetPanel, FacetStageState, PhaseStage } from '../../types/phases';
+/** The state fields narrowing to some panels filters. */
+type NarrowableState = FacetStageState & {
+    resolvedSeries?: Series<Record<string, unknown>>[];
+    flat?: unknown[];
+    scopedGroups?: {
+        panel?: string;
+    }[];
+    groupedSeries?: {
+        series: {
+            panel?: string;
+        };
+    }[];
+    processedData?: {
+        data: Record<string | symbol, unknown>[];
+    };
+};
+/** The field a processed row carries its facet panel under. */
+export declare const PANEL_KEY = "__panel";
+/**
+ * The "facet" phase: the panels the plot's `facet` lays its rows out in, and
+ * which panel each row belongs to. It runs first, so the "data" phase builds
+ * every series already split by panel. A plot drawn from pre-built `series`
+ * has no rows to split, so its facet is ignored.
+ */
+export declare class FacetPhase<TState extends FacetStageState> implements PhaseStage<TState> {
+    readonly phase: "facet";
+    run: (state: TState) => TState;
+    /** The id of a series' part in one facet panel. */
+    static buildPanelSeriesId(panel: string, name: string): string;
+    /**
+     * Each series split into one per facet panel, panel by panel: the same
+     * `name` (and so the same color and legend entry), its own `id` and `panel`,
+     * and only that panel's rows. A series with no rows in a panel has no part there.
+     */
+    static splitSeriesByPanel<S extends Series<Record<string, unknown>>>(series: S[], panels: FacetPanel[], panelOf: NonNullable<FacetStageState['panelOf']>): S[];
+    /** A state narrowed to one panel's series, rows and processed rows. */
+    static narrowToPanel<TState extends NarrowableState>(state: TState, panel: string): TState;
+    /** A state narrowed to some panels' series, rows and processed rows. */
+    static narrowToPanels<TState extends NarrowableState>(state: TState, panels: readonly string[]): TState;
+    /**
+     * One facet panel's part of a run of the data phases over every panel: its
+     * series, rows, processed rows and markers, without the facet itself, ready
+     * for the phases each panel runs on its own.
+     */
+    static buildPanelState<TState extends FacetStageState & {
+        resolvedSeries?: Series<Record<string, unknown>>[];
+        markers?: object[];
+    }>(state: TState, panel: string): Omit<TState, 'facet' | 'panels' | 'panelOf'>;
+}
+export {};