@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/curves/regression.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `regression`: a fitted trend (least squares or LOESS) with its confidence
+ * band, one per `series`, drawn as one path batch (per fit a closed band
+ * item, then an open line item) in a group whose clip the reveal sweeps.
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey } from "@sophistry/core/geometry";
+import type { Channel, PositionValue } from "../data/channels.js";
+import type { SeriesTransitionProps } from "../props.js";
+/**
+ * Props of {@link regressionPlot}: `x` and `y` default to the index and the
+ * datum when `data` is `number[]`; name them otherwise.
+ *
+ * @category Charts
+ */
+export interface RegressionProps<T = unknown> extends SeriesTransitionProps<T> {
+    /** The points the fit is through: one per datum. */
+    data: readonly T[];
+    /**
+     * Predictor, in data units (a `Date` reads as epoch ms). Defaults to the index when `data` is
+     * `number[]`; required otherwise.
+     */
+    x?: Channel<T, PositionValue>;
+    /**
+     * Response, in data units. Defaults to the datum when `data` is `number[]`; required otherwise.
+     * Pairs with a non-finite member are dropped.
+     */
+    y?: Channel<T, number>;
+    /**
+     * The fit: `"linear"`, `"poly"` (a polynomial of `degree`) or `"loess"` (a local smooth over
+     * `bandwidth` of the points).
+     * @default "linear"
+     */
+    method?: "linear" | "poly" | "loess";
+    /**
+     * Polynomial degree for `method="poly"`.
+     * @default 2
+     */
+    degree?: number;
+    /**
+     * Fraction of the points each local fit uses, for `method="loess"`.
+     * @default 0.3
+     */
+    bandwidth?: number;
+    /**
+     * Make a `method="loess"` smooth robust to outliers: `true` for 2 re-weighting passes, or a
+     * number of passes.
+     * @default false
+     */
+    robust?: boolean | number;
+    /**
+     * Confidence level of the band around the fit, 0..1 (0 for no band): the fitted mean's t-band
+     * for least squares, the standard-error band for LOESS (see {@link loessBand}).
+     * @default 0.95
+     */
+    level?: number;
+    /**
+     * How many x positions the fit is drawn through.
+     * @default 50
+     */
+    samples?: number;
+    /**
+     * The category of each datum: one fit per category, coloured through the chart's shared colour
+     * scale and legend. `color` wins.
+     */
+    series?: Channel<T, BandKey>;
+    /**
+     * Line and band colour. Defaults to the `series` colour, else the theme's first series colour.
+     */
+    color?: ColorInput;
+    /**
+     * Band fill opacity, 0..1.
+     * @default 0.2
+     */
+    bandOpacity?: number;
+    /** Line width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /**
+     * Reveal, 0..1: the line and its band sweep in left to right together.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * The data to transition to, fits matched by `series`: shared fits morph with their bands, new
+     * ones sweep in, leaving ones fade out. See {@link SeriesTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the fits. */
+    visible?: boolean;
+}
+/**
+ * A fitted trend with its confidence band over the data's x extent: least
+ * squares (a line or polynomial) or a LOESS smooth. Draw it over a
+ * `scatter` of the same data. See the `regression` and `loessBand` maths for
+ * the fits alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, regressionPlot, scatter } from "@sophistry/charts";
+ *
+ * const rows = [1, 2, 3, 4, 5, 6, 7, 8].map((x) => ({ x, y: Math.sqrt(x) + Math.sin(x) / 4 }));
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	children: [
+ * 		scatter.create({ data: rows, x: "x", y: "y" }),
+ * 		regressionPlot.create({ data: rows, x: "x", y: "y", method: "loess" }),
+ * 	],
+ * });
+ * ```
+ *
+ * Exported as `regressionPlot` (definition name `"Regression"`): the
+ * package entry already exports the `regression` fit from its maths.
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#lines-scatter-and-error-bars
+ * @category Charts
+ */
+export declare const regressionPlot: import("@sophistry/core").Definition<RegressionProps<any>, import("@sophistry/core/internal").CompositeNode<RegressionProps<any>>, keyof RegressionProps<any>>;

package/dist/curves/shared.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What the line and area marks (`linePlot`, `stackPlot`, `fillBetween`,
+ * `stairs`, `ecdf`, `density`, `regression`) share: the one path batch each
+ * draws through (with the clip a sweep reveal needs), stable items so an
+ * outline that did not move is prepared once, and group colours across a
+ * keyed transition. Internal.
+ *
+ * Every curve mark draws one shape per group (a `series` category, or the
+ * one `WHOLE` group), and those shapes have outlines of their own, so the
+ * mark is one core `pathBatch` node: an item per line, band or region, each
+ * with its own stroke or fill and opacity. A `reveal="length"` draw hands
+ * each item its `progress` (the stroke traced along
+ * the outline, a closed outline's fill coming up with it), over the whole
+ * outline; the batch keeps an outline's arrays while only that changes, so
+ * the renderer measures their arc length once.
+ */
+import type { Bindable, PathBatchItem, PathBatchItemsProps, PathBatchNode, SceneNode } from "@sophistry/core";
+import type { Bounds } from "@sophistry/core/geometry";
+import type { ChartLayer } from "../context.js";
+import type { GroupJoin } from "../join.js";
+import type { GroupKey, SeriesState } from "../series.js";
+/**
+ * A group's colour from the series scale, across a keyed transition: while
+ * one runs, over both ends' categories (`data`'s first), so a category keeps
+ * its colour. Undefined for {@link WHOLE}, or when an explicit colour wins.
+ */
+export declare function groupColors(layer: ChartLayer, series: SeriesState, join: GroupJoin): (key: GroupKey) => string | undefined;
+/**
+ * The one path batch of a curve mark, inside a group whose clip a sweep
+ * reveal moves. Call once, in `setup`.
+ */
+export interface CurveBatch {
+    /** The node to return from the mark: the group holding the batch. */
+    readonly node: SceneNode;
+    /** The batch itself. */
+    readonly batch: PathBatchNode<PathBatchItemsProps>;
+    /**
+     * Writes one update's items (`[slot key, item]` pairs, in paint order),
+     * shared props and clip. An item equal to the one its slot held last time
+     * is handed over as that same object, one whose outline alone is equal
+     * (its `progress` or a paint changed) around the same outline arrays, and
+     * an unchanged list as the same array, so the batch re-prepares only
+     * outlines that moved.
+     */
+    update(items: readonly (readonly [unknown, PathBatchItem])[], shared: Bindable<Omit<PathBatchItemsProps, "items">>, clip?: Bounds | undefined): void;
+    /** The items as last written. */
+    readonly items: readonly PathBatchItem[];
+}
+/** Makes a mark's {@link CurveBatch}. */
+export declare function createCurveBatch(): CurveBatch;
+/** A group's slot key in a batch with more than one item per group (`"fill"`, `"line"`). */
+export declare function slotOf(key: GroupKey, part: string): string;

package/dist/curves/stack-plot.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `stackPlot`: a stacked area chart, drawn as one path batch (a closed item
+ * per band) in a group whose clip the `"x"` reveal sweeps; `reveal="length"`
+ * traces each band's outline (the item's `progress`), its fill coming up
+ * with it.
+ *
+ * Across a keyed transition each end is stacked on its own, a band one end
+ * lacks stands with no thickness on its seam, and the update morphs each
+ * band's bounds together, so adjacent bands stay touching on every frame.
+ */
+import type { PaintSpec } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey, CurveKind } from "@sophistry/core/geometry";
+import type { Channel, PositionValue } from "../data/channels.js";
+import type { JoinStaging } from "../math/join.js";
+import type { StackOffset, StackOrder } from "../math/stack.js";
+import type { StackReveal, TransitionProps } from "../props.js";
+/**
+ * Props of {@link stackPlot}: `x` defaults to the index when `data` is
+ * `number[]`; name it otherwise.
+ *
+ * @category Charts
+ */
+export interface StackPlotProps<T = unknown> extends TransitionProps<T> {
+    /**
+     * Wide format (`y` a list): one row per x position. Long format (`y` one channel, with a
+     * `series`): one row per band per x position.
+     */
+    data: readonly T[];
+    /**
+     * X position, in data units (a `Date` reads as epoch ms). Defaults to the index when `data` is
+     * `number[]`; required otherwise.
+     */
+    x?: Channel<T, PositionValue>;
+    /**
+     * One channel per band, stacked in the order given (`y: ["north", "south"]`); or one channel,
+     * for long-format `data`, with `series` naming each row's band. Non-finite heights count as 0.
+     */
+    y: readonly Channel<T, number>[] | Channel<T, number>;
+    /**
+     * Which series each band is, colouring bands through the chart's shared colour scale and
+     * legend: with a list of `y` channels, one name per channel; with one `y` channel, a channel
+     * naming each row's band (rows missing at an x count as 0).
+     */
+    series?: readonly BandKey[] | Channel<T, BandKey>;
+    /**
+     * Colours cycled across bands by index. Defaults to the `series` colours, else the theme's
+     * categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Data-space y the first band stacks on, under the `"zero"` offset. Defaults to the axis
+     * baseline.
+     */
+    baseline?: number;
+    /**
+     * Where each x's stack is placed: `"zero"` on the baseline, `"normalize"` as shares of the
+     * total, `"center"` centred on zero, `"wiggle"` a streamgraph (needs ascending, evenly spaced
+     * x). See {@link StackOffset}.
+     * @default "zero"
+     */
+    offset?: StackOffset;
+    /**
+     * Which band sits at the bottom: `"appearance"`, `"reverse"`, `"sum"` (largest on top),
+     * `"insideOut"` (streamgraph order), or band indices bottom to top. Colours stay with their
+     * band.
+     * @default "appearance"
+     */
+    order?: StackOrder;
+    /**
+     * How `progress` reveals the stack: `"grow"` every band's height from the baseline together,
+     * `"x"` left to right behind one front, `"length"` each band's outline by arc length.
+     * @default "grow"
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    reveal?: StackReveal;
+    /**
+     * How band edges run between rows: `"linear"` or any {@link CurveKind} (`"monotone"` for a
+     * smooth stack). Adjacent bands still share their edge exactly.
+     * @default "linear"
+     */
+    curve?: CurveKind;
+    /**
+     * The data to transition to, bands matched by `series` (long format) or place in `y` (wide):
+     * each end is stacked on its own and shared bands morph between them, so every frame is a
+     * stack. Leaving bands shrink away, new ones grow in.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /**
+     * How the transition spends `blend`.
+     * @default "staged"
+     */
+    staging?: JoinStaging;
+    /**
+     * With `to`: fraction of the enter stage spent staggering arriving bands, bottom up, 0..0.95.
+     * @default 0
+     */
+    enterStagger?: number;
+    /** Band fill opacity 0..1. @default 0.85 */
+    fillOpacity?: number;
+    /** Band outline. @default "none" */
+    stroke?: PaintSpec;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1 (see `reveal`). @default 1 */
+    progress?: number;
+    /** Paint order (the bands paint under the axes of that order). */
+    zIndex?: number;
+    /** Set to false to hide the bands. */
+    visible?: boolean;
+}
+/**
+ * A stacked area chart: bands stacked atop a shared baseline, each shaded in
+ * its own colour. Use `offset` for 100% areas or streamgraphs. Inside a
+ * `chart` (or any `axes` whose y range covers the stacked total). See
+ * {@link stackedBands} for the stacking alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, stackPlot } from "@sophistry/charts";
+ *
+ * const rows = [
+ * 	{ year: 2022, north: 3, south: 2 },
+ * 	{ year: 2023, north: 4, south: 3 },
+ * 	{ year: 2024, north: 5, south: 3 },
+ * ];
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	children: [stackPlot.create({ data: rows, x: "year", y: ["north", "south"], series: ["North", "South"] })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#stacked-areas
+ * @category Charts
+ */
+export declare const stackPlot: import("@sophistry/core").Definition<StackPlotProps<any>, import("@sophistry/core/internal").CompositeNode<StackPlotProps<any>>, keyof StackPlotProps<any>>;

package/dist/curves/stairs.d.ts

@@ -0,0 +1,170 @@
+/**
+ * `stairs`: a step function held flat across each `[edges[i], edges[i + 1]]`
+ * interval, one open line per `series`, drawn as one path batch. Also the
+ * step-line drawing `ecdf` shares ({@link stepLineItems}): lines kept by
+ * group, coloured by the series scale unless `stroke` is set, revealed along
+ * x behind one front (or by arc length), and morphed as step functions
+ * across a keyed transition.
+ */
+import type { CoordinateSystem, PaintSpec, SceneNode } from "@sophistry/core";
+import type { BandKey, Point } from "@sophistry/core/geometry";
+import type { Channel } from "../data/channels.js";
+import type { ChartFrame } from "../frame/types.js";
+import type { GroupJoin } from "../join.js";
+import type { StepFunction } from "../math/morph.js";
+import type { CurveReveal, SeriesTransitionProps } from "../props.js";
+import type { GroupKey } from "../series.js";
+import type { CurveBatch } from "./shared.js";
+/**
+ * The stroke props every step line takes (`stairs`, `ecdf`).
+ *
+ * @category Charts
+ */
+export interface StepLineStyleProps {
+    /** Line colour (or gradient) for every line. Defaults to the `series` colour, else the theme's foreground. */
+    stroke?: PaintSpec;
+    /** Line width. Defaults to the theme's stroke width. */
+    strokeWidth?: number;
+    /** Dash pattern, in scene units. Solid when omitted. */
+    dash?: number[];
+    /** Offset into `dash`. @default 0 */
+    dashOffset?: number;
+    /** How line ends are capped. @default "round" */
+    lineCap?: CanvasLineCap;
+    /** How corners are joined. @default "round" */
+    lineJoin?: CanvasLineJoin;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1 (see `reveal`). @default 1 */
+    progress?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the lines. */
+    visible?: boolean;
+}
+/**
+ * Props of {@link stairs}: `value` defaults to the datum when `data` is
+ * `number[]`; name it otherwise.
+ *
+ * @category Charts
+ */
+export interface StairsProps<T = unknown> extends SeriesTransitionProps<T>, StepLineStyleProps {
+    /** One step per datum. */
+    data: readonly T[];
+    /**
+     * Height of each step, in data units, held across `[edges[i], edges[i + 1]]`. Defaults to the
+     * datum when `data` is `number[]`; required otherwise.
+     */
+    value?: Channel<T, number>;
+    /**
+     * Step boundaries in data units, ascending, exactly one more than `data` (else throws). With a
+     * `series`, shared by every category. Defaults to `0..data.length`.
+     */
+    edges?: readonly number[];
+    /**
+     * The category of each datum: one step line per category, coloured through the chart's shared
+     * colour scale and legend. `stroke` wins.
+     */
+    series?: Channel<T, BandKey>;
+    /**
+     * How `progress` reveals the steps: `"x"` left to right at a constant rate, or `"length"` by
+     * arc length.
+     * @default "x"
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    reveal?: CurveReveal;
+    /**
+     * The data to transition to, lines matched by `series`: shared lines morph and stay step
+     * functions every frame, new ones sweep in, leaving ones fade out. See {@link
+     * SeriesTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+}
+/** The descriptor entries of {@link StepLineStyleProps}. */
+export declare const stepLineStyleDescriptor: {
+    readonly stroke: {
+        readonly invalidates: 64;
+    };
+    readonly strokeWidth: {
+        readonly invalidates: 64;
+    };
+    readonly dash: {
+        readonly invalidates: 64;
+    };
+    readonly dashOffset: {
+        readonly invalidates: 64;
+    };
+    readonly lineCap: {
+        readonly invalidates: 64;
+    };
+    readonly lineJoin: {
+        readonly invalidates: 64;
+    };
+    readonly opacity: {
+        readonly invalidates: 64;
+    };
+    readonly progress: {
+        readonly default: 1;
+        readonly invalidates: 64;
+    };
+    readonly zIndex: {
+        readonly invalidates: 64;
+    };
+    readonly visible: {
+        readonly invalidates: 64;
+    };
+};
+/** What a step-line drawing keeps between updates. */
+export interface StepLines {
+    scene: (deps: readonly unknown[], make: () => Map<GroupKey, Point[][]>) => Map<GroupKey, Point[][]>;
+    lines: CurveBatch;
+}
+/** Makes a {@link StepLines}. Call once, in `setup`. */
+export declare function createStepLines(): StepLines;
+/**
+ * Draws one step line per group (what `stairs` and `ecdf` share): each
+ * group's line in scene units on this frame (morphed as a step function on
+ * the update stage, entering ones swept in, leaving ones faded), cut at one
+ * front along x (or by arc length), as path batch items.
+ *
+ * @internal
+ */
+export declare function drawStepLines(own: StepLines, spec: {
+    props: StepLineStyleProps;
+    theme: {
+        palette: {
+            foreground: string;
+        };
+    };
+    frame: ChartFrame | null;
+    coords: CoordinateSystem;
+    /** `data`'s step functions, per group. */
+    steps: Map<GroupKey, StepFunction>;
+    /** `to`'s, while a transition runs. */
+    to: Map<GroupKey, StepFunction> | undefined;
+    join: GroupJoin;
+    colorOf: (key: GroupKey) => string | undefined;
+    progress: number | undefined;
+    alongX: boolean;
+}): SceneNode[];
+/**
+ * A step function held flat across each `[edges[i], edges[i + 1]]` interval,
+ * drawn as one open line: a histogram's outline without the fill. Inside a
+ * `chart` or `axes`. See {@link stairsPolyline} for the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, stairs } from "@sophistry/charts";
+ *
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	children: [stairs.create({ data: [3, 5, 2, 6], edges: [0, 1, 2, 4, 5] })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#histograms
+ * @category Charts
+ */
+export declare const stairs: import("@sophistry/core").Definition<StairsProps<any>, import("@sophistry/core/internal").CompositeNode<StairsProps<any>>, keyof StairsProps<any>>;

package/dist/data/channels.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Data channels: how a chart reads one field out of each datum. A channel
+ * is a key of the datum (`x="year"`, type-checked against `T`) or a function
+ * `(d, i) => value`. Singular props are channels, plural ones (`xs`,
+ * `colors`, `edges`) literal arrays. With `number[]` data the main numeric
+ * channel defaults to the datum itself. Colour is a constant or a function,
+ * never a key; colour by a field with `series`. Dates in positional
+ * channels are read as epoch milliseconds.
+ *
+ * @packageDocumentation
+ */
+import type { ContextKey } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { TemporalValue, TimeZone } from "@sophistry/core/geometry";
+/**
+ * A channel function: reads one value from a datum and its index.
+ *
+ * @category Channels
+ */
+export type ChannelFn<T, V> = (datum: T, index: number) => V;
+/**
+ * The keys of `T` whose values suit a `V`-valued channel (`V`, `null` or `undefined`).
+ *
+ * @category Channels
+ */
+export type ChannelKey<T, V> = [T] extends [object] ? {
+    [K in keyof T & string]-?: T[K] extends V | null | undefined ? K : never;
+}[keyof T & string] : never;
+/**
+ * Where a chart finds a `V` in each `T`: a key of `T` whose value is a `V`,
+ * or a function `(d, i) => V`.
+ *
+ * @see https://sophistry.dev/guides/charts/#data-and-channels
+ * @category Channels
+ */
+export type Channel<T, V> = ChannelKey<T, V> | ChannelFn<T, V>;
+/**
+ * A position on a continuous axis, as positional channels (`x`, `y`, `x1`,
+ * …) accept it: a number, a `Date`, or a Temporal value (`Instant`,
+ * `ZonedDateTime`, `PlainDate`, `PlainDateTime`).
+ *
+ * @see https://sophistry.dev/guides/charts/#dates-and-time-zones
+ * @category Channels
+ */
+export type PositionValue = number | Date | TemporalValue;
+/**
+ * What a channel of `V`s reads once resolved: dates become epoch
+ * milliseconds, anything else is as given.
+ *
+ * @category Channels
+ */
+export type ChannelRead<V> = V extends Date | TemporalValue ? number : V;
+/**
+ * A number: one constant for every datum, or a per-datum {@link Channel}.
+ *
+ * @category Channels
+ */
+export type Quantity<T> = number | Channel<T, number>;
+/**
+ * A colour: one constant (a CSS string or a `Color` such as `BLUE`) or
+ * `(d, i) => colour`. No key form: a string is always a colour.
+ *
+ * @category Channels
+ */
+export type ColorChannel<T> = ColorInput | ChannelFn<T, ColorInput>;
+/**
+ * Placeholder type of a required channel prop; see {@link RequiredUnless}.
+ * Its name is what a "missing property" error shows.
+ *
+ * @category Channels
+ */
+export interface RequiredChannel<T, V> {
+    /** @internal */
+    readonly __channel?: [T, V];
+}
+/**
+ * Makes the channel prop `K` required unless `T` is already a `V` (then the
+ * channel defaults to the datum itself; nullish members of `T` don't
+ * count). Intersect it with a props interface declaring `K` as an optional
+ * {@link Channel}; `T` stays inferred from `data`.
+ *
+ * @category Channels
+ */
+export type RequiredUnless<T, V, K extends string> = [NonNullable<T>] extends [
+    V
+] ? unknown : {
+    [P in K]-?: RequiredChannel<T, V>;
+};
+/** The identity channel, the default for `number[]` data. */
+export declare const identity: <T, V>(datum: T) => V;
+/** Position of a datum: the default `x` channel for `number[]` data. */
+export declare const indexOf: (_datum: unknown, index: number) => number;
+/**
+ * Turns a {@link Channel} into a plain function: a key reads that property,
+ * a function is called as is. Dates come back as epoch milliseconds (plain
+ * Temporal dates in the axis's `timeZone`, else UTC); read through a
+ * positional channel under a `<Chart>`, they also make that axis a time
+ * axis. An omitted channel resolves to `fallback`, or `undefined`.
+ *
+ * A mark passes the {@link DateSink} it read from {@link dateSinkContext}.
+ *
+ * @param fallback - Used when `channel` is `undefined`.
+ * @param name - Prop name for the error message.
+ * @param sink - Where a positional channel notes dates (the enclosing chart's).
+ * @throws {TypeError} If `channel` is neither a function nor a string or symbol key.
+ * @category Channels
+ */
+export declare function resolveChannel<T, V>(channel: Channel<T, V>, fallback?: undefined, name?: string, sink?: DateSink | null): ChannelFn<T, ChannelRead<V>>;
+export declare function resolveChannel<T, V>(channel: Channel<T, V> | undefined, fallback: ChannelFn<T, V>, name?: string, sink?: DateSink | null): ChannelFn<T, ChannelRead<V>>;
+export declare function resolveChannel<T, V>(channel: Channel<T, V> | undefined, fallback?: undefined, name?: string, sink?: DateSink | null): ChannelFn<T, ChannelRead<V>> | undefined;
+/** An axis a channel's dates can be noted on: a chart's own, or a secondary one. */
+export type DateAxis = "x" | "y" | "x2" | "y2";
+/**
+ * Where positional channels note that they read dates, so `<Chart>` can
+ * infer a `"utc"` scale; also gives the zone an axis reads plain Temporal
+ * dates in.
+ *
+ * @category Extending
+ */
+export interface DateSink {
+    note(axis: DateAxis): void;
+    /** The zone `axis` names, if any, else `"UTC"`. */
+    timeZone(axis: DateAxis): TimeZone;
+}
+/**
+ * Provided by `chart` (and redirected by `secondaryX`/`secondaryY`); outside
+ * one (3D charts, transforms) it is null. Marks read it with
+ * `ctx.context(dateSinkContext)` and pass it to {@link resolveChannel}.
+ *
+ * @category Extending
+ */
+export declare const dateSinkContext: ContextKey<DateSink | null>;
+/**
+ * A {@link Quantity} as a function: a constant ignores the datum. An omitted
+ * quantity resolves to `fallback`, or `undefined`.
+ *
+ * @category Channels
+ */
+export declare function resolveQuantity<T>(quantity: Quantity<T>): ChannelFn<T, number>;
+export declare function resolveQuantity<T>(quantity: Quantity<T> | undefined, fallback: ChannelFn<T, number>): ChannelFn<T, number>;
+export declare function resolveQuantity<T>(quantity: Quantity<T> | undefined): ChannelFn<T, number> | undefined;
+/**
+ * Reads a channel across `data`.
+ *
+ * @param name - Prop name for the error message.
+ * @returns One value per datum, in order (dates as epoch milliseconds).
+ * @category Channels
+ */
+export declare function channelValues<T, V>(data: readonly T[], channel: Channel<T, V> | undefined, fallback?: ChannelFn<T, V>, name?: string, sink?: DateSink | null): (ChannelRead<V> | undefined)[];
+/**
+ * {@link channelValues} for a numeric channel: non-numbers become `NaN`
+ * (which charts skip), dates epoch milliseconds.
+ *
+ * @category Channels
+ */
+export declare function numberValues<T, V extends PositionValue = PositionValue>(data: readonly T[], channel: Channel<T, V> | undefined, fallback?: ChannelFn<T, NoInfer<V>>, name?: string, sink?: DateSink | null): number[];
+/**
+ * A {@link ColorChannel} as a function, or `undefined` when omitted.
+ *
+ * @category Channels
+ */
+export declare function resolveColor<T>(color: ColorChannel<T> | undefined): ChannelFn<T, string> | undefined;
+/**
+ * Colour of datum `i`: the per-datum `color` if given, else the `colors`
+ * palette cycled by index, else `fallback`.
+ *
+ * @param fallback - Used when the palette is empty.
+ * @category Channels
+ */
+export declare function colorResolver<T>(color: ColorChannel<T> | undefined, palette: readonly ColorInput[], fallback: ColorInput): ChannelFn<T, string>;