@fundar/data-chart-telling 0.0.13 → 0.0.15

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

@@ -0,0 +1,237 @@
+import type { Snippet } from 'svelte';
+import type { Accessor } from '../plots/data/common';
+import type { ColorsStyle } from '../plots/styles/common';
+import type { DotStyle, FontStyle, StrokeStyle } from '../plots/styling';
+import type { HoverDisplayPoint } from '../layout/tooltip';
+import type { GeoFeature, GeoJsonInput } from '../plots/data/geo';
+import type { GeoSegmentStyle } from '../plots/segments/common';
+import type { GeoProjectionName } from '../plots/scales/geo';
+/** Longitude/latitude gridlines — svelteplot's `Graticule`. */
+export type GeoGraticuleMarker = {
+    type: 'graticule';
+    step?: number;
+    stepX?: number;
+    stepY?: number;
+    style?: StrokeStyle;
+    /**
+     * Renders behind the base map's own fill/stroke instead of on top of it
+     * (markers otherwise always draw over the base map, regardless of their
+     * position in the `markers` array). Useful for a graticule meant to read
+     * as a faint background reference frame rather than an overlay obscuring
+     * the geometry above it.
+     */
+    behind?: boolean;
+};
+/** The outer globe outline (for orthographic-type projections) — svelteplot's `Sphere`. */
+export type GeoSphereMarker = {
+    type: 'sphere';
+    style?: StrokeStyle & {
+        fill?: string;
+        fillOpacity?: number;
+    };
+    /**
+     * Renders behind the base map's own fill/stroke instead of on top of it —
+     * needed any time `style.fill` is set, since a filled sphere otherwise
+     * covers every feature drawn under it (the sphere is the full globe
+     * outline, larger than any geometry on it). Off by default so an
+     * unfilled/stroke-only sphere (the common case, tracing just the globe's
+     * edge) keeps drawing on top where it stays visible over ocean fills.
+     */
+    behind?: boolean;
+};
+/**
+ * Point markers by longitude/latitude, sized/colored by value —
+ * svelteplot's `Dot`. https://svelteplot.dev/examples/dot/weather
+ */
+export type GeoDotMarker<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    type: 'dot';
+    data: TRow[];
+    x: Accessor<TRow, number>;
+    y: Accessor<TRow, number>;
+    r?: Accessor<TRow, number> | number;
+    /** Continuous value used to color each dot through a ramp — see `style.colors`. */
+    value?: Accessor<TRow, number>;
+    style?: DotStyle & {
+        colors?: ColorsStyle;
+    };
+};
+/**
+ * Arrows/spikes at points — svelteplot's `Vector`.
+ * https://svelteplot.dev/examples/vector/shift-map
+ */
+export type GeoVectorMarker<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    type: 'vector';
+    data: TRow[];
+    x: Accessor<TRow, number>;
+    y: Accessor<TRow, number>;
+    length?: Accessor<TRow, number> | number;
+    rotate?: Accessor<TRow, number> | number;
+    shape?: 'arrow' | 'spike' | 'arrow-filled';
+    anchor?: 'start' | 'middle' | 'end';
+    style?: {
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+    };
+};
+/**
+ * Geodesic-aware lines between point pairs — svelteplot's `Link` (its
+ * `curve: 'auto'` traces a great-circle arc on a geographic projection).
+ * https://svelteplot.dev/examples/link/spherical-link
+ */
+export type GeoLinkMarker<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    type: 'link';
+    data: TRow[];
+    x1: Accessor<TRow, number>;
+    y1: Accessor<TRow, number>;
+    x2: Accessor<TRow, number>;
+    y2: Accessor<TRow, number>;
+    curve?: 'auto' | 'linear';
+    style?: StrokeStyle;
+};
+/**
+ * Marching-squares contours from a scalar field — svelteplot's `Contour`.
+ * https://svelteplot.dev/examples/contour/weather
+ *
+ * Two input modes: pass `data` (+ `x`/`y`/`value` row accessors) to
+ * spatially interpolate a scatter of samples, or omit `data` and pass
+ * `value` as an `(x, y) => number` sampling function.
+ */
+export type GeoContourMarker<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    type: 'contour';
+    data?: TRow[];
+    x?: Accessor<TRow, number>;
+    y?: Accessor<TRow, number>;
+    value?: Accessor<TRow, number> | ((x: number, y: number) => number);
+    thresholds?: number | number[];
+    fill?: 'value' | string;
+    stroke?: 'value' | string;
+    blur?: number;
+    interpolate?: 'none' | 'nearest' | 'barycentric' | 'random-walk';
+    style?: {
+        strokeWidth?: number;
+        fillOpacity?: number;
+        strokeOpacity?: number;
+    };
+    /**
+     * Masks the contour to just the base map's landmass (`'land'`) or just
+     * its water (`'ocean'`) — e.g. a temperature contour that should only
+     * shade land, leaving the ocean bare (or the reverse).
+     */
+    clip?: 'land' | 'ocean';
+    /**
+     * Renders behind the base map's own fill/stroke instead of on top of it —
+     * lets a filled contour read as background shading with the base map's
+     * feature borders drawn crisply over it, rather than the contour
+     * obscuring them.
+     */
+    behind?: boolean;
+};
+/**
+ * The in-map hover highlight. `strategy` chooses which candidate point set
+ * drives matching: `'nearest-feature'` (base-map feature centroids —
+ * choropleth-style hover) or `'nearest-point'` (a `dot` marker's own rows).
+ */
+export type GeoHoverMarkerConfig = {
+    type: 'hover';
+    strategy?: 'nearest-feature' | 'nearest-point';
+    showLabels?: boolean;
+    format?: (point: HoverDisplayPoint) => string;
+    dotStyle?: DotStyle;
+    fontStyle?: FontStyle;
+};
+/** Mounts an arbitrary Svelte component as a mark — the geo analog of `CustomComponentMarker` (no `series` concept here). */
+export type GeoCustomComponentMarker = {
+    type: 'component';
+    component: any;
+    props?: Record<string, unknown>;
+    data?: any[];
+};
+/**
+ * Which edge of the plot frame an inset is anchored to, and where along that
+ * edge — a `side-anchor` pair joined by `-`, in either word order (so
+ * `'bottom-right'` and `'right-bottom'` are the same corner). `side` is
+ * `top`/`bottom`/`left`/`right`; `anchor` is the same four plus `middle`
+ * (e.g. `'right-middle'` centers the inset vertically along the right edge).
+ */
+export type GeoInsetLocation = 'top-left' | 'left-top' | 'top-middle' | 'middle-top' | 'top-right' | 'right-top' | 'middle-left' | 'left-middle' | 'middle-middle' | 'middle-right' | 'right-middle' | 'bottom-left' | 'left-bottom' | 'bottom-middle' | 'middle-bottom' | 'bottom-right' | 'right-bottom';
+/**
+ * Named projections an `inset` marker can use for its own independently-fit
+ * mini-map — everything `GeoProjectionName` offers except `'identity'`/
+ * `'reflect-y'`, which have no scale/translate of their own to fit (see
+ * `GeoProjectionConfig.domain`'s doc comment) and so can't auto-fit the way
+ * every inset needs to.
+ */
+export type GeoInsetProjectionName = Exclude<GeoProjectionName, 'identity' | 'reflect-y'>;
+/**
+ * Independent hover tooltip scoped to just one `inset` marker's own rendered
+ * features. Matched by nearest projected centroid within the inset's own
+ * local mini-projection/box — entirely decoupled from the plot's own
+ * top-level `tooltip`, which only ever matches the main map's own features
+ * (an inset draws in its own coordinate space, at its own scale, so the
+ * main map's hover has no way to reach it). No `facetId`/`sync`/`strategy`
+ * here, unlike the top-level `TooltipConfig` — an inset never broadcasts
+ * its hover to other facets and always matches punctually.
+ */
+export type GeoInsetTooltipConfig = {
+    /** Tooltip text for the nearest feature (by centroid) to the cursor, within this inset. */
+    format: (feature: GeoFeature<Record<string, unknown>>) => string;
+    /** Custom tooltip body; replaces `format` when given. */
+    content?: Snippet<[{
+        rows: GeoFeature<Record<string, unknown>>[];
+    }]>;
+};
+/** Projection config for an `inset` marker — like `GeoProjectionConfig`, minus `inset`/`domain` (insets always auto-fit to their own content) and custom factories (which can't guarantee `fitExtent`). */
+export type GeoInsetProjectionConfig = GeoInsetProjectionName | {
+    type?: GeoInsetProjectionName;
+    rotate?: [number, number] | [number, number, number];
+    center?: [number, number];
+    parallels?: [number, number];
+    clip?: boolean | null | number | 'frame';
+};
+/**
+ * A small, independently-projected map panel anchored to a corner/edge of
+ * the plot — for showing a region at a different, more legible scale than
+ * the main map (a disjoint territory, a dense metro area, etc.), the way
+ * national mapping agencies commonly draw insets for exactly this reason.
+ *
+ * What it shows is either a filtered subset of the plot's own `data` (via
+ * `features`, matched the same way `segments` keys are) or a wholly
+ * separate dataset (`data`, which takes precedence over `features` when
+ * both are given) — the inset's own mini-projection is fit to whichever one
+ * applies, independently of the main map's projection/zoom.
+ */
+export type GeoInsetMarker<TProps extends Record<string, unknown> = Record<string, unknown>> = {
+    type: 'inset';
+    location: GeoInsetLocation;
+    /** Feature ids (matching the plot's own `featureId`) to filter from the plot's own `data`. Ignored when `data` is set. */
+    features?: string[];
+    /**
+     * Narrows each `features`-matched feature down to just the geometry parts
+     * that pass this predicate (each polygon of a `MultiPolygon`, each line of
+     * a `MultiLineString`) — same `(part, feature)` signature as
+     * `GeoDataProps.excludeParts`, so the same predicate can be passed to both
+     * to split one feature's geometry between the main map and this inset
+     * without preprocessing the source data. Omitted → every part of each
+     * matched feature renders, as before. Ignored when `data` is set.
+     */
+    featurePartsFilter?: (part: {
+        centroid: [number, number];
+        geometry: GeoJSON.Geometry;
+    }, feature: GeoFeature<TProps> & {
+        __id: string;
+    }) => boolean;
+    /** A separate GeoJSON dataset rendered inside the inset instead of a filtered subset of the plot's own `data`. TopoJSON isn't supported here. */
+    data?: GeoJsonInput<TProps>;
+    /** Projection for just this inset, independently fit to whatever it ends up showing. Defaults to `'mercator'`. */
+    projection?: GeoInsetProjectionConfig;
+    /** Inset box size as a fraction of the plot's own width/height. Defaults to `0.26`/`0.22`. */
+    width?: number;
+    height?: number;
+    /** Gap between the inset box and the plot's own edge, in pixels. Defaults to `8`. */
+    margin?: number;
+    style?: GeoSegmentStyle;
+    /** Independent hover tooltip for just this inset's own rendered features — see `GeoInsetTooltipConfig`. */
+    tooltip?: GeoInsetTooltipConfig;
+};
+export type GeoMarker = GeoGraticuleMarker | GeoSphereMarker | GeoDotMarker | GeoVectorMarker | GeoLinkMarker | GeoContourMarker | GeoHoverMarkerConfig | GeoCustomComponentMarker | GeoInsetMarker;

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

@@ -0,0 +1,11 @@
+/**
+ * Baseline props every marker component receives when mounted by a plot:
+ * `data` for the points/values it draws, plus `series`/`seriesColor` when
+ * mounted per-series via a `CustomComponentMarker`. Marker components extend
+ * this with whatever else they need (e.g. PeakMarker's `mode`, `label`).
+ */
+export interface MarkerProps<TData = Record<string, unknown>> {
+    data?: TData[];
+    series?: string;
+    seriesColor?: string;
+}

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

@@ -0,0 +1,55 @@
+export type AxisValue = number | string | Date;
+/**
+ * Author-facing scale overrides for a plot axis. Mirrors svelteplot's
+ * `ScaleOptions` + `XScaleOptions` in full — `type`, `padding`, `domain`,
+ * `nice`, `reverse`, `label`, `tickFormat`, `labelAnchor`, etc.
+ *
+ * Used for both `x` and `y` entries in `ScalesConfig`. X-specific
+ * fields (`labelAnchor`, `tickRotate`) are accepted on `y` too; svelteplot
+ * silently ignores any inapplicable options.
+ *
+ * `TData` is the plot's own row type — it's what {@link AxisScale.sort}
+ * receives, so ordering isn't limited to comparing this axis's own value.
+ */
+export type AxisScale<TData = Record<string, unknown>> = {
+    type?: 'auto' | 'linear' | 'pow' | 'sqrt' | 'log' | 'symlog' | 'time' | 'utc' | 'point' | 'ordinal' | 'sequential' | 'band' | 'categorical' | 'cyclical' | 'threshold' | 'quantile-cont' | 'quantile' | 'quantize' | 'diverging' | 'diverging-log' | 'diverging-pow' | 'diverging-sqrt' | 'diverging-symlog';
+    domain?: (number | string | boolean | Date | null)[];
+    range?: (number | string | boolean | Date | null)[];
+    reverse?: boolean;
+    label?: string | false;
+    labelAnchor?: 'auto' | 'left' | 'center' | 'right' | 'bottom' | 'middle' | 'top';
+    labelOrientation?: 'horizontal' | 'vertical';
+    labelPosition?: 'top' | 'middle';
+    titleFontSize?: number;
+    interval?: string | number;
+    clamp?: boolean;
+    nice?: boolean;
+    zero?: boolean;
+    round?: boolean;
+    percent?: boolean;
+    align?: number;
+    base?: number;
+    constant?: number;
+    sort?: (a: TData, b: TData) => number;
+    grid?: boolean | {
+        stroke?: string;
+        strokeWidth?: number;
+        strokeOpacity?: number;
+        strokeDasharray?: string;
+    };
+    padding?: number;
+    paddingInner?: number;
+    paddingOuter?: number;
+    insetLeft?: number;
+    insetRight?: number;
+    insetTop?: number;
+    insetBottom?: number;
+    ticks?: (number | string | boolean | Date | null)[];
+    tickSpacing?: number;
+    tickSize?: number;
+    tickPadding?: number;
+    tickRotate?: number;
+    tickFormat?: false | Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | ((d: unknown, index: number, ticks: unknown[]) => string | string[]);
+    seriesLayout?: 'overlap' | 'grouped' | 'stacked';
+    seriesPadding?: number;
+};

package/dist/types/plots/axis.js

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

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

@@ -0,0 +1,30 @@
+/**
+ * Unified positional anchor for value labels across all plot kinds.
+ *
+ * - `'outside'` — beyond the tip of the mark (above a vertical bar, to the
+ *   far end of a horizontal bar or line). This is the only value with no
+ *   direct svelteplot equivalent; the plot computes dx/dy internally.
+ * - `'start'` — at the tip of the mark, just inside (top of a bar, far end
+ *   of a pyramid bar from zero, right of a line's last point).
+ * - `'middle'` — centred on the mark.
+ * - `'end'` — at the baseline/zero end of the mark.
+ */
+export type ValueAnchor = 'outside' | 'start' | 'middle' | 'end';
+export type SymbolType = 'circle' | 'square' | 'triangle' | 'line';
+export type LineStyle = 'solid' | 'dashed' | 'dotted' | 'dashdot';
+export type LineCap = 'butt' | 'round' | 'square';
+export type LineJoin = 'arcs' | 'bevel' | 'miter' | 'miter-clip' | 'round';
+/** `font-weight` keyword accepted by any text styling. */
+export type FontWeight = 'normal' | 'bold';
+/** `font-style` keyword accepted by any text styling. */
+export type FontStyleKeyword = 'normal' | 'italic';
+/**
+ * Horizontal text anchor. `'outside'` is only meaningful where the consuming
+ * mark resolves it per-point from a signed x value (currently `HoverMarker`
+ * only) — it anchors the label away from zero: `'start'` (extending right)
+ * for a positive x, `'end'` (extending left) for negative. Elsewhere it's
+ * treated the same as `'start'`.
+ */
+export type TextAnchor = 'start' | 'middle' | 'end' | 'outside';
+/** Vertical text anchor. */
+export type LineAnchor = 'top' | 'middle' | 'bottom';

package/dist/types/plots/constants.js

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

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

@@ -0,0 +1,40 @@
+import type { AxisValue } from '../axis';
+/**
+ * A field key or accessor function. Mirrors the shorthand used across plots
+ * so chart-level encodings (`x`, `y`, `z`, facet, timeline) feel consistent
+ * with the plot-level series definitions.
+ */
+export type Accessor<TRow extends Record<string, unknown>, V> = keyof TRow | ((d: TRow) => V);
+/**
+ * A plot series: a name, x/y accessors and the rows it draws. Shared as-is by
+ * every mark (line, bar, …) — none of them need anything beyond this shape;
+ * visual styling lives separately in `segments`.
+ */
+export type Series<T extends Record<string, unknown> = Record<string, unknown>> = {
+    name: string;
+    x: Accessor<T, AxisValue>;
+    y: Accessor<T, AxisValue>;
+    z?: Accessor<T, unknown>;
+    data: T[];
+};
+/**
+ * Pre-built series. Mutually exclusive with {@link DataProps} — takes
+ * precedence when both could apply.
+ */
+export type SeriesProps<T extends Record<string, unknown>> = {
+    series: Series<T>[];
+    data?: never;
+    x?: never;
+    y?: never;
+    z?: never;
+};
+/**
+ * Flat rows to group into series, as an alternative to {@link SeriesProps}.
+ */
+export type DataProps<T extends Record<string, unknown>> = {
+    series?: never;
+    data: T[];
+    x: Accessor<T, AxisValue>;
+    y: Accessor<T, AxisValue>;
+    z?: Accessor<T, unknown>;
+};

package/dist/types/plots/data/common.js

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

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

@@ -0,0 +1,74 @@
+import type { Accessor } from './common';
+/**
+ * One GeoJSON feature, generically typed over its `properties`. Intersected
+ * with `Record<string, unknown>` so it satisfies the same generic bound
+ * every other row type in this package does (e.g. `TooltipConfig<TRow
+ * extends Record<string, unknown>>`) — GeoJSON's own `Feature` type has no
+ * index signature on its own.
+ */
+export type GeoFeature<TProps extends Record<string, unknown> = Record<string, unknown>> = GeoJSON.Feature<GeoJSON.Geometry, TProps> & Record<string, unknown>;
+export type GeoJsonInput<TProps extends Record<string, unknown>> = GeoJSON.FeatureCollection<GeoJSON.Geometry, TProps> | GeoFeature<TProps>[];
+/**
+ * Minimal structural shape of a TopoJSON `Topology` object. Deliberately not
+ * imported from `topojson-client`'s own types, so referencing it never forces
+ * module resolution of that (optional peer) package at typecheck time for
+ * consumers who haven't installed it — see `$lib/plots/utils/topojson`.
+ */
+export type Topology = {
+    type: 'Topology';
+    objects: Record<string, unknown>;
+    arcs: unknown[][];
+    transform?: {
+        scale: [number, number];
+        translate: [number, number];
+    };
+    bbox?: number[];
+};
+/**
+ * Data contract for GeoPlot — the geo analog of {@link DataProps}/{@link SeriesProps}
+ * (`$lib/types/plots/data/common`). There's no x/y/z axis pair for geographic data:
+ * `data` IS the map.
+ */
+export type GeoDataProps<TProps extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * GeoJSON is always accepted. A TopoJSON `Topology` is also accepted, but
+     * only converted at runtime if `topojson-client` is installed (an optional
+     * peer dependency) — see `object`.
+     */
+    data: GeoJsonInput<TProps> | Topology;
+    /**
+     * Required when `data` is a `Topology` — the key under `topology.objects`
+     * to convert via topojson-client's `feature()`. Ignored for GeoJSON input.
+     */
+    object?: string;
+    /**
+     * Resolves each feature's stable id — used as the `segments` lookup key
+     * (e.g. `segments.argentina`) and for hover/click identification. Defaults
+     * to `feature.id ?? feature.properties?.id ?? feature.properties?.name`.
+     */
+    featureId?: Accessor<GeoFeature<TProps>, string>;
+    /**
+     * Optional continuous value accessor for choropleth coloring (mirrors
+     * heatmap's `z`). A feature with no `value` (or when omitted entirely)
+     * falls back to `styles.fill`/`segments`.
+     */
+    value?: (feature: GeoFeature<TProps>) => number | undefined;
+    /**
+     * Excludes matching parts of a feature's geometry from the map's own
+     * rendering and hover/click matching — e.g. so a separate `inset` marker
+     * (via its own `featurePartsFilter`) can take over showing that part
+     * elsewhere without it being drawn twice. Runs once per disjoint part of
+     * each feature's geometry (each polygon of a `MultiPolygon`, each line of
+     * a `MultiLineString`; any other geometry type is a single part). Return
+     * `true` to exclude that part — excluding every part of a feature drops
+     * it entirely, which also covers omitting a whole feature from the map.
+     * `segments` styling is unaffected (still keyed by whole-feature
+     * `featureId`, applied to whatever geometry remains).
+     */
+    excludeParts?: (part: {
+        centroid: [number, number];
+        geometry: GeoJSON.Geometry;
+    }, feature: GeoFeature<TProps> & {
+        __id: string;
+    }) => boolean;
+};

package/dist/types/plots/data/geo.js

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

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

@@ -1,5 +1,5 @@
-import type { AxisValue } from './common';
-import type { StrokeStyle, FontStyle, DotStyle } from './styles';
+import type { AxisValue } from './axis';
+import type { StrokeStyle, FontStyle, DotStyle } from './styling';
 export type DeltaTarget = {
     type: 'series';
     series: string;

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

@@ -1,23 +1,112 @@
-import type { Marker } from './markers';
-import type { TooltipRuntime } from '../layout/tooltip';
-import type { PlotStyles, Segments } from './styles';
-import type { SeriesProps, DataProps, ScalesConfig, MarginConfig } from './common';
+import type { TooltipOptions } from '../layout/tooltip';
+import type { Segment } from './segments/config';
+import type { AxisScale } from './axis';
+import type { GeoProjectionConfig } from './scales/geo';
+/** The `styles` prop accepted by every plot kind — its own
+ * styles shape ({@link BasePlotStyles}, `GeoStyles`, …). */
+export type StylesConfig<TStyles extends object> = TStyles;
+/** The `markers` prop accepted by every plot kind — a list of that
+ * kind's own marker union ({@link Marker}, `GeoMarker`, …). */
+export type MarkersConfig<TMarker> = TMarker[];
 /**
- * Common props accepted by every plot component (bar, line, heatmap, pyramid,
- * …). The `TSegmentStyle` parameter lets each plot narrow `segments` to its
- * own style shape ({@link BarSegmentStyle}, {@link LineSegmentStyle}, etc.)
- * while keeping everything else shared.
+ * The `segments` prop accepted by every plot kind.
  *
- * Data can be provided either as pre-built {@link SeriesProps} or as flat
- * rows via {@link DataProps}.
+ * A record mapping series names (or `'default'` for all series) to lists of
+ * {@link Segment}s. Segments in a named key apply only to that series;
+ * segments under `'default'` apply to every series.
+ *
+ * ```ts
+ * segments: {
+ *   female:  [{ style: { stroke: { stroke: 'tomato' } } }],   // catch-all for female
+ *   male:    [{ style: { stroke: { stroke: 'steelblue' } } }], // catch-all for male
+ *   default: [{ areas: [{ x: { from: 2012, to: 2014 } }], style: { dots: { dotSymbol: 'circle' } } }],
+ * }
+ * ```
+ *
+ * Within each resolved series list, catch-alls (no `areas`) are evaluated last
+ * so that area-specific segments always override them, regardless of position.
+ * Area-specific segments also inherit any style key absent from their own style
+ * by merging the catch-all as a baseline — the area's own style wins on conflict.
+ * This lets you set a series colour once in a catch-all and add per-range dots
+ * or dash patterns without repeating the colour on every area segment.
+ */
+export type SegmentsConfig<TStyle> = Record<string, Segment<TStyle>[]>;
+/**
+ * Partial margin override — only the sides you specify are overridden; the
+ * rest come from the theme (which itself defaults every side to `'auto'`).
+ * `'auto'` sizes that side to fit its rendered content (tick labels, axis
+ * title, rotated ticks); a number pins it exactly.
+ */
+export type MarginConfig = Partial<{
+    top: number | 'auto';
+    right: number | 'auto';
+    bottom: number | 'auto';
+    left: number | 'auto';
+}>;
+/**
+ * The `tooltip` prop a plot actually receives — the chart's resolved form of
+ * the author-facing {@link TooltipOptions} (which a chart accepts as a bare
+ * `boolean` or the full object via `TooltipProp`): `format`/`sync` become
+ * required once resolved, and `facetId` identifies the originating facet
+ * (`''` when not faceted). Presence of this object on a plot is what turns
+ * hovering on.
+ */
+export type TooltipConfig<TRow extends Record<string, unknown>> = Omit<TooltipOptions<TRow>, 'format' | 'sync'> & {
+    format: (row: TRow) => string;
+    sync: boolean;
+    facetId: string;
+};
+/**
+ * Per-axis scale overrides, passed as a single `scales` prop to every
+ * axis-based plot kind (`GeoPlot` uses {@link 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>;
+};
+/**
+ * `scales` prop for GeoPlot — the geo analog of {@link AxisBasedScalesConfig}.
+ * A map has no x/y/z axis pair, so this configures the projection and the
+ * choropleth colour domain instead.
+ */
+export type GeoScalesConfig = {
+    /** Which map projection to draw with. Defaults to `'equal-earth'`. */
+    projection?: GeoProjectionConfig;
+    /** Continuous choropleth value domain — mirrors heatmap's `scales.z.domain`. */
+    color?: {
+        domain?: [number, number];
+    };
+};
+/**
+ * The `scales` prop accepted by every plot kind — either flavor of scale
+ * config a plot kind can have ({@link AxisBasedScalesConfig} for the
+ * axis-based kinds, {@link GeoScalesConfig} for `GeoPlot`). Each concrete
+ * `Plot.svelte` narrows `BasePlotProps`'s `TScales` to exactly the one
+ * that applies to it, rather than accepting this whole union.
+ */
+export type ScalesConfig<TData = Record<string, unknown>> = AxisBasedScalesConfig<TData> | GeoScalesConfig;
+/**
+ * The shared "prop bag" every plot component accepts, parameterized over
+ * everything that varies by plot kind: `TDataContract` is the kind's own
+ * data shape ({@link SeriesProps}`|`{@link DataProps} for the axis-based
+ * kinds, `GeoDataProps` for `GeoPlot`), `TRow` is what `tooltip` resolves
+ * against, and `TStyles`/`TSegmentStyle`/`TMarker`/`TScales` are that kind's
+ * own segment/style/marker/scale shapes. Each `Plot.svelte` instantiates
+ * this directly with its own concrete arguments rather than going through a
+ * shared per-kind alias — segments/styles/markers already diverge in shape
+ * across kinds today (or will soon), so a shared alias would just be an
+ * extra layer to keep in sync.
  */
-export type PlotProps<TData extends Record<string, unknown>, TSegmentStyle extends object = object> = (SeriesProps<TData> | DataProps<TData>) & {
+export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>> = TDataContract & {
     width: number;
     height: number;
-    styles?: PlotStyles;
-    segments?: Segments<TSegmentStyle>;
-    markers?: Marker[];
-    scales?: ScalesConfig;
+    styles?: StylesConfig<TStyles>;
+    segments?: SegmentsConfig<TSegmentStyle>;
+    markers?: MarkersConfig<TMarker>;
+    scales?: TScales;
     margins?: MarginConfig;
-    tooltip?: TooltipRuntime<TData>;
+    tooltip?: TooltipConfig<TRow>;
 };

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

@@ -0,0 +1,44 @@
+/**
+ * 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`
+ * for svelteplot to stream marks through it and invert pointer coordinates
+ * back to lon/lat. Deliberately narrower than importing `GeoProjection`
+ * itself, since a hand-tuned custom projection may not implement its full
+ * surface (e.g. no single `scale`/`translate` describing it).
+ */
+export type GeoCustomProjection = Pick<GeoProjection, 'stream'> & Partial<Pick<GeoProjection, 'invert'>>;
+/**
+ * A custom projection factory, usable as `scales.projection.type` alongside
+ * (instead of) a `GeoProjectionName`. svelteplot calls this with the plot's
+ * inner width/height (already net of margins/insets) and expects a
+ * ready-to-use projection back.
+ */
+export type GeoCustomProjectionFactory = (opts: {
+    width: number;
+    height: number;
+}) => GeoCustomProjection;
+export type GeoProjectionConfig = GeoProjectionName | {
+    type?: GeoProjectionName | GeoCustomProjectionFactory;
+    rotate?: [number, number] | [number, number, number];
+    center?: [number, number] | [number, number, number];
+    parallels?: [number, number] | [number, number, number];
+    inset?: number;
+    clip?: boolean | null | number | 'frame';
+    /**
+     * Fits the projection's scale/translate to this GeoJSON object's extent
+     * instead of the projection's own default (whole-world-sized) framing,
+     * regardless of which named projection is active. Also what makes
+     * `'identity'`/`'reflect-y'` (which otherwise have no scale/translate of
+     * their own — they pass lon/lat through as-is) size themselves to fill
+     * the plot. Pass `'data'` to fit to whatever was already given to the
+     * plot's own `data` prop, instead of repeating it here.
+     */
+    domain?: GeoJSON.GeoJsonObject | GeoJSON.FeatureCollection | GeoJSON.Feature | 'data';
+};

package/dist/types/plots/scales/geo.js

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