@fundar/data-chart-telling 0.0.64 → 1.1.0

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

@@ -1,18 +1,100 @@
-export type AxisValue = number | string | Date;
+import type { SymbolType } from '../plots/constants';
+import type { AxisChannelName, IndependentChannelName } from './mapping';
+/** A continuous or categorical color ramp. */
+export type ColorScaleConfig = {
+    /** `[min, max]` for a continuous ramp, or the category list for a categorical one. Auto-computed from the data when omitted. */
+    domain?: [number, number] | string[];
+    /**
+     * A named d3-scale-chromatic ramp (e.g. `'turbo'`, `'blues'`, `'rdylbu'` -
+     * case-insensitive), 2+ literal colors interpolated across `domain`, or a
+     * category → color map. Defaults to the theme's own 2-color ramp.
+     */
+    scheme?: string | string[] | Record<string, string>;
+    /** Splits an array `scheme` into two halves meeting at this domain value (diverging). Ignored for a `Record` scheme. */
+    pivot?: number;
+    /** Fallback color for a missing/unmapped value. Defaults to `'#ccc'`. */
+    unknown?: string;
+};
+/** How groups sharing the same `grouping`/`color` value are ordered: `reverse` flips which sorts first (e.g. PyramidPlot's left/right sides). */
+export type GroupingScaleConfig = {
+    reverse?: boolean;
+};
+/** A continuous or categorical opacity ramp - maps a value to a numeric `[0,1]`-ish opacity instead of a color. */
+export type OpacityScaleConfig = {
+    /** `[min, max]` for a continuous ramp, or the category list for a categorical one. Auto-computed from the data when omitted. */
+    domain?: [number, number] | string[];
+    /** `[minOpacity, maxOpacity]` for continuous, or a category → opacity map. Defaults to the theme's own `continuous.opacityRange`. */
+    range?: [number, number] | Record<string, number>;
+    /** Fallback opacity for a missing/unmapped value. Defaults to `1`. */
+    unknown?: number;
+};
+/** A categorical shape ramp - maps distinct values to marker shapes. Always discrete. */
+export type SymbolScaleConfig = {
+    domain?: string[];
+    /** Shapes cycled through in `domain` order, or a category → shape map. Defaults to a built-in cycle. */
+    range?: SymbolType[] | Record<string, SymbolType>;
+    unknown?: SymbolType;
+};
+/** Each independent channel's scale config, on a plot's `scales` and a marker's own. */
+export type ChannelScaleConfig = {
+    color: ColorScaleConfig;
+    grouping: GroupingScaleConfig;
+    opacity: OpacityScaleConfig;
+    symbol: SymbolScaleConfig;
+};
+/** `scales.<channel>` for every channel in `TChannel` - the shared shape for both a plot's own `scales` prop and a marker's own. */
+export type ChannelScalesConfig<TChannel extends IndependentChannelName = IndependentChannelName> = {
+    [K in TChannel]?: ChannelScaleConfig[K];
+};
+/** `r` (radius/size) config - plot-level only, consumed via {@link AxisBasedScalesConfig.r}. */
+export type RScaleConfig = {
+    domain?: [number, number];
+    /** Pixel radius range, e.g. `[2, 20]`. Defaults to svelteplot's own. */
+    range?: [number, number];
+};
+/** `length` (vector/spike magnitude) config - plot-level only. */
+export type LengthScaleConfig = {
+    domain?: [number, number];
+    /** Pixel length range, e.g. `[0, 60]`. Defaults to svelteplot's own. */
+    range?: [number, number];
+};
+/** Scale types that lay out distinct categories - an axis paired with one plays the "index" role, so the other is the plain magnitude/value axis. */
+export declare const DISCRETE_SCALE_TYPES: readonly ["band", "categorical", "point", "ordinal"];
+export type DiscreteScaleType = (typeof DISCRETE_SCALE_TYPES)[number];
+/** Scale types that lay out a continuous time axis. */
+export declare const TEMPORAL_SCALE_TYPES: readonly ["time", "utc"];
+export type TemporalScaleType = (typeof TEMPORAL_SCALE_TYPES)[number];
+/** Scale types that map a numeric domain continuously onto the range, differing only in the transform applied (identity, power, log, ...). */
+export declare const CONTINUOUS_SCALE_TYPES: readonly ["linear", "pow", "sqrt", "log", "symlog"];
+export type ContinuousScaleType = (typeof CONTINUOUS_SCALE_TYPES)[number];
+/** Scale types that interpolate continuously along a single ramp (one end to the other, or around a cycle). */
+export declare const SEQUENTIAL_SCALE_TYPES: readonly ["sequential", "cyclical", "quantile-cont"];
+export type SequentialScaleType = (typeof SEQUENTIAL_SCALE_TYPES)[number];
+/** Scale types that interpolate continuously along a ramp with a neutral midpoint, diverging to either side of it. */
+export declare const DIVERGING_SCALE_TYPES: readonly ["diverging", "diverging-log", "diverging-pow", "diverging-sqrt", "diverging-symlog"];
+export type DivergingScaleType = (typeof DIVERGING_SCALE_TYPES)[number];
+/** Scale types that bucket a numeric domain into a fixed set of output values instead of interpolating. */
+export declare const BINNED_SCALE_TYPES: readonly ["threshold", "quantile", "quantize"];
+export type BinnedScaleType = (typeof BINNED_SCALE_TYPES)[number];
+/**
+ * What an axis does when the tick at the data's first or last value would
+ * crowd the nice tick next to it: `'drop-nice'` keeps the data's tick and
+ * drops the nice one, `'drop-edge'` keeps the nice tick and drops the data's,
+ * `'extend'` widens the axis to the next nice tick past the data.
+ */
+export type EdgeTickCollision = 'drop-nice' | 'drop-edge' | 'extend';
+/** Whether an axis adds ticks at the data's first and last values, and what it does when one crowds a nice tick. */
+export type EdgeTicksOptions = {
+    enabled: boolean;
+    collision: EdgeTickCollision;
+};
 /**
- * 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.
+ * Scale overrides for one plot axis - svelteplot's `ScaleOptions` and
+ * `XScaleOptions`, plus this package's own fields. `TData` is the row type
+ * {@link AxisScale.sort} compares.
  */
 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';
+    type?: 'auto' | ContinuousScaleType | TemporalScaleType | DiscreteScaleType | SequentialScaleType | DivergingScaleType | BinnedScaleType;
     domain?: (number | string | boolean | Date | null)[];
     range?: (number | string | boolean | Date | null)[];
     reverse?: boolean;
@@ -24,6 +106,10 @@ export type AxisScale<TData = Record<string, unknown>> = {
     interval?: string | number;
     clamp?: boolean;
     nice?: boolean;
+    niceTolerance?: number;
+    edgeTicks?: boolean | {
+        collision?: EdgeTickCollision;
+    };
     zero?: boolean;
     round?: boolean;
     percent?: boolean;
@@ -37,6 +123,8 @@ export type AxisScale<TData = Record<string, unknown>> = {
         strokeOpacity?: number;
         strokeDasharray?: string;
     };
+    /** Whether the axis' ticks and title draw: `'hidden'` keeps their space (so aligned panels stay aligned), `'none'` gives it back. Defaults to `'visible'`. */
+    axisDisplay?: 'visible' | 'hidden' | 'none';
     padding?: number;
     paddingInner?: number;
     paddingOuter?: number;
@@ -50,17 +138,13 @@ export type AxisScale<TData = Record<string, unknown>> = {
     tickPadding?: number;
     tickRotate?: number;
     tickFormat?: false | Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | ((d: unknown, index: number, ticks: unknown[]) => string | string[]);
-    seriesLayout?: 'overlap' | 'grouped' | 'stacked';
-    seriesPadding?: number;
 };
-/**
- * Per-axis scale overrides, passed as a single `scales` prop to every
- * axis-based plot kind (`GeoPlot` uses `GeoScalesConfig` instead — a map has
- * no x/y/z axis pair). `TData` threads through to {@link AxisScale.sort} on
- * each axis.
- */
-export type AxisBasedScalesConfig<TData = Record<string, unknown>> = {
-    x?: AxisScale<TData>;
-    y?: AxisScale<TData>;
-    z?: AxisScale<TData>;
+/** Each {@link AxisChannelName}'s own scale-config shape - both use {@link AxisScale}. */
+export type AxisChannelScaleConfig<TData = Record<string, unknown>> = {
+    [K in AxisChannelName]?: AxisScale<TData>;
 };
+/** The `scales` prop of every axis-based plot kind. */
+export type AxisBasedScalesConfig<TData = Record<string, unknown>> = AxisChannelScaleConfig<TData> & {
+    r?: RScaleConfig;
+    length?: LengthScaleConfig;
+} & ChannelScalesConfig;

package/dist/types/layout/scales.js

@@ -1 +1,19 @@
-export {};
+// ── Axis channels (x/y): one scale shared by every mark ─────────────────────
+/** Scale types that lay out distinct categories - an axis paired with one plays the "index" role, so the other is the plain magnitude/value axis. */
+export const DISCRETE_SCALE_TYPES = ['band', 'categorical', 'point', 'ordinal'];
+/** Scale types that lay out a continuous time axis. */
+export const TEMPORAL_SCALE_TYPES = ['time', 'utc'];
+/** Scale types that map a numeric domain continuously onto the range, differing only in the transform applied (identity, power, log, ...). */
+export const CONTINUOUS_SCALE_TYPES = ['linear', 'pow', 'sqrt', 'log', 'symlog'];
+/** Scale types that interpolate continuously along a single ramp (one end to the other, or around a cycle). */
+export const SEQUENTIAL_SCALE_TYPES = ['sequential', 'cyclical', 'quantile-cont'];
+/** Scale types that interpolate continuously along a ramp with a neutral midpoint, diverging to either side of it. */
+export const DIVERGING_SCALE_TYPES = [
+    'diverging',
+    'diverging-log',
+    'diverging-pow',
+    'diverging-sqrt',
+    'diverging-symlog'
+];
+/** Scale types that bucket a numeric domain into a fixed set of output values instead of interpolating. */
+export const BINNED_SCALE_TYPES = ['threshold', 'quantile', 'quantize'];

package/dist/types/layout/statistics/bollinger.d.ts

@@ -0,0 +1,18 @@
+import type { StrokeStyle } from '../../plots/styling';
+/** Band options for `type: 'bollinger'` - mirrors svelteplot's own `BollingerOptions` field-for-field. */
+export type BollingerStatisticOptions = {
+    /** Window size (the moving average's own `k`); svelteplot's default is 20. */
+    n?: number;
+    /** Band radius, a multiple of standard deviations; svelteplot's default is 2. */
+    k?: number;
+    /**
+     * `stroke`/`strokeOpacity` style the moving-average line; `bandFill`
+     * styles the ±k·σ band - confirmed empirically as the only two style
+     * channels svelteplot's own `BollingerX`/`Y` actually route through
+     * (`strokeWidth` and the rest of `StrokeStyle` are accepted but have no
+     * visible effect on the line, so deliberately not offered here).
+     */
+    styles?: Pick<StrokeStyle, 'stroke' | 'strokeOpacity'> & {
+        bandFill?: string;
+    };
+};

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

@@ -0,0 +1,8 @@
+import type { BoxMarkerConfig } from '../../markers/common';
+/**
+ * Options for `type: 'box'` - the box plot's own styling and tick options,
+ * same fields and defaults as a `box` marker (see `BoxMarkerConfig`'s own
+ * doc comment). Summarizes the source's own distribution, one box per
+ * category.
+ */
+export type BoxStatisticOptions = Omit<BoxMarkerConfig, 'type' | 'data' | 'x' | 'y' | 'series'>;

package/dist/types/layout/statistics/box.js

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

package/dist/types/layout/statistics/density.d.ts

@@ -0,0 +1,27 @@
+import type { AreaStyle } from '../../plots/styling';
+import type { DensityKernel } from '../../transforms/density';
+export type { DensityKernel } from '../../transforms/density';
+/**
+ * Options for `type: 'density'` - a 1D kernel density estimate over the
+ * `x` values, drawn as a filled area. Runs the `densityX` transform (same
+ * option names); the curve's own `y` is the density. To run the estimate on a
+ * marker of your own, or on a plot's own rows, use that transform directly.
+ */
+export type DensityStatisticOptions = {
+    kernel?: DensityKernel;
+    /** Kernel bandwidth in data units; Silverman's rule picks one from the data when unset. */
+    bandwidth?: number;
+    styles?: AreaStyle;
+};
+/**
+ * Options for `type: 'density2d'` - 2D contour bands, same options as the
+ * `density` marker (svelteplot's own `Density` mark). Set `thresholds` to
+ * control the number of bands or give the density levels explicitly.
+ */
+export type Density2DStatisticOptions = {
+    /** Gaussian kernel bandwidth in pixels - svelteplot defaults to 20. */
+    bandwidth?: number;
+    /** Contour level count, or an explicit list of density thresholds. */
+    thresholds?: number | number[];
+    styles?: AreaStyle;
+};

package/dist/types/layout/statistics/density.js

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

package/dist/types/layout/statistics/index.d.ts

@@ -0,0 +1,46 @@
+import type { RegressionStatisticOptions } from './regression';
+import type { BollingerStatisticOptions } from './bollinger';
+import type { MovingAverageStatisticOptions } from './movingAverage';
+import type { DensityStatisticOptions, Density2DStatisticOptions } from './density';
+import type { BoxStatisticOptions } from './box';
+export type { RegressionType, RegressionStatisticOptions } from './regression';
+export type { BollingerStatisticOptions } from './bollinger';
+export type { StatisticReducer, MovingAverageStatisticOptions } from './movingAverage';
+export type { DensityKernel, DensityStatisticOptions, Density2DStatisticOptions } from './density';
+export type { BoxStatisticOptions } from './box';
+/**
+ * Which series a plot-level statistic runs over. Omitted: one derived
+ * statistic per series, so a plot grouped by `color`/`grouping` gets its
+ * statistics grouped the same way. Named: only the listed series. `pooled:
+ * true`: one statistic over every series combined. Ignored on a marker's own
+ * `.statistics` - a marker has exactly one source, its own `data`.
+ */
+export type StatisticScope = {
+    series?: string[];
+    pooled?: boolean;
+};
+/**
+ * A statistic to compute and draw as one or more derived markers - the same
+ * shape whether attached to a plot's own top-level `statistics` prop or a
+ * marker's own `.statistics`. `regression`/`bollinger` resolve straight to
+ * svelteplot's own `RegressionX`/`Y` and `BollingerX`/`Y` marks (no
+ * computation of our own); `movingAverage` has no svelteplot mark, so it
+ * calls svelteplot's own `windowY` transform and wraps the result into a
+ * `line` marker. `density` (1D) calls svelteplot's own `densityX` transform
+ * and wraps the curve into an `area` marker; `density2d` and `box` resolve
+ * straight to the same `density` and `box` markers a plot author can write
+ * directly.
+ */
+export type StatisticConfig = StatisticScope & (({
+    type: 'regression';
+} & RegressionStatisticOptions) | ({
+    type: 'bollinger';
+} & BollingerStatisticOptions) | ({
+    type: 'movingAverage';
+} & MovingAverageStatisticOptions) | ({
+    type: 'density';
+} & DensityStatisticOptions) | ({
+    type: 'density2d';
+} & Density2DStatisticOptions) | ({
+    type: 'box';
+} & BoxStatisticOptions));

package/dist/types/layout/statistics/index.js

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

package/dist/types/layout/statistics/movingAverage.d.ts

@@ -0,0 +1,12 @@
+import type { StrokeStyle } from '../../plots/styling';
+import type { WindowReducer } from '../../transforms/window';
+/** Window reducers the `windowY` transform takes by name. */
+export type StatisticReducer = WindowReducer;
+/** Sliding-window options for `type: 'movingAverage'` - runs the `windowY` transform. */
+export type MovingAverageStatisticOptions = {
+    /** Window size, in number of points. */
+    k: number;
+    /** Reducer applied within each window. Defaults to `'mean'`. */
+    reduce?: StatisticReducer;
+    styles?: StrokeStyle;
+};

package/dist/types/layout/statistics/movingAverage.js

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

package/dist/types/layout/statistics/regression.d.ts

@@ -0,0 +1,20 @@
+import type { StrokeStyle } from '../../plots/styling';
+/**
+ * Regression model svelteplot's own `RegressionX`/`RegressionY` marks support
+ * - same names, so nothing new to learn if you already know svelteplot.
+ */
+export type RegressionType = 'linear' | 'quad' | 'poly' | 'exp' | 'log' | 'pow' | 'loess';
+/** Fit options for `type: 'regression'` - mirrors svelteplot's own `RegressionOptions` field-for-field. */
+export type RegressionStatisticOptions = {
+    regressionType?: RegressionType;
+    /** Polynomial order (`regressionType: 'poly'`). */
+    order?: number;
+    /** Logarithm base (`regressionType: 'log'`). */
+    base?: number;
+    /** LOESS bandwidth, as a fraction of the data range, 0-1 (`regressionType: 'loess'`). */
+    span?: number;
+    /** Confidence-band level (e.g. `0.95`); svelteplot's own default is `0.99`. Set `false` to omit the band. */
+    confidence?: number | false;
+    /** The band always renders in the same color as `stroke`, at a fixed low opacity - no separate band color to set. */
+    styles?: StrokeStyle;
+};

package/dist/types/layout/statistics/regression.js

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

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

@@ -3,37 +3,31 @@ import type { FontStyle, StrokeStyle, AreaStyle } from '../plots/styling';
 import type { GeoFeature } from '../plots/data/geo';
 import type { GapsConfig } from '../plots/gaps';
 /**
- * Controls if and how value labels are rendered on a plot. The high-level
- * `anchor` sets sensible defaults for placement; `fontStyle` (`dx`, `dy`,
- * `textAnchor`, `lineAnchor`, `lineHeight`, `rotate`, `class`, `textClass`,
- * `fill`, …) overrides those defaults field-by-field when provided — mirrors
- * {@link DeltaConfig}'s `fontStyle`/`strokeStyle` split, so label text and
- * connector-line styling never mix into one flat bag of props.
+ * Controls if and how value labels are rendered on a plot, drawn as a `text`
+ * marker over the rows the plot itself draws (after its own `transforms`):
+ * one at the end of each series on a line or area plot, one per bar on a bar,
+ * pyramid or histogram plot, one per point on a scatter plot and one per cell
+ * on a heatmap. The high-level `anchor` sets sensible defaults for placement;
+ * `fontStyle` (`dx`, `dy`, `textAnchor`, `lineAnchor`, `lineHeight`, `rotate`,
+ * `class`, `textClass`, `fill`, …) overrides those defaults field-by-field when
+ * provided - mirrors {@link DeltaConfig}'s `fontStyle`/`strokeStyle` split, so
+ * label text and connector-line styling never mix into one flat bag of props.
  */
 export type ValuesStyle = {
+    /** Whether the labels are drawn. Off by default, except on a heatmap. */
     show?: boolean;
+    /** Where each label sits on its mark - see {@link ValueAnchor}. */
     anchor?: ValueAnchor;
+    /** A label's text, from its row's own value (a histogram bin's count) and its series. */
     format?: (value: number, seriesName: string) => string;
+    /** Hovering a label dims every other series, like toggling them off in the legend. */
     hoverIsolate?: boolean;
     fontStyle?: FontStyle;
+    /** The connectors a line or area plot routes back from labels that had to move apart. */
     strokeStyle?: StrokeStyle;
 };
 /**
- * Color overrides for plots that derive their palette from data.
- * Each plot uses only the fields relevant to its kind; unused fields are
- * silently ignored.
- *
- * - `min` / `max` — sequential colour ramp endpoints (heatmap).
- * - `left` / `right` — diverging bar sides (pyramid).
- */
-export type ColorsStyle = {
-    min?: string;
-    max?: string;
-    left?: string;
-    right?: string;
-};
-/**
- * Decorative border around the plot's own content box — svelteplot's
+ * Decorative border around the plot's own content box - svelteplot's
  * `Frame` mark, purely cosmetic (drawn from the box geometry, never from
  * data). `true` enables it with svelteplot's own defaults; an object
  * enables it and overrides its look field-by-field. Insets pull the frame
@@ -46,16 +40,14 @@ export type FrameStyle = AreaStyle & {
     insetBottom?: number;
     insetLeft?: number;
 };
-/** Author-facing `styles.frame` prop — see {@link FrameStyle}. */
+/** Author-facing `styles.frame` prop - see {@link FrameStyle}. */
 export type FrameProp = boolean | FrameStyle;
 /**
- * The fields every plot kind's own `styles` shape shares, regardless of
- * whether it's built on axes ({@link AxisBasedStylesConfig}) or geometry
- * ({@link GeoStylesConfig}) — the true common parent of the two, unlike the
- * name `AxisBasedStylesConfig` might suggest before this split existed.
+ * The fields every plot kind's own `styles` shape shares - the common parent
+ * of {@link AxisBasedStylesConfig} and {@link GeoStylesConfig}.
  */
 export type BasePlotStylesConfig = {
-    /** Decorative border around the plot's content box — see {@link FrameStyle}. Available on every plot kind. */
+    /** Decorative border around the plot's content box - see {@link FrameStyle}. Available on every plot kind. */
     frame?: FrameProp;
 };
 /**
@@ -65,13 +57,12 @@ export type BasePlotStylesConfig = {
  */
 export type AxisBasedStylesConfig = BasePlotStylesConfig & {
     values?: ValuesStyle;
-    colors?: ColorsStyle;
 };
 /**
- * `AxisBasedStylesConfig` extended with `gaps` — the interpolated
+ * `AxisBasedStylesConfig` extended with `gaps` - the interpolated
  * missing-data bridge fill available to plot kinds with an inherent
  * category/sequence ordering (`LinePlot`, `BarPlot`, `PyramidPlot`).
- * Resolved per series like `segments`, at zone granularity — see
+ * Resolved per series like `segments`, at zone granularity - see
  * {@link GapsConfig}.
  */
 export type GapsAwarePlotStylesConfig<TSegmentStyle extends object> = AxisBasedStylesConfig & {
@@ -88,7 +79,7 @@ export type GeoTileLayerConfig = {
     tileSize?: number;
 };
 /**
- * `styles` prop for GeoPlot — the geo analog of `AxisBasedStylesConfig`,
+ * `styles` prop for GeoPlot - the geo analog of `AxisBasedStylesConfig`,
  * sharing only {@link BasePlotStylesConfig}'s common ground with it. Unlike
  * the other plot kinds, GeoPlot's styling needs (base map, choropleth ramp,
  * tile background, click handling) are unlike anything x/y plots need, so
@@ -100,15 +91,13 @@ export type GeoStylesConfig<TProps extends Record<string, unknown> = Record<stri
     fillOpacity?: number;
     stroke?: string;
     strokeWidth?: number;
-    /** Continuous choropleth ramp endpoints — used when `value` is provided on data. Mirrors heatmap's `styles.colors`. */
-    colors?: ColorsStyle;
     /** Raster XYZ tile basemap under the vector geometry. Mercator-family projections only. */
     tileLayer?: GeoTileLayerConfig;
     /** Fired when a base-map feature is clicked. */
     onFeatureClick?: (feature: GeoFeature<TProps>, event: Event) => void;
 };
 /**
- * `GeoTileLayerConfig`, plus `features` — never author-facing (the public
+ * `GeoTileLayerConfig`, plus `features` - never author-facing (the public
  * `styles.tileLayer` shape, {@link GeoTileLayerConfig}, doesn't declare it).
  * `GeoPlot` tacks it onto its own internal copy of `styles` so `StylesLayout`
  * can compute the tile layer's auto-fit bounds without needing raw geometry
@@ -120,7 +109,7 @@ type GeoTileLayerConfigWithFeatures = GeoTileLayerConfig & {
     }[];
 };
 /**
- * The minimal slice of a plot kind's own `styles` prop `StylesLayout` reads —
+ * The minimal slice of a plot kind's own `styles` prop `StylesLayout` reads -
  * every concrete `styles` type ({@link AxisBasedStylesConfig},
  * {@link GeoStylesConfig}) structurally satisfies this whether or not it
  * declares `tileLayer` at all (a missing optional field type-checks fine).

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

@@ -1,8 +1,13 @@
 import type { Snippet } from 'svelte';
-import type { AxisValue } from './scales';
+import type { AxisValue } from './mapping';
 import type { Accessor } from '../plots/data/common';
-import type { EasingName, EasingFn } from '../charts/interpolate';
+import type { EasingName, EasingFn } from '../misc/easing';
+/** A step as the timeline works with it: a number (a date as its timestamp). */
 export type TimeValue = number;
+/** A step as the rows hold it: a number, a `Date` or a date string. */
+export type TimeInput = TimeValue | Date | string;
+/** A step as authors see it: a `Date` on a timeline of dates, else the number. */
+export type TimelineStep = number | Date;
 export type Orientation = 'horizontal' | 'vertical';
 export type TimelineChildContext<TRow extends Record<string, unknown>> = {
     selectedValue: TimeValue;
@@ -20,13 +25,64 @@ export type TimelineInterpolation<TRow extends Record<string, unknown>> = {
     progressEasing?: EasingName | EasingFn;
     segmentEasing?: EasingName | EasingFn;
 };
-export type TimelineConfig<TRow extends Record<string, unknown>> = {
-    accessor: Accessor<TRow, TimeValue>;
-    progress: number;
-    values?: TimeValue[];
+/** How a timeline draws: a `'player'` bar in the chrome (the default), or a `'rule'` beside the plot. */
+export type TimelineType = 'rule' | 'player';
+/** A piece of the player bar. */
+export type PlayerControl = 'play' | 'value' | 'slider' | 'speed' | 'loop';
+/**
+ * The player bar (`timeline.type: 'player'`): which controls it draws, in what
+ * order, and how it plays. `loop` and `speed` are where the player starts: it
+ * keeps them from there, and tells `onloop` and `onspeed` when they change.
+ */
+export type PlayerConfig = {
+    /** The controls drawn, in this order - one left out isn't drawn. Defaults to the configuration's `timeline.player.controls`. */
+    controls?: PlayerControl[];
+    /** Starts playing as soon as the timeline has steps. */
+    autoplay?: boolean;
+    /** Starts again from the first step after the last, instead of stopping. */
+    loop?: boolean;
+    /** The playing speed, as a multiple of `stepDuration`. Defaults to `1`. */
+    speed?: number;
+    /** The speeds the speed control cycles through. Defaults to the configuration's `timeline.player.speeds`. */
+    speeds?: number[];
+    /** Milliseconds each step lasts at speed `1`. Defaults to the configuration's `timeline.player.stepDuration`. */
+    stepDuration?: number;
+    /** How a step reads, in the player and along a rule. Defaults to the step, or a date label for dates. */
+    format?: (value: TimelineStep) => string;
+    onplay?: (playing: boolean) => void;
+    onspeed?: (speed: number) => void;
+    onloop?: (loop: boolean) => void;
+};
+/** What every timeline can tell its owner, whatever it draws as. */
+export type TimelineCallbacks = {
+    /** Called with the new position, `0`-`1`, whenever the player or the reader moves it. */
+    onprogress?: (progress: number) => void;
+    /** Called with the step the position lands on, when that step changes. */
+    onvalue?: (value: TimelineStep) => void;
+};
+export type TimelineConfig<TRow extends Record<string, unknown>> = TimelineCallbacks & {
+    /** The field (or function) giving each row's step: a number, a `Date`, or an ISO or `dateFormat` date string. */
+    accessor: Accessor<TRow, TimeInput>;
+    /** How a non-ISO date string reads, with `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, e.g. `'DD/MM/YYYY'`. */
+    dateFormat?: string;
+    /** How it draws. Defaults to `'player'`. */
+    type?: TimelineType;
+    /** The player bar's own options, when `type` is `'player'`. */
+    player?: PlayerConfig;
+    /**
+     * The timeline's position, `0`-`1`. A `'player'` keeps its own position from
+     * there on (see `onprogress`), until this changes. Inside a `PlotComposer`
+     * with its own `timeline`, the composer's wins and nothing draws here.
+     */
+    progress?: number;
+    /** The steps, when not every distinct value of `accessor`. */
+    values?: TimeInput[];
+    /** Which way a `'rule'` runs. A `'player'` is always horizontal. */
     orientation?: Orientation;
     show?: boolean;
     thickness?: number;
     filterMode?: 'exact' | 'upTo';
     interpolate?: boolean | TimelineInterpolation<TRow>;
+    /** `'shared'` (default): x and y span every step's rows, so the axes hold still while scrubbing; `'free'` refits them to each step. */
+    scales?: 'shared' | 'free';
 };