@fundar/data-chart-telling 0.0.25 → 0.0.26

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

@@ -0,0 +1,45 @@
+import type { AxisValue } from '../layout/scales';
+import type { DotStyle, FontStyle } from '../plots/styling';
+import type { ColorsStyle } from '../layout/styles';
+/**
+ * A set of point marks (svelteplot's `Dot`) — usable on any plot kind, axis-based or geo.
+ *
+ * `x`/`y`/`r`/`value` accept a field key or an accessor function, like `Series.x`/`y`.
+ * `GeometryLayout` resolves the shorthand before it reaches `DotMarker.svelte`, which only
+ * ever sees functions.
+ */
+export type DotMarkerConfig = {
+    type: 'dot';
+    data: Record<string, unknown>[];
+    x: string | ((d: any) => AxisValue);
+    y: string | ((d: any) => AxisValue);
+    /** Per-row radius, or a constant — overrides `style.dotRadius`. */
+    r?: number | string | ((d: any) => number);
+    /** Per-row fill, overriding `style.dotFill` — ignored when `value` is set. */
+    fill?: (d: any) => string;
+    /** Continuous value driving a per-dot color ramp through `style.colors`. */
+    value?: string | ((d: any) => number);
+    style?: DotStyle & {
+        colors?: ColorsStyle;
+    };
+};
+/**
+ * A text label per row (svelteplot's `Text`) — usable on any plot kind, axis-based or geo.
+ *
+ * `x`/`y` accept the same field-key-or-function shorthand as `DotMarkerConfig`. `text` is a
+ * constant or a per-row accessor.
+ */
+export type TextMarkerConfig = {
+    type: 'text';
+    data: Record<string, unknown>[];
+    x: string | ((d: any) => AxisValue);
+    y: string | ((d: any) => AxisValue);
+    text: string | ((d: any) => string);
+    style?: FontStyle;
+};
+/**
+ * Every marker kind usable on any plot, axis-based or geo. `AxisBasedMarkersConfig`
+ * (`types/markers/common.ts`) and `GeoMarkersConfig` (`types/markers/geo.ts`) both extend
+ * this, so `MarkerConfig` (`types/markers/all.ts`) can union the two without a shape collision.
+ */
+export type BaseMarkersConfig = DotMarkerConfig | TextMarkerConfig;

package/dist/types/markers/base.js

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

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 {};