@pixerate/editor 0.47.0 → 0.49.0

package/dist/controller-DtbEo3om.d.ts

@@ -0,0 +1,822 @@
+import { H as HistoryManager } from './HistoryManager-DWSLd6Tf.js';
+
+/**
+ * Chart kinds.
+ *
+ * - `bar`, `line`, `area` and `scatter` are cartesian: categories along one axis, values along
+ *   the other, and series may mix them (a combo chart). A scatter chart whose series carry
+ *   numeric `x` values plots them on a numeric x axis instead.
+ * - `bubble` plots `x`, `y` (the values) and `sizes` per series.
+ * - `pie` and `donut` draw the first visible series, one slice per category.
+ * - `radar` draws each series as a polygon over one spoke per category.
+ * - `waterfall` draws the first series as running increases and decreases.
+ * - `histogram` bins every value of the visible series; `box` draws one box and whiskers per series.
+ * - `funnel` and `treemap` draw the first series, one bar or rectangle per category.
+ */
+type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap';
+/** 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;
+/** Point marker shapes for line, area and scatter series. */
+type ChartMarker = 'circle' | 'square' | 'diamond' | 'triangle' | 'cross' | 'none';
+/** Trendline fits (as in spreadsheets). */
+type ChartTrendlineType = 'linear' | 'exponential' | 'logarithmic' | 'power' | 'polynomial' | 'moving-average';
+interface ChartTrendline {
+    type: ChartTrendlineType;
+    /** Polynomial order, 2–6 (default 2). */
+    order?: number;
+    /** Moving-average period, 2 or more (default 2). */
+    period?: number;
+    /** Extend the line this many x units past the last point (default 0). */
+    forward?: number;
+    /** Extend the line this many x units before the first point (default 0). */
+    backward?: number;
+    /** Force the line through this y at x = 0 (linear, polynomial and exponential only). */
+    intercept?: number | null;
+    /** Write the fitted equation on the chart. */
+    showEquation?: boolean;
+    /** Write R² on the chart. */
+    showR2?: boolean;
+    /** Legend name (default: e.g. "Linear (Sales)"). */
+    name?: string;
+    /** CSS colour (default: the series colour). */
+    color?: string;
+}
+interface ChartSeries {
+    /** Stable id (unique within the chart). */
+    id: string;
+    name: string;
+    /** One value per category (the y values of a scatter or bubble chart). */
+    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;
+    /** Plot against the secondary value axis (on the right). */
+    axis?: 'primary' | 'secondary';
+    /** Numeric x per category (scatter and bubble charts). */
+    x?: ChartValue[];
+    /** Bubble sizes per category (bubble charts; area is proportional to size). */
+    sizes?: ChartValue[];
+    /** Colour overrides per category (`null` keeps the series colour). */
+    pointColors?: (string | null)[];
+    /** Point marker (default: circles on lines when `points` is on). */
+    marker?: ChartMarker;
+    /** Line interpolation for this series (default: the chart's `curve`). */
+    curve?: ChartCurve;
+    /** Value labels for this series (default: the chart's `dataLabels`). */
+    dataLabels?: boolean;
+    /** How this series' data labels are written (default: the value axis format). */
+    format?: ChartNumberFormat;
+    /** Fitted lines drawn over the series. */
+    trendlines?: ChartTrendline[];
+}
+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;
+    /**
+     * A spreadsheet format code such as `#,##0.0,,"M"` or `0.0%;[Red]-0.0%`. When set it
+     * wins over the other fields. Supports sections (positive;negative;zero), digit
+     * placeholders, thousands separators and scaling, percent, scientific and literal text.
+     */
+    code?: 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;
+    /** Fixed distance between ticks (default: a round number from the plot size). */
+    step: number | null;
+    /** Grid lines at each tick (default: on for the value axis). */
+    gridlines: boolean;
+    /** How tick and data labels are written (value axes, and the x axis of scatter charts). */
+    format: ChartNumberFormat;
+    /**
+     * Category axis only: `date` reads the categories as dates (ISO `2024-03-01`, `2024-03`,
+     * `2024`), labels them with calendar steps that fit, and thins the rest.
+     */
+    kind?: 'category' | 'date';
+}
+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';
+/** Where bar labels go: `auto` puts them outside, or centred on stacked segments, and drops ones that do not fit. */
+type ChartLabelPosition = 'auto' | 'inside' | 'outside' | 'center';
+/** 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 (or the numeric x axis of a scatter or bubble chart). */
+    xAxis: ChartAxis;
+    /** The value axis. */
+    yAxis: ChartAxis;
+    /** The secondary value axis, drawn on the right when a visible series uses it. */
+    yAxis2: 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;
+    /** Where bar value labels go. */
+    labelPosition: ChartLabelPosition;
+    /** Series colours in order (cycled through lighter and darker shades once used up). */
+    palette: string[];
+    /** Donut hole as a fraction of the radius (0–0.9). */
+    innerRadius: number;
+    /** Empty space between category groups, as a fraction of the category width (0–0.9). */
+    gapWidth: number;
+    /** How much bars in a group overlap, as a fraction of a bar's width (-1 to 1; negative is a gap). */
+    overlap: number;
+    /** Histogram bin count (`null`: √n, between 1 and 100). */
+    bins: number | null;
+    /** Waterfall: append a running-total bar (categories labelled "total" are always totals). */
+    showTotal: boolean;
+}
+/** What a click selects. */
+type ChartSelection = {
+    kind: 'chart';
+} | {
+    kind: 'title';
+} | {
+    kind: 'subtitle';
+} | {
+    kind: 'legend';
+} | {
+    kind: 'axis';
+    axis: 'x' | 'y' | 'y2';
+} | {
+    kind: 'series';
+    seriesId: string;
+} | {
+    kind: 'point';
+    seriesId: string;
+    index: number;
+} | {
+    kind: 'category';
+    index: number;
+} | {
+    kind: 'trendline';
+    seriesId: string;
+    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;
+    /** Waterfall increases. */
+    positive: string;
+    /** Waterfall decreases. */
+    negative: 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' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | '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 and the numeric x axis of scatter charts. */
+    axis: 'x' | 'y';
+    domain: [number, number];
+    range: [number, number];
+    ticks: number[];
+}
+/** Something the layout had to leave out or shorten, as a sentence (for agents and screen readers). */
+interface ChartWarning {
+    code: 'labels-hidden' | 'labels-truncated' | 'legend-truncated' | 'points-decimated' | 'values-skipped' | 'data-labels-hidden' | 'type-fallback';
+    message: string;
+}
+/** 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;
+    /** The secondary value scale, when a visible series uses it. */
+    valueScale2?: ChartValueScale;
+    /** The numeric x scale of a scatter or bubble chart with x values. */
+    xScale?: ChartValueScale;
+    /** Percent-stacked: values are shown as shares, so dragging is disabled. */
+    percent: boolean;
+    theme: ChartTheme;
+    /** What was left out or shortened (hidden labels, decimated lines, …). */
+    warnings: ChartWarning[];
+}
+interface ChartIssue {
+    path: string;
+    message: string;
+    /** 1-based source line, for text formats such as Mermaid. */
+    line?: number;
+}
+
+declare const CHART_TYPES: readonly ChartType[];
+declare const CHART_MARKERS: readonly ChartMarker[];
+declare const CHART_TRENDLINE_TYPES: readonly ChartTrendlineType[];
+declare const CHART_LABEL_POSITIONS: readonly ChartLabelPosition[];
+declare const CHART_AXIS_KINDS: readonly NonNullable<ChartAxis['kind']>[];
+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>>;
+/** How a chart type is laid out. */
+type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap';
+/** 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;
+/** Bar, line, area and scatter: categories (or numeric x) against values, series may mix. */
+declare function isCartesianChart(type: ChartType): boolean;
+/** Whether the chart plots series against a numeric x axis (bubble charts, and scatter charts with x values). */
+declare function isXyChart(spec: Pick<ChartSpec, 'type' | 'series'>): boolean;
+/** How a chart is laid out (see `ChartType`). */
+declare function chartFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartFamily;
+/** Chart types whose legend lists categories (one colour per category) rather than series. */
+declare function chartColorsByCategory(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;
+/** The colour of one bar or point: its override, else the series colour. */
+declare function chartPointColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number, 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[];
+/** Checks one trendline; `null` (reported) when it is unusable. */
+declare function normalizeChartTrendline(value: unknown, path: string, issues?: ChartIssue[]): ChartTrendline | null;
+/**
+ * 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`). `auto`: only
+     * when one of its value cells is not a number.
+     */
+    header?: boolean | 'auto';
+    /**
+     * Read the first column as numeric x values (scatter and bubble charts): every series gets
+     * them as `x`, and the categories are their labels.
+     */
+    xFromFirstColumn?: 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 fitted regression trendline. Exponential, logarithmic and power fits are linear fits of
+ * transformed data (`ln y ~ x`, `y ~ ln x`, `ln y ~ ln x`), as spreadsheets document them;
+ * points the transform cannot take (values ≤ 0) are skipped, and R² is for the transformed fit.
+ */
+interface ChartTrendFit {
+    type: Exclude<ChartTrendlineType, 'moving-average'>;
+    /** Coefficients `c0…cd` of `Y = Σ cₖ·Xᵏ` in the transformed variables. */
+    coefficients: number[];
+    /** Coefficient of determination; `null` when undefined (all y equal). */
+    r2: number | null;
+    /** The equation as a label, e.g. `y = 0.5x² - 2x + 1` or `y = 3e^(0.2x)`. */
+    equation: string;
+    /** Number of points used. */
+    points: number;
+    /** The fitted y at `x`, or `null` outside the fit's domain (x ≤ 0 for log and power). */
+    evaluate(x: number): number | null;
+}
+/**
+ * Fits `trendline` to the points. Returns `null` for moving averages (see
+ * `chartMovingAverage`) and degenerate data: too few usable points, all x equal, or a
+ * singular system.
+ */
+declare function fitChartTrendline(trendline: ChartTrendline, points: ReadonlyArray<readonly [number, number]>): ChartTrendFit | null;
+/** A coefficient as trendline labels show it: up to four decimals, scientific when tiny or huge. */
+declare function trendNumberText(v: number): string;
+/**
+ * Moving average of `period` consecutive points in plotted order: point `i` (from
+ * `period - 1`) is `(xᵢ, mean(yᵢ₋ₚ₊₁ … yᵢ))`. Empty when there are fewer points than `period`.
+ */
+declare function chartMovingAverage(points: ReadonlyArray<readonly [number, number]>, period: number): [number, number][];
+/** The legend name spreadsheets give a trendline, e.g. `Linear (Sales)`. */
+declare function chartTrendlineName(trendline: ChartTrendline, seriesName: string): string;
+/** Whether trendlines can be drawn for this chart type and stacking (unstacked cartesian and xy charts). */
+declare function chartSupportsTrendlines(type: string, stacking: string): boolean;
+
+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;
+    /**
+     * Fixes the value axis to this range (over `yAxis.min` / `yAxis.max`). Canvases pass
+     * `ChartPointDrag.valueDomain` during a drag so the axis does not rescale under the pointer.
+     */
+    valueDomain?: {
+        min: number;
+        max: number;
+    } | null;
+    /** Fixes the secondary value axis the same way (`ChartPointDrag.valueDomain2`). */
+    valueDomain2?: {
+        min: number;
+        max: number;
+    } | null;
+    /** Fixes the numeric x axis of a scatter or bubble chart (`ChartPointDrag.xDomain`). */
+    xDomain?: {
+        min: number;
+        max: number;
+    } | null;
+    /** Shows the value of this point next to it (a `drag-readout` text mark, kept inside the plot). */
+    readout?: {
+        seriesId: string;
+        index: number;
+    } | null;
+}
+/** 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;
+/**
+ * Black or white text for a label drawn on `fill` (#rgb, #rrggbb or rgb()), by perceived
+ * luminance (0.299 R + 0.587 G + 0.114 B). Unparseable colours (CSS variables) get white.
+ */
+declare function contrastingTextColor(fill: string): string;
+
+/** 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;
+    /** A longer description written as `<desc>` (`chartToSvg` defaults to `describeChart`). */
+    description?: 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;
+/** A ProseMirror / TipTap `DOMOutputSpec` array (kept structural so this module needs no TipTap types). */
+type ChartDomSpec = [string, Record<string, string>, ...(ChartDomSpec | string)[]];
+/**
+ * Writes a laid-out scene as a ProseMirror `DOMOutputSpec` (SVG-namespaced tags), so a
+ * TipTap node's `renderHTML` can draw a chart without parsing an SVG string. Same output
+ * as `chartSceneToSvg`.
+ */
+declare function chartSceneToDomSpec(scene: ChartScene, options?: ChartSvgOptions & {
+    attrs?: Record<string, string>;
+}): ChartDomSpec;
+
+type ChartSparklineKind = 'line' | 'column' | 'win-loss';
+interface ChartSparklineOptions {
+    kind?: ChartSparklineKind;
+    width: number;
+    height: number;
+    /** Line, positive column and win colour (default the first palette colour). */
+    color?: string;
+    /** Negative column and loss colour (default red). */
+    negativeColor?: string;
+    /** Dots on every line point (thinned past 500). */
+    markers?: boolean;
+    /** Highlight the highest and lowest point of a line (or column). */
+    highLow?: boolean;
+    /** Fixed value range (default: the data, including 0 for columns). */
+    min?: number;
+    max?: number;
+}
+/**
+ * Lays out a word-sized chart (a sparkline) as marks: a line broken at gaps, columns
+ * (negatives in `negativeColor`) or win/loss bars of equal height. Long lines are thinned past
+ * 4000 points. Returns a scene with no axes, legend or targets.
+ */
+declare function layoutSparkline(values: readonly ChartValue[], options: ChartSparklineOptions): ChartScene;
+/** A sparkline as a standalone SVG string (e.g. for an inline image in rich text). */
+declare function sparklineToSvg(values: readonly ChartValue[], options: ChartSparklineOptions & {
+    ariaLabel?: string;
+}): 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, one of its points or one of its trendlines). */
+    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' | 'yAxis2' | 'legend'>> & {
+    xAxis?: Partial<ChartAxis>;
+    yAxis?: Partial<ChartAxis>;
+    yAxis2?: Partial<ChartAxis>;
+    legend?: Partial<ChartLegend>;
+};
+interface ChartSeriesInput {
+    id?: string;
+    name?: string;
+    values?: readonly unknown[];
+    color?: string;
+    type?: ChartSeriesType;
+    hidden?: boolean;
+    axis?: 'primary' | 'secondary';
+    x?: readonly unknown[];
+    sizes?: readonly unknown[];
+    pointColors?: readonly (string | null)[];
+    marker?: ChartMarker;
+    curve?: ChartCurve;
+    dataLabels?: boolean;
+    format?: ChartNumberFormat;
+    trendlines?: readonly ChartTrendline[];
+}
+/** Changes to one series; `null` resets a field to the chart's default. */
+interface ChartSeriesPatch {
+    name?: string;
+    /** `null` goes back to the palette colour. */
+    color?: string | null;
+    /** `null` follows the chart type. */
+    type?: ChartSeriesType | null;
+    hidden?: boolean;
+    axis?: 'primary' | 'secondary' | null;
+    x?: readonly unknown[] | null;
+    sizes?: readonly unknown[] | null;
+    pointColors?: readonly (string | null)[] | null;
+    marker?: ChartMarker | null;
+    curve?: ChartCurve | null;
+    dataLabels?: boolean | null;
+    format?: ChartNumberFormat | null;
+}
+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 gestureStart;
+    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`), value (`y`) or secondary value (`y2`) axis. */
+    setAxis(axis: 'x' | 'y' | 'y2', patch: Partial<ChartAxis>): ChartActionResult;
+    /**
+     * Applies a named quick layout and / or colour scheme (see `CHART_LAYOUT_PRESETS` and
+     * `CHART_COLOR_SCHEMES`) as one undo step.
+     */
+    applyPreset(options: {
+        layout?: string;
+        colors?: string;
+    }): 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[];
+    };
+    /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
+    addTrendline(seriesId: string, input: ChartTrendline): {
+        ok: true;
+        index: number;
+        fit: ChartTrendFit | null;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a trendline (all-or-nothing). */
+    updateTrendline(seriesId: string, index: number, patch: Partial<ChartTrendline>): ChartActionResult;
+    removeTrendline(seriesId: string, index: number): ChartActionResult;
+    /** The points a series' trendlines are fitted to: (x, y) with x = 1, 2, 3 … on category charts. */
+    trendlinePoints(seriesId: string): [number, number][];
+    /** The fitted coefficients, R² and equation of a trendline (null for moving averages or unfittable data). */
+    trendlineFit(seriesId: string, index: number): ChartTrendFit | null;
+    /** The moving-average points of a trendline (empty for other kinds). */
+    trendlineMovingAverage(seriesId: string, index: number): [number, number][];
+    /**
+     * Switches rows and columns: series become categories and categories become series (one
+     * undo step). Series colours, types and other per-series settings are dropped.
+     */
+    transpose(): ChartActionResult;
+    /** 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;
+    /**
+     * Cancels the gesture in progress (Escape during a drag): everything it changed is taken
+     * back and leaves no undo or redo step.
+     */
+    cancelGesture(): 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;
+
+export { type ChartTableData as $, CHART_TYPES as A, CHART_TYPE_LABELS as B, type ChartNumberFormat as C, CSS_VARIABLE_CHART_THEME as D, type ChartActionResult as E, type ChartCircleMark as F, type ChartControllerOptions as G, type ChartCurve as H, type ChartDomSpec as I, type ChartEditOptions as J, type ChartFamily as K, type ChartLabelPosition as L, type ChartLegendPosition as M, type ChartLineMark as N, type ChartMark as O, type ChartMarkRole as P, type ChartMarker as Q, type ChartOrientation as R, type ChartPathMark as S, type ChartRectMark as T, type ChartSeriesInput as U, type ChartSeriesPatch as V, type ChartSeriesType as W, type ChartSparklineKind as X, type ChartSparklineOptions as Y, type ChartState as Z, type ChartSvgOptions as _, type ChartValue as a, type ChartTableOptions as a0, type ChartTextMark as a1, type ChartTextMeasure as a2, type ChartTheme as a3, type ChartTrendFit as a4, type ChartTrendline as a5, type ChartTrendlineType as a6, DEFAULT_CHART_PALETTE as a7, DEFAULT_CHART_THEME as a8, chartColorInputValue as a9, layoutSparkline as aA, normalizeChartAxis as aB, normalizeChartSpec as aC, normalizeChartTrendline as aD, normalizeChartValues as aE, parseChartValue as aF, sameChartSelection as aG, sparklineToSvg as aH, trendNumberText as aI, uniqueChartSeriesId as aJ, chartColorsByCategory as aa, chartDataFromTable as ab, chartDataToTable as ac, chartFamily as ad, chartMovingAverage as ae, chartPointColor as af, chartSceneToDomSpec as ag, chartSceneToSvg as ah, chartSeriesColor as ai, chartSeriesType as aj, chartSliceColor as ak, chartSupportsTrendlines as al, chartTextBaseline as am, chartTextTransform as an, chartToSvg as ao, chartTrendlineName as ap, cloneChartSeries as aq, cloneChartSpec as ar, contrastingTextColor as as, createChartController as at, createChartSpec as au, defaultChartAxis as av, estimateChartTextWidth as aw, fitChartTrendline as ax, isCartesianChart as ay, isXyChart as az, type ChartRect as b, type ChartScene as c, type ChartSpec as d, type ChartLayoutOptions as e, type ChartWarning as f, type ChartAxis as g, type ChartLegend as h, type ChartType as i, type ChartStacking as j, type ChartSeries as k, type ChartIssue as l, ChartController as m, type ChartValueScale as n, type ChartSelection as o, type ChartSpecPatch as p, CHART_AXIS_KINDS as q, CHART_CURVES as r, CHART_LABEL_POSITIONS as s, CHART_LEGEND_POSITIONS as t, CHART_MARKERS as u, CHART_NUMBER_STYLES as v, CHART_ORIENTATIONS as w, CHART_SERIES_TYPES as x, CHART_STACKINGS as y, CHART_TRENDLINE_TYPES as z };