@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/bars/transforms.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Data transforms: plain functions from rows to rows, applied to `data`
+ * before it reaches a mark, composing by nesting (`stack(group(rows, ...))`).
+ * Derived rows share field names (`x` position, `y` value, `z` series, the
+ * input kept as `datum` or `rows`), so they chain without renaming. Dates
+ * in an `x` or `by` channel are read as epoch milliseconds.
+ *
+ * @packageDocumentation
+ */
+import type { BandKey } from "@sophistry/core/geometry";
+import type { Channel, PositionValue } from "../data/channels.js";
+import type { NormalizeBasis, Reducer, RollingOptions } from "../math/aggregate.js";
+import type { HistogramOptions } from "../math/histogram.js";
+import type { StackOffset } from "../math/stack.js";
+/** @category Transforms */
+export interface StackOptions<T> {
+    /** The position rows stack at; rows sharing an `x` stack on each other. Omitted, all rows stack in one column. */
+    x?: Channel<T, BandKey | PositionValue>;
+    /** The value. Defaults to the datum itself, for `number[]` data. */
+    y?: Channel<T, number>;
+    /** The series a row belongs to; series stack in `order`. Omitted, rows stack in data order. */
+    z?: Channel<T, BandKey>;
+    /**
+     * `"zero"`, `"normalize"` (each column 0..1), `"center"` or `"wiggle"` (a
+     * streamgraph). See {@link StackOffset}.
+     * @default "zero"
+     */
+    offset?: StackOffset;
+    /**
+     * Which series sits at the bottom: `"appearance"`, `"reverse"`, `"sum"`
+     * (largest on top), `"insideOut"`, or the series keys bottom to top.
+     * @default "appearance"
+     */
+    order?: "appearance" | "reverse" | "sum" | "insideOut" | readonly BandKey[];
+}
+/** @category Transforms */
+export interface StackedRow<T> {
+    /** The input row. */
+    datum: T;
+    /** Its index in the input. */
+    index: number;
+    /** Its position, as given (undefined without `x`). */
+    x: BandKey | undefined;
+    /** Its series, as given (undefined without `z`). */
+    z: BandKey | undefined;
+    /** Its series' 0-based place in first-seen order: cycle a palette by this. */
+    zIndex: number;
+    /** Its value, as given. */
+    y: number;
+    /** Where its segment starts (towards the baseline); `NaN` when `y` is not finite. */
+    y1: number;
+    /** Where its segment ends; `NaN` when `y` is not finite. */
+    y2: number;
+}
+/**
+ * Stacks rows sharing an `x`, series by series, giving each a `y1` (segment
+ * start) and `y2` (segment end): feed them to `bars.create({ base: "y1", value: "y2" })`
+ * or any mark with lower and upper channels. Positive values stack up from
+ * zero and negative ones down, so diverging stacks need nothing extra.
+ *
+ * @returns One {@link StackedRow} per input row, in input order.
+ * @see https://sophistry.dev/guides/charts/#transforms
+ * @category Transforms
+ */
+export declare function stack<T>(data: readonly T[], options?: StackOptions<T>): StackedRow<T>[];
+/** @category Transforms */
+export interface DodgeOptions<T> {
+    /** The category whose band the rows share; required for `compact`. */
+    x?: Channel<T, BandKey | PositionValue>;
+    /** The value, copied to each row as `y`. Defaults to the datum itself, for `number[]` data. */
+    y?: Channel<T, number>;
+    /** The series that split a band, side by side in first-seen order. */
+    z: Channel<T, BandKey>;
+    /** Fraction of each sub-band left empty between neighbours, 0..1. @default 0.1 */
+    padding?: number;
+    /**
+     * Split each band only among the series present in it. Off, every series
+     * keeps its place in every band, so it reads at the same position across
+     * categories.
+     * @default false
+     */
+    compact?: boolean;
+}
+/** @category Transforms */
+export interface DodgedRow<T> {
+    datum: T;
+    index: number;
+    x: BandKey | undefined;
+    z: BandKey;
+    /** Its series' 0-based place in first-seen order. */
+    zIndex: number;
+    y: number;
+    /** The part of its category's band this row takes, as fractions `[from, to]`: `bars.create({ subband: "subband" })`. */
+    subband: [number, number];
+}
+/**
+ * Splits each category's band among its series, for grouped bars: each row
+ * gets a `subband` that `bars` (`subband`) draws.
+ *
+ * @returns One {@link DodgedRow} per input row, in input order.
+ * @see https://sophistry.dev/guides/charts/#transforms
+ * @category Transforms
+ */
+export declare function dodge<T>(data: readonly T[], options: DodgeOptions<T>): DodgedRow<T>[];
+/** @category Transforms */
+export interface GroupOptions<T> {
+    /** What to group by: one channel (the key becomes `x`), or two (`[x, z]`, ready for `stack` or `dodge`). */
+    by: Channel<T, BandKey | PositionValue> | readonly [
+        Channel<T, BandKey | PositionValue>,
+        Channel<T, BandKey | PositionValue>
+    ];
+    /** The values to reduce. Defaults to the datum itself, for `number[]` data. */
+    y?: Channel<T, number>;
+    /** How each group's values become its `y`. @default "count" */
+    reduce?: Reducer;
+}
+/** @category Transforms */
+export interface GroupedRow<T> {
+    /** The group's (first) key. */
+    x: BandKey;
+    /** The group's second key, when grouped by two. */
+    z: BandKey | undefined;
+    /** The reduced value. */
+    y: number;
+    /** The input rows in the group, in input order. */
+    rows: T[];
+    /** Their indices in the input. */
+    indexes: number[];
+}
+/**
+ * Groups rows by one or two keys and reduces each group to one number:
+ * counts per category, sums per category and series, means, medians, ...
+ *
+ * @returns One {@link GroupedRow} per group, in first-seen order.
+ * @see https://sophistry.dev/guides/charts/#transforms
+ * @category Transforms
+ */
+export declare function group<T>(data: readonly T[], options: GroupOptions<T>): GroupedRow<T>[];
+/** @category Transforms */
+export interface BinOptions<T, X extends PositionValue = PositionValue> extends HistogramOptions {
+    /**
+     * The value binned along x; dates bin in equal spans of milliseconds. Defaults to the datum
+     * itself, for `number[]` data.
+     */
+    x?: Channel<T, X>;
+    /** The values `reduce` reads in each bin. Defaults to `x`'s. */
+    y?: Channel<T, number>;
+    /** How each bin's rows become its `y`. @default "count" */
+    reduce?: Reducer;
+}
+/** @category Transforms */
+export interface BinnedRow<T> {
+    /** The bin's lower edge. */
+    x1: number;
+    /** Its upper edge. */
+    x2: number;
+    /** Its centre. */
+    x: number;
+    /** The reduced value: the count, by default. */
+    y: number;
+    rows: T[];
+    indexes: number[];
+}
+/**
+ * Bins rows into equal-width buckets along x (`binCount`, or a `range`
+ * step) and reduces each bin: a histogram of counts, sums or means. Rows
+ * with a non-finite or out-of-range `x` fall in no bin.
+ *
+ * @returns One {@link BinnedRow} per bin, left to right, empty bins included.
+ * @see https://sophistry.dev/guides/charts/#transforms
+ * @category Transforms
+ */
+export declare function bin<T, X extends PositionValue = PositionValue>(data: readonly T[], options?: BinOptions<T, X>): BinnedRow<T>[];
+/** @category Transforms */
+export interface SummarizeOptions<T> {
+    /** The position rows are pooled at: rows sharing an `x` form one sample. */
+    x: Channel<T, BandKey | PositionValue>;
+    /** The value. Defaults to the datum itself, for `number[]` data. */
+    y?: Channel<T, number>;
+    /** `"ci"` (a t-based confidence interval of the mean), `"se"` or `"sd"`. @default "ci" */
+    interval?: "ci" | "se" | "sd";
+    /** Confidence level for `"ci"`, 0..1. @default 0.95 */
+    level?: number;
+}
+/** @category Transforms */
+export interface SummaryRow<T> {
+    x: BandKey;
+    /** The mean. */
+    y: number;
+    low: number;
+    high: number;
+    /** Finite values pooled. */
+    n: number;
+    rows: T[];
+}
+/**
+ * Pools replicate rows by `x` into a mean and an interval around it. Draw
+ * `y` with a `LinePlot` and the interval with `fillBetween` (`y1: "high", y2: "low"`) for a confidence band.
+ *
+ * @returns One {@link SummaryRow} per `x`: ascending when every `x` is a number, else first-seen.
+ * @see https://sophistry.dev/guides/charts/#transforms
+ * @category Transforms
+ */
+export declare function summarize<T>(data: readonly T[], options: SummarizeOptions<T>): SummaryRow<T>[];
+/** @category Transforms */
+export interface RollingTransformOptions<T> extends RollingOptions {
+    /** The series, in order. Defaults to the datum itself, for `number[]` data. */
+    y?: Channel<T, number>;
+}
+/**
+ * A moving-window reduction down the rows (a rolling mean by default), in
+ * the order given: one number per row, for a channel such as
+ * `y={(_, i) => smooth[i]}`.
+ *
+ * @category Transforms
+ */
+export declare function rolling<T>(data: readonly T[], options?: RollingTransformOptions<T>): number[];
+/** @category Transforms */
+export interface NormalizeOptions<T> {
+    /** The series. Defaults to the datum itself, for `number[]` data. */
+    y?: Channel<T, number>;
+    /** What to normalize against. See {@link NormalizeBasis}. @default "first" */
+    basis?: NormalizeBasis;
+}
+/**
+ * Normalizes a series against a basis (its first value, sum, extent, ...):
+ * one number per row.
+ *
+ * @category Transforms
+ */
+export declare function normalize<T>(data: readonly T[], options?: NormalizeOptions<T>): number[];
+/** @category Transforms */
+export interface JitterTransformOptions<T> {
+    /**
+     * What each row's offset hashes: something stable, such as an id. Defaults to the row's index.
+     */
+    key?: Channel<T, string | number>;
+    /** Total width the offsets spread over, centred on 0. @default 1 */
+    width?: number;
+    /** Varies the pattern. @default 0 */
+    seed?: number;
+}
+/**
+ * Seeded jitter: one offset per row in `[-width / 2, width / 2)`, hashed
+ * from the row's `key` and `seed`, so it is stable across frames and scrubs.
+ *
+ * @category Transforms
+ */
+export declare function jitter<T>(data: readonly T[], options?: JitterTransformOptions<T>): number[];

package/dist/bars/waterfall.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `waterfall`: how a starting value became a final one, change by change. A
+ * preset: a `chart` whose children are a `bars` layer (floating steps) and a
+ * `ruleY` layer (the dashed connectors), then the user's children.
+ */
+import type { AxisOptions, SceneNode } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { Point, Range } from "@sophistry/core/geometry";
+import type { Channel } from "../data/channels.js";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * Props of {@link waterfall}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface WaterfallProps<T = unknown> {
+    /** One step per datum, in order. */
+    data: readonly T[];
+    /**
+     * The change this step makes. Defaults to the datum when `data` is `number[]`; ignored on a
+     * total.
+     */
+    value?: Channel<T, number>;
+    /** The name under each bar. Omitted, no names are drawn. */
+    label?: Channel<T, string>;
+    /** Marks a subtotal/total bar, drawn from zero to the running total. */
+    total?: Channel<T, boolean>;
+    /** Width of the plotting area. */
+    width: number;
+    /** Height of the plotting area. */
+    height: number;
+    /** Centre of the plotting area. Defaults to the origin. */
+    center?: Point;
+    /** `[min, max, step?]` for the value axis. Omitted, fitted to the running total, including zero. */
+    yRange?: Range;
+    /** Styling and tick options for the value axis. */
+    yAxis?: AxisOptions;
+    /**
+     * Bar width as a fraction of its slot.
+     * @default 0.6
+     */
+    barWidth?: number;
+    /** Colour of an increase. Defaults to the theme's positive colour. */
+    upColor?: ColorInput;
+    /** Colour of a decrease. Defaults to the theme's negative colour. */
+    downColor?: ColorInput;
+    /** Colour of a total. Defaults to the theme's first series colour. */
+    totalColor?: ColorInput;
+    /**
+     * Write each step's change past the bar's end (`+20`, `−30`).
+     * @default true
+     */
+    labels?: boolean;
+    /**
+     * Draw the dashed connector from each bar's end to the next bar's start.
+     * @default true
+     */
+    connectors?: boolean;
+    /** Title above the chart. */
+    title?: string;
+    /**
+     * Reveal, 0..1: the frame, then the steps left to right (each growing from the running total),
+     * connectors after.
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the data reveal spent staggering step after step, 0..0.95.
+     * @default 0.6
+     */
+    stagger?: number;
+    /** Hover tooltip per step. Defaults to the step's name and change. */
+    tooltip?: TooltipSpec<T>;
+    zIndex?: number;
+    visible?: boolean;
+    /** Placed inside the chart's coordinate context (slot `i` is centred at `i + 0.5`). */
+    children?: readonly SceneNode[];
+}
+/**
+ * A waterfall chart: how a starting value became a final one, change by
+ * change. Each bar floats from the running total before it to the total
+ * after; `total` bars stand on zero. A preset over `chart`, {@link bars}
+ * and {@link ruleY}.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { waterfall } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * scene.add(
+ * 	waterfall.create({
+ * 		data: [{ name: "Start", v: 100 }, { name: "Sales", v: 40 }, { name: "Costs", v: -25 }, { name: "End", total: true }],
+ * 		value: "v",
+ * 		label: "name",
+ * 		total: "total",
+ * 		width: 8,
+ * 		height: 4,
+ * 	}),
+ * );
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#waterfalls-funnels-and-candlesticks
+ * @category Charts
+ */
+export declare const waterfall: import("@sophistry/core").Definition<WaterfallProps<any>, import("@sophistry/core/internal").CompositeNode<WaterfallProps<any>>, keyof WaterfallProps<any>>;

package/dist/batch.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The batched-mark helper every per-datum mark draws through: one
+ * `instances()` node for the whole layer, keyed by datum key.
+ *
+ * A per-datum mark is always one instances node:
+ *
+ * - **Items.** The mark computes one plain item per drawn key on each update
+ *   (its scene-unit position, size, colour and opacity at this frame of the
+ *   reveal or keyed `to`/`blend` transition) and hands them over with
+ *   {@link BatchedMark.update}. The node reconciles them by `key`.
+ * - **Seekable transitions** (`to` + `blend`, reveals, range transitions)
+ *   are computed by the mark, so every frame is exact and scrubs: the node
+ *   is updated instantly.
+ * - **Clock-driven transitions** (the mark's `transition` prop): when the
+ *   mark's data changes and no `to` is given, the node tweens (or springs)
+ *   kept items to their new values in its tween bank, entering items from
+ *   the mark's enter state and exiting ones to its exit state. Only data
+ *   changes animate this way; a reveal or a range change stays exact.
+ * - **Picking.** Handlers get `event.item` (the spec index) and `event.key`;
+ *   {@link BatchedMark.itemAt} turns either into the mark's item.
+ * - **Individuality.** `node.promote(key)` gives one item a real node.
+ *
+ * The first items a mark draws appear in place (its reveal brings them in);
+ * only later data changes move through the bank.
+ *
+ * Every enter/exit prop must also be a channel, so turning a transition on
+ * or off never rebuilds the node's bank.
+ */
+import type { Bindable, Definition, InstanceChannels, InstancesNode, InstanceTiming, InstanceValues, SceneNode } from "@sophistry/core";
+import type { BandKey } from "@sophistry/core/geometry";
+/**
+ * A per-datum mark's `transition` prop: how its marks move when its `data`
+ * changes (not during a `to`/`blend` transition, which is seekable). A
+ * tween (`duration`, `easing`) or a spring (`spring`), with `delay` and
+ * `stagger`. `enter` / `exit` say whether new marks grow in and departing
+ * ones shrink out (each mark decides how), with their own timing if given.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export interface MarkTransition extends InstanceTiming {
+    /**
+     * Entering marks grow in the way the mark reveals; `false` makes them
+     * appear at once. @default true
+     */
+    enter?: boolean | InstanceTiming;
+    /**
+     * Departing marks shrink out the way the mark reveals, reversed; `false`
+     * removes them at once. @default true
+     */
+    exit?: boolean | InstanceTiming;
+}
+/** An item of a batched mark: anything with the datum's key. */
+export interface BatchItem {
+    key: BandKey;
+}
+/**
+ * Options of {@link createBatchedMark}.
+ *
+ * @category Extending
+ */
+export interface BatchedMarkOptions<D, P, I extends keyof P> {
+    /** Per-item props read off the item; keep them stable (made once). */
+    channels: InstanceChannels<D, P, I>;
+    /** Where an entering item starts under a `transition` (its keys must be channels). */
+    enter?: InstanceValues<D, P, I>;
+    /** Where an exiting item ends under a `transition` (its keys must be channels). */
+    exit?: InstanceValues<D, P, I>;
+    /** Props every item shares from the start (any prop; a `Readable` binds). */
+    shared?: Bindable<P>;
+}
+/**
+ * A batched mark: its node, and the update it is driven by.
+ *
+ * @category Extending
+ */
+export interface BatchedMark<D extends BatchItem, P extends object, N extends SceneNode<P>, I extends keyof P> {
+    /** The instances node; put it in the mark's children. */
+    readonly node: InstancesNode<D, P, N, I, BandKey>;
+    /**
+     * Writes one update's items and shared props. With `transition` (and
+     * `animate` true) changed items move through the node's tween bank;
+     * otherwise the change is instant.
+     */
+    update(items: readonly D[], shared?: Bindable<P>, motion?: {
+        transition: MarkTransition | undefined;
+        animate: boolean;
+    }): void;
+    /** The item at a spec index (`event.item`), or undefined (an exiting item, or none). */
+    itemAt(index: number | null | undefined): D | undefined;
+    /** The current item with `key`, or undefined. */
+    item(key: BandKey): D | undefined;
+    /** The current items, in order. */
+    readonly items: readonly D[];
+}
+/**
+ * Makes the one instances node of a per-datum mark. Call once, in `setup`;
+ * call `update` in every `update` of the mark.
+ *
+ * @example
+ * ```ts
+ * import { type CompositeContext, circle, defineComposite, Invalidate } from "@sophistry/core";
+ * import { createBatchedMark } from "@sophistry/charts";
+ *
+ * interface DotsProps {
+ * 	points: readonly { x: number; y: number }[];
+ * }
+ * interface Dot {
+ * 	key: number;
+ * 	at: { x: number; y: number };
+ * }
+ *
+ * const createDots = () =>
+ * 	createBatchedMark(circle, {
+ * 		channels: { center: (item: Dot) => item.at },
+ * 		enter: { radius: 0 },
+ * 		exit: { radius: 0 },
+ * 	});
+ * const marks = new WeakMap<object, ReturnType<typeof createDots>>();
+ *
+ * function draw(ctx: CompositeContext<DotsProps>) {
+ * 	const dots = marks.get(ctx.node)!;
+ * 	const items = ctx.props.points.map((at, key) => ({ key, at }));
+ * 	dots.update(items, { radius: 0.1, strokeWidth: 0 }, { transition: { duration: 0.4 }, animate: true });
+ * 	return [dots.node];
+ * }
+ *
+ * export const dots = defineComposite<DotsProps>({
+ * 	name: "Dots",
+ * 	props: { points: { default: [], invalidates: Invalidate.UPDATE } },
+ * 	setup: (ctx) => {
+ * 		marks.set(ctx.node, createDots());
+ * 		return draw(ctx);
+ * 	},
+ * 	update: (_changed, ctx) => draw(ctx),
+ * });
+ * ```
+ *
+ * @param definition - The shape every item is (`circle`, `rect`, `line`, ...).
+ * @category Extending
+ */
+export declare function createBatchedMark<D extends BatchItem, P extends object, N extends SceneNode<P>, I extends keyof P>(definition: Definition<P, N, I>, options: BatchedMarkOptions<D, P, I>): BatchedMark<D, P, N, I>;

package/dist/channels-_Xf-p6Lx.js

@@ -0,0 +1,56 @@
+import { createContextKey as e } from "@sophistry/core";
+import { cssColor as t, temporalEpochMs as n } from "@sophistry/core/internal";
+//#region src/data/channels.ts
+var r = (e) => e, i = (e, t) => t;
+function a(e, t, r = "channel", i) {
+	let a;
+	if (e === void 0) a = t;
+	else if (typeof e == "function") a = e;
+	else {
+		let t = typeof e;
+		if (t !== "string" && t !== "symbol") throw TypeError(`\`${r}\` must be a key of the datum or a function (d, i) => value, got ${e === null ? "null" : t}.`);
+		let n = e;
+		a = (e) => e[n];
+	}
+	if (!a) return;
+	let s = a, c = o.get(r), l = c ? i ?? void 0 : void 0;
+	return (e, t) => {
+		let r = s(e, t);
+		if (typeof r != "object" || !r) return r;
+		let i = r instanceof Date ? r.getTime() : n(r, c && l ? l.timeZone(c) : "UTC");
+		return i === void 0 ? r : (c && l?.note(c), i);
+	};
+}
+var o = /* @__PURE__ */ new Map([
+	["x", "x"],
+	["x1", "x"],
+	["x2", "x"],
+	["y", "y"],
+	["y1", "y"],
+	["y2", "y"]
+]), s = e("chartDates", null);
+function c(e, t) {
+	return typeof e == "number" ? () => e : a(e, t);
+}
+function l(e, t, n, r, i) {
+	let o = a(t, n, r, i);
+	return e.map((e, t) => o ? o(e, t) : void 0);
+}
+function u(e, t, n, r, i) {
+	return l(e, t, n, r, i).map((e) => typeof e == "number" ? e : NaN);
+}
+function d(e) {
+	if (typeof e == "function") return (n, r) => {
+		let i = e(n, r);
+		return i == null ? i : t(i);
+	};
+	if (!e) return;
+	let n = t(e);
+	return () => n;
+}
+function f(e, n, r) {
+	let i = d(e);
+	return (e, a) => i?.(e, a) ?? t(n.length === 0 ? r : n[a % n.length]);
+}
+//#endregion
+export { i as a, d as c, r as i, c as l, f as n, u as o, s as r, a as s, l as t };

package/dist/chart.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The chart frame: an `axes` that fits itself to the data drawn inside it.
+ *
+ * Layers (`bars`, `scatter`, ...) report their data extent through
+ * {@link chartLayer}; the frame fits every axis to the union, lays categories
+ * out on band axes, and shares one colour scale and legend across all
+ * layers. `progress` draws the frame first, then the data, then the legend.
+ *
+ * How it runs (one commit, no microtask): `setup` provides the stable
+ * contexts (where reports go, the tooltip, the date sink, the secondary
+ * axes' lift) and places the layers. Each layer's first update reports its
+ * extent, which asks the chart to update again (`ctx.invalidate`) in the
+ * same commit; the chart fits its axes, publishes a new {@link ChartFrame}
+ * and coordinate system, and the layers that read them update once more. A
+ * report equal by value to the last one changes nothing, so the loop
+ * settles. Every step of the fit (`frame/*`) keeps its last result while
+ * its inputs are unchanged, so a frame of a keyed transition redoes only
+ * what the blend moves, and a `ChartFrame` keeps its identity while nothing
+ * in it changed.
+ */
+import type { ContextKey, SceneNode } from "@sophistry/core";
+import type { SecondaryFlags } from "./frame/secondary.js";
+import type { ChartFrame, ChartHandle, ChartLayerExtent, ChartProps } from "./frame/types.js";
+export type * from "./frame/types.js";
+/**
+ * How `secondaryX` and `secondaryY` find their chart's secondary contexts.
+ *
+ * @internal
+ */
+export interface SecondaryLift {
+    /** The frame (and its coordinates) of `parent` with `axis` mapped through its secondary scale. */
+    lift(parent: ChartFrame, axis: "x" | "y"): ChartFrame;
+    /** Which secondary axes a frame of this chart maps through. */
+    flagsOf(frame: ChartFrame): SecondaryFlags;
+}
+/**
+ * The enclosing chart's secondary lift, or null outside a chart.
+ *
+ * @internal
+ */
+export declare const secondaryLiftContext: ContextKey<SecondaryLift | null>;
+/**
+ * A plotting frame that fits its axes to the layers inside it: an `axes`
+ * with ranges worked out for you, categorical axes, grid, title, legend and
+ * colour bar. Anything given explicitly (`xRange`, `yRange`,
+ * `xAxis.categories`) wins over fitting. Children see the coordinate system
+ * as in `axes`, so core's graphs plot in data space inside it.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { chart, okabeIto, scatter } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * const temps = [
+ * 	{ month: 1, city: "Oslo", c: -4 },
+ * 	{ month: 7, city: "Oslo", c: 17 },
+ * 	{ month: 1, city: "Rome", c: 8 },
+ * 	{ month: 7, city: "Rome", c: 25 },
+ * ];
+ * scene.add(
+ * 	chart.create({
+ * 		width: 8,
+ * 		height: 4,
+ * 		color: { range: okabeIto },
+ * 		legendTitle: "City",
+ * 		children: [scatter.create({ data: temps, x: "month", y: "c", series: "city" })],
+ * 	}),
+ * );
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#the-chart-frame
+ * @category Charts
+ */
+export declare const chart: import("@sophistry/core").Definition<ChartProps, import("@sophistry/core/internal").CompositeNode<ChartProps>, keyof ChartProps>;
+/**
+ * A chart node's handle: its coordinate system,
+ * band scales and colours, as of its last update. Brings the node up to date
+ * first, so it works right after `create`.
+ *
+ * @param node - A node made by {@link chart}.
+ * @returns The handle, or null for a node that is not a chart.
+ * @category Charts
+ */
+export declare function chartHandle(node: SceneNode): ChartHandle | null;
+/** For tests: the chart reports in `node`'s registry. @internal */
+export declare function chartReports(node: SceneNode): readonly ChartLayerExtent[];