@pixerate/editor 0.45.0 → 0.46.0

package/dist/chart/index.d.cts

@@ -0,0 +1,646 @@
+import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
+import { C as CommandSpec } from '../registry-vz6HOiiy.cjs';
+import '../types-DsiXGmjo.cjs';
+import '../schema-Di0CS6Pe.cjs';
+
+/** Chart kinds. `bar`, `line`, `area` and `scatter` are cartesian; series may mix them (a combo chart). */
+type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'pie' | 'donut';
+/** How a series is drawn in a cartesian chart. */
+type ChartSeriesType = 'bar' | 'line' | 'area' | 'scatter';
+/** One data value; `null` is a gap (missing value). */
+type ChartValue = number | null;
+interface ChartSeries {
+    /** Stable id (unique within the chart). */
+    id: string;
+    name: string;
+    /** One value per category. */
+    values: ChartValue[];
+    /** CSS colour (default: the palette colour for the series' position). */
+    color?: string;
+    /** Overrides the chart type for this series (cartesian charts only). */
+    type?: ChartSeriesType;
+    /** Hidden series keep their data but are not drawn or scaled. */
+    hidden?: boolean;
+}
+interface ChartNumberFormat {
+    /** `number` (default), `percent` (0.25 → 25%), `currency` or `compact` (1.2K). */
+    style?: 'number' | 'percent' | 'currency' | 'compact';
+    /** Fixed decimals (default: as many as the ticks need, up to 2). */
+    decimals?: number;
+    /** ISO currency code for `currency` (default `USD`). */
+    currency?: string;
+    prefix?: string;
+    suffix?: string;
+}
+interface ChartAxis {
+    /** Draw the axis line, ticks and labels (default `true`). */
+    show: boolean;
+    title: string;
+    /** Fixed lower bound (default: from the data, including 0 for bars and areas). */
+    min: number | null;
+    /** Fixed upper bound (default: from the data). */
+    max: number | null;
+    /** Grid lines at each tick (default: on for the value axis). */
+    gridlines: boolean;
+    /** How tick and data labels are written (value axis only). */
+    format: ChartNumberFormat;
+}
+type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right';
+interface ChartLegend {
+    show: boolean;
+    position: ChartLegendPosition;
+}
+type ChartStacking = 'none' | 'stacked' | 'percent';
+type ChartOrientation = 'vertical' | 'horizontal';
+type ChartCurve = 'linear' | 'smooth' | 'step';
+/** A whole chart: data plus presentation. Plain JSON, safe to persist. */
+interface ChartSpec {
+    version: 1;
+    type: ChartType;
+    title: string;
+    subtitle: string;
+    /** Category labels (the x axis, or pie slices). */
+    categories: string[];
+    series: ChartSeries[];
+    /** The category axis. */
+    xAxis: ChartAxis;
+    /** The value axis. */
+    yAxis: ChartAxis;
+    legend: ChartLegend;
+    /** Stack bars and areas (`percent` scales each category to 100%). */
+    stacking: ChartStacking;
+    /** `horizontal` draws bars sideways (bar charts only). */
+    orientation: ChartOrientation;
+    /** Line and area interpolation. */
+    curve: ChartCurve;
+    /** Dots on line and area series. */
+    points: boolean;
+    /** Value labels on bars, points and slices. */
+    dataLabels: boolean;
+    /** Series colours in order (cycled). */
+    palette: string[];
+    /** Donut hole as a fraction of the radius (0–0.9). */
+    innerRadius: number;
+}
+/** What a click selects. */
+type ChartSelection = {
+    kind: 'chart';
+} | {
+    kind: 'title';
+} | {
+    kind: 'subtitle';
+} | {
+    kind: 'legend';
+} | {
+    kind: 'axis';
+    axis: 'x' | 'y';
+} | {
+    kind: 'series';
+    seriesId: string;
+} | {
+    kind: 'point';
+    seriesId: string;
+    index: number;
+} | {
+    kind: 'category';
+    index: number;
+};
+/** Colours and type used to lay out a chart. Any CSS colour strings work. */
+interface ChartTheme {
+    /** Fill behind the chart (`transparent` lets the page show through). */
+    background: string;
+    /** The page colour: slice separators and hollow points (set it when `background` is transparent). */
+    surface: string;
+    text: string;
+    mutedText: string;
+    grid: string;
+    axis: string;
+    /** Outline drawn around the selected mark. */
+    selection: string;
+    fontFamily: string;
+    fontSize: number;
+    titleSize: number;
+}
+interface ChartRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** What a mark is, for styling and tests. */
+type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'data-label' | 'legend-swatch' | 'legend-label' | 'selection' | 'empty';
+interface ChartMarkBase {
+    /** Unique within the scene (a stable key for frameworks). */
+    key: string;
+    role: ChartMarkRole;
+    /** What clicking this mark selects (none: not clickable). */
+    target?: ChartSelection;
+    /** Mark belongs to the current selection. */
+    selected?: boolean;
+    opacity?: number;
+}
+interface ChartRectMark extends ChartMarkBase {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill: string;
+    stroke?: string;
+    strokeWidth?: number;
+    radius?: number;
+}
+interface ChartPathMark extends ChartMarkBase {
+    kind: 'path';
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    dash?: string;
+}
+interface ChartCircleMark extends ChartMarkBase {
+    kind: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+    fill: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+interface ChartLineMark extends ChartMarkBase {
+    kind: 'line';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke: string;
+    strokeWidth?: number;
+    dash?: string;
+}
+interface ChartTextMark extends ChartMarkBase {
+    kind: 'text';
+    x: number;
+    y: number;
+    text: string;
+    anchor: 'start' | 'middle' | 'end';
+    /** Vertical alignment of the text box to `y`. */
+    baseline: 'top' | 'middle' | 'bottom';
+    size: number;
+    weight?: number;
+    fill: string;
+    /** Degrees, around (x, y). */
+    rotate?: number;
+}
+type ChartMark = ChartRectMark | ChartPathMark | ChartCircleMark | ChartLineMark | ChartTextMark;
+/** Maps between data values and scene pixels along one axis of the plot. */
+interface ChartValueScale {
+    /** `y` for vertical charts, `x` for horizontal bars. */
+    axis: 'x' | 'y';
+    domain: [number, number];
+    range: [number, number];
+    ticks: number[];
+}
+/** A laid-out chart: drawing primitives in scene pixels, ready for SVG, canvas or anything else. */
+interface ChartScene {
+    width: number;
+    height: number;
+    /** The plot area (inside the axes). Empty for pies. */
+    plot: ChartRect;
+    /** Draw in order. */
+    marks: ChartMark[];
+    /** The value scale of a cartesian chart (absent for pies and empty charts). */
+    valueScale?: ChartValueScale;
+    /** Percent-stacked: values are shown as shares, so dragging is disabled. */
+    percent: boolean;
+    theme: ChartTheme;
+}
+interface ChartIssue {
+    path: string;
+    message: string;
+}
+
+declare const CHART_TYPES: readonly ChartType[];
+declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
+declare const CHART_STACKINGS: readonly ChartStacking[];
+declare const CHART_CURVES: readonly ChartCurve[];
+declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
+declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
+declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat['style']>[];
+/** Labels for pickers, shared by the React and Svelte components. */
+declare const CHART_TYPE_LABELS: Readonly<Record<ChartType, string>>;
+/** A colour-blind-friendly categorical palette (Okabe–Ito order, tuned for light and dark backgrounds). */
+declare const DEFAULT_CHART_PALETTE: readonly string[];
+declare const DEFAULT_CHART_THEME: ChartTheme;
+/**
+ * A theme that reads the page's `--background`, `--foreground`, `--muted-foreground`,
+ * `--border` and `--primary` colour variables (full colours, as the other components'
+ * inline styles use them), with light fallbacks. The React and Svelte canvases use it.
+ */
+declare const CSS_VARIABLE_CHART_THEME: ChartTheme;
+declare function isCartesianChart(type: ChartType): boolean;
+declare function defaultChartAxis(value: boolean): ChartAxis;
+/** A complete spec with every default filled in. */
+declare function createChartSpec(partial?: Partial<ChartSpec>): ChartSpec;
+/** The colour a series is drawn with. */
+declare function chartSeriesColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number): string;
+/** The colour a pie slice is drawn with (by category). */
+declare function chartSliceColor(spec: Pick<ChartSpec, 'palette'>, index: number): string;
+/** How a series is drawn in a cartesian chart. */
+declare function chartSeriesType(spec: Pick<ChartSpec, 'type'>, series: ChartSeries): ChartSeriesType;
+/** An id not used by any series (`series-1`, `series-2`, …). */
+declare function uniqueChartSeriesId(series: readonly Pick<ChartSeries, 'id'>[], base?: string): string;
+/**
+ * Reads a number the way people type it in a data grid: `1,234.5`, `12%` (→ 0.12),
+ * `$40`, `(3)` (→ -3). Blank → `null`. Returns `undefined` when it is not a number.
+ */
+declare function parseChartValue(input: unknown): ChartValue | undefined;
+declare function normalizeChartAxis(value: unknown, fallback: ChartAxis, path: string, issues?: ChartIssue[]): ChartAxis;
+/** Values as numbers or nulls; bad entries become null and are reported. */
+declare function normalizeChartValues(value: unknown, length: number | undefined, path: string, issues?: ChartIssue[]): ChartValue[];
+/**
+ * Turns any input (a partial spec, saved JSON, an agent's arguments) into a complete,
+ * valid `ChartSpec`. Every value is checked; problems are reported as sentences in
+ * `issues` and replaced by defaults, so the result is always drawable. Series values are
+ * padded or trimmed to the number of categories.
+ */
+declare function normalizeChartSpec(input: unknown): {
+    spec: ChartSpec;
+    issues: ChartIssue[];
+};
+/** A deep copy (specs are plain JSON). */
+declare function cloneChartSpec(spec: ChartSpec): ChartSpec;
+declare function cloneChartSeries(series: ChartSeries): ChartSeries;
+interface ChartTableOptions {
+    /**
+     * `columns` (default): the first column holds categories and each other column is a
+     * series. `rows`: the first row holds categories and each other row is a series.
+     */
+    seriesIn?: 'columns' | 'rows';
+    /** The first row (or column for `rows`) holds series names (default `true`). */
+    header?: boolean;
+}
+interface ChartTableData {
+    categories: string[];
+    series: ChartSeries[];
+    issues: ChartIssue[];
+}
+/**
+ * Reads a grid of cells (from CSV, a spreadsheet range or the clipboard) as categories and
+ * series. Cells that are not numbers become gaps and are reported.
+ */
+declare function chartDataFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: ChartTableOptions): ChartTableData;
+/** The chart's data as a grid: a header row of series names, then one row per category. */
+declare function chartDataToTable(spec: Pick<ChartSpec, 'categories' | 'series'>, options?: {
+    categoryHeader?: string;
+}): (string | number | null)[][];
+/** A colour input value (`#rrggbb`) for a CSS colour: `#abc` expands, non-hex colours show as black. */
+declare function chartColorInputValue(color: string): string;
+
+/** A "nice" step (1, 2, 2.5 or 5 × 10ⁿ) for about `count` intervals over `span`. */
+declare function niceStep(span: number, count: number): number;
+interface NiceScale {
+    min: number;
+    max: number;
+    step: number;
+    ticks: number[];
+}
+/**
+ * Extends `[min, max]` to round numbers and lists the ticks between them. Fixed ends
+ * (`fixedMin` / `fixedMax`) are kept exactly; ticks then start at the first nice value
+ * inside them.
+ */
+declare function niceScale(min: number, max: number, count?: number, fixedMin?: number | null, fixedMax?: number | null): NiceScale;
+/** Decimals needed to tell ticks `step` apart (at most 6). */
+declare function stepDecimals(step: number): number;
+/**
+ * Writes a number for a chart label. Locale-independent (so labels and tests are the same
+ * everywhere): `,` thousands, `.` decimals. `decimals` defaults to `fallbackDecimals`
+ * (e.g. from the tick step), else up to 2 trimmed.
+ */
+declare function formatChartNumber(value: number | null | undefined, format?: ChartNumberFormat, fallbackDecimals?: number): string;
+/** Linear map from `domain` to `range`. */
+declare function linearMap(value: number, domain: readonly [number, number], range: readonly [number, number]): number;
+
+type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
+interface ChartLayoutOptions {
+    width: number;
+    height: number;
+    theme?: Partial<ChartTheme>;
+    /** Highlighted in the scene (selection outlines, `selected` flags). */
+    selection?: ChartSelection | null;
+    /** Text width in pixels (default: an estimate from the character count). */
+    measureText?: ChartTextMeasure;
+    /** Shown when there is nothing to draw (default "No data"). */
+    emptyMessage?: string;
+}
+/** A DOM-free text width estimate (average glyph ≈ 0.56 em, bold ≈ 0.6 em). */
+declare const estimateChartTextWidth: ChartTextMeasure;
+/** Whether two selections point at the same thing. */
+declare function sameChartSelection(a: ChartSelection | null | undefined, b: ChartSelection | null | undefined): boolean;
+/**
+ * Lays a chart out as drawing primitives (rects, paths, circles, lines and text) in a
+ * `width × height` box. Pure and DOM-free: the React and Svelte canvases render the marks
+ * as SVG, `chartSceneToSvg` writes them as a string, and anything else (canvas, PDF) can
+ * draw them too. Clickable marks carry the `target` they select.
+ */
+declare function layoutChart(spec: ChartSpec, options: ChartLayoutOptions): ChartScene;
+/**
+ * The data value at a scene point along the value axis (for dragging a bar or point), or
+ * `undefined` when the scene has no value scale or is percent-stacked.
+ */
+declare function chartValueAtPoint(scene: ChartScene, point: {
+    x: number;
+    y: number;
+}): number | undefined;
+/** The value a drag should store: snapped to a tenth of the tick step (or `step`) and kept finite. */
+declare function snapChartValue(scene: ChartScene, value: number, step?: number): number;
+
+/** SVG `dominant-baseline` for a text mark's baseline (shared by every renderer). */
+declare function chartTextBaseline(baseline: ChartTextMark['baseline']): 'hanging' | 'central' | 'text-after-edge';
+/** SVG `transform` for a rotated text mark, if any. */
+declare function chartTextTransform(mark: ChartTextMark): string | undefined;
+interface ChartSvgOptions {
+    /** Leave out selection outlines (default `true`: exports show the chart only). */
+    hideSelection?: boolean;
+    /** Accessible title (default: the chart title). */
+    ariaLabel?: string;
+}
+/** Writes a laid-out scene as a standalone SVG document string. */
+declare function chartSceneToSvg(scene: ChartScene, options?: ChartSvgOptions): string;
+/** Lays out and writes a chart as SVG, e.g. for export or server rendering. */
+declare function chartToSvg(spec: ChartSpec, options: Omit<ChartLayoutOptions, 'selection'> & ChartSvgOptions): string;
+
+interface ChartControllerOptions {
+    /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
+    spec?: Partial<ChartSpec> | unknown;
+    /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
+    history?: HistoryManager;
+    /** Called after the spec changes (edit, undo, redo, load). */
+    onChange?: (spec: Readonly<ChartSpec>) => void;
+}
+/** A snapshot of the controller. The same object is returned until something changes. */
+interface ChartState {
+    spec: Readonly<ChartSpec>;
+    selection: ChartSelection | null;
+    /** The series the selection belongs to (a series or one of its points). */
+    selectedSeries: ChartSeries | null;
+    /** The category the selection belongs to (a category or a point). */
+    selectedIndex: number | null;
+    /** Problems from the last load or rejected edit, as sentences. */
+    issues: readonly ChartIssue[];
+    /** The gesture in progress (e.g. a bar drag), if any. */
+    gesture: string | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    /** Bumped on every change. */
+    revision: number;
+}
+type ChartActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    issues?: ChartIssue[];
+};
+/** Top-level fields with partial axes and legend. */
+type ChartSpecPatch = Partial<Omit<ChartSpec, 'version' | 'xAxis' | 'yAxis' | 'legend'>> & {
+    xAxis?: Partial<ChartAxis>;
+    yAxis?: Partial<ChartAxis>;
+    legend?: Partial<ChartLegend>;
+};
+interface ChartSeriesInput {
+    id?: string;
+    name?: string;
+    values?: readonly unknown[];
+    color?: string;
+    type?: ChartSeriesType;
+    hidden?: boolean;
+}
+interface ChartSeriesPatch {
+    name?: string;
+    /** `null` goes back to the palette colour. */
+    color?: string | null;
+    /** `null` follows the chart type. */
+    type?: ChartSeriesType | null;
+    hidden?: boolean;
+}
+interface ChartEditOptions {
+    /** Undo step label. */
+    label?: string;
+}
+/**
+ * Headless state for a chart editor: a validated `ChartSpec`, a selection, and undoable
+ * edits to data (values, series, categories, pasted grids, CSV) and presentation (type,
+ * titles, axes, legend, stacking, …). Drags merge into one undo step (`beginGesture`).
+ * `getState()` returns the same object until something changes, so it works with
+ * `useSyncExternalStore` and Svelte runes alike.
+ */
+declare class ChartController {
+    readonly history: HistoryManager;
+    private spec;
+    private selection;
+    private issues;
+    private gestureKey;
+    private gestureCount;
+    private revision;
+    private applying;
+    private readonly onChange?;
+    private readonly listeners;
+    private unsubscribeHistory?;
+    private state;
+    constructor(options?: ChartControllerOptions);
+    private connect;
+    /** The current snapshot (stable until the next change). */
+    getState: () => ChartState;
+    /** Calls `listener` after every change. Returns an unsubscribe function. */
+    subscribe: (listener: (state: ChartState) => void) => (() => void);
+    /** The current spec (do not mutate; edit through the controller). */
+    getSpec(): Readonly<ChartSpec>;
+    getSeries(id: string): ChartSeries | undefined;
+    private computeState;
+    private notify;
+    /** Drops a selection that no longer points at anything. */
+    private validSelection;
+    private applySpec;
+    private commit;
+    private reject;
+    /** A copy of the spec with `edit` applied (series and categories copied as needed). */
+    private edited;
+    private unknownSeries;
+    private badIndex;
+    /**
+     * Changes any presentation or data fields as one undo step. All-or-nothing: if anything
+     * is invalid, nothing changes and every problem is returned (and shown in `state.issues`).
+     */
+    update(patch: ChartSpecPatch, options?: ChartEditOptions): ChartActionResult;
+    setType(type: ChartType): ChartActionResult;
+    setTitle(title: string): ChartActionResult;
+    setSubtitle(subtitle: string): ChartActionResult;
+    /** Changes the category (`x`) or value (`y`) axis. */
+    setAxis(axis: 'x' | 'y', patch: Partial<ChartAxis>): ChartActionResult;
+    setLegend(patch: Partial<ChartLegend>): ChartActionResult;
+    /**
+     * Replaces categories and / or series as one undo step. Values are validated and padded
+     * to the categories; all-or-nothing like `update`.
+     */
+    setData(data: {
+        categories?: readonly unknown[];
+        series?: readonly ChartSeriesInput[];
+    }, options?: ChartEditOptions): ChartActionResult;
+    /**
+     * Sets one value (numbers, numeric text such as `1,200` or `12%`, or blank for a gap).
+     * One undo step, or part of the current gesture.
+     */
+    setValue(seriesId: string, index: number, value: unknown, options?: ChartEditOptions): ChartActionResult;
+    /** Several values as one undo step (all-or-nothing). */
+    setValues(cells: readonly {
+        seriesId: string;
+        index: number;
+        value: unknown;
+    }[], options?: ChartEditOptions): ChartActionResult;
+    /** Adds a series (values padded to the categories) and selects it. Returns its id. */
+    addSeries(input?: ChartSeriesInput, options?: {
+        at?: number;
+    }): {
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    removeSeries(id: string): ChartActionResult;
+    updateSeries(id: string, patch: ChartSeriesPatch): ChartActionResult;
+    toggleSeries(id: string): ChartActionResult;
+    /** Moves a series to position `to` (drawing and legend order). */
+    moveSeries(id: string, to: number): ChartActionResult;
+    /** Inserts a category (with gaps in every series) at `at` (default: the end). Returns its index. */
+    addCategory(label?: string, options?: {
+        at?: number;
+    }): {
+        ok: true;
+        index: number;
+    };
+    removeCategory(index: number): ChartActionResult;
+    renameCategory(index: number, label: string): ChartActionResult;
+    moveCategory(from: number, to: number): ChartActionResult;
+    /**
+     * Pastes a block of cells (TSV / CSV text or rows) into the data grid with its top-left at
+     * `row` (category index) and `column` (series index; `-1` is the category column). The
+     * grid grows to fit. Non-numeric value cells become gaps and are reported in `issues`.
+     */
+    pasteCells(row: number, column: number, cells: string | ReadonlyArray<ReadonlyArray<unknown>>): ChartActionResult & {
+        issues?: ChartIssue[];
+    };
+    /**
+     * Replaces the data with a grid of cells (see `chartDataFromTable`): one undo step. Series
+     * colours and types are kept by name.
+     */
+    importTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: ChartTableOptions): ChartActionResult & {
+        issues?: ChartIssue[];
+    };
+    /** Imports CSV (or TSV, detected by tabs) text; see `importTable`. */
+    importCsv(text: string, options?: ChartTableOptions & {
+        delimiter?: string;
+    }): ChartActionResult & {
+        issues?: ChartIssue[];
+    };
+    /** Selects a chart element (view state; not an undo step). */
+    select(selection: ChartSelection | null): void;
+    /**
+     * Deletes what is selected: a series or category is removed, a point becomes a gap, a
+     * title is cleared, the legend or an axis is hidden.
+     */
+    deleteSelection(): ChartActionResult;
+    /** Adds `delta` to a value (a gap counts as 0). */
+    nudgeValue(seriesId: string, index: number, delta: number): ChartActionResult;
+    /** Starts a continuous edit (a drag): every change until `endGesture()` is one undo step. */
+    beginGesture(key: string): void;
+    endGesture(): void;
+    /** The spec, for saving (a copy). */
+    toJSON(): ChartSpec;
+    /**
+     * Replaces the chart without an undo step (e.g. when opening a document). Problems are
+     * fixed with defaults and reported in `state.issues` (and returned).
+     */
+    load(input: unknown, options?: {
+        clearHistory?: boolean;
+    }): ChartIssue[];
+    undo(): boolean;
+    redo(): boolean;
+    /** Stops listening to the history (reconnected by the next `subscribe`). */
+    destroy(): void;
+}
+declare function createChartController(options?: ChartControllerOptions): ChartController;
+
+interface ChartCommandOptions {
+    /** Id prefix (default `chart.`); use one per chart when several are registered. */
+    prefix?: string;
+    /** Palette group (default `Chart`). */
+    group?: string;
+    /** Command scope. Omit for global commands. */
+    scope?: string;
+}
+/**
+ * Palette and agent commands for a chart: describe, update presentation, replace data, set
+ * values, add / remove series and categories, import CSV and export SVG. Register them in a
+ * `CommandRegistry` and agents get them through `createCommandToolProvider`. Failures throw
+ * sentences, which the registry returns as `{ ok: false, code: 'failed', message }`.
+ */
+declare function createChartCommands(controller: ChartController, options?: ChartCommandOptions): CommandSpec[];
+
+/** Scene coordinates of a pointer, given the rendered element's box (the scene is scaled to fit it). */
+declare function chartClientToScene(scene: Pick<ChartScene, 'width' | 'height'>, box: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, clientX: number, clientY: number): {
+    x: number;
+    y: number;
+};
+/** Whether a point can be dragged to a new value in this scene (cartesian, not percent-stacked, not hidden). */
+declare function canDragChartPoint(controller: ChartController, scene: ChartScene, target: ChartSelection | undefined): target is Extract<ChartSelection, {
+    kind: 'point';
+}>;
+interface ChartPointDrag {
+    /** Moves the value with the pointer (scene coordinates). */
+    move(point: {
+        x: number;
+        y: number;
+    }): void;
+    /** Ends the drag (one undo step for the whole drag). */
+    end(): void;
+}
+/**
+ * Starts dragging a bar or point: the value follows the pointer along the value axis,
+ * snapped to a tenth of the tick step (`step` overrides), and the whole drag is one undo
+ * step. Works for stacked bars too (the drag changes the segment by the distance moved).
+ * Returns `null` when the target cannot be dragged.
+ */
+declare function startChartPointDrag(controller: ChartController, scene: ChartScene, target: ChartSelection | undefined, start: {
+    x: number;
+    y: number;
+}, options?: {
+    step?: number;
+}): ChartPointDrag | null;
+interface ChartKeyInput {
+    key: string;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+}
+/**
+ * Keyboard editing on a focused chart: arrows move a point selection between categories
+ * (← →) and change its value (↑ ↓, a tenth of the tick step; Shift: a whole step), Delete /
+ * Backspace deletes the selection, Escape clears it. Returns `true` when the key was used
+ * (call `preventDefault`).
+ */
+declare function handleChartKey(controller: ChartController, scene: ChartScene | null, event: ChartKeyInput): boolean;
+/** A short description of the selection for an inspector heading or a screen reader. */
+declare function describeChartSelection(controller: ChartController, selection?: ChartSelection | null): string;
+
+export { CHART_CURVES, CHART_LEGEND_POSITIONS, CHART_NUMBER_STYLES, CHART_ORIENTATIONS, CHART_SERIES_TYPES, CHART_STACKINGS, CHART_TYPES, CHART_TYPE_LABELS, CSS_VARIABLE_CHART_THEME, type ChartActionResult, type ChartAxis, type ChartCircleMark, type ChartCommandOptions, ChartController, type ChartControllerOptions, type ChartCurve, type ChartEditOptions, type ChartIssue, type ChartKeyInput, type ChartLayoutOptions, type ChartLegend, type ChartLegendPosition, type ChartLineMark, type ChartMark, type ChartMarkRole, type ChartNumberFormat, type ChartOrientation, type ChartPathMark, type ChartPointDrag, type ChartRect, type ChartRectMark, type ChartScene, type ChartSelection, type ChartSeries, type ChartSeriesInput, type ChartSeriesPatch, type ChartSeriesType, type ChartSpec, type ChartSpecPatch, type ChartStacking, type ChartState, type ChartSvgOptions, type ChartTableData, type ChartTableOptions, type ChartTextMark, type ChartTextMeasure, type ChartTheme, type ChartType, type ChartValue, type ChartValueScale, DEFAULT_CHART_PALETTE, DEFAULT_CHART_THEME, type NiceScale, canDragChartPoint, chartClientToScene, chartColorInputValue, chartDataFromTable, chartDataToTable, chartSceneToSvg, chartSeriesColor, chartSeriesType, chartSliceColor, chartTextBaseline, chartTextTransform, chartToSvg, chartValueAtPoint, cloneChartSeries, cloneChartSpec, createChartCommands, createChartController, createChartSpec, defaultChartAxis, describeChartSelection, estimateChartTextWidth, formatChartNumber, handleChartKey, isCartesianChart, layoutChart, linearMap, niceScale, niceStep, normalizeChartAxis, normalizeChartSpec, normalizeChartValues, parseChartValue, sameChartSelection, snapChartValue, startChartPointDrag, stepDecimals, uniqueChartSeriesId };