@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/phases/sharedScales/SharedScalesPhase.d.ts

@@ -0,0 +1,58 @@
+import { ScalesPhase } from '../scales/ScalesPhase';
+import type { PlotAxes } from '../data/PlotAxes';
+import type { AxisChannelName } from '../../types/layout/mapping';
+import type { FacetStageState, PhaseStage, ProcessedData, SharedAxisValues, SharedScalesOptions } from '../../types/phases';
+import type { AxisBasedScalesConfig } from '../../types/layout/scales';
+/** One channel's shared scale: its domain, and whether svelteplot may still round it. */
+type SharedScale = {
+    domain: unknown[];
+    nice?: boolean;
+} | undefined;
+/** The state the "shared scales" step reads: a data run's output, over every panel. */
+type SharedScalesState = FacetStageState & {
+    axes?: PlotAxes;
+    processedData?: ProcessedData;
+    markers?: object[];
+    scales?: Partial<Record<AxisChannelName, {
+        niceTolerance?: number;
+    }>>;
+    sharedScales?: Record<string, AxisBasedScalesConfig<never>>;
+};
+/**
+ * The "sharedScales" phase, the last of the data phases: the figure-wide part
+ * of scales - the domains every slice shares, as `sharedScales` keyed by facet panel
+ * (`''` for the whole run without a facet). Each shared x/y domain spans
+ * where the sharing panels' rows and markers sit (as bands, or from zero, as
+ * the kind's axes and "scales" say), grouped by `facet.scales`; each `fromScalesPhase` channel
+ * takes the domain the kind's own "scales" phase sets over
+ * those panels. A panel's own "scales" phase only sees its rows, so this
+ * can't happen there. Without options, a kind still shares its domains: it just
+ * has no bands and nothing that starts from zero.
+ */
+export declare class SharedScalesPhase<TState extends SharedScalesState, TCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "sharedScales";
+    constructor(options: SharedScalesOptions | undefined, scales?: ScalesPhase<any, any>);
+    run: (state: TState, ctx: TCtx) => TState;
+    /**
+     * One axis' domain over some slices: sorted values on a band axis, `[min, max]`
+     * otherwise, or `undefined`. A numeric extent is niced here, once, so every
+     * slice gets the exact same domain - svelteplot's own `nice` rounds by a tick
+     * count derived from each panel's height, which over-rounds short panels and
+     * can disagree between panels of different heights.
+     */
+    static buildSharedAxisScale(slices: SharedAxisValues[], axis: AxisChannelName, niceTolerance?: number): SharedScale;
+    /**
+     * Where one panel's rows and markers sit on each axis, read off a pipeline
+     * run over every panel - or, without a `panel`, where all of them sit.
+     */
+    static buildPanelAxisValues(state: {
+        processedData?: ProcessedData;
+        markers?: object[];
+    }, panel: string | undefined, layout?: {
+        band?: AxisChannelName[];
+        zero?: AxisChannelName[];
+        dataOrder?: boolean;
+    }): SharedAxisValues;
+}
+export {};

package/dist/phases/sharedScales/SharedScalesPhase.js

@@ -0,0 +1,171 @@
+import { ProcessedPositions } from '../transforms/ProcessedPositions';
+import { NiceTicks } from '../../layout/scales/NiceTicks';
+import { ScalesPhase } from '../scales/ScalesPhase';
+import { Pipeline } from '../Pipeline';
+import { PANEL_KEY, FacetPanels } from '../facet/FacetPanels';
+import { isFacetWrap } from '../../layout/facet/config';
+import { MarkerAxisValues } from '../scales/MarkerAxisValues';
+/** Natural ascending order, as svelteplot sorts a band domain. */
+function ascending(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * The "sharedScales" phase, the last of the data phases: the figure-wide part
+ * of scales - the domains every slice shares, as `sharedScales` keyed by facet panel
+ * (`''` for the whole run without a facet). Each shared x/y domain spans
+ * where the sharing panels' rows and markers sit (as bands, or from zero, as
+ * the kind's axes and "scales" say), grouped by `facet.scales`; each `fromScalesPhase` channel
+ * takes the domain the kind's own "scales" phase sets over
+ * those panels. A panel's own "scales" phase only sees its rows, so this
+ * can't happen there. Without options, a kind still shares its domains: it just
+ * has no bands and nothing that starts from zero.
+ */
+export class SharedScalesPhase {
+    phase = 'sharedScales';
+    #options;
+    #kindScales;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    #scales;
+    constructor(options, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    scales = new ScalesPhase()) {
+        this.#options = options;
+        this.#scales = scales;
+        this.#kindScales = new Pipeline([scales]);
+    }
+    run = (state, ctx) => {
+        const facet = state.facet;
+        const panels = facet ? (state.panels ?? []) : [];
+        // A symmetric axis has no domain but the one the kind's "scales" phase gives it.
+        const fromPhase = new Set([
+            ...(this.#options?.fromScalesPhase ?? []),
+            ...this.#scales.symmetricAxes(state)
+        ]);
+        const layout = {
+            band: [...(state.axes?.bands ?? [])],
+            zero: this.#scales.zeroAxes(state),
+            dataOrder: this.#scales.keepsDataOrder
+        };
+        const channels = fromPhase.has('color') ? ['x', 'y', 'color'] : ['x', 'y'];
+        /** The channel's domain over `members` panels, or every row without them. */
+        const domainOver = (channel, members) => {
+            if (fromPhase.has(channel)) {
+                const scoped = members ? FacetPanels.narrowToPanels(state, members) : state;
+                const scales = this.#kindScales.run(scoped, ctx).scales;
+                const domain = scales?.[channel]?.domain;
+                return domain === undefined ? undefined : { domain };
+            }
+            if (channel === 'color')
+                return undefined;
+            const values = members
+                ? members.map((panel) => SharedScalesPhase.buildPanelAxisValues(state, panel, layout))
+                : [SharedScalesPhase.buildPanelAxisValues(state, undefined, layout)];
+            return SharedScalesPhase.buildSharedAxisScale(values, channel, state.scales?.[channel]?.niceTolerance);
+        };
+        const cache = new Map();
+        const scalesOf = (place) => {
+            const out = {};
+            for (const channel of channels) {
+                const line = SharedScalesPhase.#sharingLine(facet, channel);
+                if (!line)
+                    continue;
+                const key = line === 'all' ? '' : (place?.[line] ?? '');
+                const cacheKey = `${channel}\u0000${key}`;
+                if (!cache.has(cacheKey)) {
+                    const members = panels.length
+                        ? panels.filter((p) => line === 'all' || p[line] === key).map((p) => p.key)
+                        : undefined;
+                    // Every panel sharing a phase-derived domain is the whole run, as it was built.
+                    const whole = line === 'all' && fromPhase.has(channel);
+                    cache.set(cacheKey, domainOver(channel, whole ? undefined : members));
+                }
+                const scale = cache.get(cacheKey);
+                if (scale)
+                    out[channel] = scale;
+            }
+            return Object.keys(out).length ? out : undefined;
+        };
+        const sharedScales = {};
+        const add = (key, scales) => {
+            if (scales)
+                sharedScales[key] = scales;
+        };
+        if (panels.length)
+            for (const panel of panels)
+                add(panel.key, scalesOf(panel));
+        else
+            add('', scalesOf(undefined));
+        return { ...state, sharedScales };
+    };
+    /**
+     * One axis' domain over some slices: sorted values on a band axis, `[min, max]`
+     * otherwise, or `undefined`. A numeric extent is niced here, once, so every
+     * slice gets the exact same domain - svelteplot's own `nice` rounds by a tick
+     * count derived from each panel's height, which over-rounds short panels and
+     * can disagree between panels of different heights.
+     */
+    static buildSharedAxisScale(slices, axis, niceTolerance) {
+        const values = slices
+            .flatMap((slice) => slice[axis])
+            .filter((v) => v != null && v !== '' && !(typeof v === 'number' && !Number.isFinite(v)));
+        if (!values.length)
+            return undefined;
+        if (slices.some((slice) => slice.band.includes(axis))) {
+            const distinct = [...new Set(values)];
+            return {
+                domain: slices.some((slice) => slice.dataOrder) ? distinct : distinct.sort(ascending)
+            };
+        }
+        if (values.every((v) => typeof v === 'number')) {
+            const numbers = slices.some((slice) => slice.zero.includes(axis))
+                ? [...values, 0]
+                : values;
+            const lo = Math.min(...numbers);
+            const hi = Math.max(...numbers);
+            return { domain: NiceTicks.domain(lo, hi, 10, niceTolerance), nice: false };
+        }
+        if (values.every((v) => v instanceof Date)) {
+            const times = values.map((d) => +d);
+            return { domain: [new Date(Math.min(...times)), new Date(Math.max(...times))] };
+        }
+        return { domain: [...new Set(values)].sort(ascending) };
+    }
+    /**
+     * Where one panel's rows and markers sit on each axis, read off a pipeline
+     * run over every panel - or, without a `panel`, where all of them sit.
+     */
+    static buildPanelAxisValues(state, panel, layout = {}) {
+        const inPanel = (tagged) => panel === undefined || tagged === panel;
+        const processed = state.processedData && {
+            ...state.processedData,
+            data: state.processedData.data.filter((row) => inPanel(row[PANEL_KEY]))
+        };
+        const markers = (state.markers ?? []).filter((marker) => inPanel(marker[PANEL_KEY]));
+        const values = (axis) => [
+            ...ProcessedPositions.values(processed, axis),
+            ...MarkerAxisValues.of(markers, axis)
+        ];
+        return {
+            x: values('x'),
+            y: values('y'),
+            band: layout.band ?? [],
+            zero: layout.zero ?? [],
+            dataOrder: layout.dataOrder
+        };
+    }
+    /**
+     * Which slices share a channel's domain under `facet.scales`: every one, the
+     * panels on one column (x) or row (y) of a `rows`/`cols` grid, or none (a
+     * free axis of a wrapped facet). Color is shared by every slice.
+     */
+    static #sharingLine(facet, channel) {
+        if (!facet || channel === 'color')
+            return 'all';
+        const mode = facet.scales ?? 'shared';
+        if (mode !== 'free' && mode !== `free-${channel}`)
+            return 'all';
+        if (isFacetWrap(facet))
+            return null;
+        return channel === 'x' ? 'col' : 'row';
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { ProcessedData } from '../../types/phases';
+import type { ScopedMarkerGroup } from '../../types/layout/geometry';
+type Row = Record<string, unknown>;
+/** The plot's own author markers, made ready for the rest of the pipeline. */
+export declare class AuthorMarkers {
+    #private;
+    /**
+     * Prepares a plot's own author markers for the rest of its pipeline: inherits
+     * the plot's grouping and default color first (a transform's `z` defaults to
+     * the grouping), splits a segment-scoped marker into one marker per segment of
+     * its series, then runs each marker's own transforms over its rows - its
+     * segment's or series' rows when it's scoped to one, the plot's rows otherwise.
+     */
+    static prepare<T extends {
+        type: string;
+        component?: unknown;
+        props?: unknown;
+    }>(markers: T[], plot: {
+        grouping?: unknown;
+        color?: unknown;
+        defaultColor?: string;
+        flat: Row[];
+        resolvedSeries?: {
+            name: string;
+            data: Row[];
+        }[];
+        scopedGroups?: ScopedMarkerGroup<Row>[];
+    }): T[];
+    /**
+     * A marker that draws the plot's rows (it sets no `data`) draws them as the
+     * plot does, after the plot's own transforms: it starts from the plot's
+     * processed rows - its series' rows when scoped to one - and takes the
+     * processed channels for any position it leaves unset. A position it sets
+     * itself reads that field of the processed rows (every source field is kept).
+     * Its `grouping` defaults to the plot's series, so it splits, and its own
+     * transforms run, per series. A plot without transforms draws its rows as
+     * they are, so its markers are left as is, as is a kind that draws no rows.
+     */
+    static withProcessedRows<T extends {
+        type: string;
+    }>(marker: T, processed?: ProcessedData): T;
+}
+export {};

package/dist/phases/statistics/AuthorMarkers.js

@@ -0,0 +1,69 @@
+import { MarkerKinds } from '../../markers/MarkerKinds';
+import { Transforms } from '../transforms/Transforms';
+import { MarkerGrouping } from './MarkerGrouping';
+import { SERIES_ID_KEY, SERIES_KEY } from '../transforms/TransformsPhase';
+/** Kinds that handle `scope: 'segment'` themselves, at render time. */
+const RENDER_SCOPED_KINDS = new Set(['component', 'hover']);
+/** The plot's own author markers, made ready for the rest of the pipeline. */
+export class AuthorMarkers {
+    /**
+     * Prepares a plot's own author markers for the rest of its pipeline: inherits
+     * the plot's grouping and default color first (a transform's `z` defaults to
+     * the grouping), splits a segment-scoped marker into one marker per segment of
+     * its series, then runs each marker's own transforms over its rows - its
+     * segment's or series' rows when it's scoped to one, the plot's rows otherwise.
+     */
+    static prepare(markers, plot) {
+        return MarkerGrouping.inheritPlotGrouping(markers, plot).flatMap((marker) => {
+            const scope = marker.series;
+            const seriesRows = typeof scope === 'string'
+                ? plot.resolvedSeries?.find((s) => s.name === scope)?.data
+                : undefined;
+            const rows = seriesRows ?? plot.flat;
+            return AuthorMarkers.#splitBySegment(marker, rows, plot.scopedGroups).map((own) => Transforms.resolve(own, rows));
+        });
+    }
+    /**
+     * One marker per segment of a `scope: 'segment'` marker's series, each over
+     * that segment's rows and in its color. Any other marker is kept whole.
+     */
+    static #splitBySegment(marker, rows, scopedGroups = []) {
+        const own = marker;
+        if (own.scope !== 'segment' || RENDER_SCOPED_KINDS.has(own.type))
+            return [marker];
+        const group = scopedGroups.find((g) => g.name === own.series);
+        if (!group || group.segments.length === 0)
+            return [marker];
+        return group.segments
+            .map((seg) => ({ seg, data: (own.data ?? rows).filter((row) => seg.match(row)) }))
+            .filter(({ data }) => data.length > 0)
+            .map(({ seg, data }) => MarkerGrouping.withSeriesColor({ ...own, data }, seg.color));
+    }
+    /** Whether a marker's kind draws the plot's rows when it sets no `data`. */
+    static #drawsRows(type) {
+        return MarkerKinds.of(type)?.drawsRows ?? false;
+    }
+    /**
+     * A marker that draws the plot's rows (it sets no `data`) draws them as the
+     * plot does, after the plot's own transforms: it starts from the plot's
+     * processed rows - its series' rows when scoped to one - and takes the
+     * processed channels for any position it leaves unset. A position it sets
+     * itself reads that field of the processed rows (every source field is kept).
+     * Its `grouping` defaults to the plot's series, so it splits, and its own
+     * transforms run, per series. A plot without transforms draws its rows as
+     * they are, so its markers are left as is, as is a kind that draws no rows.
+     */
+    static withProcessedRows(marker, processed) {
+        const own = marker;
+        if (own.data !== undefined ||
+            !AuthorMarkers.#drawsRows(own.type) ||
+            !processed?.transforms.length) {
+            return marker;
+        }
+        const rows = typeof own.series === 'string'
+            ? processed.data.filter((row) => row[SERIES_KEY] === own.series)
+            : processed.data;
+        const channels = Object.fromEntries(Object.entries(processed.channels).filter(([key]) => own[key] === undefined));
+        return { ...own, ...channels, data: rows, grouping: own.grouping ?? SERIES_ID_KEY };
+    }
+}

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

@@ -0,0 +1,48 @@
+type MarkerLike = {
+    type: string;
+    series?: unknown;
+    color?: unknown;
+    fill?: unknown;
+    styles?: Record<string, unknown>;
+    bar?: object;
+};
+/** How a plot's own grouping and colors reach the markers its author adds. */
+export declare class MarkerGrouping {
+    #private;
+    /**
+     * Gives a marker one flat color (its `styles`, or a box's `bar.fill`) when it
+     * sets none of its own: a series color, the plot's default series color.
+     * Dots take `dotFill`/`dotStroke`, line-only kinds take `stroke`, text takes
+     * `fill` (a stroke would outline its glyphs), filled kinds take both so their
+     * outline matches their fill.
+     */
+    static withSeriesColor<TMarker extends MarkerLike>(marker: TMarker, color: string | undefined): TMarker;
+    /**
+     * Gives each author marker the plot's own color rules by default:
+     *
+     * - A grouped plot (`color`/`grouping`) splits its markers the same way. A
+     *   grouping-capable marker draws one shape per group, and a color-capable
+     *   marker colors each row by its group's color.
+     * - An ungrouped plot's unscoped marker takes the plot's default series color.
+     *
+     * A marker's own `grouping`/`color` or flat color always wins. Scoped markers
+     * (`series`) are colored by their own series at render time, not here.
+     */
+    static inheritPlotGrouping<TMarker extends {
+        type: string;
+    }>(markers: TMarker[], plot: {
+        grouping?: unknown;
+        color?: unknown;
+        defaultColor?: string;
+    }): TMarker[];
+    /**
+     * Gives a scoped hover marker its series color through its own `dot` and
+     * `text` styles, the way `withSeriesColor` does for other markers. A style the
+     * marker sets itself keeps its own color.
+     */
+    static withHoverSeriesColor<T extends {
+        dot?: object;
+        text?: object;
+    }>(marker: T, color: string | undefined): T;
+}
+export {};

package/dist/phases/statistics/MarkerGrouping.js

@@ -0,0 +1,113 @@
+/** Marker kinds that split their rows into separate shapes per `grouping`. */
+const GROUPING_KINDS = new Set([
+    'area',
+    'density',
+    'line',
+    'hull',
+    'trail',
+    'delaunayLink',
+    'delaunayMesh',
+    'voronoi',
+    'voronoiMesh'
+]);
+/** Marker kinds whose per-row `color` resolves through the plot's own color scale. */
+const COLOR_KINDS = new Set([
+    'area',
+    'bar',
+    'cell',
+    'density',
+    'delaunayLink',
+    'delaunayMesh',
+    'dot',
+    'hull',
+    'line',
+    'rect',
+    'tick',
+    'trail',
+    'voronoi',
+    'voronoiMesh',
+    'waffle'
+]);
+/** Kinds that draw only a line, so their flat color is `stroke` alone. */
+const LINE_KINDS = new Set(['line', 'regression', 'bollinger', 'delta']);
+/** Flat color style keys - when a marker sets one, it keeps that color instead of inheriting one. */
+const FLAT_COLOR_KEYS = ['fill', 'stroke', 'dotFill', 'dotStroke'];
+/** A style value that paints nothing isn't a color choice, so it doesn't block inheritance. */
+const isPaint = (value) => value !== undefined && value !== 'none' && value !== 'transparent';
+/** How a plot's own grouping and colors reach the markers its author adds. */
+export class MarkerGrouping {
+    /** Whether a marker sets its own flat color, which then takes precedence over any inherited one. */
+    static #hasFlatColor(marker) {
+        return isPaint(marker.fill) || FLAT_COLOR_KEYS.some((key) => isPaint(marker.styles?.[key]));
+    }
+    /**
+     * Gives a marker one flat color (its `styles`, or a box's `bar.fill`) when it
+     * sets none of its own: a series color, the plot's default series color.
+     * Dots take `dotFill`/`dotStroke`, line-only kinds take `stroke`, text takes
+     * `fill` (a stroke would outline its glyphs), filled kinds take both so their
+     * outline matches their fill.
+     */
+    static withSeriesColor(marker, color) {
+        if (!color || MarkerGrouping.#hasFlatColor(marker) || marker.color !== undefined)
+            return marker;
+        if (marker.type === 'box') {
+            return { ...marker, bar: { fill: color, ...(marker.bar ?? {}) } };
+        }
+        const keys = marker.type === 'dot'
+            ? ['dotFill', 'dotStroke']
+            : LINE_KINDS.has(marker.type)
+                ? ['stroke']
+                : marker.type === 'text'
+                    ? ['fill']
+                    : ['fill', 'stroke'];
+        const styles = { ...(marker.styles ?? {}) };
+        // A `'none'` the marker sets doesn't block the inherited color, but stays itself.
+        for (const key of keys)
+            styles[key] ??= color;
+        return { ...marker, styles };
+    }
+    /**
+     * Gives each author marker the plot's own color rules by default:
+     *
+     * - A grouped plot (`color`/`grouping`) splits its markers the same way. A
+     *   grouping-capable marker draws one shape per group, and a color-capable
+     *   marker colors each row by its group's color.
+     * - An ungrouped plot's unscoped marker takes the plot's default series color.
+     *
+     * A marker's own `grouping`/`color` or flat color always wins. Scoped markers
+     * (`series`) are colored by their own series at render time, not here.
+     */
+    static inheritPlotGrouping(markers, plot) {
+        const grouping = plot.grouping ?? plot.color;
+        return markers.map((marker) => {
+            const m = marker;
+            if (m.series !== undefined)
+                return marker;
+            if (grouping === undefined)
+                return MarkerGrouping.withSeriesColor(m, plot.defaultColor);
+            const updates = {};
+            if (GROUPING_KINDS.has(m.type) && m.grouping === undefined)
+                updates.grouping = grouping;
+            if (COLOR_KINDS.has(m.type) && m.color === undefined && !MarkerGrouping.#hasFlatColor(m)) {
+                updates.color = plot.color ?? plot.grouping;
+            }
+            return Object.keys(updates).length ? { ...m, ...updates } : marker;
+        });
+    }
+    /**
+     * Gives a scoped hover marker its series color through its own `dot` and
+     * `text` styles, the way `withSeriesColor` does for other markers. A style the
+     * marker sets itself keeps its own color.
+     */
+    static withHoverSeriesColor(marker, color) {
+        if (!color)
+            return marker;
+        const dot = (marker.dot ?? {});
+        const text = (marker.text ?? {});
+        return {
+            ...marker,
+            dot: { ...dot, dotFill: dot.dotFill ?? color, dotStroke: dot.dotStroke ?? color },
+            text: { ...text, fill: text.fill ?? color }
+        };
+    }
+}

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

@@ -0,0 +1,53 @@
+import type { StatisticSource } from '../../types/phases/statistics/source';
+import type { Series } from '../../types/plots/data/common';
+import type { StatisticConfig } from '../../types/layout/statistics';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+/**
+ * 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 declare class Statistics {
+    #private;
+    /**
+     * 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<T extends Record<string, unknown>>(source: StatisticSource<T>, config: StatisticConfig): AxisBasedMarkersConfig;
+    /**
+     * 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<T extends Record<string, unknown>>(args: {
+        series: Series<T>[];
+        statistics: StatisticConfig[] | undefined;
+        colorFor?: (seriesName: string) => string;
+    }): AxisBasedMarkersConfig[];
+    /**
+     * 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<TMarker extends {
+        type: string;
+    }, T extends Record<string, unknown>>(markers: TMarker[], fallbackData: T[]): (TMarker | AxisBasedMarkersConfig)[];
+}