@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/types/phases/state.d.ts

@@ -0,0 +1,73 @@
+import type { Series } from '../plots/data/common';
+import type { AxisBasedScalesConfig } from '../layout/scales';
+import type { SegmentsConfig, MarginConfig, HoverConfig, TooltipConfig } from '../plots/props';
+import type { HoverPosition } from './hover/phase';
+import type { VisualGroup } from '../plots/segments/config';
+import type { ScopedMarkerGroup } from '../layout/geometry';
+import type { ChannelAccessors, ResolvedChannels } from '../layout/mapping';
+import type { PlotStylesConfig } from '../configuration/styling';
+import type { AxisBasedMarkersConfig } from '../markers/common';
+import type { StatisticConfig } from '../layout/statistics';
+import type { MarkerTransform } from '../transforms';
+import type { ProcessedData } from './transforms/phase';
+import type { FacetStageState } from './facet/phase';
+import type { AxisBasedStylesConfig, ValuesStyle } from '../layout/styles';
+import type { ValueLabels } from '../../layout/styles/ValueLabels';
+import type { PlotInteraction } from '../../layout/interaction/PlotInteraction.svelte';
+import type { PlotAxes } from '../../phases/data/PlotAxes';
+import type { DiscreteGapFill, GapZonesConfig } from '../plots/gaps';
+/**
+ * The pipeline state every axis-based plot shares - raw props plus every
+ * phase's own output. A plot kind extends it with what only it has.
+ * `TSeries` is the series shape the "data" phase resolves, and `TRow` what
+ * `flat` holds, for a kind that tags its own rows.
+ */
+export type AxisPlotState<TData extends Record<string, unknown>, TStyle extends object, TSeries extends Series<TData> = Series<TData>, TRow = TData> = ChannelAccessors<TData> & {
+    series?: Series<TData>[];
+    data?: TData[];
+    segments?: SegmentsConfig<TStyle>;
+    scales: AxisBasedScalesConfig<TData>;
+    statistics?: StatisticConfig[];
+    transforms?: MarkerTransform[];
+    authorMarkers?: AxisBasedMarkersConfig[];
+    width: number;
+    height: number;
+    margins?: MarginConfig;
+    /** The plot's `styles`, which `BasePlotLayout` draws its frame from. */
+    styles?: AxisBasedStylesConfig;
+    /** The plot's `styles.values`, which its "markers" phase turns into a value-label `text` marker. */
+    values?: ValuesStyle;
+    /** The plot's `tooltip`, resolved: the "hover" phase reads it. */
+    tooltip?: TooltipConfig<TData>;
+    /** The plot's `styles.gaps`: how a discrete mark fills each series' missing values. */
+    gaps?: Record<string, GapZonesConfig<TStyle>>;
+    /** The plot's facet, which the "facet" phase splits the rows into panels by. */
+    facet?: FacetStageState['facet'];
+    panels?: FacetStageState['panels'];
+    panelOf?: FacetStageState['panelOf'];
+    /** What each position channel is, which one holds the categories, and which way the plot runs. */
+    axes?: PlotAxes;
+    resolvedSeries?: TSeries[];
+    /** Every series name, before legend-omitted ones are dropped, so colors stay put. */
+    allSeriesNames?: string[];
+    groupedSeries?: VisualGroup<TSeries, TStyle>[];
+    flat?: TRow[];
+    scopedGroups?: ScopedMarkerGroup<TData>[];
+    colorForSeries?: (name: string) => string;
+    /** A discrete mark's gap fills, per series id: the value each missing row is drawn at. */
+    gapFillMaps?: Map<string, Map<TData, DiscreteGapFill<TStyle>>>;
+    channels?: ResolvedChannels<TData>;
+    processedData?: ProcessedData;
+    valueLabels?: ValueLabels;
+    markers?: AxisBasedMarkersConfig[];
+    tooltipFormat?: (row: Record<string, unknown>) => string;
+    hover?: HoverConfig<any>;
+    hoverPosition?: HoverPosition;
+    hoverRows?: unknown[];
+};
+/** The environment every axis-based plot's phases read from, alongside the growing state. */
+export type AxisPlotCtx = {
+    cfg: PlotStylesConfig;
+    /** The legend's toggles and the figure's hover, read for one plot: which series show and how each dims. */
+    interaction?: PlotInteraction;
+};

package/dist/types/phases/state.js

@@ -0,0 +1 @@
+export {};

package/dist/types/phases/statistics/phase.d.ts

@@ -0,0 +1,41 @@
+import type { ScopedMarkerGroup } from '../../layout/geometry';
+import type { Accessor, Series } from '../../plots/data/common';
+import type { AxisValue } from '../../layout/mapping';
+import type { StatisticConfig } from '../../layout/statistics';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { ProcessedData } from '../transforms/phase';
+import type { FacetStageState } from '../facet/phase';
+import type { PlotAxes } from '../../../phases/data/PlotAxes';
+/**
+ * What the shared "statistics" stage reads from and writes to a plot's state.
+ * Every axis-based plot state carries these fields, so each satisfies it by shape.
+ */
+export type StatisticsStageState = Pick<FacetStageState, 'panels'> & {
+    x?: Accessor<any, AxisValue>;
+    y?: Accessor<any, AxisValue>;
+    grouping?: Accessor<any, unknown>;
+    color?: Accessor<any, unknown>;
+    statistics?: StatisticConfig[];
+    authorMarkers?: AxisBasedMarkersConfig[];
+    resolvedSeries?: Series<any>[];
+    axes?: PlotAxes;
+    flat?: any[];
+    colorForSeries?: (name: string) => string;
+    /** Each series' segments, which a `scope: 'segment'` author marker splits by. */
+    scopedGroups?: ScopedMarkerGroup<any>[];
+    /** The plot's rows after its own transforms, which an author marker without rows of its own draws. */
+    processedData?: ProcessedData;
+    markers?: AxisBasedMarkersConfig[];
+};
+/** What differs between plots in the shared "statistics" stage. */
+export type StatisticsStageOptions<TState extends StatisticsStageState> = {
+    /** The color an unscoped author marker inherits. Defaults to the first series' color. */
+    defaultColor?: (state: TState) => string | undefined;
+    /**
+     * Whether author markers inherit the plot's `grouping`/`color`. On by
+     * default; off for a plot whose `color` is a value channel, not a group.
+     */
+    inheritGrouping?: boolean;
+    /** Whether a line/area/dot author marker with no `x`/`y` takes the plot's own. */
+    inheritPositions?: boolean;
+};

package/dist/types/phases/statistics/phase.js

@@ -0,0 +1 @@
+export {};

package/dist/types/phases/statistics/source.d.ts

@@ -0,0 +1,20 @@
+import type { AxisValue } from '../../layout/mapping';
+/**
+ * Resolved `{data, x, y}` input a statistic computes over - a marker's own
+ * data, or one plot series/the pooled combination of every series. `x`/`y`
+ * use the same field-key-or-function shape every marker config's own `x`/`y` does.
+ */
+export type StatisticSource<T extends Record<string, unknown> = Record<string, unknown>> = {
+    data: T[];
+    x: string | ((d: any) => AxisValue);
+    y: string | ((d: any) => AxisValue);
+    /** Fallback stroke for the derived marker, used when its own `styles.stroke` is unset - typically the source series' own color. */
+    color?: string;
+};
+/**
+ * Color a derived statistic draws in when neither its own `styles` nor its
+ * source supplies one. A statistic's color is resolved in this order: its own
+ * explicit style, then its source's color (the marker's own color, or the
+ * plot's default series color - per group when grouped), then this.
+ */
+export declare const STATISTIC_FALLBACK_COLOR = "#000000";

package/dist/types/phases/statistics/source.js

@@ -0,0 +1,7 @@
+/**
+ * Color a derived statistic draws in when neither its own `styles` nor its
+ * source supplies one. A statistic's color is resolved in this order: its own
+ * explicit style, then its source's color (the marker's own color, or the
+ * plot's default series color - per group when grouped), then this.
+ */
+export const STATISTIC_FALLBACK_COLOR = '#000000';

package/dist/types/phases/styles/phase.d.ts

@@ -0,0 +1,24 @@
+import type { EdgeBox } from '../../layout/box';
+import type { ValueLabels } from '../../../layout/styles/ValueLabels';
+import type { ValueAnchor } from '../../plots/constants';
+/** A plot kind's own defaults for its value labels, under the author's `styles.values`. */
+export type ValueLabelsOptions<TState> = {
+    /** Whether the labels draw when `styles.values.show` is unset. Defaults to `false`. */
+    show?: boolean;
+    /** Where a label sits when `styles.values.anchor` is unset. Defaults to `'outside'`. */
+    anchor?: ValueAnchor;
+    /** A label's text when `styles.values.format` is unset. Defaults to the bare value. */
+    format?: (value: number, seriesName: string) => string;
+    /**
+     * Where the labels are expected to sit, from the whole data: boxes around
+     * the points they label, on the plot edges those points can reach (see
+     * {@link ValueLabels.edgeBox}). The plot's margins keep their room, so the
+     * labels fit from the first render; without it they still grow to fit,
+     * once measured.
+     */
+    reach?: (labels: ValueLabels, state: TState) => EdgeBox[];
+};
+/** What differs between plots in the shared "styles" stage. */
+export type StylesStageOptions<TState> = {
+    values?: ValueLabelsOptions<TState>;
+};

package/dist/types/phases/styles/phase.js

@@ -0,0 +1 @@
+export {};

package/dist/types/phases/transforms/adapter.d.ts

@@ -0,0 +1,27 @@
+export type Row = Record<string | symbol, unknown>;
+/** A transform's props once split: what svelteplot reads as channels, and what it takes as options. */
+export type TransformArgs = {
+    channels: Row;
+    options: Row;
+};
+/**
+ * Everything one transform type needs to run through svelteplot, and the fixes
+ * that type alone needs: `prepare` before it runs, `finish` on the marker once
+ * every transform has run. A type without a fix leaves the hook out.
+ */
+export type TransformAdapter = {
+    /** The keys svelteplot reads as channels; every other prop of the transform is an option. */
+    channelKeys: Record<string, true>;
+    /**
+     * Keys that, set on the transform, are reducers (options), while the
+     * marker's own channel of the same name is still read as the reducer's input
+     * - a `groupX`'s `y: 'sum'` sums the marker's `y`.
+     */
+    outputKeys?: Record<string, true>;
+    /** svelteplot's own function for this type, taking channels first and options second. */
+    run: (channels: Row, options: Row) => Row;
+    /** Fixes the split props before svelteplot sees them. */
+    prepare?: (args: TransformArgs) => TransformArgs;
+    /** Fixes the marker after all of its transforms have been merged onto it. */
+    finish?: (marker: Row) => Row;
+};

package/dist/types/phases/transforms/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/types/phases/transforms/phase.d.ts

@@ -0,0 +1,40 @@
+import type { Series } from '../../plots/data/common';
+import type { MarkerTransform } from '../../transforms';
+import type { PlotAxes } from '../../../phases/data/PlotAxes';
+/** A row the plot-level transforms produced: the source row's fields, plus whatever channels they add (often symbol-keyed). */
+export type ProcessedRow = Record<string | symbol, unknown>;
+/** A channel as svelteplot reads it off a processed row: a field key, a symbol key, or a function. */
+export type ProcessedChannel = string | symbol | ((row: any) => unknown);
+/** The position channels a processed row can carry. */
+export type ProcessedChannelName = 'x' | 'y' | 'x1' | 'x2' | 'y1' | 'y2';
+/**
+ * Every visible series' rows after the plot-level transforms, as one set.
+ * With no transforms, they're the source rows read by the series' own `x`/`y`.
+ */
+export type ProcessedData = {
+    /** Every row, each tagged with its series name under `SERIES_KEY`. */
+    data: ProcessedRow[];
+    /** The channels that read those rows: the series' `x`/`y`, or what the transforms set (`x1`/`x2`, `y1`/`y2`…). */
+    channels: Partial<Record<ProcessedChannelName, ProcessedChannel>>;
+    /** The transforms' own mark options (e.g. a bin's insets), for the marks that draw these rows. */
+    options: Record<string, unknown>;
+    /** The transforms the rows went through, so a mark can apply each type's `finish` fix. */
+    transforms: MarkerTransform[];
+};
+/** What the shared "transforms" stage reads from and writes to a plot's state. */
+export type TransformsStageState = {
+    resolvedSeries?: Series<any>[];
+    axes?: PlotAxes;
+    /** Each series' gap fills, by series id: the value each missing row is drawn at. */
+    gapFillMaps?: Map<string, Map<unknown, {
+        value: number;
+        kind: string;
+    }>>;
+    transforms?: MarkerTransform[];
+    processedData?: ProcessedData;
+};
+/** What differs between plots in the shared "transforms" stage. */
+export type TransformsStageOptions<TState extends TransformsStageState, TCtx> = {
+    /** The transforms to run. Defaults to the plot's own `transforms`. */
+    transforms?: (state: TState, ctx: TCtx) => MarkerTransform[];
+};

package/dist/types/phases/transforms/phase.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/area/props.d.ts

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { AxisBasedStylesConfig } from '../../layout/styles';
+import type { AreaStyle } from '../styling';
+/** `AreaPlot`'s public props. */
+export type AreaPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `AreaPlot`'s core draws from. */
+export type AreaPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/area/props.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/area/state.d.ts

@@ -0,0 +1,6 @@
+import type { AreaStyle } from '../styling';
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+/** AreaPlot's pipeline state: the shared axis-based state, with no extras of its own. */
+export type AreaPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
+/** The environment every AreaPlot phase reads from, alongside the growing state. */
+export type AreaPlotCtx = AxisPlotCtx;

package/dist/types/plots/area/state.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/bar/props.d.ts

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { GapsAwarePlotStylesConfig } from '../../layout/styles';
+import type { BarSegmentStyle } from '../segments/common';
+/** `BarPlot`'s public props. */
+export type BarPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `BarPlot`'s core draws from. */
+export type BarPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/bar/props.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/bar/state.d.ts

@@ -0,0 +1,6 @@
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+import type { BarSegmentStyle } from '../segments/common';
+/** BarPlot's pipeline state: the shared axis-based state. */
+export type BarPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, BarSegmentStyle>;
+/** The environment every BarPlot phase reads from, alongside the growing state. */
+export type BarPlotCtx = AxisPlotCtx;

package/dist/types/plots/bar/state.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/camera.d.ts

@@ -1,6 +1,6 @@
-import type { EasingName, EasingFn } from '../charts/interpolate';
+import type { EasingName, EasingFn } from '../misc/easing';
 import type { GeoInsetLocation } from '../markers/geo';
-/** What the camera frames. `features` shares its id space with `segments`/`featureId`. `center` has no extent of its own — see `GeoCameraConfig.zoom`. */
+/** What the camera frames. `features` shares its id space with `segments`/`featureId`. `center` has no extent of its own - see `GeoCameraConfig.zoom`. */
 export type GeoCameraTarget = {
     features: string[];
 } | {
@@ -8,33 +8,23 @@ export type GeoCameraTarget = {
 } | {
     bounds: GeoJSON.GeoJsonObject;
 };
-/**
- * How the camera moves to a newly resolved target.
- * - `progress` unset: auto-plays once over `duration` ms, eased by `easing`.
- * - `progress` set (a live 0–1 value, e.g. from scroll): renders the move as
- *   a pure function of it instead — stalls/reverses with the input.
- */
+/** How the camera moves to a new target: auto-played over `duration` ms, or driven by a live 0-1 `progress`. */
 export type GeoCameraTransition = {
     /** Auto-play duration in ms, ignored once `progress` is set. Defaults to 750. */
     duration?: number;
     /** Same `EasingName | EasingFn` vocabulary as `styles.gaps`/`TimelineConfig.interpolate`. */
     easing?: EasingName | EasingFn;
-    /** A live 0–1 value the host drives itself instead of an auto-played duration. */
+    /** A live 0-1 value the host drives itself instead of an auto-played duration. */
     progress?: number;
-    /** Which way to interpolate rotation when ambiguous — only relevant for `orthographic`. `'shortest'` (default) or `'longest'`. No-op for 2D projections. */
+    /** Which way to interpolate rotation when ambiguous - only relevant for `orthographic`. `'shortest'` (default) or `'longest'`. No-op for 2D projections. */
     direction?: 'shortest' | 'longest';
 };
-/**
- * `coordinates.camera` — `GeoPlot`'s declarative "current viewpoint": frames,
- * zooms and anchors on `target`, animated on change. Realized as a
- * pixel-space pan/zoom transform for 2D projections, plus a `rotate`
- * override for `orthographic`. Composes with interactive `coordinates.pan`/`zoom`/`rotate`.
- */
+/** `coordinates.camera`: the viewpoint `GeoPlot` frames on `target`, animated on change. */
 export type GeoCameraConfig = {
     target: GeoCameraTarget;
     /** Multiplier on the auto-fit scale for a `features`/`bounds` target (`1` = tight fit). For a `center` target, used directly as the pixel scale instead. */
     zoom?: number;
-    /** Where the framed target lands within the plot frame — the same 9-point vocabulary `inset` markers use. Defaults to `'middle-middle'`. */
+    /** Where the framed target lands within the plot frame - the same 9-point vocabulary `inset` markers use. Defaults to `'middle-middle'`. */
     anchor?: GeoInsetLocation;
     /** Pixel gap kept between the framed target and whichever edge(s) `anchor` pushes it toward. Defaults to 24. */
     padding?: number;

package/dist/types/plots/constants.d.ts

@@ -1,27 +1,35 @@
 /**
  * Unified positional anchor for value labels across all plot kinds.
  *
- * - `'outside'` — beyond the tip of the mark (above a vertical bar, to the
+ * - `'outside'` - beyond the tip of the mark (above a vertical bar, to the
  *   far end of a horizontal bar or line). This is the only value with no
  *   direct svelteplot equivalent; the plot computes dx/dy internally.
- * - `'start'` — at the tip of the mark, just inside (top of a bar, far end
+ * - `'start'` - at the tip of the mark, just inside (top of a bar, far end
  *   of a pyramid bar from zero, right of a line's last point).
- * - `'middle'` — centred on the mark.
- * - `'end'` — at the baseline/zero end of the mark.
+ * - `'middle'` - centred on the mark.
+ * - `'end'` - at the baseline/zero end of the mark.
  */
 export type ValueAnchor = 'outside' | 'start' | 'middle' | 'end';
-export type SymbolType = 'circle' | 'square' | 'triangle' | 'line';
+/**
+ * Shared by two unrelated renderers: a `dot` mark's own point shape
+ * (delegated to svelteplot/d3-shape) and a discrete legend item's own icon
+ * (`DiscreteSymbolIcon.svelte`, the same shape fitted to the icon). `'line'` is legend-only - it represents
+ * a Line series' own swatch there, but isn't a real d3-shape symbol name, so
+ * a `dot` mark (or the `symbol` channel) given `'line'` renders as
+ * `'circle'` instead.
+ */
+export type SymbolType = 'circle' | 'square' | 'triangle' | 'line' | 'diamond' | 'star' | 'cross';
 export type LineStyle = 'solid' | 'dashed' | 'dotted' | 'dashdot';
 export type LineCap = 'butt' | 'round' | 'square';
 export type LineJoin = 'arcs' | 'bevel' | 'miter' | 'miter-clip' | 'round';
-/** `font-weight` keyword accepted by any text styling. */
-export type FontWeight = 'normal' | 'bold';
+/** `font-weight` accepted by any text styling: a keyword, or a numeric weight (100-900). */
+export type FontWeight = 'normal' | 'bold' | number;
 /** `font-style` keyword accepted by any text styling. */
 export type FontStyleKeyword = 'normal' | 'italic';
 /**
  * Horizontal text anchor. `'outside'` is only meaningful where the consuming
  * mark resolves it per-point from a signed x value (currently `HoverMarker`
- * only) — it anchors the label away from zero: `'start'` (extending right)
+ * only) - it anchors the label away from zero: `'start'` (extending right)
  * for a positive x, `'end'` (extending left) for negative. Elsewhere it's
  * treated the same as `'start'`.
  */

package/dist/types/plots/data/common.d.ts

@@ -1,40 +1,48 @@
-import type { AxisValue } from '../../layout/scales';
+import type { AxisValue, AxisChannelName, ChannelAccessors } from '../../layout/mapping';
 /**
  * A field key or accessor function. Mirrors the shorthand used across plots
- * so chart-level encodings (`x`, `y`, `z`, facet, timeline) feel consistent
- * with the plot-level series definitions.
+ * so chart-level encodings (`x`, `y`, `color`, facet, timeline) feel
+ * consistent with the plot-level series definitions.
  */
 export type Accessor<TRow extends Record<string, unknown>, V> = keyof TRow | ((d: TRow) => V);
 /**
  * A plot series: a name, x/y accessors and the rows it draws. Shared as-is by
- * every mark (line, bar, …) — none of them need anything beyond this shape;
+ * every mark (line, bar, …) - none of them need anything beyond this shape;
  * visual styling lives separately in `segments`.
  */
 export type Series<T extends Record<string, unknown> = Record<string, unknown>> = {
     name: string;
-    x: Accessor<T, AxisValue>;
-    y: Accessor<T, AxisValue>;
-    z?: Accessor<T, unknown>;
+    /** Tells apart series that share a `name`, such as one per facet panel. Defaults to `name`. */
+    id?: string;
+    /** The facet panel the series belongs to, once the "facet" phase splits it. */
+    panel?: string;
+    /** Horizontal position. A plot reading one position channel only (a histogram) takes either alone. */
+    x?: Accessor<T, AxisValue>;
+    /** Vertical position. */
+    y?: Accessor<T, AxisValue>;
+    /** The `color` channel's own accessor - a pre-built series is already one group, so this is purely the color value (per-name for most plot kinds; per-cell for HeatmapPlot). */
+    color?: Accessor<T, unknown>;
     data: T[];
 };
+/** The channels a pre-built {@link Series} carries itself, so a plot given `series` takes none of them. */
+type SeriesChannelName = AxisChannelName | 'color' | 'grouping';
 /**
- * Pre-built series. Mutually exclusive with {@link DataProps} — takes
- * precedence when both could apply.
+ * Pre-built series. Mutually exclusive with {@link DataProps} - takes
+ * precedence when both could apply. Any channel a series doesn't carry
+ * itself is still a plot-level prop.
  */
 export type SeriesProps<T extends Record<string, unknown>> = {
     series: Series<T>[];
     data?: never;
-    x?: never;
-    y?: never;
-    z?: never;
-};
+} & {
+    [K in SeriesChannelName]?: never;
+} & Omit<ChannelAccessors<T>, SeriesChannelName>;
 /**
  * Flat rows to group into series, as an alternative to {@link SeriesProps}.
+ * Takes every channel; `x`/`y` are required.
  */
 export type DataProps<T extends Record<string, unknown>> = {
     series?: never;
     data: T[];
-    x: Accessor<T, AxisValue>;
-    y: Accessor<T, AxisValue>;
-    z?: Accessor<T, unknown>;
-};
+} & ChannelAccessors<T> & Required<Pick<ChannelAccessors<T>, AxisChannelName>>;
+export {};

package/dist/types/plots/data/geo.d.ts

@@ -3,7 +3,7 @@ import type { Accessor } from './common';
  * One GeoJSON feature, generically typed over its `properties`. Intersected
  * with `Record<string, unknown>` so it satisfies the same generic bound
  * every other row type in this package does (e.g. `TooltipConfig<TRow
- * extends Record<string, unknown>>`) — GeoJSON's own `Feature` type has no
+ * extends Record<string, unknown>>`) - GeoJSON's own `Feature` type has no
  * index signature on its own.
  */
 export type GeoFeature<TProps extends Record<string, unknown> = Record<string, unknown>> = GeoJSON.Feature<GeoJSON.Geometry, TProps> & Record<string, unknown>;
@@ -12,7 +12,7 @@ export type GeoJsonInput<TProps extends Record<string, unknown>> = GeoJSON.Featu
  * Minimal structural shape of a TopoJSON `Topology` object. Deliberately not
  * imported from `topojson-client`'s own types, so referencing it never forces
  * module resolution of that (optional peer) package at typecheck time for
- * consumers who haven't installed it — see `$lib/plots/utils/topojson`.
+ * consumers who haven't installed it - see `$lib/plots/utils/topojson`.
  */
 export type Topology = {
     type: 'Topology';
@@ -25,42 +25,56 @@ export type Topology = {
     bbox?: number[];
 };
 /**
- * Data contract for GeoPlot — the geo analog of {@link DataProps}/{@link SeriesProps}
- * (`$lib/types/plots/data/common`). There's no x/y/z axis pair for geographic data:
+ * Data contract for GeoPlot - the geo analog of {@link DataProps}/{@link SeriesProps}
+ * (`$lib/types/plots/data/common`). There's no x/y axis pair for geographic data:
  * `data` IS the map.
  */
 export type GeoDataProps<TProps extends Record<string, unknown> = Record<string, unknown>> = {
     /**
      * GeoJSON is always accepted. A TopoJSON `Topology` is also accepted, but
      * only converted at runtime if `topojson-client` is installed (an optional
-     * peer dependency) — see `object`.
+     * peer dependency) - see `object`.
      */
     data: GeoJsonInput<TProps> | Topology;
     /**
-     * Required when `data` is a `Topology` — the key under `topology.objects`
+     * Required when `data` is a `Topology` - the key under `topology.objects`
      * to convert via topojson-client's `feature()`. Ignored for GeoJSON input.
      */
     object?: string;
     /**
-     * Resolves each feature's stable id — used as the `segments` lookup key
+     * Resolves each feature's stable id - used as the `segments` lookup key
      * (e.g. `segments.argentina`) and for hover/click identification. Defaults
      * to `feature.id ?? feature.properties?.id ?? feature.properties?.name`.
      */
     featureId?: Accessor<GeoFeature<TProps>, string>;
     /**
-     * Optional continuous value accessor for choropleth coloring (mirrors
-     * heatmap's `z`). A feature with no `value` (or when omitted entirely)
+     * Optional continuous color-value accessor for choropleth coloring - the
+     * channel driving the ramp (mirrors heatmap's `color`), configured via
+     * `scales.color`. A feature with no `color` (or when omitted entirely)
      * falls back to `styles.fill`/`segments`.
      */
-    value?: (feature: GeoFeature<TProps>) => number | undefined;
+    color?: (feature: GeoFeature<TProps>) => number | undefined;
+    /**
+     * Optional structural grouping key - splits features into named buckets
+     * for `segments` to address by name (e.g. `segments.global_south`),
+     * independent of `color`. Unlike the axis-based plot kinds, this has no
+     * implicit default: `color` here is a per-feature *continuous* value, not
+     * a series-splitting key, so defaulting `grouping` to `color` would try
+     * to bucket by every distinct numeric value instead of leaving features
+     * ungrouped. A feature whose `grouping` value has no matching `segments`
+     * key simply falls through to `segments.default`/the plot-level ramp.
+     */
+    grouping?: (feature: GeoFeature<TProps>) => string | undefined;
+    /** Continuous or categorical opacity-value accessor - configure the ramp via `scales.opacity`. */
+    opacity?: (feature: GeoFeature<TProps>) => number | undefined;
     /**
      * Excludes matching parts of a feature's geometry from the map's own
-     * rendering and hover/click matching — e.g. so a separate `inset` marker
+     * rendering and hover/click matching - e.g. so a separate `inset` marker
      * (via its own `featurePartsFilter`) can take over showing that part
      * elsewhere without it being drawn twice. Runs once per disjoint part of
      * each feature's geometry (each polygon of a `MultiPolygon`, each line of
      * a `MultiLineString`; any other geometry type is a single part). Return
-     * `true` to exclude that part — excluding every part of a feature drops
+     * `true` to exclude that part - excluding every part of a feature drops
      * it entirely, which also covers omitting a whole feature from the map.
      * `segments` styling is unaffected (still keyed by whole-feature
      * `featureId`, applied to whatever geometry remains).

package/dist/types/plots/gaps.d.ts

@@ -1,54 +1,35 @@
-import type { EasingName } from '../charts/interpolate';
-import type { AxisValue } from '../layout/scales';
-/**
- * How one gap zone bridges its hole: `interpolate` eases the synthetic
- * segment's value between its two endpoints (defaults to `'linear'`, a
- * straight line); `style` is the per-mark shape drawn for it
- * ({@link LineSegmentStyle} for `LinePlot`), independent of that plot
- * kind's own default marker style unless the caller repeats it.
- */
+import type { EasingName } from '../misc/easing';
+import type { AxisValue } from '../layout/mapping';
+/** How one gap zone is bridged: `interpolate` eases the value (default `'linear'`), `style` draws it. */
 export type GapZoneConfig<TStyle> = {
     interpolate?: EasingName;
     style?: TStyle;
 };
 /**
- * A leading/trailing gap has only one real boundary — `x` (required to opt
- * in) is the domain value the synthetic segment extends to, and `y` is the
- * value it reaches there (defaults to holding the nearest real point's
- * value, i.e. a flat extrapolation). Omitting the zone entirely leaves that
- * end of the series unfilled — extrapolating without an explicit target
- * would imply data that doesn't exist.
- *
- * On `LinePlot`, `x`'s value is the actual spatial target the bridge draws
- * out to (its axis is continuous). On `BarPlot`/`PyramidPlot`, each gap row
- * already has its own real category, so `x`'s *presence* is only the opt-in
- * gate — its value isn't read; `y` is what drives the fill.
+ * A gap before the first or after the last real point: bridged out to `x`
+ * (required to fill it), reaching `y` there (default: the nearest real
+ * value). On bar plots only `x`'s presence matters.
  */
 export type OpenGapZoneConfig<TStyle> = GapZoneConfig<TStyle> & {
     x: AxisValue;
     y?: AxisValue;
 };
-/**
- * One series' gap-fill config: `start` (before its first real point),
- * `middle` (any internal run of missing rows, bounded by real data on both
- * sides) and `end` (after its last real point). A row counts as missing
- * when its resolved value is `null`, `undefined`, or `NaN` — the same
- * convention svelteplot's own `Line` mark already uses to break the line
- * there. See {@link GapsConfig} for how this is keyed per series on a
- * gap-aware plot kind's `styles.gaps`.
- */
+/** One series' gap fill: `start`, `middle` and `end`. A row is missing when its value is `null`, `undefined` or `NaN`. */
 export type GapZonesConfig<TStyle> = {
     start?: OpenGapZoneConfig<TStyle>;
     middle?: GapZoneConfig<TStyle>;
     end?: OpenGapZoneConfig<TStyle>;
 };
-/**
- * The `gaps` field a gap-aware plot kind's `styles` accepts (see
- * {@link GapsAwarePlotStylesConfig}, `types/layout/styles.ts`) — series name
- * (or `'default'` for all series) to that series' {@link GapZonesConfig}.
- * Mirrors `SegmentsConfig`'s series-keyed shape: a named entry applies only
- * to that series; `'default'` fills in whichever of its zones
- * (`start`/`middle`/`end`) the named entry itself leaves unset, at zone
- * granularity rather than a merged style.
- */
+/** `styles.gaps`: series name (or `'default'`) to its {@link GapZonesConfig}; `'default'` fills the zones a named entry leaves unset. */
 export type GapsConfig<TStyle> = Record<string, GapZonesConfig<TStyle>>;
+/** A point sampled along a gap-fill bridge, already resolved to plot data-space numbers. */
+export type GapPoint = {
+    x: number;
+    y: number;
+};
+/** One gap row's resolved fill - the interpolated value to render instead of the missing one, and which zone produced it. */
+export type DiscreteGapFill<TStyle> = {
+    value: number;
+    kind: 'start' | 'middle' | 'end';
+    style?: TStyle;
+};