@weasel-js/plot 0.0.0-stage → 1.15.0

package/dist/index.d.ts

@@ -0,0 +1,679 @@
+import { Path } from '@weasel-js/geom';
+import { ResolvedTheme } from '@weasel-js/theme';
+import { AddNodeSpec, RectPose, Scene, NodeId, RenderLayer, InvocationCtx, Action, Contribution, Paint } from '@weasel-js/core';
+import { ReactElement } from 'react';
+
+/** What every positional scale answers, and what an axis is drawn from: where a value sits along its range, the
+ *  values an axis marks, and how one reads. */
+interface Scale<T> {
+    readonly kind: 'linear' | 'log' | 'band' | 'time';
+    /** Where the scale's output runs, in drawing units: start to end, either way round. */
+    readonly range: readonly [number, number];
+    /** Where `value` sits along the range. A band scale answers its band's center. */
+    position(value: T): number;
+    /** The values an axis marks, about `count` of them where the scale chooses. */
+    ticks(count?: number): T[];
+    /** `value` as an axis label reads it. */
+    format(value: T): string;
+}
+/** A scale over numbers that maps both ways. */
+interface ContinuousScale extends Scale<number> {
+    readonly kind: 'linear' | 'log' | 'time';
+    readonly domain: readonly [number, number];
+    /** `value` along the range; the same as {@link Scale.position}. */
+    map(value: number): number;
+    /** The value at `at` along the range. */
+    invert(at: number): number;
+}
+
+/** Options for {@link linearScale}. */
+interface LinearScaleOptions {
+    domain: readonly [number, number];
+    range: readonly [number, number];
+    /** Widen the domain out to whole tick steps for about this many ticks. Default no widening. */
+    nice?: number;
+}
+/** A scale that maps numbers proportionally, as a value axis does. */
+interface LinearScale extends ContinuousScale {
+    readonly kind: 'linear';
+    /** The distance between ticks when about `count` are asked for. */
+    tickStep(count?: number): number;
+}
+/** The round step, 1, 2 or 5 times a power of ten, that cuts `lo`..`hi` into about `count` pieces. */
+declare function tickStep(lo: number, hi: number, count?: number): number;
+/** Every multiple of `step` from `lo` to `hi`, inclusive. */
+declare function stepTicks(lo: number, hi: number, step: number): number[];
+/** `value` written as plainly as a grid of `step` allows: no trailing zeros, no exponent. */
+declare function formatNumber(value: number, step: number): string;
+/** `domain` widened to whole steps of a tick grid of about `count` ticks. */
+declare function niceDomain(domain: readonly [number, number], count?: number): [number, number];
+/** A linear scale from `domain` onto `range`. */
+declare function linearScale(opts: LinearScaleOptions): LinearScale;
+
+/** Options for {@link logScale}. */
+interface LogScaleOptions {
+    /** Both ends above zero. */
+    domain: readonly [number, number];
+    range: readonly [number, number];
+    /** Default 10. */
+    base?: number;
+}
+/** A scale that maps the logarithm of a value proportionally. */
+interface LogScale extends ContinuousScale {
+    readonly kind: 'log';
+    readonly base: number;
+}
+/** A logarithmic scale from `domain`, whose ends must both be above zero, onto `range`. */
+declare function logScale(opts: LogScaleOptions): LogScale;
+
+/** Options for {@link bandScale}. */
+interface BandScaleOptions {
+    /** The categories, one band each, in order. */
+    domain: readonly string[];
+    range: readonly [number, number];
+    /** The share of each step left empty between bands, 0 to 1. Default 0.2. */
+    paddingInner?: number;
+    /** The room before the first band and after the last, in steps. Default half of `paddingInner`. */
+    paddingOuter?: number;
+}
+/** A scale that cuts its range into equal bands, one per category, as a bar chart's category axis does. */
+interface BandScale extends Scale<string> {
+    readonly kind: 'band';
+    readonly domain: readonly string[];
+    /** The width of each band. */
+    readonly bandwidth: number;
+    /** From one band's start to the next's. */
+    readonly step: number;
+    /** Where `key`'s band starts, or `NaN` for a key not in the domain. */
+    start(key: string): number;
+    /** The key whose band is nearest `at`; `undefined` for an empty domain. */
+    invert(at: number): string | undefined;
+}
+/** A band scale over `domain`. */
+declare function bandScale(opts: BandScaleOptions): BandScale;
+
+/** Options for {@link timeScale}. */
+interface TimeScaleOptions {
+    /** Milliseconds since the epoch, as `Date.getTime` gives them. */
+    domain: readonly [number, number];
+    range: readonly [number, number];
+}
+/** A scale over instants, whose ticks fall on whole seconds, minutes, hours, days, months or years, in UTC. */
+interface TimeScale extends ContinuousScale {
+    readonly kind: 'time';
+}
+type Unit = 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year';
+/** `t` written to the precision of `unit`. */
+declare function formatInstant(t: number, unit: Unit): string;
+/** A time scale from `domain`, in milliseconds since the epoch, onto `range`. */
+declare function timeScale(opts: TimeScaleOptions): TimeScale;
+
+/** Options for {@link ordinalScale}. */
+interface OrdinalScaleOptions<T> {
+    /** The keys, in order. */
+    domain: readonly string[];
+    /** What each key maps to, in domain order, wrapping when there are fewer than keys. */
+    range: readonly T[];
+}
+/** A scale from keys to values in turn, as a series' colors are chosen. */
+interface OrdinalScale<T> {
+    readonly kind: 'ordinal';
+    readonly domain: readonly string[];
+    readonly range: readonly T[];
+    /** `key`'s value; a key not in the domain takes the next value after the last, and joins the domain. */
+    map(key: string): T;
+    /** The keys a legend lists. */
+    ticks(): string[];
+    format(key: string): string;
+}
+/** An ordinal scale from `domain` to `range`. Throws on an empty range. */
+declare function ordinalScale<T>(opts: OrdinalScaleOptions<T>): OrdinalScale<T>;
+
+/** The kinds of mark a chart is drawn with. */
+type MarkKind = 'bar' | 'span' | 'line' | 'area' | 'point' | 'arc' | 'ribbon' | 'rule' | 'text';
+/** The value a mark stands for, as plain fields: a series and index, a category, a value. */
+type PlotDatum = Readonly<Record<string, string | number | boolean>>;
+/** What a mark's scene data says about it: its kind, and the datum it draws. */
+interface PlotMarkTrait {
+    kind: MarkKind;
+    datum?: PlotDatum;
+}
+/** A solid paint, as the kit's painters read one. */
+interface SolidFill {
+    paint: {
+        color: string;
+        opacity?: number;
+    };
+}
+/** A solid stroke, as the kit's painters read one. */
+interface SolidStroke {
+    paint: {
+        color: string;
+    };
+    width: number;
+    dash?: number[];
+    cap?: 'butt' | 'round' | 'square';
+    join?: 'miter' | 'round' | 'bevel';
+}
+/**
+ * A mark's scene data: the trait under `plotMark`, and the fields the kit's
+ * painters draw it from — `path` for a shape, a line or a region, `text` for
+ * a label.
+ */
+interface PlotMarkData {
+    plotMark: PlotMarkTrait;
+    path?: Path;
+    fill?: SolidFill;
+    stroke?: SolidStroke;
+    text?: string;
+    style?: {
+        fontFamily: string;
+        fontSize: number;
+        align?: 'left' | 'center' | 'right';
+        fontWeight?: number;
+    };
+    verticalAlign?: 'top' | 'center' | 'bottom';
+}
+/** A box, in the plot's own coordinates: from its root's corner. */
+interface PlotBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Radians about the box's center. */
+    rotation?: number;
+}
+/** One mark, ready to be a scene node: a key unique within its plot, where it is drawn, and its data. */
+interface PlotMark {
+    key: string;
+    pose: PlotBox;
+    data: PlotMarkData;
+}
+/** A point in the plot's coordinates. */
+interface PlotPoint {
+    x: number;
+    y: number;
+}
+
+/** Options for {@link barMark}. */
+interface BarMarkOptions {
+    key: string;
+    /** Where the bar stands along the category axis: its left edge, or its top for a horizontal bar. */
+    x: number;
+    /** The bar's breadth across the category axis. */
+    width: number;
+    /** The baseline the bar rises from, and the end it reaches, along the value axis. */
+    from: number;
+    to: number;
+    color: string;
+    datum?: PlotDatum;
+    /** Default `'vertical'`: `x` and `width` run along x. */
+    orient?: 'vertical' | 'horizontal';
+}
+/** A bar from `from` to `to`, either way round. */
+declare function barMark(opts: BarMarkOptions): PlotMark;
+/** Options for {@link spanMark}. */
+interface SpanMarkOptions {
+    key: string;
+    /** Start and end along x. */
+    x0: number;
+    x1: number;
+    /** Its row: top and height. */
+    y: number;
+    height: number;
+    color: string;
+    opacity?: number;
+    datum?: PlotDatum;
+}
+/** A span across x, as a task's bar on a timeline is. */
+declare function spanMark(opts: SpanMarkOptions): PlotMark;
+/** Options for {@link pointMark}. */
+interface PointMarkOptions {
+    key: string;
+    x: number;
+    y: number;
+    /** Default 3. */
+    radius?: number;
+    color: string;
+    datum?: PlotDatum;
+}
+/** A dot centered on `x`, `y`. */
+declare function pointMark(opts: PointMarkOptions): PlotMark;
+
+/** Options for {@link lineMark}. */
+interface LineMarkOptions {
+    key: string;
+    /** At least one. */
+    points: readonly PlotPoint[];
+    color: string;
+    /** Default 2. */
+    width?: number;
+    dash?: number[];
+    datum?: PlotDatum;
+}
+/** A line through `points`, in order. */
+declare function lineMark(opts: LineMarkOptions): PlotMark;
+/** Options for {@link ruleMark}. */
+interface RuleMarkOptions {
+    key: string;
+    from: PlotPoint;
+    to: PlotPoint;
+    color: string;
+    /** Default 1. */
+    width?: number;
+    dash?: number[];
+    datum?: PlotDatum;
+}
+/** A straight rule from `from` to `to`: an axis line, a tick, a grid line, a marker. */
+declare function ruleMark(opts: RuleMarkOptions): PlotMark;
+/** Options for {@link areaMark}. */
+interface AreaMarkOptions {
+    key: string;
+    /** The upper edge, in order. */
+    top: readonly PlotPoint[];
+    /** The lower edge, in the same order as `top`. Default a baseline at `baseline` under each top point. */
+    bottom?: readonly PlotPoint[];
+    baseline?: number;
+    color: string;
+    /** Default 0.35. */
+    opacity?: number;
+    datum?: PlotDatum;
+}
+/** The region between two edges, as an area chart or a radar's polygon fills it. */
+declare function areaMark(opts: AreaMarkOptions): PlotMark;
+/** Options for {@link arcMark}. */
+interface ArcMarkOptions {
+    key: string;
+    center: PlotPoint;
+    /** 0 for a pie slice. */
+    innerRadius: number;
+    outerRadius: number;
+    /** Radians clockwise from twelve o'clock. */
+    startAngle: number;
+    endAngle: number;
+    color: string;
+    datum?: PlotDatum;
+}
+/** A slice of a ring, as a pie or a donut is cut. */
+declare function arcMark(opts: ArcMarkOptions): PlotMark;
+/** Options for {@link ribbonMark}. */
+interface RibbonMarkOptions {
+    key: string;
+    /** The end it leaves: an x, and the span along y it leaves across. */
+    from: {
+        x: number;
+        y0: number;
+        y1: number;
+    };
+    to: {
+        x: number;
+        y0: number;
+        y1: number;
+    };
+    color: string;
+    /** Default 0.45. */
+    opacity?: number;
+    datum?: PlotDatum;
+}
+/** A band curving from one span to another, as a flow between two nodes is drawn. */
+declare function ribbonMark(opts: RibbonMarkOptions): PlotMark;
+
+/** The face a chart's text is set in. */
+interface PlotFont {
+    fontFamily: string;
+    fontSize: number;
+}
+/** The colors a chart is drawn in, by role, and its face. Plain strings, so a scene can keep it. */
+interface PlotTheme {
+    /** Titles, labels and values. */
+    text: string;
+    /** Axis rules and ticks. */
+    axis: string;
+    /** Grid lines behind the marks. */
+    grid: string;
+    /** The colors series take in turn. Never empty. */
+    series: readonly string[];
+    font: PlotFont;
+}
+/** A plot theme from a resolved weasel theme: text in `fg`, axes in `border-strong`, grid in `border`, series in
+ *  its swatches. */
+declare function plotThemeFrom(resolved: Readonly<Record<string, string>> | ResolvedTheme, font?: PlotFont): PlotTheme;
+/** 12px sans-serif. */
+declare const PLOT_FONT: PlotFont;
+/** The weasel theme in its dark mode. */
+declare const PLOT_THEME: PlotTheme;
+/** The `i`th series' color, wrapping. */
+declare const seriesColor: (theme: PlotTheme, i: number) => string;
+
+/** How wide and tall one line of text is set in `font`. */
+type PlotMeasure = (text: string, font: PlotFont) => {
+    width: number;
+    height: number;
+};
+/** Measures as the kit's text renderer lays text out, from the registered face's metrics; a line is 1.2 sizes tall. */
+declare const textMeasure: PlotMeasure;
+
+/** Marks drawn as text: titles, tick labels, values. */
+
+/** Options for {@link textMark}. */
+interface TextMarkOptions {
+    key: string;
+    text: string;
+    /** The anchor point. */
+    x: number;
+    y: number;
+    /** Which part of the text stands on `x`. Default `'middle'`. */
+    anchor?: 'start' | 'middle' | 'end';
+    /** Which part of the text stands on `y`. Default `'middle'`. */
+    baseline?: 'top' | 'middle' | 'bottom';
+    font: PlotFont;
+    color: string;
+    measure: PlotMeasure;
+    /** Turns the text a quarter turn counterclockwise about the anchor, as a vertical axis's title reads. */
+    vertical?: boolean;
+    bold?: boolean;
+    datum?: PlotDatum;
+}
+/** One line of text, its box measured with `measure` and placed by its anchor. */
+declare function textMark(opts: TextMarkOptions): PlotMark;
+
+/** Which side of the plot an axis runs along. Its scale's range runs along x for top and bottom, along y otherwise. */
+type AxisSide = 'top' | 'bottom' | 'left' | 'right';
+/** Options for {@link axisMarks} and {@link axisRoom}. */
+interface AxisOptions<T> {
+    scale: Scale<T>;
+    side: AxisSide;
+    /** Where the axis line stands across its scale: a y for top and bottom, an x for left and right. */
+    at: number;
+    /** Draw a grid line at each tick, from the axis across to here. */
+    gridTo?: number;
+    title?: string;
+    /** How many ticks to ask the scale for. */
+    ticks?: number;
+    /** Prefixes every mark's key. Default `axis:<side>`. */
+    key?: string;
+    theme: PlotTheme;
+    measure: PlotMeasure;
+}
+/** How far an axis reaches out from its line: ticks, labels and title. */
+declare function axisRoom<T>(opts: AxisOptions<T>): number;
+/** Every mark one axis is drawn with. Keys: `<key>:rule`, `<key>:tick:<i>`, `<key>:label:<i>`, `<key>:grid:<i>`, `<key>:title`. */
+declare function axisMarks<T>(opts: AxisOptions<T>): PlotMark[];
+
+/** A category axis: one band per label, in order; with none, bands numbered from 1. */
+interface XyBandAxis {
+    kind: 'band';
+    title?: string;
+    categories: readonly string[];
+}
+/** A numeric axis from `min` to `max`, the series' values spread evenly across it. */
+interface XyRangeAxis {
+    kind: 'range';
+    title?: string;
+    min: number;
+    max: number;
+}
+/** The value axis. A missing end fits the series' values, zero included. */
+interface XyValueAxis {
+    title?: string;
+    min?: number;
+    max?: number;
+}
+/** One series: a value per category, drawn as bars or as a line. */
+interface XySeries {
+    kind: 'bar' | 'line';
+    name?: string;
+    values: readonly number[];
+}
+/** A bar and line chart over categories or a numeric range. */
+interface XyChartData {
+    kind: 'xychart';
+    title?: string;
+    /** Default `'vertical'`: categories along x, values up y. */
+    orientation?: 'vertical' | 'horizontal';
+    /** Absent, bands numbered from 1, one per value of the longest series. */
+    x?: XyBandAxis | XyRangeAxis;
+    y?: XyValueAxis;
+    series: readonly XySeries[];
+}
+
+/** Chart specs, and the one table that compiles each kind to marks. */
+
+/** A chart, as data: one spec per kind, told apart by `kind`. */
+type PlotData = XyChartData;
+/** The kinds of chart {@link PlotData} holds. */
+type PlotKind = PlotData['kind'];
+/** What a kind's compiler is given and gives back: its spec laid out in a box of `size`, as marks. */
+type PlotCompiler<D extends PlotData> = (data: D, size: {
+    width: number;
+    height: number;
+}, theme: PlotTheme, measure: PlotMeasure) => {
+    marks: PlotMark[];
+};
+/** `data` laid out in a box of `size`, as the marks it is drawn with, in drawing order. */
+declare function compilePlot(data: PlotData, size: {
+    width: number;
+    height: number;
+}, theme: PlotTheme, measure: PlotMeasure): PlotMark[];
+
+/** Where an xychart's parts landed: the plot area, the value scale, and each value index's place across it. */
+interface XyLayout {
+    orientation: 'vertical' | 'horizontal';
+    /** The area the marks are drawn in, inside the axes. */
+    plot: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Values along y for a vertical chart, along x for a horizontal one. */
+    value: LinearScale;
+    /** Each value index's center along the category axis. */
+    slots: readonly number[];
+    /** How much of the category axis each index's bars share. */
+    slotWidth: number;
+}
+/** How many values the longest series holds. */
+declare const xyLength: (data: XyChartData) => number;
+/** The value axis's domain: its own ends, and where one is missing, the values' reach with zero in it, made round. */
+declare function xyValueDomain(data: XyChartData): [number, number];
+/** Lays out an xychart in a box of `size`: its title, axes, bars, lines and points. */
+declare function compileXyChart(data: XyChartData, size: {
+    width: number;
+    height: number;
+}, theme: PlotTheme, measure: PlotMeasure): {
+    marks: PlotMark[];
+    layout: XyLayout;
+};
+
+/** `data` with series `series`'s value at `index` set to `value`. Throws on an index the series does not hold. */
+declare function setXyValue(data: XyChartData, series: number, index: number, value: number): XyChartData;
+/** The value a point stands at along `layout`'s value axis, rounded to a tenth of its tick step. */
+declare function xyValueAt(layout: XyLayout, at: {
+    x: number;
+    y: number;
+}): number;
+
+/**
+ * A plot in a scene: one root node holding the spec, its marks derived
+ * children rebuilt from it. An edit replaces the spec and rebuilds the marks
+ * as one undo entry.
+ */
+
+/** What a plot's root node keeps: the spec, and the theme its marks were drawn in. */
+interface PlotRootTrait {
+    data: PlotData;
+    theme: PlotTheme;
+}
+/** A plot root's scene data. */
+interface PlotRootData {
+    plot: PlotRootTrait;
+}
+/** The data of any node a plot puts in a scene. */
+type PlotSceneData = PlotRootData | PlotMarkData;
+/** A scene node spec, as {@link plotSpecs} returns them. */
+type PlotSpec<TLayer extends string = 'main'> = AddNodeSpec<PlotSceneData, TLayer, RectPose>;
+/** Options for {@link plotSpecs}. */
+interface PlotSpecsOptions<TLayer extends string = 'main'> {
+    /** The root's id. Default `'plot'`. */
+    id?: string;
+    /** The box the plot fills. */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Default `'main'`. */
+    layer?: TLayer;
+    /** Default {@link PLOT_THEME}. */
+    theme?: PlotTheme;
+    /** Default {@link textMeasure}. */
+    measure?: PlotMeasure;
+}
+/** The trait a plot root's data carries, or `null` for any other node. */
+declare function plotRootOf(node: {
+    data: unknown;
+} | undefined): PlotRootTrait | null;
+/** The trait a plot mark's data carries, or `null` for any other node. */
+declare function plotMarkOf(node: {
+    data: unknown;
+} | undefined): PlotMarkTrait | null;
+/** The id of the mark keyed `key` under the root `rootId`. */
+declare const plotMarkId: (rootId: string, key: string) => string;
+/** `marks` as children of the root `rootId`, in its frame. */
+declare function markSpecs<TLayer extends string>(rootId: string, layer: TLayer, marks: readonly PlotMark[]): PlotSpec<TLayer>[];
+/** The nodes a plot of `data` is: its root, a group filling `box`, then each mark under it, in drawing order. */
+declare function plotSpecs<TLayer extends string = 'main'>(data: PlotData, opts: PlotSpecsOptions<TLayer>): PlotSpec<TLayer>[];
+/** Options for {@link replacePlotData}. */
+interface ReplacePlotOptions {
+    /** The undo entry's label. Default `'Edit chart'`. */
+    label?: string;
+    /** Draw in this theme from now on. Default the one the root keeps. */
+    theme?: PlotTheme;
+    /** Default {@link textMeasure}. */
+    measure?: PlotMeasure;
+}
+/** Replaces the spec of the plot rooted at `rootId` with `data` and rebuilds its marks, as one undo entry. */
+declare function replacePlotData<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>, rootId: string, data: PlotData, opts?: ReplacePlotOptions): void;
+/** Every plot root in `scene`, in render order. */
+declare function plotRootsIn(scene: Scene<unknown, string, unknown>): NodeId[];
+
+/** What each chart kind lets a drag edit: which marks carry a handle, and the spec a drag of one proposes. */
+
+/** A handle a press can take: where it stands in the plot's coordinates, and the cursor over it. */
+interface PlotHandle {
+    at: PlotPoint;
+    cursor: 'ns-resize' | 'ew-resize' | 'move';
+}
+/** One chart kind's edits. */
+interface PlotEditor<D extends PlotData> {
+    /** The handle on a mark, or `null` for a mark a drag does not edit. */
+    handle(data: D, mark: {
+        trait: PlotMarkTrait;
+        pose: PlotBox;
+    }): PlotHandle | null;
+    /** A drag that took the handle on `mark`: the spec it proposes with the pointer at a point in the plot's coordinates.
+     *  `null` when the mark has nothing to edit. */
+    drag(data: D, mark: PlotMarkTrait, size: {
+        width: number;
+        height: number;
+    }, theme: PlotTheme, measure: PlotMeasure): ((at: PlotPoint) => D) | null;
+}
+/** The edits `data`'s kind allows, or `null` for a kind with none. */
+declare const plotEditorOf: (data: PlotData) => PlotEditor<PlotData> | null;
+
+/**
+ * What makes a plot's editable marks grabbable: a hit-only point region at
+ * each handle its kind's editor names, composed into a layer whose id is the
+ * kind a press reports.
+ */
+
+/** The layer id the handles are composed into. */
+declare const PLOT_HANDLE_LAYER_ID = "plot-handles";
+/** The affordance kind a press on a handle reports. */
+declare const PLOT_HANDLE_AFFORDANCE_KIND: "layer:plot-handles";
+/** What a press on a handle hands the drag, as the hit's `payload`. */
+interface PlotHandleScratch {
+    rootId: string;
+    markId: string;
+    /** The handle, in world coordinates. */
+    at: PlotPoint;
+}
+/** A press's scratch, read back off the hit an action was handed. */
+declare function plotHandleScratchOf(hit: {
+    payload?: unknown;
+} | null | undefined): PlotHandleScratch | null;
+type AnyScene = Scene<unknown, string, unknown>;
+/** Where the plot root `rootId`'s corner stands in world coordinates. */
+declare function plotOrigin(scene: AnyScene, rootId: string): PlotPoint;
+/** Every handle in `scene` an edit may take, in world coordinates, in render order. */
+declare function plotHandles(scene: AnyScene): Iterable<PlotHandleScratch & PlotHandle>;
+/** The handle layer, for `CanvasExtensionApi.registerLayer`. */
+declare function plotHandleLayer(scene: Scene<unknown, string, unknown>): RenderLayer<unknown>;
+
+/**
+ * Dragging a plot's handle to edit the value behind it. The handle layer
+ * claims the press; this action previews every mark the proposed spec
+ * redraws, and commits the spec as one edit of the plot's root.
+ */
+
+/** The action that drags a plot's handle. */
+declare const PLOT_DRAG_ACTION_ID = "plot.dragValue";
+/** A plot edited: the root, and the spec it now holds. */
+interface PlotEdit {
+    rootId: string;
+    data: PlotData;
+}
+/** Options for {@link createPlotDragAction}. */
+interface PlotDragOptions {
+    id?: string;
+    /** Default {@link textMeasure}. */
+    measure?: PlotMeasure;
+    /** Defaults to {@link replacePlotData} against `deps.scene`, labeled "Edit value". */
+    commit?: (edit: PlotEdit, ctx: InvocationCtx) => void;
+}
+/** The default commit: the spec into the root, its marks rebuilt, as one history entry, "Edit value". */
+declare function commitPlotToScene(edit: PlotEdit, ctx: InvocationCtx, measure?: PlotMeasure): void;
+/** The `plot.dragValue` action: an ongoing drag that moves one value of a plot, previewing the marks it redraws. */
+declare function createPlotDragAction(opts?: PlotDragOptions): Action;
+
+/** The action id that absorbs a press on a handle, so it reaches neither marquee nor pan. */
+declare const GRAB_PLOT_HANDLE_ACTION_ID = "plot.grabHandle";
+/**
+ * Both halves of editing a scene's plots by dragging: the handle layer to
+ * `registerLayer`, and the contribution to pass as `ambient`, which binds a
+ * drag on a handle to `plot.dragValue`. One without the other fails quietly:
+ * the layer alone claims presses that start nothing, the contribution alone
+ * binds a kind nothing reports.
+ */
+declare function plotEditing(opts: PlotDragOptions & {
+    scene: Scene<unknown, string, unknown>;
+}): {
+    layer: RenderLayer<unknown>;
+    contribution: Contribution;
+};
+
+/** Props for {@link PlotView}. */
+interface PlotViewProps {
+    /** The chart. A new value redraws it, with no undo entry. */
+    data: PlotData;
+    /** Hears each edit a drag commits, with the spec it leaves. Undo and redo in the view report too. */
+    onChange?: (data: PlotData) => void;
+    width: number;
+    height: number;
+    /** Default the weasel theme's dark mode. */
+    theme?: PlotTheme;
+    measure?: PlotMeasure;
+    background?: Paint;
+    className?: string;
+    'aria-label'?: string;
+}
+/**
+ * A chart on its own canvas, edited by dragging its marks: a bar's end or a
+ * line's point moves its value. Each drag is one undo entry. Text paints only
+ * in a registered font family, so register the theme's (`registerCanvasFont`).
+ */
+declare function PlotView(props: PlotViewProps): ReactElement;
+
+export { type ArcMarkOptions, type AreaMarkOptions, type AxisOptions, type AxisSide, type BandScale, type BandScaleOptions, type BarMarkOptions, type ContinuousScale, GRAB_PLOT_HANDLE_ACTION_ID, type LineMarkOptions, type LinearScale, type LinearScaleOptions, type LogScale, type LogScaleOptions, type MarkKind, type OrdinalScale, type OrdinalScaleOptions, PLOT_DRAG_ACTION_ID, PLOT_FONT, PLOT_HANDLE_AFFORDANCE_KIND, PLOT_HANDLE_LAYER_ID, PLOT_THEME, type PlotBox, type PlotCompiler, type PlotData, type PlotDatum, type PlotDragOptions, type PlotEdit, type PlotEditor, type PlotFont, type PlotHandle, type PlotHandleScratch, type PlotKind, type PlotMark, type PlotMarkData, type PlotMarkTrait, type PlotMeasure, type PlotPoint, type PlotRootData, type PlotRootTrait, type PlotSceneData, type PlotSpec, type PlotSpecsOptions, type PlotTheme, PlotView, type PlotViewProps, type PointMarkOptions, type ReplacePlotOptions, type RibbonMarkOptions, type RuleMarkOptions, type Scale, type SolidFill, type SolidStroke, type SpanMarkOptions, type TextMarkOptions, type TimeScale, type TimeScaleOptions, type XyBandAxis, type XyChartData, type XyLayout, type XyRangeAxis, type XySeries, type XyValueAxis, arcMark, areaMark, axisMarks, axisRoom, bandScale, barMark, commitPlotToScene, compilePlot, compileXyChart, createPlotDragAction, formatInstant, formatNumber, lineMark, linearScale, logScale, markSpecs, niceDomain, ordinalScale, plotEditing, plotEditorOf, plotHandleLayer, plotHandleScratchOf, plotHandles, plotMarkId, plotMarkOf, plotOrigin, plotRootOf, plotRootsIn, plotSpecs, plotThemeFrom, pointMark, replacePlotData, ribbonMark, ruleMark, seriesColor, setXyValue, spanMark, stepTicks, textMark, textMeasure, tickStep, timeScale, xyLength, xyValueAt, xyValueDomain };