@fundar/data-chart-telling 0.0.24 → 0.0.26

package/dist/plots/utils/declutter.js

@@ -15,11 +15,34 @@
  * already >= minGap and the average of two such gaps is too.
  *
  * Also records, per adjacent pair, whether either pass actually had to push
- * — the ground truth for "did these two really interact," which `mirrorRanks`
- * needs and can't reliably reconstruct from positions alone after the fact
- * (see its own doc comment).
+ * — the ground truth for "did these two really interact," which
+ * `laneAssignment` needs and can't reliably reconstruct from positions alone
+ * after the fact (see its own doc comment).
+ *
+ * `bounds`, if given, keeps every *run* (a maximal stretch of connected
+ * items — lone, unconnected items are left at their true position
+ * regardless) inside `[lo, hi]`: nothing pushed apart by this function is
+ * ever allowed to end up off the edge of whatever pixel range the caller
+ * considers in-bounds (typically the plot's own content box). A run that
+ * already fits is only shifted, never resized; a run too big to fit even
+ * at its natural spacing is shrunk just enough to fit, uniformly, so it's
+ * still evenly spaced — just tighter than `minGap` calls for. See
+ * `fitRunsWithinBounds` for the actual shift/shrink math.
+ *
+ * `bounds` also biases *which* pass a run's average leans on, via
+ * {@link runBiasWeights}: a run sitting close to one edge has little slack on
+ * that side, so a plain 50/50 blend would still ask the up-pass and
+ * down-pass to pull the block symmetrically toward *both* edges before
+ * `fitRunsWithinBounds` shifts/shrinks it back — the up-pass reaching for
+ * room that was never really there, needlessly widening how far members end
+ * up travelling from their original positions (`laneAssignment`'s own lane
+ * count grows with exactly that travel distance — see its doc comment) — so
+ * a run near an edge leans toward whichever pass already grows away from it
+ * instead — the block still expands to clear `minGap` everywhere, just
+ * mostly in the one direction that was actually available, the way a person
+ * sliding books apart on a shelf pinned against one wall would.
  */
-export function declutter1D(items, minGap) {
+export function declutter1D(items, minGap, bounds) {
     const sorted = [...items].sort((a, b) => a.pos - b.pos);
     const n = sorted.length;
     const connected = new Array(Math.max(0, n - 1)).fill(false);
@@ -39,55 +62,174 @@ export function declutter1D(items, minGap) {
             connected[i] = true;
         }
     }
-    const positions = sorted.map((d, i) => ({ ...d, pos: (down[i] + up[i]) / 2 }));
+    const weights = bounds ? runBiasWeights(down, up, connected, bounds) : sorted.map(() => 0.5);
+    const averaged = sorted.map((_, i) => down[i] * weights[i] + up[i] * (1 - weights[i]));
+    const fitted = bounds ? fitRunsWithinBounds(averaged, connected, bounds) : averaged;
+    const positions = sorted.map((d, i) => ({ ...d, pos: fitted[i] }));
     return { positions, connected };
 }
+/**
+ * Per-run blend weight (applied to the down-pass; `1 - weight` goes to the
+ * up-pass) favouring whichever pass already grows away from the nearer edge
+ * — see {@link declutter1D}'s doc comment for why. `0.5` (the down/up
+ * midpoint, i.e. no bias) when a run's naturally-centred span has roughly
+ * equal room on both sides; sliding toward `1` (all down-pass) as room above
+ * vanishes, toward `0` (all up-pass) as room below vanishes. Every member of
+ * a run gets the *same* weight — the point is the block moving as one
+ * (mostly) one-directional piece, not each member picking its own bias.
+ */
+function runBiasWeights(down, up, connected, [lo, hi]) {
+    const weights = down.map(() => 0.5);
+    let i = 0;
+    while (i < down.length) {
+        let j = i;
+        while (j < connected.length && connected[j])
+            j++;
+        if (j > i) {
+            const center = ((down[i] + up[i]) / 2 + (down[j] + up[j]) / 2) / 2;
+            const roomAbove = Math.max(0, center - lo);
+            const roomBelow = Math.max(0, hi - center);
+            const total = roomAbove + roomBelow;
+            const weight = total > 0 ? roomBelow / total : 0.5;
+            for (let k = i; k <= j; k++)
+                weights[k] = weight;
+        }
+        i = j + 1;
+    }
+    return weights;
+}
+/**
+ * Shifts, and shrinks only if it must, each run of `connected` positions so
+ * it lands entirely inside `[lo, hi]`. A run's own relative spacing is
+ * preserved as-is (just translated) whenever it already fits in `hi - lo`;
+ * only a run wider than the available space gets uniformly scaled down
+ * around its centre first. Lone, unconnected positions pass through
+ * untouched — they were never pushed by `declutter1D` in the first place,
+ * so clamping one to the bounds would move a label away from the data point
+ * it's honestly reporting, for no collision-avoidance reason at all.
+ */
+function fitRunsWithinBounds(positions, connected, [lo, hi]) {
+    const out = [...positions];
+    const available = hi - lo;
+    let i = 0;
+    while (i < out.length) {
+        let j = i;
+        while (j < connected.length && connected[j])
+            j++;
+        if (j > i) {
+            const runMin = out[i];
+            const runMax = out[j];
+            if (runMin < lo || runMax > hi) {
+                const naturalSpan = runMax - runMin;
+                const scale = naturalSpan > 0 ? Math.min(1, available / naturalSpan) : 1;
+                const idealCenter = (runMin + runMax) / 2;
+                const newSpan = naturalSpan * scale;
+                const newCenter = Math.min(Math.max(idealCenter, lo + newSpan / 2), hi - newSpan / 2);
+                for (let k = i; k <= j; k++) {
+                    out[k] = newCenter + (out[k] - idealCenter) * scale;
+                }
+            }
+        }
+        i = j + 1;
+    }
+    return out;
+}
 /**
  * Groups `declutter1D`'s own `connected` flags into runs (maximal stretches
- * of consecutive connected pairs), then assigns each run member a lane by
- * *mirrored* position within it: the run's top and bottom member share lane
- * 0, the next-in-from-top and next-in-from-bottom share lane 1, and so on
- * toward the run's centre (an odd-sized run's exact middle member gets the
- * innermost lane alone). `depth` is the run's own size, the same for every
- * member; the number of *distinct* lanes it actually needs is
- * `ceil(depth / 2)`.
+ * of consecutive connected pairs), then gives every run member its own,
+ * unique lane — no two members ever share one, deliberately (see below) —
+ * ordered so that a leader line drawn through lane `rank` never crosses, or
+ * even draws visually flush against, one drawn through any other lane of
+ * the same run.
+ *
+ * Every member's leader line is the same three-segment elbow: a horizontal
+ * stub from the data point out to its lane, a vertical run up/down that
+ * lane to the label's height, then a final horizontal run in to the shared
+ * label column. Two such elbows, `i` (in the tighter of the two lanes) and
+ * `j` (further out), are safe from crossing *specifically* when neither of
+ * these can happen:
+ * - `j`'s own stub (at `j`'s original height) reaches out past `i`'s lane
+ *   while `i`'s vertical run passes through that height — `j`'s stub would
+ *   cut across `i`'s vertical segment.
+ * - `i`'s final run (at `i`'s label height) reaches past `i`'s own lane out
+ *   to the shared column, and in doing so crosses `j`'s lane while `j`'s
+ *   vertical run passes through *that* height — `i`'s own final segment
+ *   would cut across `j`'s vertical segment.
  *
- * Deliberately doesn't re-derive connectivity from before/after positions —
- * an early version tried that (some mix of "both moved" and "final gap is
- * near minGap") and it's unreliable both ways: a real one-sided interaction
- * (an item that only moved because its neighbour got pushed into it) can
- * settle with more slack than minGap, so a gap-threshold check misses it;
- * and "both moved" over-connects, since two unrelated, far-apart clusters
- * that each independently needed to declutter still each have moved members
- * sitting next to each other in sort order, which a moved-only check can't
- * tell apart from a real interaction. `declutter1D`'s own `connected` array
- * has neither problem, because it's not inferred — it's the actual record
- * of which pushes happened.
+ * Whether `i` can safely take the tighter lane depends on both members'
+ * *actual* pixel geometry — not simply on which one moved further — so each
+ * pair is checked directly per {@link saferNearer} rather than inferred from
+ * a single sort key. A pair with a clean, provable answer either way (the
+ * overwhelmingly common case for `declutter1D`'s own output) is ordered by
+ * that answer; a pair with no clean answer (both directions equally
+ * "unsafe," or, symmetrically, both fine) falls back to the same *travel
+ * distance* heuristic used before this per-pair check existed — furthest
+ * `|final - original|` first — which is what decides ties and keeps the
+ * "furthest traveller gets the tightest lane, so it starts bending
+ * immediately rather than reaching across everyone else's leader lines
+ * first" intent for every pair the geometry itself doesn't already settle.
  *
- * Meant to drive a leader line's lane: `rank` 0 bends right off the data
- * point (a short first stub); higher ranks travel further before bending
- * (right up to the shared label column, for a run's own centre member).
- * Two members sharing a lane never collide: by how `declutter1D` centers
- * its result, a run's top half only ever ends up at or above its original
- * spot and its bottom half only ever at or below, so paired members bend
- * away from each other — same lane, opposite direction, no shared space.
- * This also roughly halves the lane depth (and so the horizontal room) a
- * run needs, versus giving every member its own lane.
+ * No sharing, ever, is the other half of this: two members can only have
+ * non-overlapping travel spans (and so pass the old, now-removed,
+ * share-a-lane check) by sitting far apart along the axis — but "far apart"
+ * is exactly the case with the most room to spare, so it never needed the
+ * lane it would save by sharing, while any pair close enough to actually be
+ * short on room has spans close enough together that sharing draws their
+ * two leader lines only a couple pixels apart — visually indistinguishable
+ * from one continuous line touching the next label down. A run of `n`
+ * members uses exactly `n` lanes; letting the lane count grow is the price
+ * of a fan that never has two leader lines touching *or* crossing, and
+ * `ValueLabels`' own auto-margin measurement (see its doc comment) already
+ * grows `margins.right` to fit however many lanes that turns out to be, so
+ * nothing has to be guessed up front.
+ *
+ * `rank` is the lane index (0-indexed) to drive a leader line's routing:
+ * `rank` 0 bends right off the data point (a short first stub); higher
+ * ranks travel further before bending (right up to the shared label
+ * column). `lanesUsed` is the run's own total lane count — always equal to
+ * `runSize` — shared by every member; `runSize` is the run's member count,
+ * for callers that just need to know whether a given member belongs to a
+ * real run at all.
  */
-export function mirrorRanks(connected) {
+export function laneAssignment(originals, finals, connected) {
     const n = connected.length + 1;
-    const out = Array.from({ length: n }, () => ({ rank: 0, depth: 1 }));
+    const out = Array.from({ length: n }, () => ({ rank: 0, lanesUsed: 1, runSize: 1 }));
+    const span = (k) => {
+        const a = originals[k];
+        const b = finals[k];
+        return a < b ? [a, b] : [b, a];
+    };
+    const distance = (k) => Math.abs(finals[k] - originals[k]);
+    /** Whether lane-`i`-nearer-than-`j` is provably crossing-free — see this function's doc comment. */
+    function saferNearer(i, j) {
+        const [loI, hiI] = span(i);
+        const [loJ, hiJ] = span(j);
+        const jStubCutsI = originals[j] >= loI && originals[j] <= hiI;
+        const iFinalCutsJ = finals[i] >= loJ && finals[i] <= hiJ;
+        return !jStubCutsI && !iFinalCutsJ;
+    }
     let i = 0;
     while (i < n) {
         let j = i;
         while (j < connected.length && connected[j])
             j++;
-        const runLength = j - i + 1;
-        if (runLength > 1) {
-            for (let k = i; k <= j; k++) {
-                const posInRun = k - i;
-                out[k] = { rank: Math.min(posInRun, runLength - 1 - posInRun), depth: runLength };
-            }
+        const runSize = j - i + 1;
+        if (runSize > 1) {
+            // Members of this run, ordered so each is provably safe to place
+            // nearer than the next whenever that's decidable, furthest-travelled
+            // first otherwise (ties keep their original — i.e. top-to-bottom —
+            // order, since `sort` is stable). Position in this order *is* the
+            // rank: no sharing.
+            const order = Array.from({ length: runSize }, (_, k) => i + k).sort((a, b) => {
+                const aNearer = saferNearer(a, b);
+                const bNearer = saferNearer(b, a);
+                if (aNearer !== bNearer)
+                    return aNearer ? -1 : 1;
+                return distance(b) - distance(a);
+            });
+            order.forEach((k, rank) => {
+                out[k] = { rank, lanesUsed: runSize, runSize };
+            });
         }
         i = j + 1;
     }

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

@@ -36,7 +36,7 @@ export declare function geometryPartCentroids(geometry: GeoJSON.Geometry): [numb
  * 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
  * feature's geometry be split between the main map and an `inset` marker
- * (see `GeoDataProps.excludeParts`/`GeoInsetMarker.featurePartsFilter`)
+ * (see `GeoDataProps.excludeParts`/`GeoInsetMarkerConfig.featurePartsFilter`)
  * without preprocessing the source data: e.g. a province whose `MultiPolygon`
  * spans both a mainland part and a far-flung part can have the main map
  * exclude the latter while an inset shows only it.

package/dist/plots/utils/geoAccessors.js

@@ -102,7 +102,7 @@ export function geometryPartCentroids(geometry) {
  * 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
  * feature's geometry be split between the main map and an `inset` marker
- * (see `GeoDataProps.excludeParts`/`GeoInsetMarker.featurePartsFilter`)
+ * (see `GeoDataProps.excludeParts`/`GeoInsetMarkerConfig.featurePartsFilter`)
  * without preprocessing the source data: e.g. a province whose `MultiPolygon`
  * spans both a mainland part and a far-flung part can have the main map
  * exclude the latter while an inset shows only it.

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

@@ -1,8 +1,9 @@
-import type { AxisValue } from '../../types/plots/axis';
+import type { AxisValue } from '../../types/layout/scales';
 import type { Series } from '../../types/plots/data/common';
 import type { LineSegmentStyle } from '../../types/plots/segments/common';
 import type { Segment, VisualGroup } from '../../types/plots/segments/config';
 import type { SegmentsConfig } from '../../types/plots/props';
+import type { ScopedMarkerGroup } from '../../types/layout/geometry';
 /**
  * Returns the flat {@link Segment} list for one series.
  * Series-specific segments are added before `'default'` segments so that
@@ -11,15 +12,6 @@ import type { SegmentsConfig } from '../../types/plots/props';
 export declare function resolveSegmentsForSeries<TStyle>(segments: SegmentsConfig<TStyle>, seriesName: string): Segment<TStyle>[];
 /** Returns true when `xVal` falls inside any of a segment's x ranges. */
 export declare function matchesSegmentX<TStyle>(xVal: AxisValue, seg: Segment<TStyle>): boolean;
-/**
- * For each segment in `segs`, returns the subset of `data` rows whose x value
- * (from `xAccessor`) falls inside any of the segment's x ranges. Rows are
- * not deduplicated across segments — a row that matches multiple segments
- * appears in each resulting array.
- *
- * Used by component and hover markers with the `'segment'` strategy.
- */
-export declare function getDataForSegments<TData, TStyle>(data: TData[], xAccessor: (d: TData) => AxisValue, segs: Segment<TStyle>[]): TData[][];
 /**
  * Warns about obvious configuration mistakes: multiple catch-all segments
  * (no `areas`) in the same series list. Since catch-alls are evaluated last
@@ -38,3 +30,18 @@ export declare function validateSegments<TStyle>(segments: SegmentsConfig<TStyle
  * aren't duplicated as an extra, separately-styled mark.
  */
 export declare function buildGroupedSeries<S extends Series<any>, TStyle = LineSegmentStyle>(seriesList: S[], segments: SegmentsConfig<TStyle>, connect?: boolean): VisualGroup<S, TStyle>[];
+/**
+ * Builds the `ScopedMarkerGroup[]` a `Plot.svelte` hands to `GeometryLayout`
+ * for rendering `series`-scoped `hover`/`component` markers — one group per
+ * series, carrying its resolved segments' match predicates and colors.
+ * `colorFor` resolves a series' own default color; `segmentColorFor` reads
+ * whichever field counts as "color" out of that plot kind's segment style
+ * shape (e.g. `fill` vs `stroke.stroke`), since that's the only part of this
+ * that isn't shared across plot kinds.
+ */
+export declare function buildScopedMarkerGroups<TData extends Record<string, unknown>, S extends Series<any>, TStyle>(args: {
+    groupedSeries: VisualGroup<S, TStyle>[];
+    segments: SegmentsConfig<TStyle>;
+    colorFor: (series: S, seriesIndex: number) => string;
+    segmentColorFor: (style: TStyle | undefined, defaultColor: string) => string;
+}): ScopedMarkerGroup<TData>[];

package/dist/plots/utils/segments.js

@@ -35,22 +35,6 @@ function areaMatchesXY(xVal, yVal, area) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (area.y.to === undefined || yVal <= area.y.to);
 }
-/**
- * For each segment in `segs`, returns the subset of `data` rows whose x value
- * (from `xAccessor`) falls inside any of the segment's x ranges. Rows are
- * not deduplicated across segments — a row that matches multiple segments
- * appears in each resulting array.
- *
- * Used by component and hover markers with the `'segment'` strategy.
- */
-export function getDataForSegments(data, xAccessor, segs) {
-    return segs.map((seg) => {
-        const areas = seg.areas;
-        if (!areas || areas.length === 0)
-            return data;
-        return data.filter((d) => areas.some((area) => areaMatchesX(xAccessor(d), area)));
-    });
-}
 /**
  * Warns about obvious configuration mistakes: multiple catch-all segments
  * (no `areas`) in the same series list. Since catch-alls are evaluated last
@@ -209,3 +193,29 @@ export function buildGroupedSeries(seriesList, segments, connect = true) {
         visualSegments: resolveSeriesSegments(s, resolveSegmentsForSeries(segments, s.name), connect),
     }));
 }
+/**
+ * Builds the `ScopedMarkerGroup[]` a `Plot.svelte` hands to `GeometryLayout`
+ * for rendering `series`-scoped `hover`/`component` markers — one group per
+ * series, carrying its resolved segments' match predicates and colors.
+ * `colorFor` resolves a series' own default color; `segmentColorFor` reads
+ * whichever field counts as "color" out of that plot kind's segment style
+ * shape (e.g. `fill` vs `stroke.stroke`), since that's the only part of this
+ * that isn't shared across plot kinds.
+ */
+export function buildScopedMarkerGroups(args) {
+    const { groupedSeries, segments, colorFor, segmentColorFor } = args;
+    return groupedSeries.map((group, seriesIndex) => {
+        const defaultColor = colorFor(group.series, seriesIndex);
+        const xFor = resolveAccessor(group.series.x);
+        const segs = resolveSegmentsForSeries(segments, group.series.name);
+        return {
+            name: group.series.name,
+            data: group.series.data,
+            color: defaultColor,
+            segments: segs.map((seg) => ({
+                match: (row) => matchesSegmentX(xFor(row), seg),
+                color: segmentColorFor(seg.style, defaultColor),
+            })),
+        };
+    });
+}

package/dist/types/charts/common.d.ts

@@ -1,5 +1,5 @@
 import type { Snippet } from 'svelte';
-import type { AxisValue } from '../plots/axis';
+import type { AxisValue } from '../layout/scales';
 import type { Accessor } from '../plots/data/common';
 import type { EasingName, EasingFn } from './interpolate';
 export type TimeValue = number;

package/dist/types/charts/props.d.ts

@@ -1,10 +1,9 @@
 import type { Snippet } from 'svelte';
-import type { AxisValue } from '../plots/axis';
+import type { AxisValue, AxisBasedScalesConfig } from '../layout/scales';
 import type { Accessor } from '../plots/data/common';
-import type { AxisBasedScalesConfig } from '../plots/props';
-import type { BasePlotStyles } from '../plots/styles/common';
+import type { BasePlotStylesConfig } from '../layout/styles';
 import type { SegmentsConfig, MarginConfig } from '../plots/props';
-import type { Marker } from '../markers/common';
+import type { AxisBasedMarkersConfig } from '../markers/common';
 import type { TooltipProp } from '../layout/tooltip';
 import type { LegendSection } from './legend';
 import type { FacetConfig, TimelineConfig } from './common';
@@ -30,9 +29,9 @@ export type ChartProps<TRow extends Record<string, unknown>, TSegmentStyle exten
     x: Accessor<TRow, AxisValue>;
     y: Accessor<TRow, AxisValue>;
     z?: Accessor<TRow, unknown>;
-    styles?: BasePlotStyles;
+    styles?: BasePlotStylesConfig;
     segments?: SegmentsConfig<TSegmentStyle>;
-    markers?: Marker[];
+    markers?: AxisBasedMarkersConfig[];
     scales?: AxisBasedScalesConfig<TRow>;
     margins?: MarginConfig;
     facet?: FacetConfig<TRow>;

package/dist/types/configuration/styling.d.ts

@@ -1,4 +1,4 @@
-import type { StrokeStyle, DotStyle, FontStyle } from '../plots/styling';
+import type { StrokeStyle, DotStyle, FontStyle, AreaStyle } from '../plots/styling';
 export type TextStyle = {
     /** font-family */
     font: string;
@@ -83,6 +83,27 @@ export type ChartConfig = {
     line: {
         strokeWidth: number;
         dotRadius: number;
+        /**
+         * End-of-line value-label declutter geometry and connector styling —
+         * `LinePlot`-specific, since only line charts spread colliding
+         * end-point labels apart with elbow-routed leader lines.
+         */
+        valueLabels: {
+            /** Shortest lane's distance (px) from the data point before a leader line bends. */
+            elbowGap: number;
+            /** Extra distance (px) each subsequent lane sits out from the last. */
+            laneStep: number;
+            /** Clearance (px) between the outermost lane and the label text it feeds into. */
+            labelGap: number;
+            /** Default leader-line colour — overridable per-plot via `styles.values.strokeStyle`. */
+            connectorColor: string;
+            /** Default leader-line width — overridable per-plot via `styles.values.strokeStyle`. */
+            connectorWidth: number;
+        };
+    };
+    /** Default scatter point geometry. */
+    scatter: {
+        dotRadius: number;
     };
     /** Timeline gutter styling. */
     timeline: {
@@ -90,11 +111,12 @@ export type ChartConfig = {
         activeColor: string;
         thickness: number;
     };
-    /** In-SVG hover highlight (crosshair rule, dot, and value label). */
+    /** In-SVG hover highlight: crosshair rule, dot + value label, and geo feature restyle. */
     hover: {
         rule: StrokeStyle;
         dot: DotStyle;
         font: FontStyle;
+        area: AreaStyle;
     };
 };
 /** Deep-partial input accepted by `setConfiguration`. */

package/dist/types/{plots/scales/geo.d.ts → layout/coordinates.d.ts}

@@ -1,10 +1,10 @@
+import type { GeoProjection } from 'd3-geo';
 /**
  * The projection names svelteplot's `<Plot projection>` accepts as a string
  * (svelteplot itself doesn't export this as a type — defined here so authors
  * get autocomplete/type-checking over the full supported set).
  */
 export type GeoProjectionName = 'albers-usa' | 'albers' | 'azimuthal-equal-area' | 'azimuthal-equidistant' | 'conic-conformal' | 'conic-equal-area' | 'conic-equidistant' | 'equal-earth' | 'equirectangular' | 'gnomonic' | 'identity' | 'reflect-y' | 'mercator' | 'orthographic' | 'stereographic' | 'transverse-mercator';
-import type { GeoProjection } from 'd3-geo';
 /**
  * What a custom projection factory (e.g. `argentinaBicontinental` under
  * `$lib`'s geo projections) must return — just enough of d3's `GeoProjection`
@@ -42,3 +42,35 @@ export type GeoProjectionConfig = GeoProjectionName | {
      */
     domain?: GeoJSON.GeoJsonObject | GeoJSON.FeatureCollection | GeoJSON.Feature | 'data';
 };
+/**
+ * `scales` prop for GeoPlot — the geo analog of `AxisBasedScalesConfig`.
+ * A map has no x/y/z axis pair, so this only configures the choropleth
+ * colour domain (the coordinate system itself is `coordinates.projection`).
+ */
+export type GeoScalesConfig = {
+    /** Continuous choropleth value domain — mirrors heatmap's `scales.z.domain`. */
+    color?: {
+        domain?: [number, number];
+    };
+};
+export type GeoZoomConfig = {
+    min?: number;
+    max?: number;
+    initial?: {
+        x?: number;
+        y?: number;
+        k?: number;
+    };
+};
+/**
+ * `coordinates` prop for GeoPlot — the only plot kind with a coordinate
+ * system other than implicit cartesian. Bundles the projection (a `GoG`
+ * Coordinates concern) and pan/zoom (navigating within that coordinate
+ * system), resolved together by `CoordinatesLayout`.
+ */
+export type CoordinatesConfig = {
+    /** Which map projection to draw with. Defaults to `'equal-earth'`. */
+    projection?: GeoProjectionConfig;
+    /** `true`/config enables drag-pan + scroll-zoom. Omitted/`false` = static map. */
+    zoom?: boolean | GeoZoomConfig;
+};

package/dist/types/layout/geometry.d.ts

@@ -0,0 +1,17 @@
+/** One resolved segment for scoped-marker rendering — see {@link ScopedMarkerGroup}. */
+export type ScopedMarkerSegment<TData> = {
+    match: (row: TData) => boolean;
+    color: string;
+};
+/**
+ * One series' resolved context for rendering its `series`-scoped `'hover'`/
+ * `'component'` markers — built by each `Plot.svelte`, consumed by
+ * `GeometryLayout`. Keeps `GeometryLayout` itself agnostic of each plot
+ * kind's segment style shape (e.g. `fill` vs `stroke.stroke`).
+ */
+export type ScopedMarkerGroup<TData> = {
+    name: string;
+    data: TData[];
+    color: string;
+    segments: ScopedMarkerSegment<TData>[];
+};

package/dist/types/{plots/axis.d.ts → layout/scales.d.ts}

@@ -53,3 +53,14 @@ export type AxisScale<TData = Record<string, unknown>> = {
     seriesLayout?: 'overlap' | 'grouped' | 'stacked';
     seriesPadding?: number;
 };
+/**
+ * Per-axis scale overrides, passed as a single `scales` prop to every
+ * axis-based plot kind (`GeoPlot` uses `GeoScalesConfig` instead — a map has
+ * no x/y/z axis pair). `TData` threads through to {@link AxisScale.sort} on
+ * each axis.
+ */
+export type AxisBasedScalesConfig<TData = Record<string, unknown>> = {
+    x?: AxisScale<TData>;
+    y?: AxisScale<TData>;
+    z?: AxisScale<TData>;
+};