@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/plots/scatter/markers.js

@@ -0,0 +1,129 @@
+import { ProcessedPositions } from '../../phases/transforms/ProcessedPositions';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+import { ValueLabels } from '../../layout/styles/ValueLabels';
+/**
+ * ScatterPlot's `styles.values` as one `'text'` marker over the same
+ * processed rows its dots draw, each labelled with its own `y` value. A label
+ * sits beside its point and flips to the other side where its text would
+ * cross the plot's edge (`edgeAware`).
+ */
+export function buildValueLabels(labels, state, ctx) {
+    const { processedData } = state;
+    if (!processedData?.data.length)
+        return [];
+    const { font, format } = labels;
+    const position = ProcessedPositions.of(processedData);
+    const nameOf = (d) => String(d[SERIES_KEY]);
+    const valueOf = ValueLabels.valueOf(state);
+    return [
+        {
+            type: 'text',
+            data: processedData.data,
+            x: position.x,
+            y: position.y,
+            text: (d) => format(Number(valueOf(d)), nameOf(d)),
+            styles: {
+                ...font,
+                fill: font?.fill ?? ctx.cfg.axis.color,
+                fontSize: font?.fontSize ?? 11,
+                fontWeight: font?.fontWeight ?? 500,
+                dx: font?.dx ?? 8,
+                dy: font?.dy ?? 0,
+                textAnchor: labels.textAnchor ?? 'start',
+                lineAnchor: font?.lineAnchor ?? 'middle'
+            },
+            edgeAware: true
+        }
+    ];
+}
+/**
+ * ScatterPlot's "markers" phase: one `'dot'` marker per visual segment of the
+ * rows the "transforms" phase left, in their own order, so a reordering
+ * transform decides which dots paint on top - prepended onto whatever the
+ * "statistics" phase already put in `state.markers` - and its value labels on
+ * top of everything.
+ */
+export function buildMarks(state, ctx) {
+    const { channels, colorForSeries, scales, flat } = state;
+    const { cfg, interaction } = ctx;
+    const r = channels.r;
+    const rFn = r === undefined || typeof r === 'number' ? r : r.accessor;
+    const opacityFn = channels.opacity?.accessor;
+    const symbolFn = channels.symbol?.accessor;
+    /**
+     * `color`/`grouping` splits `flat` into one series per category, so each
+     * marker call below only ever sees one series' own rows - computing a
+     * channel's domain from just that slice would collapse a categorical
+     * domain to a single value (every row in a series shares the same
+     * category by construction) and skew a continuous one to that series'
+     * own range. Computed once here, across every (non-disabled) series'
+     * combined rows, and passed down as an explicit `domain` so each
+     * marker's own local computation (in `DotMarker.svelte`) is overridden
+     * instead of silently re-deriving a wrong, per-series one.
+     */
+    function globalValuesFor(fn) {
+        if (!fn || !flat?.length)
+            return [];
+        return flat.map((d) => fn(d)).filter((v) => v != null);
+    }
+    function globalOpacityDomain() {
+        const vals = globalValuesFor(opacityFn);
+        if (!vals.length)
+            return undefined;
+        const allNumeric = vals.every((v) => Number.isFinite(Number(v)));
+        return allNumeric
+            ? [Math.min(...vals.map(Number)), Math.max(...vals.map(Number))]
+            : [...new Set(vals.map(String))];
+    }
+    function globalSymbolDomain() {
+        const vals = globalValuesFor(symbolFn);
+        return vals.length ? [...new Set(vals.map(String))] : undefined;
+    }
+    const channelScales = opacityFn || symbolFn
+        ? {
+            opacity: opacityFn
+                ? { ...scales.opacity, domain: scales.opacity?.domain ?? globalOpacityDomain() }
+                : undefined,
+            symbol: symbolFn
+                ? { ...scales.symbol, domain: scales.symbol?.domain ?? globalSymbolDomain() }
+                : undefined
+        }
+        : undefined;
+    const markers = [];
+    (state.processedGroups ?? []).forEach((group) => {
+        const defaultColor = colorForSeries(group.series.name);
+        const disabledDots = interaction?.dotsFor(group.series.name);
+        for (const seg of group.visualSegments) {
+            const dotStyle = seg.styles;
+            markers.push({
+                type: 'dot',
+                data: seg.data,
+                // Forwarded raw (a field key or function, whatever `series.x`/`.y`
+                // is) rather than pre-resolved into a closure - `DotMarker.svelte`
+                // and svelteplot's own `resolve()` already handle a field-key
+                // string per row, and only a literal string (not a function)
+                // lets svelteplot's axis-title auto-inference see the field name.
+                // `keyof TData` is always a real string key in practice (every
+                // row is a plain field-keyed record), just not provably so to
+                // TypeScript here.
+                x: group.series.x,
+                y: group.series.y,
+                r: rFn,
+                opacity: opacityFn,
+                symbol: symbolFn,
+                scales: channelScales,
+                styles: {
+                    dotRadius: disabledDots?.dotRadius ?? dotStyle.dotRadius ?? cfg.scatter.dotRadius,
+                    dotFill: disabledDots?.dotFill ?? dotStyle.dotFill ?? defaultColor,
+                    dotSymbol: disabledDots?.dotSymbol ?? dotStyle.dotSymbol,
+                    dotStroke: disabledDots?.dotStroke ?? dotStyle.dotStroke,
+                    dotStrokeWidth: disabledDots?.dotStrokeWidth ?? dotStyle.dotStrokeWidth,
+                    dotFillOpacity: disabledDots?.dotFillOpacity ?? dotStyle.dotFillOpacity,
+                    dotStrokeOpacity: disabledDots?.dotStrokeOpacity ?? dotStyle.dotStrokeOpacity,
+                    dotStrokeDasharray: disabledDots?.dotStrokeDasharray ?? dotStyle.dotStrokeDasharray
+                }
+            });
+        }
+    });
+    return markers;
+}

package/dist/plots/utils/ChannelName.d.ts

@@ -0,0 +1,9 @@
+/** The name a channel reads under on a legend, taken from the function that computes it. */
+export declare class ChannelName {
+    /**
+     * `channel`'s own name, when it is a function with one worth showing: not
+     * anonymous, and not the name of the property it was assigned to (`color`
+     * for a `color: (d) => ...`), which says nothing a legend doesn't.
+     */
+    static of(channel: unknown, property: string): string | undefined;
+}

package/dist/plots/utils/ChannelName.js

@@ -0,0 +1,14 @@
+/** The name a channel reads under on a legend, taken from the function that computes it. */
+export class ChannelName {
+    /**
+     * `channel`'s own name, when it is a function with one worth showing: not
+     * anonymous, and not the name of the property it was assigned to (`color`
+     * for a `color: (d) => ...`), which says nothing a legend doesn't.
+     */
+    static of(channel, property) {
+        if (typeof channel !== 'function')
+            return undefined;
+        const name = channel.name;
+        return name && name !== property && name !== 'anonymous' ? name : undefined;
+    }
+}

package/dist/plots/utils/accessors.d.ts

@@ -1,6 +1,6 @@
 /**
  * Converts a field key or a function into a data accessor function.
- * Svelteplot marks expect `(d: T) => value` — this bridges the
+ * Svelteplot marks expect `(d: T) => value` - this bridges the
  * shorthand key notation used in series definitions.
  */
 export declare function resolveAccessor<T extends Record<string, unknown>>(field: keyof T | ((d: T) => any)): (d: T) => any;

package/dist/plots/utils/accessors.js

@@ -1,10 +1,12 @@
 /**
  * Converts a field key or a function into a data accessor function.
- * Svelteplot marks expect `(d: T) => value` — this bridges the
+ * Svelteplot marks expect `(d: T) => value` - this bridges the
  * shorthand key notation used in series definitions.
  */
 export function resolveAccessor(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-field) {
+field
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
     return typeof field === 'function' ? field : (d) => d[field];
 }

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

@@ -1,20 +1,16 @@
 import type { Series } from '../../types/plots/data/common';
-import type { GapZonesConfig, GapZoneConfig } from '../../types/plots/gaps';
+import type { DiscreteGapFill, GapPoint, GapZonesConfig, GapZoneConfig } from '../../types/plots/gaps';
 import type { AreaStyle } from '../../types/plots/styling';
+import type { AxisChannelName } from '../../types/layout/mapping';
 /**
  * Resolves one series' zone config out of `LinePlot`'s full `gaps` prop: a
  * named entry (keyed by the series' own `name`) applies only to that
  * series; `'default'` fills in whichever zone the named entry itself leaves
  * unset. Unlike `segments`' own specific/default resolution (which
- * concatenates two rule lists), this merges at zone granularity — there's
+ * concatenates two rule lists), this merges at zone granularity - there's
  * no list to concatenate, just three independent slots.
  */
-export declare function resolveGapsForSeries<TStyle>(gaps: Record<string, GapZonesConfig<TStyle>>, seriesName: 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;
-};
+export declare function resolveGapsForSeries<TStyle>(gaps: Record<string, GapZonesConfig<TStyle>> | undefined, seriesName: string): GapZonesConfig<TStyle>;
 export type GapRun<TStyle> = {
     kind: 'start' | 'middle' | 'end';
     zone: GapZoneConfig<TStyle>;
@@ -28,25 +24,24 @@ export declare function isGapValue(v: unknown): boolean;
  * configured, builds the eased bridge points that visually fill it. Rows
  * are sorted by `x` first, so an out-of-order series is handled the same as
  * a sorted one. A series with no valid (non-missing) rows at all produces
- * no runs — there's nothing to bridge from or to.
+ * no runs - there's nothing to bridge from or to.
  */
 export declare function resolveGapRuns<T extends Record<string, unknown>, TStyle>(series: Series<T>, gaps: GapZonesConfig<TStyle>): GapRun<TStyle>[];
-/** 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;
-};
 /**
  * Bar/pyramid analog of `resolveGapRuns`: a category axis has no continuous
  * bridge to sample, so this returns one interpolated value per *individual*
  * gap row instead. Runs are detected by `series.data`'s own array order
- * (not a numeric `x` sort like `resolveGapRuns` — a category axis is often
+ * (not a numeric `x` sort like `resolveGapRuns` - a category axis is often
  * nominal, so there's no meaningful numeric ordering to sort by). Keyed by
  * row object reference rather than category, since a series' `y` accessor
- * may be an arbitrary function — there's no general way to write the
+ * may be an arbitrary function - there's no general way to write the
  * interpolated value back onto a row, so callers look it up here instead.
  */
-export declare function resolveDiscreteGapFills<T extends Record<string, unknown>, TStyle>(series: Series<T>, gaps: GapZonesConfig<TStyle>): Map<T, DiscreteGapFill<TStyle>>;
-/** Field-by-field style fallback for a discrete gap-fill marker — mirrors how `buildGapMarkers.ts` merges a line gap zone's style under `cfg.line.gap`. */
+export declare function resolveDiscreteGapFills<T extends Record<string, unknown>, TStyle>(series: Series<T>, gaps: GapZonesConfig<TStyle>, valueAxis?: AxisChannelName): Map<T, DiscreteGapFill<TStyle>>;
+/** Field-by-field style fallback for a discrete gap-fill marker - mirrors how `buildGapMarkers.ts` merges a line gap zone's style under `cfg.line.gap`. */
 export declare function resolveGapAreaStyle(zoneStyle: AreaStyle | undefined, defaultColor: string, gapDefaults: AreaStyle): AreaStyle;
+/**
+ * Each series' gap fills, keyed by series id - the interpolated value a
+ * `styles.gaps` zone gives each missing row along `valueAxis`, resolved per series like `segments`.
+ */
+export declare function buildGapFillMaps<TData extends Record<string, unknown>, TStyle>(seriesList: Series<TData>[], gaps: Record<string, GapZonesConfig<TStyle>> | undefined, valueAxis?: AxisChannelName): Map<string, Map<TData, DiscreteGapFill<TStyle>>>;

package/dist/plots/utils/gaps.js

@@ -1,15 +1,16 @@
+import { seriesIdOf } from '../../utils/grouping';
 import { resolveAccessor } from './accessors';
-import { resolveEasing } from '../../utils/interpolate';
+import { Interpolation } from '../../utils/Interpolation';
 const DEFAULT_KEY = 'default';
 /**
  * Resolves one series' zone config out of `LinePlot`'s full `gaps` prop: a
  * named entry (keyed by the series' own `name`) applies only to that
  * series; `'default'` fills in whichever zone the named entry itself leaves
  * unset. Unlike `segments`' own specific/default resolution (which
- * concatenates two rule lists), this merges at zone granularity — there's
+ * concatenates two rule lists), this merges at zone granularity - there's
  * no list to concatenate, just three independent slots.
  */
-export function resolveGapsForSeries(gaps, seriesName) {
+export function resolveGapsForSeries(gaps = {}, seriesName) {
     const specific = gaps[seriesName];
     const defaults = gaps[DEFAULT_KEY];
     if (!specific)
@@ -19,7 +20,7 @@ export function resolveGapsForSeries(gaps, seriesName) {
     return {
         start: specific.start ?? defaults.start,
         middle: specific.middle ?? defaults.middle,
-        end: specific.end ?? defaults.end,
+        end: specific.end ?? defaults.end
     };
 }
 const BRIDGE_STEPS = 24;
@@ -29,7 +30,7 @@ export function isGapValue(v) {
 }
 /** Samples `BRIDGE_STEPS + 1` points between two endpoints, x moving linearly and y eased by the zone's `interpolate`. */
 function buildBridge(from, to, zone) {
-    const ease = resolveEasing(zone.interpolate);
+    const ease = Interpolation.buildEasing(zone.interpolate);
     const points = [];
     for (let i = 0; i <= BRIDGE_STEPS; i++) {
         const t = i / BRIDGE_STEPS;
@@ -43,10 +44,12 @@ function buildBridge(from, to, zone) {
  * configured, builds the eased bridge points that visually fill it. Rows
  * are sorted by `x` first, so an out-of-order series is handled the same as
  * a sorted one. A series with no valid (non-missing) rows at all produces
- * no runs — there's nothing to bridge from or to.
+ * no runs - there's nothing to bridge from or to.
  */
 export function resolveGapRuns(series, gaps) {
-    if (!gaps.start && !gaps.middle && !gaps.end)
+    if ((!gaps.start && !gaps.middle && !gaps.end) ||
+        series.x === undefined ||
+        series.y === undefined)
         return [];
     const xFn = resolveAccessor(series.x);
     const yFn = resolveAccessor(series.y);
@@ -63,7 +66,10 @@ export function resolveGapRuns(series, gaps) {
     const firstValid = validIdx[0];
     if (firstValid > 0 && gaps.start) {
         const to = pt(sorted[firstValid]);
-        const from = { x: Number(gaps.start.x), y: gaps.start.y != null ? Number(gaps.start.y) : to.y };
+        const from = {
+            x: Number(gaps.start.x),
+            y: gaps.start.y != null ? Number(gaps.start.y) : to.y
+        };
         runs.push({ kind: 'start', zone: gaps.start, points: buildBridge(from, to, gaps.start) });
     }
     if (gaps.middle) {
@@ -74,7 +80,7 @@ export function resolveGapRuns(series, gaps) {
                 runs.push({
                     kind: 'middle',
                     zone: gaps.middle,
-                    points: buildBridge(pt(sorted[a]), pt(sorted[b]), gaps.middle),
+                    points: buildBridge(pt(sorted[a]), pt(sorted[b]), gaps.middle)
                 });
             }
         }
@@ -82,7 +88,10 @@ export function resolveGapRuns(series, gaps) {
     const lastValid = validIdx[validIdx.length - 1];
     if (lastValid < sorted.length - 1 && gaps.end) {
         const from = pt(sorted[lastValid]);
-        const to = { x: Number(gaps.end.x), y: gaps.end.y != null ? Number(gaps.end.y) : from.y };
+        const to = {
+            x: Number(gaps.end.x),
+            y: gaps.end.y != null ? Number(gaps.end.y) : from.y
+        };
         runs.push({ kind: 'end', zone: gaps.end, points: buildBridge(from, to, gaps.end) });
     }
     return runs;
@@ -91,17 +100,18 @@ export function resolveGapRuns(series, gaps) {
  * Bar/pyramid analog of `resolveGapRuns`: a category axis has no continuous
  * bridge to sample, so this returns one interpolated value per *individual*
  * gap row instead. Runs are detected by `series.data`'s own array order
- * (not a numeric `x` sort like `resolveGapRuns` — a category axis is often
+ * (not a numeric `x` sort like `resolveGapRuns` - a category axis is often
  * nominal, so there's no meaningful numeric ordering to sort by). Keyed by
  * row object reference rather than category, since a series' `y` accessor
- * may be an arbitrary function — there's no general way to write the
+ * may be an arbitrary function - there's no general way to write the
  * interpolated value back onto a row, so callers look it up here instead.
  */
-export function resolveDiscreteGapFills(series, gaps) {
+export function resolveDiscreteGapFills(series, gaps, valueAxis = 'y') {
     const result = new Map();
-    if (!gaps.start && !gaps.middle && !gaps.end)
+    const accessor = series[valueAxis];
+    if ((!gaps.start && !gaps.middle && !gaps.end) || accessor === undefined)
         return result;
-    const yFn = resolveAccessor(series.y);
+    const yFn = resolveAccessor(accessor);
     const rows = series.data;
     const valueAt = (i) => Number(yFn(rows[i]));
     const validIdx = rows.reduce((acc, row, i) => {
@@ -112,7 +122,7 @@ export function resolveDiscreteGapFills(series, gaps) {
     if (validIdx.length === 0)
         return result;
     function fillRun(indices, from, to, zone, kind) {
-        const ease = resolveEasing(zone.interpolate);
+        const ease = Interpolation.buildEasing(zone.interpolate);
         const span = indices.length + 1;
         indices.forEach((idx, i) => {
             const t = (i + 1) / span;
@@ -142,7 +152,7 @@ export function resolveDiscreteGapFills(series, gaps) {
     }
     return result;
 }
-/** Field-by-field style fallback for a discrete gap-fill marker — mirrors how `buildGapMarkers.ts` merges a line gap zone's style under `cfg.line.gap`. */
+/** Field-by-field style fallback for a discrete gap-fill marker - mirrors how `buildGapMarkers.ts` merges a line gap zone's style under `cfg.line.gap`. */
 export function resolveGapAreaStyle(zoneStyle, defaultColor, gapDefaults) {
     return {
         fill: zoneStyle?.fill ?? gapDefaults.fill ?? defaultColor,
@@ -151,6 +161,16 @@ export function resolveGapAreaStyle(zoneStyle, defaultColor, gapDefaults) {
         strokeWidth: zoneStyle?.strokeWidth ?? gapDefaults.strokeWidth,
         strokeOpacity: zoneStyle?.strokeOpacity ?? gapDefaults.strokeOpacity,
         strokeDasharray: zoneStyle?.strokeDasharray ?? gapDefaults.strokeDasharray,
-        borderRadius: zoneStyle?.borderRadius ?? gapDefaults.borderRadius,
+        borderRadius: zoneStyle?.borderRadius ?? gapDefaults.borderRadius
     };
 }
+/**
+ * Each series' gap fills, keyed by series id - the interpolated value a
+ * `styles.gaps` zone gives each missing row along `valueAxis`, resolved per series like `segments`.
+ */
+export function buildGapFillMaps(seriesList, gaps, valueAxis = 'y') {
+    return new Map(seriesList.map((s) => [
+        seriesIdOf(s),
+        resolveDiscreteGapFills(s, resolveGapsForSeries(gaps, s.name), valueAxis)
+    ]));
+}

package/dist/plots/utils/geoAccessors.d.ts

@@ -1,9 +1,9 @@
 import type { GeoFeature } from '../../types/plots/data/geo';
 /**
- * Bounding-box center of a geometry's flattened coordinates — a cheap
+ * Bounding-box center of a geometry's flattened coordinates - a cheap
  * approximation used for default label placement, not a true
  * geographic/area centroid (no polygon-hole or geodesic-area weighting).
- * For hover-matching specifically, see `geometryPartCentroids` instead —
+ * For hover-matching specifically, see `geometryPartCentroids` instead -
  * this single combined point can land far from every actual part of a
  * multi-part geometry whose pieces are geographically spread out.
  */
@@ -20,10 +20,10 @@ export declare function splitGeometryParts(geometry: GeoJSON.Geometry): GeoJSON.
 /**
  * Like `geometryCentroid`, but returns one point per disjoint part instead
  * of a single bounding-box center across all of them. A `MultiPolygon`
- * whose parts are geographically far apart — e.g. Argentina's "Tierra del
+ * whose parts are geographically far apart - e.g. Argentina's "Tierra del
  * Fuego, Antártida e Islas del Atlántico Sur" province, whose `MultiPolygon`
  * spans the mainland island, the Antarctic sector, and the South Atlantic
- * islands in one feature — would otherwise get a single hover point
+ * islands in one feature - would otherwise get a single hover point
  * stranded somewhere between all of them, matching hovers over *none* of
  * the actually-rendered shapes. Multiple points attributed to the same
  * feature is fine for hover-matching (nearest point wins, whichever part
@@ -34,7 +34,7 @@ export declare function geometryPartCentroids(geometry: GeoJSON.Geometry): [numb
 /**
  * Keeps or drops each disjoint part of a geometry (see `splitGeometryParts`)
  * based on a per-part predicate, reassembling a geometry of the same type
- * from whatever survives — `null` if nothing does. Used to let a single
+ * from whatever survives - `null` if nothing does. Used to let a single
  * feature's geometry be split between the main map and an `inset` marker
  * (see `GeoDataProps.excludeParts`/`GeoInsetMarkerConfig.featurePartsFilter`)
  * without preprocessing the source data: e.g. a province whose `MultiPolygon`
@@ -48,7 +48,7 @@ export declare function filterGeometryParts(geometry: GeoJSON.Geometry, keep: (p
 /** Default `featureId`: `feature.id`, else `properties.id`, else `properties.name`. */
 export declare function defaultFeatureId<TProps extends Record<string, unknown>>(f: GeoFeature<TProps>): string;
 /**
- * `[minLon, minLat, maxLon, maxLat]` across every coordinate of a geometry —
+ * `[minLon, minLat, maxLon, maxLat]` across every coordinate of a geometry -
  * `null` for one with none (an empty `GeometryCollection`). Used by
  * `Plot.svelte`'s `dataLonLatBounds` to cap how far a tile layer's
  * letterboxed margin reaches (see `clampBoundsToDataPadding` in
@@ -57,14 +57,14 @@ export declare function defaultFeatureId<TProps extends Record<string, unknown>>
 export declare function geometryLonLatBounds(geometry: GeoJSON.Geometry): [number, number, number, number] | null;
 /**
  * Densifies a great-circle arc between two lon/lat points into `steps + 1`
- * points via spherical linear interpolation (slerp) — used to draw a `link`
+ * points via spherical linear interpolation (slerp) - used to draw a `link`
  * marker's geodesic curve through the `Geo` mark (see `Plot.svelte`).
  *
  * Not delegated to svelteplot's own `Link` mark: its 0.14.2 projection
  * integration (`Mark.svelte`'s paired-channel handling) reads a single
  * `row.x`/`row.y` pair regardless of channel suffix, so a mark bound to
  * `x1`/`y1`/`x2`/`y2` (never plain `x`/`y`) resolves every point as invalid
- * whenever the plot has an active `projection` scale — which GeoPlot always
+ * whenever the plot has an active `projection` scale - which GeoPlot always
  * does. `Geo` has no such limitation (geo marks are explicitly excluded from
  * that code path), so a manually-interpolated `LineString` feature sidesteps
  * the bug entirely while still producing the same geodesic visual.

package/dist/plots/utils/geoAccessors.js

@@ -49,10 +49,10 @@ function boundsCenter(coords) {
     return [(minX + maxX) / 2, (minY + maxY) / 2];
 }
 /**
- * Bounding-box center of a geometry's flattened coordinates — a cheap
+ * Bounding-box center of a geometry's flattened coordinates - a cheap
  * approximation used for default label placement, not a true
  * geographic/area centroid (no polygon-hole or geodesic-area weighting).
- * For hover-matching specifically, see `geometryPartCentroids` instead —
+ * For hover-matching specifically, see `geometryPartCentroids` instead -
  * this single combined point can land far from every actual part of a
  * multi-part geometry whose pieces are geographically spread out.
  */
@@ -84,10 +84,10 @@ export function splitGeometryParts(geometry) {
 /**
  * Like `geometryCentroid`, but returns one point per disjoint part instead
  * of a single bounding-box center across all of them. A `MultiPolygon`
- * whose parts are geographically far apart — e.g. Argentina's "Tierra del
+ * whose parts are geographically far apart - e.g. Argentina's "Tierra del
  * Fuego, Antártida e Islas del Atlántico Sur" province, whose `MultiPolygon`
  * spans the mainland island, the Antarctic sector, and the South Atlantic
- * islands in one feature — would otherwise get a single hover point
+ * islands in one feature - would otherwise get a single hover point
  * stranded somewhere between all of them, matching hovers over *none* of
  * the actually-rendered shapes. Multiple points attributed to the same
  * feature is fine for hover-matching (nearest point wins, whichever part
@@ -100,7 +100,7 @@ export function geometryPartCentroids(geometry) {
 /**
  * Keeps or drops each disjoint part of a geometry (see `splitGeometryParts`)
  * based on a per-part predicate, reassembling a geometry of the same type
- * from whatever survives — `null` if nothing does. Used to let a single
+ * from whatever survives - `null` if nothing does. Used to let a single
  * feature's geometry be split between the main map and an `inset` marker
  * (see `GeoDataProps.excludeParts`/`GeoInsetMarkerConfig.featurePartsFilter`)
  * without preprocessing the source data: e.g. a province whose `MultiPolygon`
@@ -118,11 +118,14 @@ export function filterGeometryParts(geometry, keep) {
         return keptParts[0];
     switch (geometry.type) {
         case 'MultiPolygon':
-            return { type: 'MultiPolygon', coordinates: keptParts.map((part) => part.coordinates) };
+            return {
+                type: 'MultiPolygon',
+                coordinates: keptParts.map((part) => part.coordinates)
+            };
         case 'MultiLineString':
             return {
                 type: 'MultiLineString',
-                coordinates: keptParts.map((part) => part.coordinates),
+                coordinates: keptParts.map((part) => part.coordinates)
             };
         case 'GeometryCollection':
             return { type: 'GeometryCollection', geometries: keptParts };
@@ -136,7 +139,7 @@ export function defaultFeatureId(f) {
     return String(f.id ?? props?.id ?? props?.name ?? '');
 }
 /**
- * `[minLon, minLat, maxLon, maxLat]` across every coordinate of a geometry —
+ * `[minLon, minLat, maxLon, maxLat]` across every coordinate of a geometry -
  * `null` for one with none (an empty `GeometryCollection`). Used by
  * `Plot.svelte`'s `dataLonLatBounds` to cap how far a tile layer's
  * letterboxed margin reaches (see `clampBoundsToDataPadding` in
@@ -171,14 +174,14 @@ function toDeg(rad) {
 }
 /**
  * Densifies a great-circle arc between two lon/lat points into `steps + 1`
- * points via spherical linear interpolation (slerp) — used to draw a `link`
+ * points via spherical linear interpolation (slerp) - used to draw a `link`
  * marker's geodesic curve through the `Geo` mark (see `Plot.svelte`).
  *
  * Not delegated to svelteplot's own `Link` mark: its 0.14.2 projection
  * integration (`Mark.svelte`'s paired-channel handling) reads a single
  * `row.x`/`row.y` pair regardless of channel suffix, so a mark bound to
  * `x1`/`y1`/`x2`/`y2` (never plain `x`/`y`) resolves every point as invalid
- * whenever the plot has an active `projection` scale — which GeoPlot always
+ * whenever the plot has an active `projection` scale - which GeoPlot always
  * does. `Geo` has no such limitation (geo marks are explicitly excluded from
  * that code path), so a manually-interpolated `LineString` feature sidesteps
  * the bug entirely while still producing the same geodesic visual.
@@ -193,11 +196,12 @@ export function greatCircleInterpolate(lon1, lat1, lon2, lat2, steps = 64) {
     const sinPhi2 = Math.sin(phi2);
     const cosPhi2 = Math.cos(phi2);
     const d = 2 *
-        Math.asin(Math.sqrt(Math.sin((phi2 - phi1) / 2) ** 2 + cosPhi1 * cosPhi2 * Math.sin((lambda2 - lambda1) / 2) ** 2));
+        Math.asin(Math.sqrt(Math.sin((phi2 - phi1) / 2) ** 2 +
+            cosPhi1 * cosPhi2 * Math.sin((lambda2 - lambda1) / 2) ** 2));
     if (!Number.isFinite(d) || d === 0) {
         return [
             [lon1, lat1],
-            [lon2, lat2],
+            [lon2, lat2]
         ];
     }
     const points = [];

package/dist/plots/utils/geoSegments.d.ts

@@ -1,14 +1,29 @@
+import type { ChannelScalesConfig } from '../../types/layout/scales';
 import type { Segment } from '../../types/plots/segments/config';
 import type { SegmentsConfig } from '../../types/plots/props';
-/** Feature-specific segments listed after 'default' so they override it on merge (see `resolveFeatureStyle`). */
-export declare function resolveSegmentsForFeature<TStyle>(segments: SegmentsConfig<TStyle>, featureId: string): Segment<TStyle>[];
 /**
- * A geo feature is atomic — `Segment.areas` (x/y range restriction) doesn't
+ * Feature-specific segments listed after 'default' so they override it on
+ * merge (see `resolveFeatureStyle`). When the feature has a resolved
+ * `grouping` bucket, that bucket's own entries are listed in between -
+ * `default` < grouping bucket < feature-specific, most specific last.
+ */
+export declare function resolveSegmentsForFeature<TStyle>(segments: SegmentsConfig<TStyle>, featureId: string, groupingValue?: string): Segment<TStyle>[];
+/**
+ * A geo feature is atomic - `Segment.areas` (x/y range restriction) doesn't
  * apply, so every entry under a key is treated as a flat style patch applied
- * in order: `'default'` entries apply first, feature-specific entries
- * override. This intentionally does NOT reuse `segments.ts`'s
- * `validateSegments` — its "only the first catch-all wins" warning assumes
- * area-based semantics that don't hold here, since every geo segment entry
- * merges rather than being dropped.
+ * in order: `'default'` entries apply first, then the grouping bucket's (if
+ * any), then feature-specific entries. This intentionally does NOT reuse
+ * `segments.ts`'s `validateSegments` - its "only the first catch-all wins"
+ * warning assumes area-based semantics that don't hold here, since every geo
+ * segment entry merges rather than being dropped.
+ */
+export declare function resolveFeatureStyle<TStyle extends object>(segments: SegmentsConfig<TStyle>, featureId: string, groupingValue?: string): TStyle;
+/**
+ * A feature's own effective `scales` override, if any of its matching
+ * segments (`default`, its grouping bucket, or itself) set one - the last
+ * (most specific) entry that defines `scales` wins outright, unlike
+ * `resolveFeatureStyle`'s field-by-field merge, since a ramp config isn't
+ * sensibly mergeable key-by-key (a `domain` from one entry and a `scheme`
+ * from another wouldn't be a coherent scale).
  */
-export declare function resolveFeatureStyle<TStyle extends object>(segments: SegmentsConfig<TStyle>, featureId: string): TStyle;
+export declare function resolveFeatureScales<TStyle>(segments: SegmentsConfig<TStyle>, featureId: string, groupingValue?: string): ChannelScalesConfig | undefined;

package/dist/plots/utils/geoSegments.js

@@ -1,17 +1,37 @@
 const DEFAULT_KEY = 'default';
-/** Feature-specific segments listed after 'default' so they override it on merge (see `resolveFeatureStyle`). */
-export function resolveSegmentsForFeature(segments, featureId) {
-    return [...(segments[DEFAULT_KEY] ?? []), ...(segments[featureId] ?? [])];
+/**
+ * Feature-specific segments listed after 'default' so they override it on
+ * merge (see `resolveFeatureStyle`). When the feature has a resolved
+ * `grouping` bucket, that bucket's own entries are listed in between -
+ * `default` < grouping bucket < feature-specific, most specific last.
+ */
+export function resolveSegmentsForFeature(segments, featureId, groupingValue) {
+    return [
+        ...(segments[DEFAULT_KEY] ?? []),
+        ...(groupingValue ? (segments[groupingValue] ?? []) : []),
+        ...(segments[featureId] ?? [])
+    ];
 }
 /**
- * A geo feature is atomic — `Segment.areas` (x/y range restriction) doesn't
+ * A geo feature is atomic - `Segment.areas` (x/y range restriction) doesn't
  * apply, so every entry under a key is treated as a flat style patch applied
- * in order: `'default'` entries apply first, feature-specific entries
- * override. This intentionally does NOT reuse `segments.ts`'s
- * `validateSegments` — its "only the first catch-all wins" warning assumes
- * area-based semantics that don't hold here, since every geo segment entry
- * merges rather than being dropped.
+ * in order: `'default'` entries apply first, then the grouping bucket's (if
+ * any), then feature-specific entries. This intentionally does NOT reuse
+ * `segments.ts`'s `validateSegments` - its "only the first catch-all wins"
+ * warning assumes area-based semantics that don't hold here, since every geo
+ * segment entry merges rather than being dropped.
+ */
+export function resolveFeatureStyle(segments, featureId, groupingValue) {
+    return resolveSegmentsForFeature(segments, featureId, groupingValue).reduce((acc, seg) => ({ ...acc, ...(seg.styles ?? {}) }), {});
+}
+/**
+ * A feature's own effective `scales` override, if any of its matching
+ * segments (`default`, its grouping bucket, or itself) set one - the last
+ * (most specific) entry that defines `scales` wins outright, unlike
+ * `resolveFeatureStyle`'s field-by-field merge, since a ramp config isn't
+ * sensibly mergeable key-by-key (a `domain` from one entry and a `scheme`
+ * from another wouldn't be a coherent scale).
  */
-export function resolveFeatureStyle(segments, featureId) {
-    return resolveSegmentsForFeature(segments, featureId).reduce((acc, seg) => ({ ...acc, ...(seg.style ?? {}) }), {});
+export function resolveFeatureScales(segments, featureId, groupingValue) {
+    return resolveSegmentsForFeature(segments, featureId, groupingValue).reduce((acc, seg) => seg.scales ?? acc, undefined);
 }