@fundar/data-chart-telling 0.0.25 → 0.0.26

package/dist/plots/utils/declutter.js

@@ -34,14 +34,13 @@
  * 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. That round trip is exactly what makes
- * individual members travel far past their neighbours' original positions
- * (`laneAssignment`'s doc comment calls this out as the thing that forces an
- * unsafe, overlapping travel span), 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.
+ * 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, bounds) {
     const sorted = [...items].sort((a, b) => a.pos - b.pos);
@@ -137,41 +136,60 @@ function fitRunsWithinBounds(positions, connected, [lo, hi]) {
 }
 /**
  * Groups `declutter1D`'s own `connected` flags into runs (maximal stretches
- * of consecutive connected pairs), then assigns each run member a lane by
- * *mirrored* position — 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) — but only after checking that a proposed pair's
- * *travel spans* (`[min(original, final), max(original, final)]`, the pixel
- * range a leader line's vertical segment actually sweeps through) don't
- * overlap. A pair that would collide is split into two lanes of its own
- * instead of one shared one, so correctness never depends on the pairing
- * being right — only on this check.
+ * 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.
  *
- * Mirrored position is still the *first* thing tried, not span-overlap
- * colouring picking lanes on its own, because minimizing lane count isn't
- * actually the goal here — a run of `n` safely-non-overlapping members could
- * often be greedily packed into far fewer than `ceil(n / 2)` lanes, but
- * doing that defeats the point: it's what visually fans a pileup's leader
- * lines apart in the first place. Mirrored pairing keeps that fan-out
- * exactly where it's safe (the common case for `declutter1D`'s own output),
- * and only degrades — never breaks — where it isn't.
+ * 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.
  *
- * A run whose members still end up with genuinely overlapping travel spans
- * (heavy, edge-adjacent compression) has no lane assignment that's both
- * crossing-free *and* touch-free under this shared-`px`/shared-`labelX`
- * elbow geometry — sharing draws two segments on top of each other, splitting
- * draws an actual crossing. `declutter1D`'s bounds-aware margin bias (see its
- * own doc comment) exists specifically to keep that from happening in the
- * first place, by keeping a run's displacement mostly one-directional when
- * it sits close to an edge, rather than papering over it here.
+ * 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.
+ *
+ * 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 (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.
+ * 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 laneAssignment(originals, finals, connected) {
     const n = connected.length + 1;
@@ -181,7 +199,15 @@ export function laneAssignment(originals, finals, connected) {
         const b = finals[k];
         return a < b ? [a, b] : [b, a];
     };
-    const overlaps = (a, b) => a[0] < b[1] && b[0] < a[1];
+    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;
@@ -189,32 +215,21 @@ export function laneAssignment(originals, finals, connected) {
             j++;
         const runSize = j - i + 1;
         if (runSize > 1) {
-            const rankOf = new Array(runSize);
-            let lo = 0;
-            let hi = runSize - 1;
-            let nextLane = 0;
-            while (lo <= hi) {
-                if (lo === hi) {
-                    rankOf[lo] = nextLane;
-                    nextLane += 1;
-                }
-                else if (!overlaps(span(i + lo), span(i + hi))) {
-                    rankOf[lo] = nextLane;
-                    rankOf[hi] = nextLane;
-                    nextLane += 1;
-                }
-                else {
-                    rankOf[lo] = nextLane;
-                    rankOf[hi] = nextLane + 1;
-                    nextLane += 2;
-                }
-                lo += 1;
-                hi -= 1;
-            }
-            const lanesUsed = nextLane;
-            for (let k = 0; k < runSize; k++) {
-                out[i + k] = { rank: rankOf[k], lanesUsed, runSize };
-            }
+            // 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;
@@ -101,17 +101,22 @@ export type ChartConfig = {
             connectorWidth: number;
         };
     };
+    /** Default scatter point geometry. */
+    scatter: {
+        dotRadius: number;
+    };
     /** Timeline gutter styling. */
     timeline: {
         axisColor: string;
         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>;
+};

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

@@ -0,0 +1,126 @@
+import type { ValueAnchor } from '../plots/constants';
+import type { FontStyle, StrokeStyle, AreaStyle } from '../plots/styling';
+import type { GeoFeature } from '../plots/data/geo';
+/**
+ * Controls if and how value labels are rendered on a plot. The high-level
+ * `anchor` sets sensible defaults for placement; `fontStyle` (`dx`, `dy`,
+ * `textAnchor`, `lineAnchor`, `lineHeight`, `rotate`, `class`, `textClass`,
+ * `fill`, …) overrides those defaults field-by-field when provided — mirrors
+ * {@link DeltaConfig}'s `fontStyle`/`strokeStyle` split, so label text and
+ * connector-line styling never mix into one flat bag of props.
+ */
+export type ValuesStyle = {
+    show?: boolean;
+    anchor?: ValueAnchor;
+    /** Called with the numeric value and the series name. Return a string to render. */
+    format?: (value: number, seriesName: string) => string;
+    /** Text styling for the label itself. */
+    fontStyle?: FontStyle;
+    /**
+     * Style for the leader line drawn from a label displaced to clear an
+     * overlap with another series' label, back to its real data point.
+     * Labels only ever move when they'd otherwise collide — this is a no-op
+     * style until that happens. Falls back to a neutral grey, thin, solid
+     * stroke — deliberately not the series' own colour or stroke width, since
+     * matching the data line reads as more data rather than as a leader,
+     * right where several lines are already converging. Unset fields keep
+     * that fallback.
+     */
+    strokeStyle?: StrokeStyle;
+};
+/**
+ * Color overrides for plots that derive their palette from data.
+ * Each plot uses only the fields relevant to its kind; unused fields are
+ * silently ignored.
+ *
+ * - `min` / `max` — sequential colour ramp endpoints (heatmap).
+ * - `left` / `right` — diverging bar sides (pyramid).
+ */
+export type ColorsStyle = {
+    min?: string;
+    max?: string;
+    left?: string;
+    right?: string;
+};
+/**
+ * Decorative border around the plot's own content box — svelteplot's
+ * `Frame` mark, purely cosmetic (drawn from the box geometry, never from
+ * data). `true` enables it with svelteplot's own defaults; an object
+ * enables it and overrides its look field-by-field. Insets pull the frame
+ * in from the content box's own edges, in pixels.
+ */
+export type FrameStyle = AreaStyle & {
+    inset?: number;
+    insetTop?: number;
+    insetRight?: number;
+    insetBottom?: number;
+    insetLeft?: number;
+};
+/** Author-facing `styles.frame` prop — see {@link FrameStyle}. */
+export type FrameProp = boolean | FrameStyle;
+/**
+ * Top-level rendering style overrides shared by the non-geo plot kinds.
+ * Passed as the `styles` prop. Each plot reads only the fields it cares
+ * about.
+ */
+export type BasePlotStylesConfig = {
+    values?: ValuesStyle;
+    colors?: ColorsStyle;
+    /** Decorative border around the plot's content box — see {@link FrameStyle}. Available on every plot kind. */
+    frame?: FrameProp;
+};
+export type GeoTileLayerConfig = {
+    /** XYZ tile URL template, e.g. `'https://tile.openstreetmap.org/{z}/{x}/{y}.png'`. */
+    url: string;
+    attribution?: string;
+    opacity?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Tile edge length in pixels. Defaults to `256`. */
+    tileSize?: number;
+};
+/**
+ * `styles` prop for GeoPlot — the geo analog of `BasePlotStylesConfig`.
+ * Unlike the other plot kinds, GeoPlot's styling needs (base map, choropleth
+ * ramp, tile background, click handling) are unlike anything x/y plots need,
+ * so this is its own type rather than a reuse of `BasePlotStylesConfig`.
+ */
+export type GeoStylesConfig<TProps extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Base map fill, used when a feature isn't styled by `segments` or the choropleth ramp. */
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Continuous choropleth ramp endpoints — used when `value` is provided on data. Mirrors heatmap's `styles.colors`. */
+    colors?: ColorsStyle;
+    /** Raster XYZ tile basemap under the vector geometry. Mercator-family projections only. */
+    tileLayer?: GeoTileLayerConfig;
+    /** Fired when a base-map feature is clicked. */
+    onFeatureClick?: (feature: GeoFeature<TProps>, event: Event) => void;
+    /** Decorative border around the plot's content box — see {@link FrameStyle}. Available on every plot kind. */
+    frame?: FrameProp;
+};
+/**
+ * `GeoTileLayerConfig`, plus `features` — never author-facing (the public
+ * `styles.tileLayer` shape, {@link GeoTileLayerConfig}, doesn't declare it).
+ * `GeoPlot` tacks it onto its own internal copy of `styles` so `StylesLayout`
+ * can compute the tile layer's auto-fit bounds without needing raw geometry
+ * threaded through as a separate prop.
+ */
+type GeoTileLayerConfigWithFeatures = GeoTileLayerConfig & {
+    features?: {
+        geometry: GeoJSON.Geometry;
+    }[];
+};
+/**
+ * The minimal slice of a plot kind's own `styles` prop `StylesLayout` reads —
+ * every concrete `styles` type ({@link BasePlotStylesConfig},
+ * {@link GeoStylesConfig}) structurally satisfies this whether or not it
+ * declares `tileLayer` at all (a missing optional field type-checks fine).
+ */
+export type StylesLayoutConfig = {
+    tileLayer?: GeoTileLayerConfigWithFeatures;
+    frame?: FrameProp;
+    [key: string]: unknown;
+};
+export {};

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

@@ -1,5 +1,5 @@
 import type { Snippet } from 'svelte';
-import type { AxisValue } from '../plots/axis';
+import type { AxisValue } from './scales';
 /**
  * How the hover highlight finds related points within a facet.
  * - `'x'` all points sharing the hovered x (default for line / bar).
@@ -7,6 +7,21 @@ import type { AxisValue } from '../plots/axis';
  * - `'punctual'` exact XY match — one cell at a time (default for heatmap).
  */
 export type HoverStrategy = 'x' | 'y' | 'punctual';
+/**
+ * Preferred horizontal placement of the floating tooltip relative to the
+ * cursor: `'right'`/`'left'` offset it clear of the cursor (so it never
+ * covers the hovered point); `'middle'` centers it on the cursor's x, same
+ * as the plot's own vertical `'middle'`. Falls back toward the opposite
+ * side (via `'middle'`) when the preferred side would overflow the plot's
+ * bounds — see {@link resolveTooltipPlacement}. System default: `'right'`.
+ */
+export type TooltipAnchorX = 'left' | 'middle' | 'right';
+/**
+ * Preferred vertical placement of the floating tooltip relative to the
+ * cursor — same fallback behavior as {@link TooltipAnchorX}, along the other
+ * axis. System default: `'bottom'`.
+ */
+export type TooltipAnchorY = 'top' | 'middle' | 'bottom';
 /** Author-facing tooltip option on the chart kinds. `true` = enable with defaults. */
 export type TooltipOptions<TRow extends Record<string, unknown>> = {
     /** Matching strategy. Defaults to the chart kind's own default. */
@@ -24,6 +39,10 @@ export type TooltipOptions<TRow extends Record<string, unknown>> = {
     content?: Snippet<[{
         rows: TRow[];
     }]>;
+    /** Preferred horizontal anchor — see {@link TooltipAnchorX}. */
+    anchorX?: TooltipAnchorX;
+    /** Preferred vertical anchor — see {@link TooltipAnchorY}. */
+    anchorY?: TooltipAnchorY;
 };
 /** Either a bare on/off flag or the full option object. */
 export type TooltipProp<TRow extends Record<string, unknown>> = boolean | TooltipOptions<TRow>;

package/dist/types/markers/all.d.ts

@@ -0,0 +1,11 @@
+import type { AxisBasedMarkersConfig } from './common';
+import type { GeoMarkersConfig, GeoFeaturesMarkerConfig } from './geo';
+import type { LineMarkersConfig } from './line';
+/**
+ * Every marker kind `GeometryLayout`/`BasePlotLayout` can route to — the
+ * union of every plot kind's own `markers` prop type, plus
+ * `GeoFeaturesMarkerConfig` (built internally, never author-facing). Not
+ * used as any `Plot.svelte`'s own `TMarker` — see each kind's own precise
+ * type instead.
+ */
+export type MarkerConfig = AxisBasedMarkersConfig | LineMarkersConfig | GeoMarkersConfig | GeoFeaturesMarkerConfig;