@fundar/data-chart-telling 0.0.64 → 1.1.0

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

@@ -1,54 +1,35 @@
-import type { EasingName } from '../charts/interpolate';
-import type { AxisValue } from '../layout/scales';
-/**
- * How one gap zone bridges its hole: `interpolate` eases the synthetic
- * segment's value between its two endpoints (defaults to `'linear'`, a
- * straight line); `style` is the per-mark shape drawn for it
- * ({@link LineSegmentStyle} for `LinePlot`), independent of that plot
- * kind's own default marker style unless the caller repeats it.
- */
+import type { EasingName } from '../misc/easing';
+import type { AxisValue } from '../layout/mapping';
+/** How one gap zone is bridged: `interpolate` eases the value (default `'linear'`), `style` draws it. */
 export type GapZoneConfig<TStyle> = {
     interpolate?: EasingName;
     style?: TStyle;
 };
 /**
- * A leading/trailing gap has only one real boundary — `x` (required to opt
- * in) is the domain value the synthetic segment extends to, and `y` is the
- * value it reaches there (defaults to holding the nearest real point's
- * value, i.e. a flat extrapolation). Omitting the zone entirely leaves that
- * end of the series unfilled — extrapolating without an explicit target
- * would imply data that doesn't exist.
- *
- * On `LinePlot`, `x`'s value is the actual spatial target the bridge draws
- * out to (its axis is continuous). On `BarPlot`/`PyramidPlot`, each gap row
- * already has its own real category, so `x`'s *presence* is only the opt-in
- * gate — its value isn't read; `y` is what drives the fill.
+ * A gap before the first or after the last real point: bridged out to `x`
+ * (required to fill it), reaching `y` there (default: the nearest real
+ * value). On bar plots only `x`'s presence matters.
  */
 export type OpenGapZoneConfig<TStyle> = GapZoneConfig<TStyle> & {
     x: AxisValue;
     y?: AxisValue;
 };
-/**
- * One series' gap-fill config: `start` (before its first real point),
- * `middle` (any internal run of missing rows, bounded by real data on both
- * sides) and `end` (after its last real point). A row counts as missing
- * when its resolved value is `null`, `undefined`, or `NaN` — the same
- * convention svelteplot's own `Line` mark already uses to break the line
- * there. See {@link GapsConfig} for how this is keyed per series on a
- * gap-aware plot kind's `styles.gaps`.
- */
+/** One series' gap fill: `start`, `middle` and `end`. A row is missing when its value is `null`, `undefined` or `NaN`. */
 export type GapZonesConfig<TStyle> = {
     start?: OpenGapZoneConfig<TStyle>;
     middle?: GapZoneConfig<TStyle>;
     end?: OpenGapZoneConfig<TStyle>;
 };
-/**
- * The `gaps` field a gap-aware plot kind's `styles` accepts (see
- * {@link GapsAwarePlotStylesConfig}, `types/layout/styles.ts`) — series name
- * (or `'default'` for all series) to that series' {@link GapZonesConfig}.
- * Mirrors `SegmentsConfig`'s series-keyed shape: a named entry applies only
- * to that series; `'default'` fills in whichever of its zones
- * (`start`/`middle`/`end`) the named entry itself leaves unset, at zone
- * granularity rather than a merged style.
- */
+/** `styles.gaps`: series name (or `'default'`) to its {@link GapZonesConfig}; `'default'` fills the zones a named entry leaves unset. */
 export type GapsConfig<TStyle> = Record<string, GapZonesConfig<TStyle>>;
+/** A point sampled along a gap-fill bridge, already resolved to plot data-space numbers. */
+export type GapPoint = {
+    x: number;
+    y: number;
+};
+/** One gap row's resolved fill - the interpolated value to render instead of the missing one, and which zone produced it. */
+export type DiscreteGapFill<TStyle> = {
+    value: number;
+    kind: 'start' | 'middle' | 'end';
+    style?: TStyle;
+};

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

@@ -0,0 +1,23 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { GeoScalesConfig, CoordinatesConfig } from '../../layout/coordinates';
+import type { GeoFeature, GeoDataProps } from '../data/geo';
+import type { GeoStylesConfig } from '../../layout/styles';
+import type { GeoSegmentStyle } from '../segments/common';
+import type { GeoMarkersConfig } from '../../markers/geo';
+import type { TimelineConfig } from '../../layout/timeline';
+import type { FacetConfig } from '../../layout/facet';
+/** `Omit` on each member of a union, so the union (and what tells its members apart) survives. */
+type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * `GeoPlot`'s public props. Its `timeline` and `facet` slice both the map's
+ * features (reading a field key from each feature's `properties`) and every
+ * marker's own `data` rows; a feature or row without the field is context,
+ * drawn in every slice.
+ */
+export type GeoPlotProps<TProps extends Record<string, unknown>> = OmitEach<BasePlotProps<GeoDataProps<TProps>, GeoFeature<TProps>, GeoStylesConfig<TProps>, GeoSegmentStyle, GeoMarkersConfig, GeoScalesConfig, CoordinatesConfig>, 'timeline' | 'facet'> & {
+    timeline?: TimelineConfig<Record<string, unknown>>;
+    facet?: FacetConfig<Record<string, unknown>>;
+};
+/** What `GeoPlot`'s core draws from. */
+export type GeoPlotCoreProps<TProps extends Record<string, unknown>> = PlotCoreProps<GeoDataProps<TProps>, GeoFeature<TProps>, GeoStylesConfig<TProps>, GeoSegmentStyle, GeoMarkersConfig, GeoScalesConfig, CoordinatesConfig>;
+export {};

package/dist/types/plots/geo/props.js

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

package/dist/types/plots/geo/state.d.ts

@@ -0,0 +1,82 @@
+import type { Accessor } from '../data/common';
+import type { GeoFeature } from '../data/geo';
+import type { GeoScalesConfig } from '../../layout/coordinates';
+import type { SegmentsConfig, MarginConfig, HoverConfig } from '../props';
+import type { HoverPosition } from '../../phases';
+import type { TooltipProp } from '../../layout/tooltip';
+import type { GeoSegmentStyle } from '../segments/common';
+import type { GeoMarkersConfig } from '../../markers/geo';
+import type { MarkerConfig } from '../../markers/all';
+import type { PlotStylesConfig } from '../../configuration/styling';
+import type { LegendDisabledStyle } from '../../layout/legend';
+/** One feature tagged with its resolved id/centroid as plain fields. */
+export type TaggedGeoFeature<TProps extends Record<string, unknown>> = GeoFeature<TProps> & {
+    __id: string;
+    __cx: number;
+    __cy: number;
+};
+/** One resolved-style bucket of features - `opacity` is a second bucketing dimension alongside `style`, quantized so the channel produces a bounded number of mark instances. */
+export type GeoStyleGroup<TProps extends Record<string, unknown>> = {
+    style: GeoSegmentStyle;
+    opacity: number | undefined;
+    data: TaggedGeoFeature<TProps>[];
+};
+/** The active continuous-legend range filter, if any - mirrors HeatmapPlot's own. */
+export type GeoRangeFilter = {
+    min: number;
+    max: number;
+    mode: 'rescale' | 'filter';
+    disabledStyle: LegendDisabledStyle;
+};
+/** GeoPlot's shared pipeline state - raw props plus every phase's own output. */
+export type GeoPlotState<TProps extends Record<string, unknown>> = {
+    /** Already resolved to plain GeoJSON - TopoJSON's async conversion happens in `Plot.svelte` itself, before the pipeline runs. */
+    rawFeatures: GeoFeature<TProps>[];
+    featureId?: Accessor<GeoFeature<TProps>, string>;
+    /** Color-value accessor - see `GeoDataProps.color`. */
+    color?: (feature: GeoFeature<TProps>) => number | undefined;
+    /** Structural grouping-bucket accessor - see `GeoDataProps.grouping`. */
+    grouping?: (feature: GeoFeature<TProps>) => string | undefined;
+    /** Opacity-value accessor - see `GeoDataProps.opacity`. */
+    opacity?: (feature: GeoFeature<TProps>) => number | undefined;
+    excludeParts?: (part: {
+        centroid: [number, number];
+        geometry: GeoJSON.Geometry;
+    }, feature: TaggedGeoFeature<TProps>) => boolean;
+    segments: SegmentsConfig<GeoSegmentStyle>;
+    scales: GeoScalesConfig;
+    /** The plot's `tooltip`, which the "hover" phase reads. */
+    tooltip?: TooltipProp<TaggedGeoFeature<TProps>>;
+    /** The raw `markers` prop - GeoPlot interleaves it with the base map by draw order, not a plain append. */
+    authoredMarkers: GeoMarkersConfig[];
+    width: number;
+    height: number;
+    margins?: MarginConfig;
+    allFeatures?: TaggedGeoFeature<TProps>[];
+    features?: TaggedGeoFeature<TProps>[];
+    /** "scales" phase output: the `[min, max]` the color ramp spans, before any legend range narrows it - `undefined` without a `color`. */
+    colorDomain?: [number, number];
+    /** "scales" phase output: the `[min, max]` of the `opacity` values - `undefined` without an `opacity`. */
+    opacityDomain?: [number, number];
+    /** "scales" phase output: each feature's own resolved color, composed from `color` and the color ramp - `undefined` where `color` itself is unset/returns nothing. */
+    resolveColor?: (feature: GeoFeature<TProps>) => string | undefined;
+    /** "scales" phase output: each feature's own resolved opacity, composed from `opacity` and the opacity ramp - `undefined` where `opacity` itself is unset/returns nothing. */
+    resolveOpacity?: (feature: GeoFeature<TProps>) => number | undefined;
+    markers?: MarkerConfig[];
+    styleGroups?: GeoStyleGroup<TProps>[];
+    /** "tooltip" phase output: how a hovered feature reads, unless `tooltip.format` says otherwise. */
+    tooltipFormat?: (feature: GeoFeature<TProps>) => string;
+    hover?: HoverConfig<TaggedGeoFeature<TProps>>;
+    hoverPosition?: HoverPosition;
+    hoverRows?: TaggedGeoFeature<TProps>[];
+};
+/** The environment every GeoPlot phase reads from, alongside the growing state. */
+export type GeoPlotCtx<TProps extends Record<string, unknown>> = {
+    cfg: PlotStylesConfig;
+    range: GeoRangeFilter | null | undefined;
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    onFeatureClick?: (d: TaggedGeoFeature<TProps>, e: Event) => void;
+};

package/dist/types/plots/geo/state.js

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

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

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { AxisBasedStylesConfig } from '../../layout/styles';
+import type { CellSegmentStyle } from '../segments/common';
+/** `HeatmapPlot`'s public props. */
+export type HeatmapPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, CellSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `HeatmapPlot`'s core draws from. */
+export type HeatmapPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, CellSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/heatmap/props.js

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

package/dist/types/plots/heatmap/state.d.ts

@@ -0,0 +1,28 @@
+import type { CellSegmentStyle } from '../segments/common';
+import type { ResolvedChannel, ResolvedChannels } from '../../layout/mapping';
+import type { LegendRange } from '../../layout/legend';
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+/**
+ * The active continuous-legend range filter, if any - narrows which cells
+ * render at full opacity, and in `'rescale'` mode, the color domain itself.
+ */
+export type HeatmapRangeFilter = LegendRange;
+/**
+ * HeatmapPlot's pipeline state: the shared axis-based state, where `color` is
+ * each cell's value channel (so always resolved) rather than a grouping key.
+ */
+export type HeatmapPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, CellSegmentStyle> & {
+    channels?: ResolvedChannels<TData> & {
+        color: ResolvedChannel<TData, unknown>;
+    };
+    /** "scales" phase output: each row's own resolved color, composed from `channels.color` and the color ramp. */
+    resolveColor?: (row: TData) => string;
+    /** "scales" phase output: the `[min, max]` of the `opacity` values - `undefined` unless `opacity` is numeric. */
+    opacityDomain?: [number, number];
+    /** "scales" phase output: each row's own resolved opacity, composed from `channels.opacity` and the opacity ramp - `undefined` when `opacity` itself is unset. */
+    resolveOpacity?: (row: TData) => number;
+};
+/** The environment every HeatmapPlot phase reads from, alongside the growing state. */
+export type HeatmapPlotCtx = AxisPlotCtx & {
+    range: HeatmapRangeFilter | null | undefined;
+};

package/dist/types/plots/heatmap/state.js

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

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

@@ -0,0 +1,18 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { AxisBasedStylesConfig } from '../../layout/styles';
+import type { AreaStyle } from '../styling';
+import type { AxisChannelName, ChannelAccessors } from '../../layout/mapping';
+/** Flat rows binned on one axis: `x` for vertical bars, or `y` alone for horizontal ones. A bin's count is its length. */
+type HistogramDataProps<TRow extends Record<string, unknown>> = Omit<DataProps<TRow>, AxisChannelName> & ((Required<Pick<ChannelAccessors<TRow>, 'x'>> & {
+    y?: never;
+}) | (Required<Pick<ChannelAccessors<TRow>, 'y'>> & {
+    x?: never;
+}));
+/** `HistogramPlot`'s public props. */
+export type HistogramPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | HistogramDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `HistogramPlot`'s core draws from. */
+export type HistogramPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | HistogramDataProps<TData>, TData, AxisBasedStylesConfig, AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export {};

package/dist/types/plots/histogram/props.js

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

package/dist/types/plots/histogram/state.d.ts

@@ -0,0 +1,6 @@
+import type { AreaStyle } from '../styling';
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+/** HistogramPlot's pipeline state: the shared axis-based state, with no extras of its own. */
+export type HistogramPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, AreaStyle>;
+/** The environment every HistogramPlot phase reads from, alongside the growing state. */
+export type HistogramPlotCtx = AxisPlotCtx;

package/dist/types/plots/histogram/state.js

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

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

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { GapsAwarePlotStylesConfig } from '../../layout/styles';
+import type { LineSegmentStyle } from '../segments/common';
+/** `LinePlot`'s public props. */
+export type LinePlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<LineSegmentStyle>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `LinePlot`'s core draws from. */
+export type LinePlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<LineSegmentStyle>, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/line/props.js

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

package/dist/types/plots/line/state.d.ts

@@ -0,0 +1,9 @@
+import type { GapsConfig } from '../gaps';
+import type { LineSegmentStyle } from '../segments/common';
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+/** LinePlot's pipeline state: the shared axis-based state plus its gaps. */
+export type LinePlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, LineSegmentStyle> & {
+    gaps?: GapsConfig<LineSegmentStyle>;
+};
+/** The environment every LinePlot phase reads from, alongside the growing state. */
+export type LinePlotCtx = AxisPlotCtx;

package/dist/types/plots/line/state.js

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

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

@@ -1,44 +1,42 @@
-import type { HoverPoint, HoverStrategy, TooltipOptions } from '../layout/tooltip';
+import type { Pipeline } from '../../phases/Pipeline';
+import type { Snippet } from 'svelte';
+import type { TooltipOptions, TooltipProp } from '../layout/tooltip';
+import type { HoverPoint, HoverStrategy } from '../layout/hover';
+import type { LegendExtension, LegendSection } from '../layout/legend';
+import type { FacetConfig } from '../layout/facet';
+import type { GridPlacement } from '../layout/grid';
+import type { TimelineConfig } from '../layout/timeline';
 import type { Segment } from './segments/config';
 import type { AxisBasedScalesConfig } from '../layout/scales';
 import type { GeoScalesConfig } from '../layout/coordinates';
-/** The `styles` prop accepted by every plot kind — its own
+import type { StatisticConfig } from '../layout/statistics';
+import type { MarkerTransform } from '../transforms';
+/** The `styles` prop accepted by every plot kind - its own
  * styles shape ({@link AxisBasedStylesConfig}, `GeoStylesConfig`, …). */
 export type StylesConfig<TStyles extends object> = TStyles;
-/** The `markers` prop accepted by every plot kind — a list of that kind's own marker union. */
+/** The `markers` prop accepted by every plot kind - a list of that kind's own marker union. */
 export type MarkersConfig<TMarker> = TMarker[];
 /**
- * The `segments` prop accepted by every plot kind — series name (or
- * `'default'` for all series) to a list of {@link Segment}s. Within a
- * series, catch-all segments (no `areas`) evaluate first as a baseline;
- * area-specific segments merge on top and win on conflict.
+ * The `segments` prop - series name (or `'default'`) to its {@link Segment}s.
+ * Area-specific segments win over catch-all ones.
  */
 export type SegmentsConfig<TStyle> = Record<string, Segment<TStyle>[]>;
-/**
- * Partial margin override — unset sides fall back to the theme (itself
- * `'auto'` by default). `'auto'` fits the side to its rendered content; a
- * number pins it exactly.
- */
+/** One side of a box. */
+export type MarginSide = 'top' | 'right' | 'bottom' | 'left';
+/** Margin overrides per side: a number pins it, `'auto'` fits it to its content. Unset sides use the theme's. */
 export type MarginConfig = Partial<{
     top: number | 'auto';
     right: number | 'auto';
     bottom: number | 'auto';
     left: number | 'auto';
 }>;
-/**
- * The `tooltip` prop a plot actually receives — the resolved form of the
- * author-facing {@link TooltipOptions}. `format`/`sync` become required;
- * `facetId` identifies the originating facet (`''` when not faceted).
- * Presence of this object is what turns hovering on.
- */
-export type TooltipConfig<TRow extends Record<string, unknown>> = Omit<TooltipOptions<TRow>, 'format' | 'sync'> & {
-    format: (row: TRow) => string;
+/** The tooltip a plot's core draws from: {@link TooltipOptions} with `sync` resolved. Without `format`, the core uses its own default. */
+export type TooltipConfig<TRow extends Record<string, unknown>> = Omit<TooltipOptions<TRow>, 'sync'> & {
     sync: boolean;
-    facetId: string;
 };
 /** How a pointer event resolves to a candidate point: `'nearest'` (closest within a distance threshold) or `'contains'` (whichever candidate's own rendered shape contains the cursor). */
 export type PointMatchingStrategy = 'nearest' | 'contains';
-/** `BasePlotLayout`'s single `hover` prop — every plot kind's own resolved hover/tooltip wiring. */
+/** `BasePlotLayout`'s single `hover` prop - every plot kind's own resolved hover/tooltip wiring. */
 export type HoverConfig<TRow extends Record<string, unknown>> = {
     /** Whether the pointer/hover/tooltip machinery should mount at all. */
     active: boolean;
@@ -50,28 +48,115 @@ export type HoverConfig<TRow extends Record<string, unknown>> = {
     strategy?: HoverStrategy;
     /** Resolved sync flag for the *local* hover store (ignored once a shared store is in scope). */
     sync?: boolean;
-    tooltip?: TooltipConfig<TRow>;
-    /** When it returns `true`, that pointer event is treated as a leave instead of a move — lets a nested layout opt part of the plot out of hover matching. */
+    /** The resolved tooltip: its `format`, and the order its text reads the rows in (a `content` snippet gets them as matched). */
+    tooltip?: TooltipConfig<TRow> & {
+        format: (row: TRow) => string;
+        sort?: (a: TRow, b: TRow) => number;
+    };
+    /** When it returns `true`, that pointer event is treated as a leave instead of a move - lets a nested layout opt part of the plot out of hover matching. */
     exclude?: (e: PointerEvent) => boolean;
-    /** How to resolve a pointer event to a candidate point — see {@link PointMatchingStrategy}. Defaults to `'nearest'`. */
+    /** How to resolve a pointer event to a candidate point - see {@link PointMatchingStrategy}. Defaults to `'nearest'`. */
     pointMatching?: PointMatchingStrategy;
     /** Forces the crosshair rule(s) a `hover` marker draws off entirely, overriding whatever `strategy` implies. */
     crosshair?: boolean;
 };
+/** The `scales` prop of any plot kind. */
+export type ScalesConfig<TData = Record<string, unknown>> = AxisBasedScalesConfig<TData> | GeoScalesConfig;
 /**
- * The `scales` prop accepted by every plot kind — either flavor of scale
- * config a plot kind can have. Each concrete `Plot.svelte` narrows
- * `BasePlotProps`'s `TScales` to exactly the one that applies to it.
+ * A block a plot's chrome draws, `plot` for the plot itself, `timeline` for
+ * its timeline when that's a player bar, or `divider` for a line between two
+ * blocks, styled by the configuration's `divider`.
  */
-export type ScalesConfig<TData = Record<string, unknown>> = AxisBasedScalesConfig<TData> | GeoScalesConfig;
+export type PlotChromeItem = 'title' | 'subtitle' | 'header' | 'legend' | 'plot' | 'caption' | 'footer' | 'timeline' | 'divider';
+/**
+ * Two or three blocks drawn side by side in one row of the chrome, written as
+ * `'(plot, timeline)'`. The `plot` takes the width the others leave, and the
+ * others take as much as they need; a row without a `plot` shares its width
+ * among its blocks, none of them stretching.
+ */
+export type PlotChromeRow<TItem extends string = Exclude<PlotChromeItem, 'divider'>> = `(${TItem}, ${TItem})` | `(${TItem}, ${TItem}, ${TItem})`;
+/** One entry of a chrome `order`: a block, or a row of blocks. */
+export type PlotChromeEntry = PlotChromeItem | PlotChromeRow;
+/**
+ * What's drawn around a figure, as `Figure` and `FigureChrome` read it: every block
+ * optional, `header` drawn instead of `title`/`subtitle` and `footer` instead
+ * of `caption`. `order` lists the blocks top to bottom (by default, the
+ * configuration's `chrome.order`); one left out isn't drawn, except `plot`, which then
+ * goes last. Any number of `divider`s may sit in it, each drawn only between
+ * two drawn blocks.
+ */
+export type PlotChromeConfig = {
+    title?: string;
+    subtitle?: string;
+    caption?: string;
+    header?: Snippet;
+    footer?: Snippet;
+    /**
+     * The figure's legend: unset or `true`, the one its plots read as - their
+     * series, scales, and the segments and markers that name themselves; `false`,
+     * none; a list of sections, exactly those; `{ items, sections }`, the
+     * automatic one with those added, and `{ series, color, opacity, size,
+     * symbol }`, with the section of each channel adjusted (see {@link LegendExtension}).
+     */
+    legend?: LegendSection[] | LegendExtension | boolean;
+    order?: PlotChromeEntry[];
+};
+/**
+ * One way to fill part of the chrome, and the `order` items it allows. A block
+ * that's passed may still be `undefined` at runtime: it's then just not drawn.
+ */
+type ChromeBlock<TProps, TItem extends PlotChromeItem> = {
+    props: TProps;
+    item: TItem;
+};
+type HeadingBlock = ChromeBlock<{
+    header: Snippet | undefined;
+    title?: never;
+    subtitle?: never;
+}, 'header'> | ChromeBlock<{
+    header?: never;
+    title: string | undefined;
+    subtitle: string | undefined;
+}, 'title' | 'subtitle'> | ChromeBlock<{
+    header?: never;
+    title: string | undefined;
+    subtitle?: never;
+}, 'title'> | ChromeBlock<{
+    header?: never;
+    title?: never;
+    subtitle: string | undefined;
+}, 'subtitle'> | ChromeBlock<{
+    header?: never;
+    title?: never;
+    subtitle?: never;
+}, never>;
+/** The legend is always there to place: unset, a figure reads one off what its plots draw. */
+type LegendBlock = ChromeBlock<{
+    legend?: LegendSection[] | LegendExtension | boolean | undefined;
+}, 'legend'>;
+type ClosingBlock = ChromeBlock<{
+    footer: Snippet | undefined;
+    caption?: never;
+}, 'footer'> | ChromeBlock<{
+    footer?: never;
+    caption: string | undefined;
+}, 'caption'> | ChromeBlock<{
+    footer?: never;
+    caption?: never;
+}, never>;
+/** Every combination of the three parts, each with an `order` of only the blocks it fills, plus `plot` and dividers. */
+type ChromeCombination<THeading, TLegend, TClosing> = THeading extends ChromeBlock<infer HP, infer HI> ? TLegend extends ChromeBlock<infer LP, infer LI> ? TClosing extends ChromeBlock<infer CP, infer CI> ? HP & LP & CP & {
+    order?: (HI | LI | CI | 'plot' | 'timeline' | 'divider' | PlotChromeRow<HI | LI | CI | 'plot' | 'timeline'>)[];
+} : never : never : never;
 /**
- * The shared prop bag every plot component accepts, parameterized over
- * everything that varies by plot kind: `TDataContract` is its own data
- * shape, `TRow` is what `tooltip` resolves against, and the rest are its
- * own segment/style/marker/scale/coordinate-system shapes. `TCoordinates`
- * defaults to `undefined` — only `GeoPlot` instantiates it.
+ * What's drawn around a plot: accepted by every plot kind and by
+ * `PlotComposer`. `header` replaces `title`/`subtitle` and `footer`
+ * replaces `caption`, so each excludes the other. `order` lists the blocks
+ * top to bottom, out of the ones set here plus `plot`, `timeline` and `divider`; see {@link PlotChromeConfig}.
  */
-export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>, TCoordinates = undefined> = TDataContract & {
+export type PlotChromeProps = ChromeCombination<HeadingBlock, LegendBlock, ClosingBlock>;
+/** The props every plot kind shares between its core and its public component. */
+type PlotCommonProps<TStyles extends object, TSegmentStyle extends object, TMarker, TScales, TCoordinates> = {
     width: number;
     height: number;
     styles?: StylesConfig<TStyles>;
@@ -80,5 +165,30 @@ export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, T
     scales?: TScales;
     coordinates?: TCoordinates;
     margins?: MarginConfig;
+    statistics?: StatisticConfig[];
+    transforms?: MarkerTransform[];
+};
+/** The props a plot kind's core draws from. `TCoordinates` is only set by `GeoPlot`. */
+export type PlotCoreProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>, TCoordinates = undefined> = TDataContract & PlotCommonProps<TStyles, TSegmentStyle, TMarker, TScales, TCoordinates> & {
     tooltip?: TooltipConfig<TRow>;
+    /** One facet panel's part of a run of the data phases over every panel: the core then runs only the phases after them. */
+    panelState?: object;
+    /** The kind's pipeline, built once by its plot: the core runs it over its own props. */
+    pipeline?: Pipeline<any, any>;
+};
+/**
+ * A figure's box - a plot's or a `PlotComposer`'s: its own `width` and
+ * `height`, or, drawn straight inside a `PlotComposer`, the cell it takes
+ * there (an `area`, or an `inset` floating over it), whose size it draws at.
+ */
+export type FigureBoxProps = GridPlacement & {
+    width?: number;
+    height?: number;
+};
+/** A plot component's public props: its core props, chrome, `timeline`, `facet` and an author-facing `tooltip`. */
+export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>, TCoordinates = undefined> = TDataContract & Omit<PlotCommonProps<TStyles, TSegmentStyle, TMarker, TScales, TCoordinates>, 'width' | 'height'> & FigureBoxProps & PlotChromeProps & {
+    tooltip?: TooltipProp<TRow>;
+    timeline?: TimelineConfig<TRow>;
+    facet?: FacetConfig<TRow>;
 };
+export {};

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

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { GapsAwarePlotStylesConfig } from '../../layout/styles';
+import type { BarSegmentStyle } from '../segments/common';
+/** `PyramidPlot`'s public props. */
+export type PyramidPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `PyramidPlot`'s core draws from. */
+export type PyramidPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/pyramid/props.js

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

package/dist/types/plots/pyramid/state.d.ts

@@ -0,0 +1,16 @@
+import type { Series } from '../data/common';
+import type { BarSegmentStyle } from '../segments/common';
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+export type PyramidSide = 'left' | 'right';
+/** A resolved series tagged with which side of the shared zero baseline it renders on. */
+export type PyramidSeries<TData extends Record<string, unknown>> = Series<TData> & {
+    side: PyramidSide;
+};
+/**
+ * PyramidPlot's pipeline state: the shared axis-based state with its own series
+ * and row shapes. Its `x`/`y` are the visual axes, as on every plot: the one
+ * holding categories decides whether its sides run left/right or bottom/top.
+ */
+export type PyramidPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, BarSegmentStyle, PyramidSeries<TData>>;
+/** The environment every PyramidPlot phase reads from, alongside the growing state. */
+export type PyramidPlotCtx = AxisPlotCtx;

package/dist/types/plots/pyramid/state.js

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

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

@@ -0,0 +1,10 @@
+import type { BasePlotProps, PlotCoreProps } from '../props';
+import type { AxisBasedScalesConfig } from '../../layout/scales';
+import type { AxisBasedMarkersConfig } from '../../markers/common';
+import type { SeriesProps, DataProps } from '../data/common';
+import type { AxisBasedStylesConfig } from '../../layout/styles';
+import type { ScatterSegmentStyle } from '../segments/common';
+/** `ScatterPlot`'s public props. */
+export type ScatterPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, ScatterSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+/** What `ScatterPlot`'s core draws from. */
+export type ScatterPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, AxisBasedStylesConfig, ScatterSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

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

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

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

@@ -0,0 +1,6 @@
+import type { ScatterSegmentStyle } from '../segments/common';
+import type { AxisPlotState, AxisPlotCtx } from '../../phases';
+/** ScatterPlot's pipeline state: the shared axis-based state, with no extras of its own. */
+export type ScatterPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, ScatterSegmentStyle>;
+/** The environment every ScatterPlot phase reads from, alongside the growing state. */
+export type ScatterPlotCtx = AxisPlotCtx;

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

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

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

@@ -10,7 +10,7 @@ export type BarSegmentStyle = AreaStyle;
 export type CellSegmentStyle = AreaStyle;
 /** Per-segment styling for a scatter point cloud. */
 export type ScatterSegmentStyle = DotStyle;
-/** Per-feature styling override for `GeoPlot` — the geo analog of `CellSegmentStyle`. */
+/** Per-feature styling override for `GeoPlot` - the geo analog of `CellSegmentStyle`. */
 export type GeoSegmentStyle = {
     fill?: string;
     fillOpacity?: number;