@fundar/data-chart-telling 0.0.64 → 1.0.0

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

@@ -1,4 +1,6 @@
 import type { StrokeStyle, DotStyle, FontStyle, AreaStyle } from '../plots/styling';
+import type { SymbolType } from '../plots/constants';
+import type { PlotChromeEntry } from '../plots/props';
 export type TextStyle = {
     /** font-family */
     font: string;
@@ -13,17 +15,34 @@ export type TextStyle = {
     /** letter-spacing */
     spacing: string;
 };
-export type ChartConfig = {
+/** How a chrome divider's line is drawn, as a CSS border style. */
+export type DividerLineStyle = 'solid' | 'dashed' | 'dotted' | 'double';
+export type PlotStylesConfig = {
     font: string;
     color: string;
     background: string;
-    border: string;
     spacing: {
         headerPadding: string;
         legendPadding: string;
         captionPadding: string;
         bleed: string;
     };
+    /** The line every `'divider'` in a plot's chrome `order` draws. */
+    divider: {
+        color: string;
+        /** Line thickness, e.g. `'1px'`. */
+        width: string;
+        style: DividerLineStyle;
+        /** Space around the line, as a CSS `margin`. */
+        margin: string;
+    };
+    /** What a plot's or composer's chrome draws around it. */
+    chrome: {
+        /** The blocks, top to bottom, when a figure doesn't set its own `order` - see {@link PlotChromeEntry}. */
+        order: PlotChromeEntry[];
+        /** The space between the blocks of a row of the chrome, as a CSS length. */
+        rowGap: string;
+    };
     title: TextStyle;
     subtitle: TextStyle;
     caption: TextStyle;
@@ -40,6 +59,25 @@ export type ChartConfig = {
         swatchSize: string;
         /** Fallback opacity for a legend-disabled series/value when a section doesn't set its own style. */
         disabledOpacity: number;
+        /**
+         * Whether names read off the data show as words (`gdp_per_capita` as
+         * "Gdp per capita"): an item with no `label`, and the titles the
+         * automatic legend takes from field names. Display only - toggling
+         * still goes by the name itself.
+         */
+        pretty: boolean;
+        /**
+         * The automatic legend's series section, titled `text` once the legend
+         * shows other sections too - a size or shape scale, or sections it adds.
+         */
+        seriesTitle: {
+            enabled: boolean;
+            text: string;
+        };
+        /** A size section: `gap` is the room between its dots (CSS length). */
+        sizeScale: {
+            gap: string;
+        };
         /** Prev/next arrows shown when a `layout: { type: 'horizontal' }` discrete section overflows `maxRows`. */
         navButton: {
             background: string;
@@ -84,7 +122,7 @@ export type ChartConfig = {
                     enabled: boolean;
                     /** How many px of horizontal slack the two labels need between them before they're considered overlapping (and flipped). */
                     margin: number;
-                    /** Rotation magnitude applied once overlapping — lo rotates by this amount, hi by its negation, so both still grow inward toward the bar instead of off its edges. */
+                    /** Rotation magnitude applied once overlapping - lo rotates by this amount, hi by its negation, so both still grow inward toward the bar instead of off its edges. */
                     rotate: string;
                 };
             };
@@ -101,6 +139,7 @@ export type ChartConfig = {
         yTickPadding: number;
         grid: boolean;
         locale: string;
+        /** Compact units abbreviated (`'short'`, the default: `1 M`) or spelled out (`'long'`: `1 millón`). Axes and size legends. */
         compactDisplay: 'short' | 'long';
     };
     tooltip: {
@@ -113,8 +152,8 @@ export type ChartConfig = {
     };
     /**
      * Per-side plot margin. `'auto'` (the default) lets svelteplot size that
-     * side to fit whatever it actually renders there — tick labels, an axis
-     * title, rotated ticks — instead of clipping content or leaving unused
+     * side to fit whatever it actually renders there - tick labels, an axis
+     * title, rotated ticks - instead of clipping content or leaving unused
      * space. A number pins that side exactly, opting out of auto-sizing.
      */
     margins: {
@@ -123,20 +162,33 @@ export type ChartConfig = {
         bottom: number | 'auto';
         left: number | 'auto';
     };
+    /** Marker clipping to the plot's inner frame (see `FrameClip`). */
+    frameClip: {
+        /**
+         * How far (px) a clipped mark may reach past the frame before it's cut,
+         * so strokes and labels on the edge aren't shaved off. A number sets all
+         * four sides; a string takes CSS shorthand px values for 1-4 sides, e.g.
+         * `'4px'`, `'4px 8px'`, `'0 8px 4px'`, `'0 8px 4px 2px'`.
+         */
+        tolerance: number | string;
+    };
     /** Discrete categorical palette (grouped series). */
     palette: string[];
-    /** Continuous gradient endpoints + on-cell label colour. */
+    /** Default shape cycle for the `symbol` channel, in order. */
+    symbols: SymbolType[];
+    /** Continuous gradient endpoints + on-cell label colour, plus the default opacity-channel range. */
     continuous: {
         min: string;
         max: string;
         labelColor: string;
+        opacityRange: [number, number];
     };
     /** Default line geometry. */
     line: {
         strokeWidth: number;
         dotRadius: number;
         /**
-         * Default gap-fill bridge styling (`LinePlot`'s `styles.gaps`) — the
+         * Default gap-fill bridge styling (`LinePlot`'s `styles.gaps`) - the
          * fallback merged under whatever a gap zone's own `style` sets, the
          * same way `hover.rule`/`hover.dot` back every hover marker's style.
          */
@@ -144,40 +196,49 @@ export type ChartConfig = {
             stroke: StrokeStyle;
             dots: DotStyle;
         };
-        /**
-         * End-of-line value-label declutter geometry and connector styling —
-         * `LinePlot`-specific, since only line charts spread colliding
-         * end-point labels apart with elbow-routed leader lines.
-         */
-        valueLabels: {
-            /** Shortest lane's distance (px) from the data point before a leader line bends. */
+    };
+    /** Default text-marker behavior. */
+    text: {
+        /** Geometry and connector of a decluttered text marker (`declutter`) - e.g. LinePlot's end-of-line value labels. */
+        declutter: {
+            /** Shortest lane's distance (px) from the point before a connector bends. */
             elbowGap: number;
-            /** Extra distance (px) each subsequent lane sits out from the last. */
+            /** Extra distance (px) each further lane sits out from the last. */
             laneStep: number;
-            /** Clearance (px) between the outermost lane and the label text it feeds into. */
+            /** Clearance (px) between the outermost lane and the label text. */
             labelGap: number;
-            /** Default leader-line colour — overridable per-plot via `styles.values.strokeStyle`. */
-            connectorColor: string;
-            /** Default leader-line width — overridable per-plot via `styles.values.strokeStyle`. */
-            connectorWidth: number;
+            /** Default connector stroke. */
+            connector: StrokeStyle;
         };
     };
     /** Default bar-mark styling. */
     bar: {
-        /** Default gap-fill styling (`BarPlot`'s `styles.gaps`) — the fallback merged under whatever a gap zone's own `style` sets. */
+        /** Default gap-fill styling (`BarPlot`'s `styles.gaps`) - the fallback merged under whatever a gap zone's own `style` sets. */
         gap: AreaStyle;
-        /** Fallback `scales.z.seriesPadding` (0–1) for 'grouped' series layout, when a plot doesn't set its own. */
+        /** Gap (0-1) between the bars of side-by-side series within one category, as a fraction of each bar's slice. */
         seriesPadding: number;
-        /** Fallback gap (0–1) *between* category groups on BarPlot's own category axis, when a plot doesn't set its own `scales.x/y.paddingInner`. */
+        /** Fallback gap (0-1) *between* category groups on BarPlot's own category axis, when a plot doesn't set its own `scales.x/y.paddingInner`. */
         paddingInner: number;
-        /** Fallback gap (0–1) before the first and after the last category group on BarPlot's own category axis, when a plot doesn't set its own `scales.x/y.paddingOuter`. */
+        /** Fallback gap (0-1) before the first and after the last category group on BarPlot's own category axis, when a plot doesn't set its own `scales.x/y.paddingOuter`. */
         paddingOuter: number;
     };
     /** Default pyramid-bar styling. */
     pyramid: {
-        /** Default gap-fill styling (`PyramidPlot`'s `styles.gaps`) — the fallback merged under whatever a gap zone's own `style` sets. */
+        /** Default gap-fill styling (`PyramidPlot`'s `styles.gaps`) - the fallback merged under whatever a gap zone's own `style` sets. */
         gap: AreaStyle;
     };
+    /** Default area-plot styling. */
+    area: {
+        /** Fill opacity of every area marker that sets none of its own. */
+        fillOpacity: number;
+    };
+    /** Default histogram styling. */
+    histogram: {
+        /** Pixels taken off each side of every bar, so neighbouring bars leave a gap of twice this. */
+        inset: number;
+        /** Fill opacity of every bar, so a grouped histogram's bars behind another group's still show. */
+        fillOpacity: number;
+    };
     /** Default scatter point geometry. */
     scatter: {
         dotRadius: number;
@@ -187,10 +248,74 @@ export type ChartConfig = {
         axisColor: string;
         activeColor: string;
         thickness: number;
+        /** Space between a plot (or a composition's panels) and its timeline, as a CSS length. */
+        gap: string;
+        /** The `'rule'` timeline beside a plot: a line with its steps written along it. */
+        rule: {
+            /** Font size of the steps, in px. */
+            fontSize: number;
+            /** Font size of the current step, in px. */
+            activeFontSize: number;
+            activeFontWeight: number | string;
+            /** Opacity of the steps other than the current one. */
+            labelOpacity: number;
+            /** Width of the line, in px. */
+            axisWidth: number;
+            axisOpacity: number;
+        };
+        /** The `'player'` timeline: a bar in the chrome with play, the current step, a slider and more. */
+        player: {
+            /** The controls it draws, in order, unless a timeline sets its own `player.controls`. */
+            controls: ('play' | 'value' | 'slider' | 'speed' | 'loop')[];
+            /** The speeds its speed control cycles through, as multiples of `stepDuration`. */
+            speeds: number[];
+            /** Milliseconds each step lasts at speed `1`. */
+            stepDuration: number;
+            background: string;
+            color: string;
+            /** CSS length. */
+            radius: string;
+            padding: string;
+            gap: string;
+            fontSize: string;
+            fontWeight: number | string;
+            /** Width reserved for the current step's text, so the slider doesn't shift as it changes. */
+            valueWidth: string;
+            /** The play and pause button. */
+            button: {
+                size: string;
+                background: string;
+                color: string;
+                hoverBackground: string;
+                radius: string;
+            };
+            /** The slider's line. */
+            track: {
+                height: string;
+                color: string;
+                fillColor: string;
+                radius: string;
+            };
+            /** The slider's handle. */
+            thumb: {
+                size: string;
+                color: string;
+            };
+            /** The speed and loop buttons. */
+            toggle: {
+                background: string;
+                color: string;
+                activeBackground: string;
+                activeColor: string;
+                radius: string;
+                fontSize: string;
+                padding: string;
+            };
+        };
     };
     /**
      * In-SVG hover highlight: crosshair rule, dot + value label, and the area
-     * highlight — a restyled feature on `GeoPlot`, or an `areaX`/`areaY` band
+     * highlight - a restyled feature on `GeoPlot`, or an `areaX`/`areaY` band
      * on an axis-based plot's band scale.
      */
     hover: {
@@ -220,7 +345,7 @@ export type ChartConfig = {
     };
 };
 /** Deep-partial input accepted by `setConfiguration`. */
-export type ChartConfigInput = DeepPartial<ChartConfig>;
+export type PlotStylesConfigInput = DeepPartial<PlotStylesConfig>;
 type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends (infer U)[] ? U[] : T[K] extends object ? DeepPartial<T[K]> : T[K];
 };

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

@@ -0,0 +1,24 @@
+import type { Box } from '../../layout/margins/Box';
+import type { MarginSide } from '../plots/props';
+/** Where a box sits along one axis, next to a point: before it, centred on it, or after it. */
+export type BoxAnchor = 'before' | 'middle' | 'after';
+/** A {@link BoxAnchor} per axis. */
+export type BoxAnchors = {
+    x: BoxAnchor;
+    y: BoxAnchor;
+};
+/** Where a box goes next to a point: the side it ends up on, per axis, and its offset from the point. */
+export type BoxFlip = {
+    anchor: BoxAnchors;
+    dx: number;
+    dy: number;
+};
+/**
+ * A box placed around a point (its origin), and the plot edges that point
+ * can sit on: how far the box reaches past each of those edges is room the
+ * plot's margins keep for it - see `PlotMargins`.
+ */
+export type EdgeBox = {
+    box: Box;
+    edges: MarginSide[];
+};

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

@@ -0,0 +1,36 @@
+import type { HoverStrategy } from './hover';
+import type { Orientation, PlayerConfig, TimeValue, TimelineCallbacks, TimelineType } from './timeline';
+/**
+ * How a `PlotComposer` arranges its panels: `areas` names the grid cells
+ * (one string per row, `.` for empty), else panels flow into `columns`;
+ * `widths`/`heights` are relative track sizes. `align` lines up every
+ * panel's plot area with its row and column, like facets do - for panels
+ * whose plots draw no chrome of their own.
+ */
+export type ComposerLayout = {
+    areas?: string[];
+    columns?: number;
+    widths?: number[];
+    heights?: number[];
+    gap?: number;
+    align?: boolean;
+};
+/** Labels a composer stamps on its panels in order: `'A'` (A, B, C…), `'a'`, `'1'`, `'I'` (roman), or an explicit list. */
+export type ComposerTags = 'A' | 'a' | '1' | 'I' | 'i' | string[];
+/** One timeline for every panel: plots with a `timeline` follow its `progress` over `values`. */
+export type ComposerTimelineConfig = TimelineCallbacks & {
+    progress?: number;
+    values: TimeValue[];
+    /** How it draws. Defaults to `'player'`. */
+    type?: TimelineType;
+    /** The player bar's own options, when `type` is `'player'`. */
+    player?: PlayerConfig;
+    orientation?: Orientation;
+    show?: boolean;
+    thickness?: number;
+};
+/** Hover shared by every panel: `sync` broadcasts one panel's hover to the others. */
+export type ComposerHoverConfig = {
+    strategy?: HoverStrategy;
+    sync?: boolean;
+};

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

@@ -1,14 +1,15 @@
 import type { GeoProjection } from 'd3-geo';
 import type { GeoCameraConfig } from '../plots/camera';
+import type { ChannelScalesConfig, LengthScaleConfig } from './scales';
 /**
  * The projection names svelteplot's `<Plot projection>` accepts as a string
- * (svelteplot itself doesn't export this as a type — defined here so authors
+ * (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';
 /**
  * What a custom projection factory (e.g. `argentinaBicontinental` under
- * `$lib`'s geo projections) must return — just enough of d3's `GeoProjection`
+ * `$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
@@ -37,24 +38,23 @@ export type GeoProjectionConfig = GeoProjectionName | {
      * 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
+     * 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';
 };
 /**
- * `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`).
+ * `scales` prop for GeoPlot - the geo analog of `AxisBasedScalesConfig`. A
+ * map has no x/y axis pair (the coordinate system is `coordinates.projection`),
+ * so this carries the channels in {@link ChannelScalesConfig} plus `length` -
+ * GeoPlot's own plot-wide-only channel (a `vector` marker's magnitude),
+ * the geo analog of `AxisBasedScalesConfig.r`.
  */
-export type GeoScalesConfig = {
-    /** Continuous choropleth value domain — mirrors heatmap's `scales.z.domain`. */
-    color?: {
-        domain?: [number, number];
-    };
+export type GeoScalesConfig = ChannelScalesConfig & {
+    length?: LengthScaleConfig;
 };
-/** Wheel/pinch scale gesture only — see `CoordinatesConfig.pan` for drag-to-translate, and `.rotate` for drag-to-spin-the-globe. */
+/** Wheel/pinch scale gesture only - see `CoordinatesConfig.pan` for drag-to-translate, and `.rotate` for drag-to-spin-the-globe. */
 export type GeoZoomConfig = {
     min?: number;
     max?: number;
@@ -65,7 +65,7 @@ export type GeoZoomConfig = {
     };
 };
 /**
- * `coordinates` prop for GeoPlot — bundles the projection, interactive
+ * `coordinates` prop for GeoPlot - bundles the projection, interactive
  * gestures, and the declarative `camera`, resolved by `CoordinatesLayout`.
  */
 export type CoordinatesConfig = {
@@ -77,6 +77,6 @@ export type CoordinatesConfig = {
     pan?: boolean;
     /** `true` enables drag-to-rotate on `orthographic` (claims the drag gesture from `pan`). */
     rotate?: boolean;
-    /** `GeoPlot`'s own declarative "current viewpoint" — frame/zoom/anchor on a target, animated on change. See `GeoCameraConfig`. */
+    /** `GeoPlot`'s own declarative "current viewpoint" - frame/zoom/anchor on a target, animated on change. See `GeoCameraConfig`. */
     camera?: GeoCameraConfig;
 };

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

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { Accessor } from '../plots/data/common';
 import type { MarginConfig } from '../plots/props';
+import type { CellEdges } from './grid';
 export type Responsive<T> = T | {
     desktop: T;
     mobile: T;
@@ -8,13 +9,33 @@ export type Responsive<T> = T | {
 export type FacetColumns = Responsive<number>;
 export type FacetMode = 'grid' | 'carousel' | 'paginated';
 export type FacetNavLayout = 'overlay' | 'below';
+/**
+ * Which position scales facets share: `'shared'` (default), `'free'`, or
+ * `'free-x'`/`'free-y'` for one axis. In a `rows`/`cols` grid a free x is
+ * shared down each column and a free y along each row.
+ */
+export type FacetScales = 'shared' | 'free' | 'free-x' | 'free-y';
+/**
+ * Which facets draw their axes: `'all'` (default), or `'outer'` for only the
+ * left column's y and the bottom row's x, with panels resized to equal boxes.
+ */
+export type FacetAxes = 'all' | 'outer';
+/** Where a facet sits in its grid - whether each of its sides is on the grid's outer edge. */
+export type FacetEdges = CellEdges;
 export type FacetCellContext<TRow extends Record<string, unknown>> = {
+    /** The facet's label: its `by` value, or its `rows`/`cols` values joined. */
     facetValue: string;
+    /** The facet's `rows` value, in a `rows`/`cols` grid. */
+    row?: string;
+    /** The facet's `cols` value, in a `rows`/`cols` grid. */
+    col?: string;
     data: TRow[];
     width: number;
     height: number;
-    /** Margin sized off every facet's own natural need, per side — see `marginsForFacet`. Present only when it's given. */
+    /** The margins pinned on the facet's plot so its panel lines up with its row and column - once every facet reported its own. */
     margins?: MarginConfig;
+    /** Which of the facet's sides sit on the grid's outer edge. */
+    edges: FacetEdges;
 };
 export type FacetCellSnippet<TRow extends Record<string, unknown>> = Snippet<[
     FacetCellContext<TRow>
@@ -31,11 +52,19 @@ export type FacetNavContext = {
     onclick: () => void;
 };
 export type FacetNavSnippet = Snippet<[FacetNavContext]>;
-export type FacetConfig<TRow extends Record<string, unknown>> = {
+/** Options every facet layout shares. */
+type FacetCommonConfig = {
+    gap?: number;
+    scales?: FacetScales;
+    axes?: FacetAxes;
+};
+/** One facet per `by` value, wrapped into `columns` - laid out all at once, paged, or as a carousel. */
+export type FacetWrapConfig<TRow extends Record<string, unknown>> = FacetCommonConfig & {
     by: Accessor<TRow, unknown>;
+    rows?: never;
+    cols?: never;
     columns?: FacetColumns;
     values?: string[];
-    gap?: number;
     mode?: Responsive<FacetMode>;
     visible?: number;
     pageSize?: number;
@@ -43,23 +72,16 @@ export type FacetConfig<TRow extends Record<string, unknown>> = {
     formatIndicator?: (current: number, total: number) => string;
     indicator?: FacetIndicatorSnippet;
     navButton?: FacetNavSnippet;
-    /**
-     * One facet's own natural margin need, per side — measured across every
-     * facet and combined with `Math.max` per side (`FacetLayout`'s own
-     * `cellMargins`) to size one shared margin every facet's `cell` receives
-     * through its own `margins`, instead of each facet growing its own margin
-     * independently off what its own content happens to need (which drifts
-     * out of alignment facet to facet, and — for a facet cramped enough that
-     * its content can never fully fit — can grow without bound). A plot type
-     * that draws content needing this (a categorical axis's labels, a value
-     * label's own text) implements this by calling its own margin-estimating
-     * export against the facet's rows — e.g. `BarPlot`'s left margin from its
-     * category labels, `LinePlot`'s right margin from its end-of-line value
-     * labels (see each plot's own docs for what its estimator assumes, such as
-     * `LinePlot`'s one-line-per-facet caveat) — this callback only carries
-     * that per-facet result up to where every facet's results can be compared.
-     * Any side left unset by every facet stays unpinned, falling back to the
-     * plot's own default (`'auto'`) sizing.
-     */
-    marginsForFacet?: (rows: TRow[]) => MarginConfig;
 };
+/** One facet per `rows` × `cols` combination, with each value labelled; combinations without rows stay empty. */
+export type FacetGridConfig<TRow extends Record<string, unknown>> = FacetCommonConfig & {
+    by?: never;
+    rows?: Accessor<TRow, unknown>;
+    cols?: Accessor<TRow, unknown>;
+    /** The `rows` values to show, in order. Defaults to every value, in data order. */
+    rowValues?: string[];
+    /** The `cols` values to show, in order. Defaults to every value, in data order. */
+    colValues?: string[];
+};
+export type FacetConfig<TRow extends Record<string, unknown>> = FacetWrapConfig<TRow> | FacetGridConfig<TRow>;
+export {};

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

@@ -0,0 +1,7 @@
+import type { Snippet } from 'svelte';
+/** A box measured for a plot to draw into. */
+export type PlotBoxContext = {
+    width: number;
+    height: number;
+};
+export type PlotBoxSnippet = Snippet<[PlotBoxContext]>;

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

@@ -1,16 +1,20 @@
-/** One resolved segment for scoped-marker rendering — see {@link ScopedMarkerGroup}. */
+/** 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
+ * `'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;
+    /** The series' id, when it differs from its name - see `Series.id`. */
+    id?: string;
+    /** The facet panel the series belongs to. */
+    panel?: string;
     data: TData[];
     color: string;
     segments: ScopedMarkerSegment<TData>[];

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

@@ -0,0 +1,66 @@
+import type { Snippet } from 'svelte';
+import type { Margins } from '../../layout/margins/Margins';
+/** Where a cell sits in its grid - whether each of its sides is on the grid's outer edge (no cell beyond it). */
+export type CellEdges = {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+};
+/** A cell's slot: its top-left track and how many tracks it spans. */
+export type GridSpan = {
+    row: number;
+    col: number;
+    rowSpan: number;
+    colSpan: number;
+};
+/** Where a cell asks to sit: a named `area`, an explicit `row`/`col`, or - with neither - the next free slot. */
+export type GridCellSpec = {
+    area?: string;
+    row?: number;
+    col?: number;
+    rowSpan?: number;
+    colSpan?: number;
+};
+/** A floating cell's box as fractions of its area (or of the whole grid), from the left and bottom edges. */
+export type GridInset = {
+    left: number;
+    bottom: number;
+    right: number;
+    top: number;
+};
+/**
+ * Where a figure drawn straight inside a `Grid` (a `PlotComposer`'s)
+ * sits: a named `area`, or - with `inset` - a box floating over its area.
+ * Without either, it takes the next free cell.
+ */
+export type GridPlacement = {
+    area?: string;
+    inset?: GridInset;
+};
+/** The box a grid cell hands its content. */
+export type GridCellContext = {
+    width: number;
+    height: number;
+    /** The margins pinned on the cell's plot so its panel lines up with its row and column - only in an aligned grid. */
+    margins?: Margins;
+    edges: CellEdges;
+};
+export type GridCellSnippet = Snippet<[GridCellContext]>;
+/** One cell's box: its size and, in an aligned grid, the margins pinned on it. */
+export type CellBox = {
+    width: number;
+    height: number;
+    margins?: Margins;
+};
+/** What a cell asks of its grid: a slot, or - with `inset` - a box floating over one. */
+export type GridCellRequest = GridCellSpec & {
+    inset?: GridInset;
+};
+/** Where the grid put a cell: its CSS placement, its box and which sides face the grid's edge. */
+export type GridCellLayout = {
+    gridRow?: string;
+    gridColumn?: string;
+    box: CellBox;
+    edges: CellEdges;
+};

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

@@ -0,0 +1,48 @@
+import type { AxisValue } from './mapping';
+/**
+ * How the hover highlight finds related points within a facet.
+ * - `'x'` all points sharing the hovered x (default for line / bar).
+ * - `'y'` all points sharing the hovered y (default for pyramid).
+ * - `'punctual'` exact XY match - one cell at a time (default for heatmap).
+ * - `'series'` all points sharing the hovered series, regardless of x/y.
+ */
+export type HoverStrategy = 'x' | 'y' | 'punctual' | 'series';
+/** Hover state shared by every plot under one figure - see `HoverState`. */
+export type HoverStore = {
+    activeX: AxisValue | null;
+    activeY: AxisValue | null;
+    /** Series of the hovered row, when the plot kind has a series concept (line/bar). */
+    activeSeries: string | null;
+    /** The cursor's position in the source plot's box, as fractions of its width and height. */
+    cursorFrac: {
+        x: number;
+        y: number;
+    } | null;
+    /** Facet id that currently owns the hover (`''` when not faceted). */
+    source: string | null;
+    /** How related points are found within a facet. */
+    strategy: HoverStrategy;
+    /** Whether the hover is broadcast to other facets. */
+    sync: boolean;
+};
+/** A slice of a category band, as start/end fractions (0-1) of the whole band. */
+export type BandSlice = {
+    start: number;
+    end: number;
+};
+/** A point ready to render: its plotted position plus its label. */
+export type HoverDisplayPoint = {
+    x: AxisValue;
+    y: AxisValue;
+    label: string;
+    /** Owning series name; undefined for plot kinds with no series concept (heatmap). */
+    series?: string;
+    /** Resolved series color - used by HoverMarker when dotFill/fill is `'currentColor'`. */
+    color?: string;
+    /** A 'grouped' series' own slice of the category band, as start/end fractions (0-1) of the whole band. `undefined` means the whole band. */
+    areaInset?: BandSlice;
+};
+/** A candidate point for hover matching/highlighting - also carries its source row. */
+export type HoverPoint<T> = HoverDisplayPoint & {
+    row: T;
+};