@fundar/data-chart-telling 0.0.64 → 1.0.0

package/dist/phases/facet/FacetPhase.js

@@ -0,0 +1,114 @@
+import { buildFacetKeyOf, buildFacetPanels } from '../../layout/facet/config';
+/** The field a processed row carries its facet panel under. */
+export 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 class FacetPhase {
+    phase = 'facet';
+    run = (state) => {
+        const { data, series } = state;
+        const facet = state.facet;
+        if (!facet || series || !data)
+            return state;
+        const panels = buildFacetPanels(facet, data).map(({ rows: _rows, ...panel }) => panel);
+        const keys = new Set(panels.map((p) => p.key));
+        const keyOf = buildFacetKeyOf(facet);
+        const panelOf = (row) => {
+            const tagged = row[PANEL_KEY];
+            if (typeof tagged === 'string')
+                return tagged;
+            const key = keyOf(row);
+            return keys.has(key) ? key : undefined;
+        };
+        return { ...state, panels, panelOf };
+    };
+    /** The id of a series' part in one facet panel. */
+    static buildPanelSeriesId(panel, name) {
+        return `${panel}\u0000${name}`;
+    }
+    /**
+     * 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(series, panels, panelOf) {
+        const rowsByPanel = series.map((s) => {
+            const groups = new Map();
+            for (const row of s.data) {
+                const key = panelOf(row);
+                if (key === undefined)
+                    continue;
+                const bucket = groups.get(key);
+                if (bucket)
+                    bucket.push(row);
+                else
+                    groups.set(key, [row]);
+            }
+            return groups;
+        });
+        return panels.flatMap((panel) => series.flatMap((s, i) => {
+            const rows = rowsByPanel[i].get(panel.key);
+            if (!rows?.length)
+                return [];
+            return [
+                {
+                    ...s,
+                    id: FacetPhase.buildPanelSeriesId(panel.key, s.name),
+                    panel: panel.key,
+                    data: rows
+                }
+            ];
+        }));
+    }
+    /** A state narrowed to one panel's series, rows and processed rows. */
+    static narrowToPanel(state, panel) {
+        return FacetPhase.narrowToPanels(state, [panel]);
+    }
+    /** A state narrowed to some panels' series, rows and processed rows. */
+    static narrowToPanels(state, panels) {
+        const keep = new Set(panels);
+        const has = (panel) => keep.has(panel);
+        const resolvedSeries = state.resolvedSeries?.filter((s) => has(s.panel));
+        const { panelOf } = state;
+        return {
+            ...state,
+            resolvedSeries,
+            flat: panelOf
+                ? state.flat?.filter((row) => has(panelOf(row)))
+                : resolvedSeries?.flatMap((s) => s.data),
+            scopedGroups: state.scopedGroups?.filter((g) => has(g.panel)),
+            groupedSeries: state.groupedSeries?.filter((g) => has(g.series.panel)),
+            processedData: state.processedData && {
+                ...state.processedData,
+                data: state.processedData.data.filter((row) => has(row[PANEL_KEY]))
+            }
+        };
+    }
+    /**
+     * 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(state, panel) {
+        const narrowed = FacetPhase.narrowToPanel(state, panel);
+        const markers = state.markers?.flatMap((marker) => {
+            const own = marker;
+            if (own[PANEL_KEY] === undefined)
+                return [marker];
+            if (own[PANEL_KEY] !== panel)
+                return [];
+            const untagged = { ...own };
+            delete untagged[PANEL_KEY];
+            return [untagged];
+        });
+        const out = { ...narrowed, markers };
+        delete out.facet;
+        delete out.panels;
+        delete out.panelOf;
+        return out;
+    }
+}

package/dist/phases/hover/HoverPhase.d.ts

@@ -0,0 +1,73 @@
+import { PlotAxes } from '../data/PlotAxes';
+import type { HoverDisplayPoint, HoverPoint, HoverStrategy } from '../../types/layout/hover';
+import type { HoverConfig, PointMatchingStrategy, TooltipConfig } from '../../types/plots/props';
+import type { LegendState } from '../../layout/legend/LegendState.svelte';
+import type { AxisPlotCtx, AxisPlotState, HoverPosition, HoverStageOptions, PhaseStage, ProcessedData } from '../../types/phases';
+type AnyAxisState = AxisPlotState<any, any, any, any>;
+/**
+ * The "hover" phase every axis-based plot shares: what the pointer can match
+ * (`hover`, the config `BasePlotLayout` mounts), the rows it draws and hovers
+ * over (`hoverRows`) and where each sits (`hoverPosition`), from the kind's
+ * options over everything placed before - the plot's `tooltip` and hover
+ * markers, the tooltip phase's format, the legend in scope. A core only reads them.
+ *
+ * Every plot gets the same candidates: each processed row of a series the
+ * legend shows, at its position, in its series' color - except a gap row (one
+ * with no value, or filled in) and a row whose color falls outside the
+ * legend's narrowed range.
+ */
+export declare class HoverPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "hover";
+    constructor(options?: HoverStageOptions<TState, TCtx>);
+    run: (state: TState, ctx: TCtx) => TState;
+    /**
+     * The hover strategy a plot's axes ask for: along the axis that isn't
+     * measured (a bar's categories, a line's `x`), or one exact cell at a time
+     * when both axes hold categories.
+     */
+    static strategyOf(state: {
+        axes?: PlotAxes;
+    }): HoverStrategy;
+    /**
+     * A plot's `hover` config for `BasePlotLayout`: active whenever there's a
+     * tooltip or a hover marker, with the strategy and sync those two resolve to
+     * (the plot kind's own `defaultStrategy` when neither sets one). The tooltip
+     * reads as `format` unless it sets its own.
+     */
+    static buildHoverConfig<TRow extends Record<string, unknown>>(args: {
+        tooltip: TooltipConfig<TRow> | undefined;
+        format: (row: TRow) => string;
+        markers: {
+            type: string;
+        }[];
+        points: HoverPoint<TRow>[];
+        label: (row: TRow) => string;
+        defaultStrategy: HoverStrategy;
+        pointMatching?: PointMatchingStrategy;
+    }): HoverConfig<TRow>;
+    /**
+     * Hover candidates for a plot's own processed rows: each visible row at its
+     * position (a stacked row's top, a bin's centre), in its series' color. A
+     * series the legend turned off is left out, as is any row `include` rejects.
+     */
+    static buildProcessedHoverPoints<TRow extends Record<string, unknown>>(args: {
+        processed: ProcessedData;
+        colorFor: (seriesName: string) => string;
+        legendInteraction?: LegendState | null;
+        label: (row: TRow) => string;
+        include?: (row: TRow) => boolean;
+        /** The row a hovered point reads as, e.g. with derived fields added. Defaults to the processed row. */
+        row?: (row: TRow) => TRow;
+        /** Fields to add to (or replace on) each point. */
+        decorate?: (row: TRow) => Partial<HoverDisplayPoint>;
+        /** Where a row sits, as is. Defaults to its processed position, with `y` as a number. */
+        position?: HoverPosition;
+    }): HoverPoint<TRow>[];
+    /** Whether a value sits within the legend's narrowed range; one with no value is never dimmed. */
+    static inRange(value: number | null | undefined, range: {
+        min: number;
+        max: number;
+    }): boolean;
+}
+export {};

package/dist/phases/hover/HoverPhase.js

@@ -0,0 +1,144 @@
+import { GAP_VALUE, SERIES_KEY, TransformsPhase } from '../transforms/TransformsPhase';
+import { HoverSettings } from '../../layout/hover/HoverSettings';
+import { PlotAxes } from '../data/PlotAxes';
+import { isGapValue } from '../../plots/utils/gaps';
+/**
+ * The "hover" phase every axis-based plot shares: what the pointer can match
+ * (`hover`, the config `BasePlotLayout` mounts), the rows it draws and hovers
+ * over (`hoverRows`) and where each sits (`hoverPosition`), from the kind's
+ * options over everything placed before - the plot's `tooltip` and hover
+ * markers, the tooltip phase's format, the legend in scope. A core only reads them.
+ *
+ * Every plot gets the same candidates: each processed row of a series the
+ * legend shows, at its position, in its series' color - except a gap row (one
+ * with no value, or filled in) and a row whose color falls outside the
+ * legend's narrowed range.
+ */
+export class HoverPhase {
+    phase = 'hover';
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    run = (state, ctx) => {
+        const options = this.#options;
+        const valueAxis = PlotAxes.valueOf(state);
+        const raw = options.position?.(state) ??
+            TransformsPhase.processedPosition(state.processedData, valueAxis);
+        // A processed position reads as raw; the hover controller and the plot's
+        // scales want its value as a number, unless that axis lays out categories.
+        const position = options.position || state.axes?.isDiscrete(valueAxis)
+            ? raw
+            : { ...raw, [valueAxis]: (row) => Number(raw[valueAxis](row)) };
+        const label = options.label?.(state) ??
+            ((row) => String(state.channels[valueAxis].accessor(row)));
+        const points = HoverPhase.buildProcessedHoverPoints({
+            processed: state.processedData,
+            colorFor: state.colorForSeries,
+            legendInteraction: ctx.interaction?.legend,
+            label: label,
+            position,
+            include: HoverPhase.#hoverable(state, ctx, raw, valueAxis),
+            row: options.row?.(state),
+            decorate: options.decorate?.(state, ctx)
+        });
+        const hover = HoverPhase.buildHoverConfig({
+            tooltip: state.tooltip,
+            format: state.tooltipFormat,
+            markers: state.authorMarkers ?? [],
+            points: points,
+            label: label,
+            defaultStrategy: options.strategy ?? HoverPhase.strategyOf(state),
+            pointMatching: options.pointMatching
+        });
+        const hitAreas = options.hitAreas?.(state, hover, ctx) ?? [];
+        return {
+            ...state,
+            hover,
+            hoverPosition: position,
+            hoverRows: state.processedData.data,
+            ...(hitAreas.length > 0 ? { markers: [...(state.markers ?? []), ...hitAreas] } : {})
+        };
+    };
+    /**
+     * The hover strategy a plot's axes ask for: along the axis that isn't
+     * measured (a bar's categories, a line's `x`), or one exact cell at a time
+     * when both axes hold categories.
+     */
+    static strategyOf(state) {
+        const { axes } = state;
+        if (!axes)
+            return 'x';
+        if (axes.isDiscrete('x') && axes.isDiscrete('y'))
+            return 'punctual';
+        return PlotAxes.other(PlotAxes.valueOf(state));
+    }
+    /**
+     * A plot's `hover` config for `BasePlotLayout`: active whenever there's a
+     * tooltip or a hover marker, with the strategy and sync those two resolve to
+     * (the plot kind's own `defaultStrategy` when neither sets one). The tooltip
+     * reads as `format` unless it sets its own.
+     */
+    static buildHoverConfig(args) {
+        const { tooltip, format, markers, points, label, defaultStrategy, pointMatching } = args;
+        const settings = new HoverSettings(tooltip, markers, defaultStrategy);
+        return {
+            active: settings.active,
+            points,
+            label,
+            strategy: settings.strategy,
+            sync: settings.sync,
+            tooltip: tooltip && { ...tooltip, format: tooltip.format ?? format },
+            ...(pointMatching ? { pointMatching } : {})
+        };
+    }
+    /**
+     * Hover candidates for a plot's own processed rows: each visible row at its
+     * position (a stacked row's top, a bin's centre), in its series' color. A
+     * series the legend turned off is left out, as is any row `include` rejects.
+     */
+    static buildProcessedHoverPoints(args) {
+        const { processed, colorFor, legendInteraction, label, include, row: rowOf, decorate } = args;
+        const processedPosition = TransformsPhase.processedPosition(processed);
+        const position = args.position ?? {
+            x: processedPosition.x,
+            y: (row) => Number(processedPosition.y(row))
+        };
+        const x = position.x;
+        const y = position.y;
+        return processed.data
+            .filter((d) => !legendInteraction?.isOff(d[SERIES_KEY]))
+            .filter((d) => !include || include(d))
+            .map((d) => {
+            const row = d;
+            const seriesName = d[SERIES_KEY];
+            return {
+                x: x(d),
+                y: y(d),
+                row: rowOf ? rowOf(row) : row,
+                label: label(row),
+                series: seriesName,
+                color: colorFor(seriesName),
+                ...decorate?.(row)
+            };
+        });
+    }
+    /**
+     * Which processed rows can be hovered: not a gap (no value where it sits, or
+     * filled in by `styles.gaps`), and, while the legend narrows a continuous
+     * color to a range, not outside it. A dimmed row stays drawn, never matched.
+     */
+    static #hoverable(state, ctx, position, valueAxis) {
+        const range = ctx.interaction?.legend?.range;
+        const color = state.channels?.color?.accessor;
+        return (row) => {
+            if (isGapValue(position[valueAxis](row)) || row[GAP_VALUE] !== undefined)
+                return false;
+            return !range || !color || HoverPhase.inRange(Number(color(row)), range);
+        };
+    }
+    /** Whether a value sits within the legend's narrowed range; one with no value is never dimmed. */
+    static inRange(value, range) {
+        return value == null || (value >= range.min && value <= range.max);
+    }
+}

package/dist/phases/mapping/MappingPhase.d.ts

@@ -0,0 +1,17 @@
+import type { AxisPlotState, AxisPlotCtx, MappingStageOptions, PhaseStage } from '../../types/phases';
+type AnyAxisState = AxisPlotState<any, any, any, any>;
+/**
+ * The "mapping" phase every axis-based plot shares: every channel resolved to
+ * a row accessor. `x`/`y` (and `color`) read the first series' own, falling
+ * back to the plot's props; `grouping` is the key the "data" phase split rows
+ * by ({@link DataPhase.buildGrouping}); any other channel resolves only when
+ * its prop is set, and a size channel given a number stays that literal size.
+ * An unset `x`/`y` reads each row itself, with no `source`.
+ */
+export declare class MappingPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "mapping";
+    constructor(options?: MappingStageOptions<TState, TCtx>);
+    run: (state: TState, ctx: TCtx) => TState;
+}
+export {};

package/dist/phases/mapping/MappingPhase.js

@@ -0,0 +1,42 @@
+import { resolveAccessor } from '../../plots/utils/accessors';
+import { DataPhase } from '../data/DataPhase';
+/**
+ * The "mapping" phase every axis-based plot shares: every channel resolved to
+ * a row accessor. `x`/`y` (and `color`) read the first series' own, falling
+ * back to the plot's props; `grouping` is the key the "data" phase split rows
+ * by ({@link DataPhase.buildGrouping}); any other channel resolves only when
+ * its prop is set, and a size channel given a number stays that literal size.
+ * An unset `x`/`y` reads each row itself, with no `source`.
+ */
+export class MappingPhase {
+    phase = 'mapping';
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    run = (state, ctx) => {
+        const first = state.resolvedSeries?.[0];
+        const identity = { accessor: (d) => d };
+        const grouping = DataPhase.buildGrouping(state);
+        const size = (value) => typeof value === 'number' ? value : MappingPhase.#channel(value);
+        const channels = {
+            x: MappingPhase.#channel(first?.x ?? state.x) ?? identity,
+            y: MappingPhase.#channel(first?.y ?? state.y) ?? identity,
+            grouping: MappingPhase.#channel(grouping),
+            color: MappingPhase.#channel(first?.color ?? state.color),
+            opacity: MappingPhase.#channel(state.opacity),
+            symbol: MappingPhase.#channel(state.symbol),
+            r: size(state.r),
+            length: size(state.length)
+        };
+        const next = { ...state, channels };
+        return this.#options.extend ? this.#options.extend(next, ctx) : next;
+    };
+    /** A channel prop resolved to a row accessor, keeping it as `source`, or left out when unset. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static #channel(accessor) {
+        return accessor !== undefined
+            ? { accessor: resolveAccessor(accessor), source: accessor }
+            : undefined;
+    }
+}

package/dist/phases/markers/MarkersPhase.d.ts

@@ -0,0 +1,14 @@
+import type { AxisPlotCtx, AxisPlotState, MarkersStageOptions, PhaseStage } from '../../types/phases';
+/**
+ * The shared "markers" phase: everything the plot draws, bottom to top - the
+ * plot kind's own marks, then what the "statistics" phase left in
+ * `state.markers` (the author's markers and the plot's statistics), then its
+ * value labels when `styles.values.show` turns them on, each with what every
+ * label shares ({@link ValueLabels.hooks}).
+ */
+export declare class MarkersPhase<TState extends AxisPlotState<any, any, any, any>, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "markers";
+    constructor(options: MarkersStageOptions<TState, TCtx>);
+    run: (state: TState, ctx: TCtx) => TState;
+}

package/dist/phases/markers/MarkersPhase.js

@@ -0,0 +1,27 @@
+/**
+ * The shared "markers" phase: everything the plot draws, bottom to top - the
+ * plot kind's own marks, then what the "statistics" phase left in
+ * `state.markers` (the author's markers and the plot's statistics), then its
+ * value labels when `styles.values.show` turns them on, each with what every
+ * label shares ({@link ValueLabels.hooks}).
+ */
+export class MarkersPhase {
+    phase = 'markers';
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    run = (state, ctx) => {
+        const options = this.#options;
+        const labels = state.valueLabels;
+        const valueLabels = labels?.show && options.valueLabels
+            ? options
+                .valueLabels(labels, state, ctx)
+                .map((marker) => ({ ...labels.hooks(ctx), ...marker }))
+            : [];
+        return {
+            ...state,
+            markers: [...options.marks(state, ctx), ...(state.markers ?? []), ...valueLabels]
+        };
+    };
+}

package/dist/phases/scales/MarkerAxisValues.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every finite numeric value a set of markers draws on one axis, read from
+ * each marker's own `data`: its position channel and its range edges (`x1`/`x2`
+ * for `x`), so a rect's or a band's full extent counts, not just its middle.
+ * Markers without their own `data` reuse the plot's rows, which the plot's
+ * domain already covers, so they're skipped. Lets a plot's scale domain grow to
+ * fit derived marks (a density curve's peak, a regression band) instead of
+ * clipping them.
+ */
+export declare class MarkerAxisValues {
+    static of(markers: object[], axis: 'x' | 'y'): number[];
+}

package/dist/phases/scales/MarkerAxisValues.js

@@ -0,0 +1,34 @@
+/**
+ * Every finite numeric value a set of markers draws on one axis, read from
+ * each marker's own `data`: its position channel and its range edges (`x1`/`x2`
+ * for `x`), so a rect's or a band's full extent counts, not just its middle.
+ * Markers without their own `data` reuse the plot's rows, which the plot's
+ * domain already covers, so they're skipped. Lets a plot's scale domain grow to
+ * fit derived marks (a density curve's peak, a regression band) instead of
+ * clipping them.
+ */
+export class MarkerAxisValues {
+    static of(markers, axis) {
+        return markers.flatMap((markerConfig) => {
+            const marker = markerConfig;
+            const rows = marker.data;
+            if (!rows)
+                return [];
+            return [axis, `${axis}1`, `${axis}2`].flatMap((channel) => {
+                const accessor = marker[channel];
+                // A literal edge (a bar anchored at `0`) counts as is.
+                if (typeof accessor === 'number')
+                    return Number.isFinite(accessor) ? [accessor] : [];
+                // svelteplot's own transforms key their output rows by symbols, so a symbol accessor is read like a field key.
+                if (!(typeof accessor === 'string' ||
+                    typeof accessor === 'symbol' ||
+                    typeof accessor === 'function'))
+                    return [];
+                return rows
+                    .map((row) => (typeof accessor === 'function' ? accessor(row) : row[accessor]))
+                    .map(Number)
+                    .filter(Number.isFinite);
+            });
+        });
+    }
+}

package/dist/phases/scales/ScalesPhase.d.ts

@@ -0,0 +1,31 @@
+import { PlotAxes } from '../data/PlotAxes';
+import type { AxisChannelName } from '../../types/layout/mapping';
+import type { AxisPlotState, AxisPlotCtx, PhaseStage, ProcessedData, ScalesStageOptions } from '../../types/phases';
+type AnyAxisState = AxisPlotState<any, any, any, any>;
+/**
+ * The shared "scales" phase. Each axis the kind lays out as categories
+ * (`state.axes.bands`) becomes a band scale, padded and ordered as the kind
+ * says; each `symmetric` axis reaches as far below zero as above it; and an
+ * unpinned numeric axis grows to cover derived markers and the ranges the
+ * transforms gave the rows - from zero on the axes `zero` names. The author's
+ * `scales` always win, and a kind adds its own on top (`defaults`, `fit`, `extend`).
+ */
+export declare class ScalesPhase<TState extends AnyAxisState, TCtx extends AxisPlotCtx> implements PhaseStage<TState, TCtx> {
+    #private;
+    readonly phase: "scales";
+    constructor(options?: ScalesStageOptions<TState, TCtx>);
+    /** The axes whose marks grow from zero, in this state. */
+    zeroAxes(state: {
+        axes?: PlotAxes;
+    }): AxisChannelName[];
+    /** The axes that reach as far below zero as above it, in this state. */
+    symmetricAxes(state: {
+        axes?: PlotAxes;
+    }): AxisChannelName[];
+    /** Whether the kind keeps its categories in the order the data gives them. */
+    get keepsDataOrder(): boolean;
+    run: (state: TState, ctx: TCtx) => TState;
+    /** Every value the plot's own processed rows sit at on one axis. */
+    static processedValues(processed: ProcessedData | undefined, axis: AxisChannelName): unknown[];
+}
+export {};