@fundar/data-chart-telling 1.1.0 → 1.3.0

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

@@ -33,6 +33,8 @@ export type LegendItem = {
     name: string;
     label?: string;
     color?: string;
+    /** How the series draws; with no `symbol`, `legend.icon.marks` picks the icon from it. */
+    mark?: LegendMark;
     symbol?: SymbolType;
     /** Whether the symbol is filled, or drawn as an outline. Defaults to `true`. */
     filled?: boolean;
@@ -111,6 +113,8 @@ export type ContinuousInteractiveConfig = {
 export type ContinuousLegendSection = {
     type: 'continuous';
     title?: string;
+    /** The channel the section reads, which tells apart automatic sections that share a title. */
+    channel?: Exclude<LegendChannel, 'series'>;
     columns?: number;
     min: number;
     max: number;
@@ -120,7 +124,7 @@ export type ContinuousLegendSection = {
     scheme?: string | string[];
     /** Splits an array `scheme` into two halves meeting at this value (diverging). */
     pivot?: number;
-    /** Draws the bar in one color (`colorMin`, the text color by default) fading across this opacity range, instead of a color ramp. */
+    /** Draws the bar in one color (`colorMin`, `legend.continuous.opacity.color` by default) fading across this opacity range over a checkerboard, instead of a color ramp. */
     opacity?: [number, number];
     ticks?: number[];
     width?: number;
@@ -135,6 +139,8 @@ export type ContinuousLegendSection = {
 export type SizeLegendSection = {
     type: 'size';
     title?: string;
+    /** The channel the section reads, which tells apart automatic sections that share a title. */
+    channel?: Exclude<LegendChannel, 'series'>;
     columns?: number;
     domain: [number, number];
     range: [number, number];
@@ -157,6 +163,8 @@ export type SizeLegendSection = {
 export type SymbolLegendSection = {
     type: 'symbol';
     title?: string;
+    /** The channel the section reads, which tells apart automatic sections that share a title. */
+    channel?: Exclude<LegendChannel, 'series'>;
     columns?: number;
     /** Item flow direction, as in a discrete section. */
     layout?: LegendItemsLayout;
@@ -247,8 +255,8 @@ export type LegendEntry = {
 export type MarkLegend = string | (Omit<LegendItem, 'name' | 'disabled'> & {
     label: string;
 });
-/** What a legend reads each automatic section from: the series, or the channel a scale encodes. */
-export type LegendChannel = 'series' | 'color' | 'opacity' | 'size' | 'symbol';
+/** What a legend reads each automatic section from: the series, or the channel a scale encodes - named as the plot's own prop (`r` for sizes). */
+export type LegendChannel = 'series' | 'color' | 'opacity' | 'r' | 'symbol';
 /**
  * How to adjust one automatic section: its own configuration, minus what the
  * plots compute for it. An entry with a `match` (one, or several in a list) adjusts
@@ -289,7 +297,7 @@ export type LegendExtension = {
     series?: Omit<DiscreteLegendSection, 'type' | 'items'>;
     color?: ColorOverride | ColorOverride[];
     opacity?: LegendOverride<ContinuousLegendSection, 'min' | 'max' | 'colorMin' | 'colorMax' | 'scheme' | 'pivot' | 'opacity' | 'interactive'>;
-    size?: LegendOverride<SizeLegendSection, 'domain' | 'range' | 'color' | 'filled' | 'symbol'>;
+    r?: LegendOverride<SizeLegendSection, 'domain' | 'range' | 'color' | 'filled' | 'symbol'>;
     symbol?: LegendOverride<SymbolLegendSection, 'items' | 'color' | 'filled'>;
 };
 /** A segment or marker as the legend reads it: whether it names itself, the channels it draws with and the colors it draws in. */
@@ -306,7 +314,7 @@ export type LegendSource = {
         opacity?: OpacityScaleConfig;
         symbol?: SymbolScaleConfig;
     };
-    legend?: MarkLegend;
+    legend?: MarkLegend | false;
     fill?: unknown;
     stroke?: unknown;
     styles?: {
@@ -322,12 +330,22 @@ export type LegendSource = {
 export type LegendPlot = {
     resolvedSeries?: {
         name: string;
+        data?: unknown[];
     }[];
     colorForSeries?: (name: string) => string;
     markers?: LegendSource[];
     segments?: Record<string, LegendSource[] | undefined>;
     /** The `[min, max]` a plot-level color ramp spans, when the plot has no `color` channel to read it from. */
     colorDomain?: [number, number];
+    /** The ramps of the segments that set their own color scale, each over its own features' values. */
+    colorRamps?: {
+        name: string;
+        domain: [number, number];
+        scale: {
+            scheme?: unknown;
+            pivot?: number;
+        };
+    }[];
     /** The `[min, max]` of a plot-level numeric `opacity` channel. */
     opacityDomain?: [number, number];
     channels?: {

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

@@ -1,7 +1,12 @@
 import type { Snippet } from 'svelte';
 import type { TimeValue } from './timeline';
 import type { GridPlacement } from './grid';
-import type { MarginConfig, TooltipConfig } from '../plots/props';
+import type { MarginConfig, TooltipConfig, HoverConfig as PlotHoverConfig } from '../plots/props';
+import type { Margins as MarginsType } from '../../layout/margins/Margins';
+import type { EdgeBox } from './box';
+import type { StylesLayoutConfig } from './styles';
+import type { HoverPosition } from '../phases';
+import type { PlotAxes } from '../../phases/data/PlotAxes';
 /** Where one cell sits among the slices: the timeline step and the facet it shows. */
 export type SlicePlace = {
     time?: TimeValue;
@@ -24,6 +29,8 @@ export type PlotCellContext<TRow extends Record<string, unknown>, TScales extend
     scales?: TScales;
     /** This slice's facet panel, as a {@link Pipeline.runData} over every panel resolved it. */
     panel?: object;
+    /** Where this slice sits among the facet panels - `undefined` when the plot has no facet. */
+    facet?: NonNullable<SlicePlace['facet']>;
     /** Whether any row - the plot's own or a marker's - belongs in this slice; rows without a slicing field belong in all. */
     keep: (row: TRow) => boolean;
 };
@@ -39,3 +46,41 @@ export type PlotCoreBase = GridPlacement & {
     scales?: object;
     margins?: MarginConfig;
 };
+/**
+ * What `BasePlotLayout` draws from: the end of a plot's pipeline. An axis
+ * kind's state is one as is; GeoPlot builds its own.
+ */
+export type PlotLayoutState = {
+    /** What the pointer can match, and how the hover reads. */
+    hover?: PlotHoverConfig<any>;
+    /** Where each row sits, for hover matching and the plot's scales. */
+    hoverPosition?: HoverPosition;
+    /** The rows the plot draws and hovers over. */
+    hoverRows?: unknown[];
+    /** The plot's x/y/r/length scales, and the scales a marker without its own inherits. */
+    scales?: object;
+    /** The axes whose domain the plot kind fit itself rather than the author pinned. */
+    fittedAxes?: string[];
+    /** What the plot's position channels are and which way it runs, for what draws inside it. */
+    axes?: PlotAxes;
+    /** The plot's channels as given, whose field titles an axis with no rows. */
+    channels?: Record<string, {
+        source?: unknown;
+    } | undefined>;
+    /** Every marker the pipeline resolved. */
+    markers?: object[];
+    /** All resolved series - axis kinds only. */
+    resolvedSeries?: object[];
+    /** Each series' color, by name - axis kinds only. */
+    colorForSeries?: (name: string) => string;
+    /** Per-series marker groups - axis kinds only. */
+    scopedGroups?: object[];
+    /** The plot's `styles`: its frame and, on a map, its tile layer. */
+    styles?: StylesLayoutConfig;
+    /** What an `'auto'` margin side reads as. Defaults to {@link Margins.AXIS_ESTIMATE}. */
+    marginEstimate?: MarginsType;
+    /** The plot's value labels, whose `reach` is the room the margins start from. */
+    valueLabels?: {
+        reach: EdgeBox[];
+    };
+};

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

@@ -10,6 +10,10 @@ export type ColorScaleConfig = {
      * category → color map. Defaults to the theme's own 2-color ramp.
      */
     scheme?: string | string[] | Record<string, string>;
+    /**
+     * The part of a named `scheme` ramp to use, as `[from, to]` fractions of it (default `[0, 1]`). `[0.3, 1]` skips the near-white start of a sequential ramp such as `'blues'`, so its first color stays visible. Ignored for a literal `scheme`.
+     */
+    schemeRange?: [number, number];
     /** 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'`. */
@@ -49,13 +53,18 @@ export type ChannelScalesConfig<TChannel extends IndependentChannelName = Indepe
 /** `r` (radius/size) config - plot-level only, consumed via {@link AxisBasedScalesConfig.r}. */
 export type RScaleConfig = {
     domain?: [number, number];
+    /** How a value maps to a radius. Defaults to svelteplot's `'sqrt'`, so an area is proportional to its value; `'linear'` makes the radius (a trail's half-width) proportional instead. */
+    type?: 'linear' | 'sqrt';
+    /** Includes 0 in the domain, so a size is proportional to its value. On by default; `false` starts the domain at its lowest value, spreading out values that sit close together. */
+    zero?: boolean;
     /** 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 = {
+    /** Magnitudes mapped to the two ends of `range`, e.g. `[0, 40]`; values past them extend the line. Defaults to the data's extent. */
     domain?: [number, number];
-    /** Pixel length range, e.g. `[0, 60]`. Defaults to svelteplot's own. */
+    /** Pixel lengths of the `domain`'s ends, 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. */
@@ -83,11 +92,36 @@ export type BinnedScaleType = (typeof BINNED_SCALE_TYPES)[number];
  * `'extend'` widens the axis to the next nice tick past the data.
  */
 export type EdgeTickCollision = 'drop-nice' | 'drop-edge' | 'extend';
+/**
+ * Whether a continuous axis rounds its domain out to round numbers. As an
+ * object, it does, and `tolerance` is how far past a tick, as a share of the
+ * step, the data may end and still stay on it (default `0.05`; `0` rounds like d3).
+ */
+export type NiceOption = boolean | {
+    tolerance?: number;
+};
 /** 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;
 };
+/** A scale's `edgeTicks`: `true` or `false`, or an object that turns them on with its own `collision`. */
+export type EdgeTicksOption = boolean | Partial<Omit<EdgeTicksOptions, 'enabled'>>;
+/**
+ * A category axis ordered by what each category holds: `'value'` by its value
+ * in one `series` (or, without one, the sum of its values) and `'range'` by the
+ * spread between its lowest and its highest value (an interval's ends count, on the plots that have them). A category with nothing to
+ * sort by goes last.
+ */
+export type CategorySort = {
+    by: 'value' | 'range';
+    /** For `by: 'value'`: the series whose value orders the categories. */
+    series?: string;
+    /** Defaults to `'ascending'`. */
+    order?: 'ascending' | 'descending';
+    /** Sort within each series instead of across all of them: the series stay together, in the order they first appear. */
+    grouped?: boolean;
+};
 /**
  * Scale overrides for one plot axis - svelteplot's `ScaleOptions` and
  * `XScaleOptions`, plus this package's own fields. `TData` is the row type
@@ -105,18 +139,16 @@ export type AxisScale<TData = Record<string, unknown>> = {
     titleFontSize?: number;
     interval?: string | number;
     clamp?: boolean;
-    nice?: boolean;
-    niceTolerance?: number;
-    edgeTicks?: boolean | {
-        collision?: EdgeTickCollision;
-    };
+    nice?: NiceOption;
+    edgeTicks?: EdgeTicksOption;
     zero?: boolean;
     round?: boolean;
     percent?: boolean;
     align?: number;
     base?: number;
     constant?: number;
-    sort?: (a: TData, b: TData) => number;
+    /** The order of a category axis: a comparator of two rows (each category's first), or a {@link CategorySort} by what the categories hold. Ignored when `domain` is set. */
+    sort?: ((a: TData, b: TData) => number) | CategorySort;
     grid?: boolean | {
         stroke?: string;
         strokeWidth?: number;

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

@@ -0,0 +1,40 @@
+import type { AreaStyle, FontStyle, StrokeStyle } from '../../plots/styling';
+/** The value a `deviation` statistic centers on. */
+export type DeviationEstimator = 'mean' | 'median' | 'midrange';
+/** How far the band reaches from the estimator, before `k` scales it. */
+export type DeviationSpread = 'stdev' | 'mad';
+/** A label written against the plot's edge, beside the line it names. */
+export type DeviationLabel = {
+    /** The text. Defaults to the estimator's name for the rule (`'MEAN'`) and the spread's for the band (`'STDEV'`). */
+    text?: string;
+    /** `dx`/`dy` here add to the default gap between the label and its line. */
+    styles?: FontStyle;
+};
+/** A band label's place: which edge it names and which side of that edge it sits on. */
+export type DeviationBandLabel = DeviationLabel & {
+    /** The edge it names. Defaults to `'upper'`. */
+    edge?: 'lower' | 'upper';
+    /** Whether it sits inside the band or outside it. Defaults to `'inside'`. */
+    position?: 'inside' | 'outside';
+};
+/**
+ * Options for `type: 'deviation'` - an estimator of the source's values along
+ * the plot's value axis, drawn as a rule, and the band `k` spreads wide on
+ * each side of it.
+ */
+export type DeviationStatisticOptions = {
+    /** The value the rule sits at. Defaults to `'mean'`. */
+    estimator?: DeviationEstimator;
+    /** The spread the band measures. `'stdev'` is the sample standard deviation, `'mad'` the median absolute deviation scaled to match it. Defaults to `'stdev'`. */
+    spread?: DeviationSpread;
+    /** The band's half-width, a multiple of the spread. Defaults to 1. */
+    k?: number;
+    /** The estimator's rule; `false` omits it. `label` names it - `true` takes the defaults. */
+    rule?: false | (StrokeStyle & {
+        label?: DeviationLabel | true;
+    });
+    /** The band around the rule; `false` omits it. `label` names one of its edges - `true` takes the defaults. */
+    band?: false | (AreaStyle & {
+        label?: DeviationBandLabel | true;
+    });
+};

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

@@ -3,6 +3,8 @@ import type { BollingerStatisticOptions } from './bollinger';
 import type { MovingAverageStatisticOptions } from './movingAverage';
 import type { DensityStatisticOptions, Density2DStatisticOptions } from './density';
 import type { BoxStatisticOptions } from './box';
+import type { DeviationStatisticOptions } from './deviation';
+export type { DeviationBandLabel, DeviationEstimator, DeviationLabel, DeviationSpread, DeviationStatisticOptions } from './deviation';
 export type { RegressionType, RegressionStatisticOptions } from './regression';
 export type { BollingerStatisticOptions } from './bollinger';
 export type { StatisticReducer, MovingAverageStatisticOptions } from './movingAverage';
@@ -29,7 +31,8 @@ export type StatisticScope = {
  * `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.
+ * directly; `deviation` computes an estimator and its spread over the plot's
+ * value axis and draws them as a `rule` and a `rect` marker.
  */
 export type StatisticConfig = StatisticScope & (({
     type: 'regression';
@@ -43,4 +46,6 @@ export type StatisticConfig = StatisticScope & (({
     type: 'density2d';
 } & Density2DStatisticOptions) | ({
     type: 'box';
-} & BoxStatisticOptions));
+} & BoxStatisticOptions) | ({
+    type: 'deviation';
+} & DeviationStatisticOptions));

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

@@ -0,0 +1,18 @@
+import type { FrameProp } from './frame';
+import type { ValuesStyle } from './values';
+/**
+ * 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. */
+    frame?: FrameProp;
+};
+/**
+ * Top-level rendering style overrides shared by the non-geo plot kinds.
+ * Passed as the `styles` prop. Each plot reads only the fields it cares
+ * about.
+ */
+export type AxisBasedStylesConfig = BasePlotStylesConfig & {
+    values?: ValuesStyle;
+};

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

@@ -0,0 +1,25 @@
+import type { GapsAwarePlotStylesConfig } from './gaps';
+import type { BarSegmentStyle } from '../../plots/segments/common';
+/** `BulletPlot`'s `styles`: a bar plot's, with the look of its ranges and its target. Each field falls back to `bullet` in the configuration. */
+export type BulletStylesConfig = GapsAwarePlotStylesConfig<BarSegmentStyle> & {
+    /** The bar that shows the value. */
+    bar?: {
+        /** Its thickness across the category band, in px. */
+        thickness?: number;
+    };
+    /** The bands that grade the value. */
+    ranges?: {
+        /** Their colors, from the smallest band to the largest; the last one repeats if there are more bands. */
+        colors?: string[];
+        /** Their thickness, in px. */
+        width?: number;
+    };
+    /** The tick at each target. */
+    target?: {
+        color?: string;
+        /** Its thickness, in px. */
+        width?: number;
+        /** Its length across the band, in px. */
+        length?: number;
+    };
+};

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

@@ -0,0 +1,98 @@
+import type { FontStyle } from '../../plots/styling';
+import type { ColorScaleConfig } from '../scales';
+import type { AxisBasedStylesConfig } from './base';
+/** What a connector styles and labels itself from: where it runs, and what its dots say about the category. */
+export type ConnectorRange = {
+    category: unknown;
+    /** The lowest value of the category, or the baseline when that is lower. */
+    from: number;
+    /** The highest value of the category, or the baseline when that is higher. */
+    to: number;
+    /** How long the connector is: `to - from`. */
+    length: number;
+    /** The value of the `to` series minus that of the `from` series (see {@link ConnectorStyle}), `undefined` when either has none here. With a baseline, the value minus the baseline. */
+    difference: number | undefined;
+    /** The stretch between the `from` series' dot and the `to` series' - lowest value first - `undefined` when either has none. */
+    span: [number, number] | undefined;
+    /** The series of the category's only dot - `undefined` when it has several. */
+    series: string | undefined;
+};
+/**
+ * How connectors are colored: one color; a color scale over what each one
+ * measures (`'difference'`, which a diverging `scheme` with `pivot: 0` splits
+ * into rising and falling; or `'length'`); the sign of its difference
+ * (`'sign'`); or a function of the connector.
+ */
+export type ConnectorColor = string | ({
+    by: 'difference' | 'length';
+} & ColorScaleConfig) | {
+    by: 'sign';
+    positive?: string;
+    negative?: string;
+    zero?: string;
+} | ((range: ConnectorRange) => string);
+/** The text written on each connector. */
+export type ConnectorLabel = {
+    /** What it says: the connector's `'difference'` (signed) or `'length'`, or a function of the connector. Defaults to `'difference'`. */
+    text?: 'difference' | 'length' | ((range: ConnectorRange) => string);
+    /** A number as text, for `text: 'difference'` and `'length'`. Defaults to the bare number, signed for a difference. */
+    format?: (value: number, range: ConnectorRange) => string;
+    /** `'outside'` writes it beside the connector - above it, or to the right of a vertical one - and `'middle'` on it, along its length, for a connector thick enough to hold it. Defaults to `'outside'`. */
+    anchor?: 'outside' | 'middle';
+    /** The text's style. */
+    fontStyle?: FontStyle;
+};
+/**
+ * `styles.connector` of the Cleveland family: the connector each category
+ * draws between its dots, and the label on it.
+ */
+export type ConnectorStyle = {
+    /**
+     * Where a difference starts: a series by its name, `'first'` or `'last'` for that series, or
+     * `'min'` or `'max'` for the category's lowest or highest dot. Defaults to `'first'`. The
+     * stretch between `from` and `to` is what `color`, `opacity` and the label are for; the rest
+     * of the connector is `outside`.
+     */
+    from?: string;
+    /** Where a difference ends - the same options as `from`. Defaults to `'last'`. With `from: 'min'` and `to: 'max'`, the stretch is the whole connector. */
+    to?: string;
+    /** The connector's thickness in px; `'dots'` makes it as thick as the dots are wide, a band. Or a function of the connector. */
+    width?: number | 'dots' | ((range: ConnectorRange) => number);
+    /** The connector's color - see {@link ConnectorColor}. A segment's own `stroke` wins on a lone dot's stem. */
+    color?: ConnectorColor;
+    /** The connector's opacity (0-1), or a function of the connector. */
+    opacity?: number | ((range: ConnectorRange) => number);
+    /**
+     * How the part of a connector outside the stretch between `from` and `to` looks - the dots of
+     * the other series lie there: a color, or `{ color, opacity }`. Defaults to the neutral
+     * connector color at a lower opacity. The stretch between the two keeps `color` and `opacity`.
+     */
+    outside?: string | {
+        color?: string;
+        opacity?: number;
+    };
+    /**
+     * Draws the stretch between `from` and `to` as an arrow pointing at the `to` dot - the way
+     * the value moved - instead of a line. `true` takes the configuration's head, or give its
+     * `headLength` (px) and `headAngle` (degrees). An arrow is as thick as `width` says, else
+     * the configuration's `connector.arrow.width`: thinner than a band.
+     */
+    arrow?: boolean | {
+        headLength?: number;
+        headAngle?: number;
+    };
+    /** Caps - a short tick across the connector - at each end of it: `true`, or `{ length }` in px (the configuration's `connector.capLength`). Defaults to the plot's own: on for a forest plot, off for the rest. */
+    caps?: boolean | {
+        length?: number;
+    };
+    /** A label on each connector, centered on the stretch between `from` and `to`: `true` for the difference with its defaults, or its options. */
+    label?: boolean | ConnectorLabel;
+};
+/**
+ * `AxisBasedStylesConfig` extended with `connector` - the line each category
+ * draws between its dots, on the plots that join them (`ClevelandPlot`,
+ * `DumbbellPlot`, `LollipopPlot`) - see {@link ConnectorStyle}.
+ */
+export type ConnectorBasedStylesConfig = AxisBasedStylesConfig & {
+    connector?: ConnectorStyle;
+};

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

@@ -0,0 +1,11 @@
+import type { AxisBasedStylesConfig } from './base';
+/** Curve interpolation for a line, area, difference or trail - svelteplot's own `CurveName`. */
+export type CurveName = 'basis' | 'basis-closed' | 'basis-open' | 'bundle' | 'bump-x' | 'bump-y' | 'cardinal' | 'cardinal-closed' | 'cardinal-open' | 'catmull-rom' | 'catmull-rom-closed' | 'catmull-rom-open' | 'linear' | 'linear-closed' | 'monotone-x' | 'monotone-y' | 'natural' | 'step' | 'step-after' | 'step-before';
+/**
+ * `styles` of the plots that draw lines: the shared axis-based fields, plus the
+ * curve of every line. A segment's own `curve` wins over it.
+ */
+export type CurveAwarePlotStylesConfig = AxisBasedStylesConfig & {
+    /** How every line joins its points. Defaults to `'linear'`. */
+    curve?: CurveName;
+};

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

@@ -0,0 +1,17 @@
+import type { AreaStyle } from '../../plots/styling';
+/**
+ * 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
+ * in from the content box's own edges, in pixels.
+ */
+export type FrameStyle = AreaStyle & {
+    inset?: number;
+    insetTop?: number;
+    insetRight?: number;
+    insetBottom?: number;
+    insetLeft?: number;
+};
+/** Author-facing `styles.frame` prop - see {@link FrameStyle}. */
+export type FrameProp = boolean | FrameStyle;

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

@@ -0,0 +1,12 @@
+import type { GapsConfig } from '../../plots/gaps';
+import type { AxisBasedStylesConfig } from './base';
+/**
+ * `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
+ * {@link GapsConfig}.
+ */
+export type GapsAwarePlotStylesConfig<TSegmentStyle extends object> = AxisBasedStylesConfig & {
+    gaps?: GapsConfig<TSegmentStyle>;
+};

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

@@ -0,0 +1,55 @@
+import type { GeoFeature } from '../../plots/data/geo';
+import type { FrameProp } from './frame';
+import type { BasePlotStylesConfig } from './base';
+export type GeoTileLayerConfig = {
+    /** XYZ tile URL template, e.g. `'https://tile.openstreetmap.org/{z}/{x}/{y}.png'`. */
+    url: string;
+    attribution?: string;
+    opacity?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Tile edge length in pixels. Defaults to `256`. */
+    tileSize?: number;
+};
+/**
+ * `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
+ * this is its own type rather than a reuse of `AxisBasedStylesConfig`.
+ */
+export type GeoStylesConfig<TProps extends Record<string, unknown> = Record<string, unknown>> = BasePlotStylesConfig & {
+    /** Base map fill, used when a feature isn't styled by `segments` or the choropleth ramp. */
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    /** 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
+ * `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
+ * threaded through as a separate prop.
+ */
+type GeoTileLayerConfigWithFeatures = GeoTileLayerConfig & {
+    features?: {
+        geometry: GeoJSON.Geometry;
+    }[];
+};
+/**
+ * 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).
+ */
+export type StylesLayoutConfig = {
+    tileLayer?: GeoTileLayerConfigWithFeatures;
+    frame?: FrameProp;
+    [key: string]: unknown;
+};
+export {};

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

@@ -0,0 +1,8 @@
+export * from './base';
+export * from './frame';
+export * from './values';
+export * from './connector';
+export * from './gaps';
+export * from './geo';
+export * from './curve';
+export * from './bullet';

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

@@ -0,0 +1,8 @@
+export * from './base';
+export * from './frame';
+export * from './values';
+export * from './connector';
+export * from './gaps';
+export * from './geo';
+export * from './curve';
+export * from './bullet';

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

@@ -0,0 +1,47 @@
+import type { ValueAnchor } from '../../plots/constants';
+import type { FontStyle, StrokeStyle } from '../../plots/styling';
+/**
+ * Which of a group's rows get a value label: its first or last, or the one
+ * with the lowest or highest value (read on the plot's value axis). The group
+ * is each plot's own: a series for a line or an area, a category for the
+ * plots that join several series' dots.
+ */
+export type ValueSelect = 'first' | 'last' | 'min' | 'max';
+/**
+ * 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;
+    /**
+     * Which rows of each group are labelled: one selector, or a list of them (a
+     * row picked by any is labelled) - see {@link ValueSelect}. Each plot has its
+     * own default: a line or an area labels its series' last point, the plots
+     * that join dots label them all.
+     */
+    select?: ValueSelect | ValueSelect[];
+    /** Labels only the rows of these series, by name. Defaults to every series. */
+    series?: string | string[];
+    /**
+     * The labels' color: `'series'` writes each in its series' color, any other
+     * CSS color writes them all in it. `fontStyle.fill` wins when it is set.
+     */
+    color?: 'series' | (string & {});
+    /** A label's text, from its row's own value (a histogram bin's count) and its series - and, on the plots that label one row each, that row, for the other fields of the data. */
+    format?: (value: number, seriesName: string, row?: Record<string, unknown>) => 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;
+};

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

@@ -83,6 +83,9 @@ export type TimelineConfig<TRow extends Record<string, unknown>> = TimelineCallb
     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';
+    /**
+     * Which position scales the steps share: `'shared'` (default), where x and y span every step's rows, so the axes hold still while scrubbing; `'free'`,
+     * which refits both to each step; or `'free-x'`/`'free-y'` to refit one and keep the other still.
+     */
+    scales?: 'shared' | 'free' | 'free-x' | 'free-y';
 };