@fundar/data-chart-telling 0.0.25 → 0.0.27

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

@@ -1,21 +1,18 @@
-import type { AxisValue } from '../plots/axis';
-import type { DotStyle, FontStyle, StrokeStyle } from '../plots/styling';
+import type { AxisValue } from '../layout/scales';
+import type { FontStyle, StrokeStyle, DotStyle, AreaStyle } from '../plots/styling';
 import type { HoverStrategy, HoverDisplayPoint } from '../layout/tooltip';
-export type RuleXMarker = {
-    type: 'ruleX';
-    x: AxisValue;
-    style?: StrokeStyle;
-};
-export type RuleYMarker = {
-    type: 'ruleY';
-    y: AxisValue;
+import type { BaseMarkersConfig } from './base';
+export type { DotMarkerConfig } from './base';
+export type RuleMarkerConfig = {
+    type: 'rule';
+    axis: 'x' | 'y';
+    value: AxisValue;
     style?: StrokeStyle;
 };
 /**
- * The in-SVG hover highlight (crosshair + dot + label), opt-in via `markers`
- * so it can be combined freely with — or used entirely without — the HTML
- * tooltip. Omitting `series` mounts it unscoped (all series); scoping it to
- * one series follows the same targeting fields as {@link CustomComponentMarker}.
+ * In-SVG hover highlight (crosshair + dot + label). Omitting `series`
+ * applies it to all series; scoping follows the same fields as
+ * {@link CustomComponentMarkerConfig}.
  */
 export type HoverMarkerConfig = {
     type: 'hover';
@@ -31,7 +28,51 @@ export type HoverMarkerConfig = {
     dotStyle?: DotStyle;
     fontStyle?: FontStyle;
 };
-export type CustomComponentMarker = {
+/** A single line-segment stroke. Endpoint dots are a separate `'dot'` marker rather than a field here. */
+export type LineMarkerConfig = {
+    type: 'line';
+    data: Record<string, unknown>[];
+    x: (d: any) => AxisValue;
+    y: (d: any) => AxisValue;
+    style?: StrokeStyle;
+};
+/**
+ * A single bar mark. `role: 'segment'` is a visible bar
+ * (`x`/`y`/`x1`/`x2`/`y1`/`y2` map to svelteplot's `<BarX>`/`<BarY>` per
+ * `isHorizontal`); `role: 'hitArea'` is an invisible per-category hit region
+ * for hover, resolved against the live scale at render time.
+ */
+export type BarMarkerConfig = {
+    type: 'bar';
+    role: 'segment' | 'hitArea';
+    isHorizontal: boolean;
+    data: Record<string, unknown>[];
+    x?: (d: any) => AxisValue;
+    y?: (d: any) => AxisValue;
+    x1?: number | ((d: any) => number);
+    x2?: number | ((d: any) => number);
+    y1?: number | ((d: any) => number);
+    y2?: number | ((d: any) => number);
+    insetTop?: number;
+    insetBottom?: number;
+    insetLeft?: number;
+    insetRight?: number;
+    style?: AreaStyle;
+    category?: AxisValue;
+    onpointerenter?: () => void;
+    onpointerleave?: () => void;
+};
+/** A single heatmap cell mark. `fill` stays a per-row accessor; the rest of the style is constant per call. */
+export type CellMarkerConfig = {
+    type: 'cell';
+    data: Record<string, unknown>[];
+    x: (d: any) => AxisValue;
+    y: (d: any) => AxisValue;
+    fill: (d: any) => string;
+    style?: AreaStyle;
+    inset?: number;
+};
+export type CustomComponentMarkerConfig = {
     type: 'component';
     series?: string;
     component: any;
@@ -39,4 +80,11 @@ export type CustomComponentMarker = {
     data?: any[];
     scope?: 'series' | 'segment';
 };
-export type Marker = RuleXMarker | RuleYMarker | HoverMarkerConfig | CustomComponentMarker;
+/**
+ * Every marker kind any axis-based plot can render: {@link BaseMarkersConfig}
+ * plus every axis-based-only kind. `BarPlot`/`HeatmapPlot`/`PyramidPlot` use
+ * this directly as their `markers` prop type; `LinePlot`'s own
+ * `LineMarkersConfig` (`types/markers/line.ts`) unions it with the line-only
+ * `delta` annotation instead.
+ */
+export type AxisBasedMarkersConfig = BaseMarkersConfig | RuleMarkerConfig | HoverMarkerConfig | LineMarkerConfig | BarMarkerConfig | CellMarkerConfig | CustomComponentMarkerConfig;

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

@@ -1,65 +1,36 @@
 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 { AreaStyle, StrokeStyle } from '../plots/styling';
 import type { GeoFeature, GeoJsonInput } from '../plots/data/geo';
 import type { GeoSegmentStyle } from '../plots/segments/common';
-import type { GeoProjectionName } from '../plots/scales/geo';
+import type { GeoProjectionName } from '../layout/coordinates';
+import type { TooltipAnchorX, TooltipAnchorY } from '../layout/tooltip';
+import type { BaseMarkersConfig } from './base';
 /** Longitude/latitude gridlines — svelteplot's `Graticule`. */
-export type GeoGraticuleMarker = {
+export type GeoGraticuleMarkerConfig = {
     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.
-     */
+    /** Renders behind the base map's own fill/stroke instead of on top of it (markers otherwise draw over the base map). */
     behind?: boolean;
 };
 /** The outer globe outline (for orthographic-type projections) — svelteplot's `Sphere`. */
-export type GeoSphereMarker = {
+export type GeoSphereMarkerConfig = {
     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.
-     */
+    /** Renders behind the base map's own fill/stroke instead of on top of it — needed when `style.fill` is set. */
     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>> = {
+export type GeoVectorMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = {
     type: 'vector';
     data: TRow[];
     x: Accessor<TRow, number>;
@@ -79,7 +50,7 @@ export type GeoVectorMarker<TRow extends Record<string, unknown> = Record<string
  * `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>> = {
+export type GeoLinkMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = {
     type: 'link';
     data: TRow[];
     x1: Accessor<TRow, number>;
@@ -97,7 +68,7 @@ export type GeoLinkMarker<TRow extends Record<string, unknown> = Record<string,
  * 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>> = {
+export type GeoContourMarkerConfig<TRow extends Record<string, unknown> = Record<string, unknown>> = {
     type: 'contour';
     data?: TRow[];
     x?: Accessor<TRow, number>;
@@ -113,65 +84,48 @@ export type GeoContourMarker<TRow extends Record<string, unknown> = Record<strin
         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).
-     */
+    /** Masks the contour to just the base map's landmass (`'land'`) or water (`'ocean'`). */
     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.
-     */
+    /** Renders behind the base map's own fill/stroke instead of on top of it. */
     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).
+ * The in-map hover highlight — restyles the hovered feature's own shape.
+ * Its own `type: 'geo-hover'` tag (rather than the axis-based `'hover'`)
+ * keeps it unambiguous: both configs are all-optional, so an author writing
+ * `{ type: 'hover' }` for a `GeoPlot` would otherwise be structurally
+ * indistinguishable from the axis-based marker.
  */
 export type GeoHoverMarkerConfig = {
-    type: 'hover';
-    strategy?: 'nearest-feature' | 'nearest-point';
-    showLabels?: boolean;
-    format?: (point: HoverDisplayPoint) => string;
-    dotStyle?: DotStyle;
-    fontStyle?: FontStyle;
+    type: 'geo-hover';
+    style?: AreaStyle;
 };
-/** Mounts an arbitrary Svelte component as a mark — the geo analog of `CustomComponentMarker` (no `series` concept here). */
-export type GeoCustomComponentMarker = {
-    type: 'component';
+/**
+ * Mounts an arbitrary Svelte component as a mark — the geo analog of
+ * `CustomComponentMarkerConfig` (no `series` concept here). Its own
+ * `type: 'geo-component'` tag (rather than the axis-based `'component'`)
+ * keeps the two unambiguous at `GeometryLayout`'s dispatch — same reasoning
+ * as `GeoHoverMarkerConfig`'s `'geo-hover'` tag.
+ */
+export type GeoCustomComponentMarkerConfig = {
+    type: 'geo-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).
+ * Which edge of the plot frame an inset is anchored to, and where along it
+ * — a `side-anchor` pair in either word order (`'bottom-right'` ==
+ * `'right-bottom'`). `side` is `top`/`bottom`/`left`/`right`; `anchor` is
+ * the same four plus `middle`.
  */
 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.
- */
+/** Named projections an `inset` marker can use, minus `'identity'`/`'reflect-y'`, which have no scale/translate to auto-fit. */
 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.
+ * features, matched by nearest projected centroid within the inset's own
+ * local mini-projection. Decoupled from the plot's own top-level `tooltip`.
  */
 export type GeoInsetTooltipConfig = {
     /** Tooltip text for the nearest feature (by centroid) to the cursor, within this inset. */
@@ -180,6 +134,13 @@ export type GeoInsetTooltipConfig = {
     content?: Snippet<[{
         rows: GeoFeature<Record<string, unknown>>[];
     }]>;
+    /**
+     * Preferred anchor for this inset's own tooltip. Unset falls back to the
+     * plot's own top-level `tooltip.anchorX`/`anchorY` when explicitly set
+     * there, then to the system default — see {@link TooltipAnchorX}.
+     */
+    anchorX?: TooltipAnchorX;
+    anchorY?: TooltipAnchorY;
 };
 /** 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 | {
@@ -191,29 +152,21 @@ export type GeoInsetProjectionConfig = GeoInsetProjectionName | {
 };
 /**
  * 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.
+ * the plot, showing a region at a different scale than the main map. Shows
+ * either a filtered subset of the plot's own `data` (via `features`) or a
+ * wholly separate dataset (`data`, which takes precedence when both are
+ * given).
  */
-export type GeoInsetMarker<TProps extends Record<string, unknown> = Record<string, unknown>> = {
+export type GeoInsetMarkerConfig<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.
+     * Narrows each `features`-matched feature to just the geometry parts that
+     * pass this predicate — same signature as `GeoDataProps.excludeParts`, so
+     * one feature's geometry can be split between the main map and this inset.
+     * Ignored when `data` is set.
      */
     featurePartsFilter?: (part: {
         centroid: [number, number];
@@ -234,4 +187,26 @@ export type GeoInsetMarker<TProps extends Record<string, unknown> = Record<strin
     /** 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;
+/**
+ * `GeoPlot`'s own `markers` prop type — unions {@link BaseMarkersConfig} with
+ * every geo-only kind. Independent of `AxisBasedMarkersConfig`
+ * (`types/markers/common.ts`): geo has no axis to `rule` against, and its
+ * `hover`/`component` variants differ in shape from the axis-based kinds'.
+ */
+export type GeoMarkersConfig = BaseMarkersConfig | GeoGraticuleMarkerConfig | GeoSphereMarkerConfig | GeoVectorMarkerConfig | GeoLinkMarkerConfig | GeoContourMarkerConfig | GeoHoverMarkerConfig | GeoCustomComponentMarkerConfig | GeoInsetMarkerConfig;
+/**
+ * The base choropleth/base-map mark — one per distinct resolved feature
+ * style. Never author-facing: `buildGeoMarkers` builds it from `GeoPlot`'s
+ * own `styleGroups`.
+ */
+export type GeoFeaturesMarkerConfig = {
+    type: 'geo';
+    data: Record<string, unknown>[];
+    fill: (d: any) => string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    onclick?: (e: Event, d: any) => void;
+    onpointerenter?: (e: Event, d: any) => void;
+    onpointerleave?: (e: Event) => void;
+};

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

@@ -0,0 +1,34 @@
+import type { AxisValue } from '../layout/scales';
+import type { StrokeStyle, FontStyle, DotStyle } from '../plots/styling';
+import type { AxisBasedMarkersConfig } from './common';
+/** Which endpoint a delta measures from/to: a named series, or a fixed axis value (defaults to `0`). */
+export type DeltaTarget = {
+    type: 'series';
+    series: string;
+} | {
+    type: 'axis';
+    value?: number;
+};
+/** How far apart two points are on a line chart: a given x (or y), or a series' distance from a fixed axis value. */
+export type DeltaConfig = {
+    axis: 'x' | 'y';
+    at: AxisValue;
+    from: DeltaTarget;
+    to?: DeltaTarget;
+    formatDiff?: (diff: number) => string;
+    strokeStyle?: StrokeStyle;
+    fontStyle?: FontStyle;
+    dotStyle?: DotStyle;
+};
+/**
+ * A delta annotation between two points on a line chart, resolved against
+ * series data (`utils/delta.ts`). `xDomain`/`yDomain` optionally clamp
+ * the varying endpoint to the plot's own axis range.
+ */
+export type DeltaMarkerConfig = {
+    type: 'delta';
+    xDomain?: (number | string | Date)[];
+    yDomain?: (number | string | Date)[];
+} & DeltaConfig;
+/** `LinePlot`'s own `markers` prop type — every {@link AxisBasedMarkersConfig} kind plus the line-only `'delta'` annotation. */
+export type LineMarkersConfig = AxisBasedMarkersConfig | DeltaMarkerConfig;

package/dist/types/markers/line.js

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

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * mounted per-series via a `CustomComponentMarkerConfig`. Marker components extend
  * this with whatever else they need (e.g. PeakMarker's `mode`, `label`).
  */
 export interface MarkerProps<TData = Record<string, unknown>> {

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

@@ -1,4 +1,4 @@
-import type { AxisValue } from '../axis';
+import type { AxisValue } from '../../layout/scales';
 /**
  * A field key or accessor function. Mirrors the shorthand used across plots
  * so chart-level encodings (`x`, `y`, `z`, facet, timeline) feel consistent

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

@@ -0,0 +1,13 @@
+import type { Accessor, SeriesProps, DataProps } from './common';
+/**
+ * `SeriesProps`/`DataProps`, plus an optional per-row bubble radius —
+ * ScatterPlot's own data contract. A field key or accessor function is
+ * bound to svelteplot's own auto sqrt scale (mirroring how `x`/`y` are
+ * bound to their own scales), so bubble *area* — not radius — ends up
+ * proportional to the raw values with no manual scaling needed; feeding it
+ * an already-scaled value double-scales it. A literal number bypasses
+ * scaling entirely (a fixed pixel radius, same as the default dot size).
+ */
+export type ScatterDataProps<T extends Record<string, unknown>> = (SeriesProps<T> | DataProps<T>) & {
+    r?: Accessor<T, number> | number;
+};

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

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

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

@@ -1,41 +1,23 @@
-import type { TooltipOptions } from '../layout/tooltip';
+import type { HoverPoint, HoverStrategy, TooltipOptions } from '../layout/tooltip';
 import type { Segment } from './segments/config';
-import type { AxisScale } from './axis';
-import type { GeoProjectionConfig } from './scales/geo';
+import type { AxisBasedScalesConfig } from '../layout/scales';
+import type { GeoScalesConfig } from '../layout/coordinates';
 /** The `styles` prop accepted by every plot kind — its own
- * styles shape ({@link BasePlotStyles}, `GeoStyles`, …). */
+ * styles shape ({@link BasePlotStylesConfig}, `GeoStylesConfig`, …). */
 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`, …). */
+/** The `markers` prop accepted by every plot kind — a list of that kind's own marker union. */
 export type MarkersConfig<TMarker> = TMarker[];
 /**
- * The `segments` prop accepted by every plot kind.
- *
- * 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.
+ * The `segments` prop accepted by every plot kind — series name (or
+ * `'default'` for all series) to a list of {@link Segment}s. Within a
+ * series, catch-all segments (no `areas`) evaluate first as a baseline;
+ * area-specific segments merge on top and win on conflict.
  */
 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.
+ * Partial margin override — unset sides fall back to the theme (itself
+ * `'auto'` by default). `'auto'` fits the side to its rendered content; a
+ * number pins it exactly.
  */
 export type MarginConfig = Partial<{
     top: number | 'auto';
@@ -44,69 +26,59 @@ export type MarginConfig = Partial<{
     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.
+ * The `tooltip` prop a plot actually receives — the resolved form of the
+ * author-facing {@link TooltipOptions}. `format`/`sync` become required;
+ * `facetId` identifies the originating facet (`''` when not faceted).
+ * Presence of this object 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];
-    };
+/** How a pointer event resolves to a candidate point: `'nearest'` (closest within a distance threshold) or `'contains'` (whichever candidate's own rendered shape contains the cursor). */
+export type PointMatchingStrategy = 'nearest' | 'contains';
+/** `BasePlotLayout`'s single `hover` prop — every plot kind's own resolved hover/tooltip wiring. */
+export type HoverConfig<TRow extends Record<string, unknown>> = {
+    /** Whether the pointer/hover/tooltip machinery should mount at all. */
+    active: boolean;
+    /** Candidate points hover matching searches against. */
+    points: HoverPoint<TRow>[];
+    /** Short label drawn next to the highlight dot (e.g. the value). */
+    label: (row: TRow) => string;
+    /** Resolved hover strategy for the *local* hover store (ignored once a shared store is in scope). */
+    strategy?: HoverStrategy;
+    /** Resolved sync flag for the *local* hover store (ignored once a shared store is in scope). */
+    sync?: boolean;
+    tooltip?: TooltipConfig<TRow>;
+    /** When it returns `true`, that pointer event is treated as a leave instead of a move — lets a nested layout opt part of the plot out of hover matching. */
+    exclude?: (e: PointerEvent) => boolean;
+    /** How to resolve a pointer event to a candidate point — see {@link PointMatchingStrategy}. Defaults to `'nearest'`. */
+    pointMatching?: PointMatchingStrategy;
+    /** Forces the crosshair rule(s) a `hover` marker draws off entirely, overriding whatever `strategy` implies. */
+    crosshair?: boolean;
 };
 /**
  * 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.
+ * config a plot kind can have. Each concrete `Plot.svelte` narrows
+ * `BasePlotProps`'s `TScales` to exactly the one that applies to it.
  */
 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.
+ * The shared prop bag every plot component accepts, parameterized over
+ * everything that varies by plot kind: `TDataContract` is its own data
+ * shape, `TRow` is what `tooltip` resolves against, and the rest are its
+ * own segment/style/marker/scale/coordinate-system shapes. `TCoordinates`
+ * defaults to `undefined` — only `GeoPlot` instantiates it.
  */
-export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>> = TDataContract & {
+export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>, TCoordinates = undefined> = TDataContract & {
     width: number;
     height: number;
     styles?: StylesConfig<TStyles>;
     segments?: SegmentsConfig<TSegmentStyle>;
     markers?: MarkersConfig<TMarker>;
     scales?: TScales;
+    coordinates?: TCoordinates;
     margins?: MarginConfig;
     tooltip?: TooltipConfig<TRow>;
 };

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

@@ -1,21 +1,15 @@
-import type { StrokeStyle, DotStyle } from '../styling';
+import type { StrokeStyle, DotStyle, AreaStyle } from '../styling';
 /** Per-segment styling for a line: its stroke and/or its endpoint dots. */
 export type LineSegmentStyle = {
     stroke?: StrokeStyle;
     dots?: DotStyle;
 };
-/** Per-segment styling for a bar-shaped mark: its fill. Shared by `BarPlot` and `PyramidPlot`. */
-export type BarSegmentStyle = {
-    fill?: string;
-    fillOpacity?: number;
-};
+/** Per-segment styling for a bar-shaped mark. Shared by `BarPlot` and `PyramidPlot`. */
+export type BarSegmentStyle = AreaStyle;
 /** Per-cell styling override for a heatmap cell. */
-export type CellSegmentStyle = {
-    fill?: string;
-    fillOpacity?: number;
-    stroke?: string;
-    strokeWidth?: number;
-};
+export type CellSegmentStyle = AreaStyle;
+/** Per-segment styling for a scatter point cloud. */
+export type ScatterSegmentStyle = DotStyle;
 /** Per-feature styling override for `GeoPlot` — the geo analog of `CellSegmentStyle`. */
 export type GeoSegmentStyle = {
     fill?: string;

package/dist/types/plots/segments/config.d.ts

@@ -1,4 +1,4 @@
-import type { AxisValue } from '../axis';
+import type { AxisValue } from '../../layout/scales';
 import type { Series } from '../data/common';
 import type { LineSegmentStyle } from './common';
 /** A half-open interval on one axis. Both bounds are inclusive; omit either to leave that end open. */