@damoqiongqiu/ice-chart 0.17.0

package/dist/types/ICEChart.d.mts

@@ -0,0 +1,330 @@
+import { ICE, ICEGroup } from 'ice-render';
+import type { ChartOption, DataItem } from './types.mjs';
+import type { ChartLayout, InternalSeries, NormalizedOption } from './internal.mjs';
+import { GridLines } from './components/GridLines.mjs';
+import { PlotArea } from './components/PlotArea.mjs';
+import { Axis } from './components/Axis.mjs';
+import { Legend } from './components/Legend.mjs';
+import { Title } from './components/Title.mjs';
+import { Tooltip } from './components/Tooltip.mjs';
+import { Crosshair } from './components/Crosshair.mjs';
+import { Highlight } from './components/Highlight.mjs';
+import { Brush } from './components/Brush.mjs';
+import { RadarGrid } from './components/RadarGrid.mjs';
+import { PolarGrid } from './components/PolarGrid.mjs';
+import { DataZoomSlider } from './components/DataZoomSlider.mjs';
+import type { SeriesBase } from './components/series/SeriesBase.mjs';
+import { InteractionController } from './interaction/InteractionController.mjs';
+import { type A11yTreeOptions, type DataTable } from './a11y.mjs';
+/** 快照格式版本：结构变化时递增，还原时校验。 */
+export declare const SNAPSHOT_VERSION = 1;
+export { setMotionPreference, getMotionPreference, shouldAnimate } from './animation/motion.mjs';
+export type { MotionPreference } from './animation/motion.mjs';
+export interface SnapshotRestoreOptions {
+    /**
+     * 还原时叠加的非序列化配置补丁（formatter、函数型回调等）。
+     * series 按 id 或下标逐项合并，不会覆盖快照里的数据。
+     */
+    optionPatch?: Partial<ChartOption> & {
+        series?: any[];
+    };
+}
+export interface ChartSnapshot {
+    version: number;
+    option: ChartOption;
+    view: {
+        x: [any, any] | null;
+        y: [any, any] | null;
+        yAxes: Array<[any, any] | null>;
+    };
+    hidden: Record<string, boolean>;
+    hiddenSlices: Record<string, boolean>;
+}
+/** 判断一个对象是不是 ice-chart 快照（用于 createChart 的入参分派）。 */
+export declare function isChartSnapshot(value: any): boolean;
+/** 把补丁合进快照里的 option：series 按 id/下标逐项合并，其余字段浅覆盖。 */
+export declare function mergeOptionPatch(base: any, patch: any): any;
+export interface ICEChartOptions {
+    renderMode?: 'dirty-rect' | 'full';
+    dpr?: number;
+    /** 监听容器尺寸变化并自动重排（需要 ResizeObserver）。 */
+    autoResize?: boolean;
+}
+export interface ApplyOptionOptions {
+    /** true = 播「更新」动画；'enter' = 播「入场」动画；false = 不播。 */
+    animate?: boolean | 'enter' | 'update';
+    /** 保留当前缩放窗口（图例切换、数据更新时用）。 */
+    preserveView?: boolean;
+}
+/**
+ * ICEChart：把一份声明式 option 编译成 ice-render 组件树，并挂上交互层。
+ *
+ * 分工：
+ * - 归一化（数据 → 数据域 / 堆叠）由 option/normalize 负责，纯函数、可单测；
+ * - 布局（标题 / 图例 / 坐标轴 / 绘图区）由 layout 负责，纯函数、可单测；
+ * - 渲染由 ice-render 组件负责（脏矩形局部重绘、离屏缓存、HiDPI 全部由引擎兜底）；
+ * - 交互由 InteractionController 负责，对外只抛语义事件。
+ */
+export declare class ICEChart {
+    ice: ICE;
+    option: ChartOption;
+    norm: NormalizedOption;
+    layout: ChartLayout;
+    root: ICEGroup;
+    plotArea: PlotArea;
+    grid: GridLines;
+    radarGrid: RadarGrid;
+    /** 极坐标网格（r(θ) 曲线用；画在直角坐标场景里，配合 aspect:'equal'）。 */
+    polarGrid: PolarGrid;
+    axisX: Axis;
+    /** y 轴组件，与 norm.yAxes 一一对应（axisYList[0] 是主 y 轴）。 */
+    axisYList: Axis[];
+    legend: Legend | null;
+    titleComponent: Title | null;
+    tooltip: Tooltip | null;
+    crosshair: Crosshair | null;
+    highlight: Highlight | null;
+    brushComponent: Brush | null;
+    dataZoomSlider: DataZoomSlider | null;
+    seriesComponents: SeriesBase[];
+    controller: InteractionController;
+    /** 交互层使用的别名（与 InteractionHost 接口约定一致）。 */
+    get brush(): Brush | null;
+    /** 未经缩放/筛选的完整数据域（缩放约束与跨图联动用）。 */
+    fullXDomain: any[];
+    fullYDomain: any[];
+    /** 每个 y 轴的完整数据域（未缩放）。 */
+    fullYDomains: any[][];
+    private emitter;
+    private canvasEl;
+    private chartOptions;
+    private viewState;
+    /** 存在 function 系列时为真：y 轴数据域每次重建都按可视 x 区间重算（自动贴合）。 */
+    private autoYCurve;
+    private hiddenIds;
+    private hiddenSlices;
+    private seriesSignature;
+    private axisSignature;
+    private resizeObserver;
+    private destroyed;
+    /** 抑制对外事件的重入深度（跨图联动时避免 A→B→A 的回环）。 */
+    private silenceDepth;
+    private a11yMirror;
+    /**
+     * 更新动画期间的坐标轴数据域过渡。
+     *
+     * 数据更新时 y 轴数据域常常会变（例如最大值从 50 掉到 40），如果域瞬跳，
+     * 柱子会在动画**开始的那一帧**整体位移一下，值插值反而看不见。
+     * 所以域要和系列的值一起插值：每帧按同一进度重算域与坐标，动画结束时再回到常规路径。
+     */
+    private domainTransition;
+    private domainFrameHandler;
+    constructor(target: any, option: ChartOption, chartOptions?: ICEChartOptions);
+    /** 更新配置。默认保留当前缩放窗口，可用 resetZoom 恢复。 */
+    setOption(option: ChartOption, options?: ApplyOptionOptions): this;
+    /** 取当前配置（函数字段保留；持久化请用 toJSON）。 */
+    getOption(): ChartOption;
+    /**
+     * 函数绘图 / 参数曲线的表达式诊断（**回答「用户是不是写错了公式」**）。
+     *
+     * 三类都覆盖：
+     * - `error`：语法错误（带位置）、未定义的变量、在当前区间内没有任何可绘制的值；
+     * - `warning`：参数定义了没用上、输出恒定（画出来是一条水平线）。
+     *
+     * 表达式来自用户输入，写错**不会**让图表崩掉（那会让表单很难用），
+     * 但错误必须能被拿到：表单据此标红 / 提示，控制台不必猜。
+     */
+    expressionDiagnostics(): Array<{
+        seriesId: string;
+        diagnostics: NonNullable<InternalSeries['expressionDiagnostics']>;
+    }>;
+    /** 只取错误（标红用）。需要警告（提示用）请用 `expressionDiagnostics()`。 */
+    expressionErrors(): Array<{
+        seriesId: string;
+        message: string;
+    }>;
+    /** 更新单个系列的数据。 */
+    setData(seriesIdOrIndex: string | number, data: DataItem[]): this;
+    /**
+     * **追加**数据（实时数据流专用）：把新点接到系列末尾，超出 `maxPoints` 时从头裁掉，
+     * 形成滑动窗口。相对 `setData` 的两点差别：
+     *
+     * 1. **不做值插值**（`animate` 默认 false）：窗口滑动会让下标整体前移，
+     *    插值会把「这一点」插向「下一点的值」，看起来像被拖住。
+     *    流畅度由推送频率决定（60Hz 推送就是 60fps 的平滑滚动）；
+     * 2. 只重算被追加的系列所在的那条链路（走 `applyOption` 的常规更新路径，`preserveView` 保持缩放窗口）。
+     *
+     * ```ts
+     * chart.appendData('cpu', [[t, value]], { maxPoints: 180 });
+     * ```
+     */
+    appendData(seriesIdOrIndex: string | number, items: DataItem[], options?: {
+        maxPoints?: number;
+        animate?: boolean;
+    }): this;
+    /** 设置数据域（缩放 / 联动入口）。 */
+    setDomain(axis: 'x' | 'y', domain: any[], source?: string): this;
+    /** 恢复完整数据域。 */
+    resetZoom(): this;
+    /** 切换系列显隐（图例点击、程序化控制都走这里）。 */
+    toggleSeries(seriesId: string, forceSelected?: boolean): this;
+    isSeriesSelected(seriesId: string): boolean;
+    /**
+     * 切换饼图扇区显隐（极坐标图例点击走这里）。
+     * 扇区键是 `seriesId#dataIndex`，与系列显隐彼此独立。
+     */
+    toggleSlice(seriesId: string, dataIndex: number, forceSelected?: boolean): this;
+    /** 键盘 / 程序化焦点：把悬停定位到某个数据点。 */
+    showHoverAt(seriesId: string, dataIndex: number): this;
+    /** 跨图联动：按 x 数据值显示悬停。 */
+    showHoverAtValue(xValue: any): this;
+    clearHover(): this;
+    getSelection(): any[];
+    clearSelection(): this;
+    /** 当前数据域。 */
+    getDomain(axis: 'x' | 'y'): any[];
+    /** 指定 y 轴的数据域（多轴叠加时按 index 区分）。 */
+    getAxisDomain(index: number): any[];
+    /** 设置指定 y 轴的数据域（多轴叠加时的程序化控制）。 */
+    setAxisDomain(index: number, domain: any[], source?: string): this;
+    /** 完整数据域（未缩放）。 */
+    fullDomain(axis: 'x' | 'y'): any[];
+    /** canvas 元素（无障碍镜像等 DOM 相关能力需要）。 */
+    get canvasElement(): any;
+    /** 数据表：屏幕阅读器可直接读取的「图表等价文本」。 */
+    getDataTable(): DataTable;
+    /**
+     * 无障碍节点树：引擎的组件树 + 逐数据点的虚拟节点。
+     * 应用层可据此构建自己的 DOM 镜像（焦点环、行内提示等）。
+     */
+    getA11yTree(options?: A11yTreeOptions): any[];
+    /**
+     * 在 canvas 旁挂载视觉隐藏的数据表 + aria-live 播报区，
+     * 让屏幕阅读器既能读到整张数据表，也能听到当前悬停/键盘导航到的数据点。
+     */
+    attachA11yMirror(): boolean;
+    detachA11yMirror(): void;
+    get a11yMirrorAttached(): boolean;
+    /** 手动播报一段无障碍文本（自定义交互时用）。 */
+    announceA11y(text: string): void;
+    on(event: string, fn: (payload: any) => void, scope?: any): this;
+    once(event: string, fn: (payload: any) => void, scope?: any): this;
+    off(event: string, fn?: (payload: any) => void, scope?: any): this;
+    emit(event: string, payload?: any): boolean;
+    /**
+     * 在「静默」状态下执行一段操作：期间抛出的事件不会对外广播。
+     * 跨图联动用它打断 A→B→A 的事件回环，同时保留内部的视觉更新。
+     */
+    silent<T>(fn: () => T): T;
+    /** 手动重排（响应式容器变化时调用）。不传尺寸则读取 canvas 的内容盒尺寸。 */
+    resize(cssWidth?: number, cssHeight?: number): this;
+    destroy(): void;
+    /** 等待下一帧渲染完成（测试与截图场景很有用）。 */
+    nextFrame(): Promise<void>;
+    /** 便捷方法：立即标脏并等待一帧（等价于 requestRender + nextFrame）。 */
+    render(): Promise<void>;
+    /** 文本格式化（坐标轴 / 提示框共用）。 */
+    formatAxisValue(axis: 'x' | 'y', value: any): string;
+    /** 导出成图片（透传引擎的 canvas 能力）：常用于「保存为 PNG」。 */
+    toDataURL(type?: string, quality?: any): string;
+    /** 导出成 Blob（浏览器环境）。 */
+    toBlob(callback: (blob: any) => void, type?: string, quality?: any): void;
+    /**
+     * 从快照还原一个图表（静态工厂，等价于先 new 再 fromJSONObject）。
+     *
+     * ```ts
+     * const json = chart.toJSONString();
+     * const restored = ICEChart.restore('canvas-2', json);
+     * ```
+     */
+    static restore(target: any, snapshot: ChartSnapshot | string, options?: SnapshotRestoreOptions & {
+        chartOptions?: ICEChartOptions;
+        initialOption?: ChartOption;
+    }): ICEChart;
+    /**
+     * 导出图表快照（可 JSON 化）。
+     *
+     * 序列化的**唯一事实来源是 option**（声明式规格），不是引擎的组件树：
+     * 组件树只是 option 的渲染投影，里面没有数据语义（比例尺、数据点、命中缓存），
+     * 反序列化一棵组件树只会得到一个空壳。所以这里存的是
+     * 「option + 视图窗口 + 图例/扇区显隐」，这三样足以完整重建图形。
+     *
+     * 注意：函数字段（formatter 等）无法进 JSON，导出时会被丢弃；
+     * 还原时用 `restore(target, snapshot, { optionPatch })` 或 `fromJSONObject(snapshot, { patch })` 补回来。
+     */
+    toJSON(): {
+        version: number;
+        option: ChartOption;
+        view: {
+            x: [any, any] | null;
+            y: [any, any] | null;
+            yAxes: Array<[any, any] | null>;
+        };
+        hidden: Record<string, boolean>;
+        hiddenSlices: Record<string, boolean>;
+    };
+    toJSONString(): string;
+    fromJSONString(json: string, options?: SnapshotRestoreOptions): this;
+    fromJSONObject(snapshot: any, options?: SnapshotRestoreOptions): this;
+    private loadSnapshot;
+    private applyOption;
+    /** dataZoom 的 start/end 只影响初始窗口。 */
+    private initialWindow;
+    /** 用当前 viewState 重新归一化 → 布局 → 同步组件。 */
+    /** 启动数据域过渡：每帧按系列动画进度插值 y 轴数据域。 */
+    private startDomainTransition;
+    private stepDomainTransition;
+    private stopDomainTransition;
+    private rebuild;
+    private buildScales;
+    private syncComponents;
+    /** 当前 x 数据域在完整数据域中的比例窗口（0~1），供 dataZoom 滑块显示。 */
+    domainFractions(): [number, number];
+    /** 由 dataZoom 滑块的比例窗口反推数据域。 */
+    setDomainFromFractions(start: number, end: number, source?: string): this;
+    /** 让 y 轴组件数量 / 位置与 norm.yAxes 保持一致（轴数量变化时增删组件）。 */
+    private syncAxisComponents;
+    private syncSeries;
+    /**
+     * 让引擎的 AnimationManager 把 progress 从 0 推到 1。
+     *
+     * 实测（`hitTest` 逐帧采样）：引擎在补间期间把 `interactive` 置 false 只发生在
+     * 同一帧的同步块内（保存→置 false→补间→恢复），事件处理与命中检测看不到，
+     * 所以动画期间交互照常可用 —— 不需要额外的「驱动组件」绕开它。
+     */
+    playStage(seriesComponent: SeriesBase, stage: {
+        duration?: number;
+        delay?: number;
+        easing?: string;
+        stagger?: number;
+        kind?: 'enter' | 'update';
+    }): void;
+    /** 兼容旧 API：按「入场」阶段播放。 */
+    playEnter(seriesComponent: SeriesBase, duration: number, easing: string): void;
+    /** 把当前所有未完成的动画一次性推到终态（截图 / 测试 / 无障碍瞬时模式用）。 */
+    finishAnimations(): this;
+    private currentRange;
+    private clampDomain;
+    /** index = -1 表示 x 轴，>=0 表示对应的 y 轴。 */
+    private clampAxisDomain;
+    private canvasRect;
+    private observeResize;
+    private registerTypes;
+}
+/** 计算分组柱形的槽位：同 stack 的系列共用一个槽，其余各自一槽。 */
+export declare function computeBarSlots(series: InternalSeries[]): Record<string, {
+    index: number;
+    count: number;
+}>;
+/** 某个饼图系列里被隐藏的扇区下标。 */
+export declare function hiddenSliceIndexes(norm: NormalizedOption, seriesId: string): number[];
+/**
+ * 工厂函数：第二个参数既可以是声明式 option，也可以是 `toJSON()` 产出的快照。
+ *
+ * ```ts
+ * const chart = createChart('canvas-1', option);
+ * const snapshot = chart.toJSONString();
+ * const restored = createChart('canvas-2', snapshot);   // 直接吃快照
+ * ```
+ */
+export declare function createChart(target: any, optionOrSnapshot: ChartOption | ChartSnapshot | string, chartOptions?: ICEChartOptions): ICEChart;

package/dist/types/ICEChart.d.ts

@@ -0,0 +1,330 @@
+import { ICE, ICEGroup } from 'ice-render';
+import type { ChartOption, DataItem } from './types';
+import type { ChartLayout, InternalSeries, NormalizedOption } from './internal';
+import { GridLines } from './components/GridLines';
+import { PlotArea } from './components/PlotArea';
+import { Axis } from './components/Axis';
+import { Legend } from './components/Legend';
+import { Title } from './components/Title';
+import { Tooltip } from './components/Tooltip';
+import { Crosshair } from './components/Crosshair';
+import { Highlight } from './components/Highlight';
+import { Brush } from './components/Brush';
+import { RadarGrid } from './components/RadarGrid';
+import { PolarGrid } from './components/PolarGrid';
+import { DataZoomSlider } from './components/DataZoomSlider';
+import type { SeriesBase } from './components/series/SeriesBase';
+import { InteractionController } from './interaction/InteractionController';
+import { type A11yTreeOptions, type DataTable } from './a11y';
+/** 快照格式版本：结构变化时递增，还原时校验。 */
+export declare const SNAPSHOT_VERSION = 1;
+export { setMotionPreference, getMotionPreference, shouldAnimate } from './animation/motion';
+export type { MotionPreference } from './animation/motion';
+export interface SnapshotRestoreOptions {
+    /**
+     * 还原时叠加的非序列化配置补丁（formatter、函数型回调等）。
+     * series 按 id 或下标逐项合并，不会覆盖快照里的数据。
+     */
+    optionPatch?: Partial<ChartOption> & {
+        series?: any[];
+    };
+}
+export interface ChartSnapshot {
+    version: number;
+    option: ChartOption;
+    view: {
+        x: [any, any] | null;
+        y: [any, any] | null;
+        yAxes: Array<[any, any] | null>;
+    };
+    hidden: Record<string, boolean>;
+    hiddenSlices: Record<string, boolean>;
+}
+/** 判断一个对象是不是 ice-chart 快照（用于 createChart 的入参分派）。 */
+export declare function isChartSnapshot(value: any): boolean;
+/** 把补丁合进快照里的 option：series 按 id/下标逐项合并，其余字段浅覆盖。 */
+export declare function mergeOptionPatch(base: any, patch: any): any;
+export interface ICEChartOptions {
+    renderMode?: 'dirty-rect' | 'full';
+    dpr?: number;
+    /** 监听容器尺寸变化并自动重排（需要 ResizeObserver）。 */
+    autoResize?: boolean;
+}
+export interface ApplyOptionOptions {
+    /** true = 播「更新」动画；'enter' = 播「入场」动画；false = 不播。 */
+    animate?: boolean | 'enter' | 'update';
+    /** 保留当前缩放窗口（图例切换、数据更新时用）。 */
+    preserveView?: boolean;
+}
+/**
+ * ICEChart：把一份声明式 option 编译成 ice-render 组件树，并挂上交互层。
+ *
+ * 分工：
+ * - 归一化（数据 → 数据域 / 堆叠）由 option/normalize 负责，纯函数、可单测；
+ * - 布局（标题 / 图例 / 坐标轴 / 绘图区）由 layout 负责，纯函数、可单测；
+ * - 渲染由 ice-render 组件负责（脏矩形局部重绘、离屏缓存、HiDPI 全部由引擎兜底）；
+ * - 交互由 InteractionController 负责，对外只抛语义事件。
+ */
+export declare class ICEChart {
+    ice: ICE;
+    option: ChartOption;
+    norm: NormalizedOption;
+    layout: ChartLayout;
+    root: ICEGroup;
+    plotArea: PlotArea;
+    grid: GridLines;
+    radarGrid: RadarGrid;
+    /** 极坐标网格（r(θ) 曲线用；画在直角坐标场景里，配合 aspect:'equal'）。 */
+    polarGrid: PolarGrid;
+    axisX: Axis;
+    /** y 轴组件，与 norm.yAxes 一一对应（axisYList[0] 是主 y 轴）。 */
+    axisYList: Axis[];
+    legend: Legend | null;
+    titleComponent: Title | null;
+    tooltip: Tooltip | null;
+    crosshair: Crosshair | null;
+    highlight: Highlight | null;
+    brushComponent: Brush | null;
+    dataZoomSlider: DataZoomSlider | null;
+    seriesComponents: SeriesBase[];
+    controller: InteractionController;
+    /** 交互层使用的别名（与 InteractionHost 接口约定一致）。 */
+    get brush(): Brush | null;
+    /** 未经缩放/筛选的完整数据域（缩放约束与跨图联动用）。 */
+    fullXDomain: any[];
+    fullYDomain: any[];
+    /** 每个 y 轴的完整数据域（未缩放）。 */
+    fullYDomains: any[][];
+    private emitter;
+    private canvasEl;
+    private chartOptions;
+    private viewState;
+    /** 存在 function 系列时为真：y 轴数据域每次重建都按可视 x 区间重算（自动贴合）。 */
+    private autoYCurve;
+    private hiddenIds;
+    private hiddenSlices;
+    private seriesSignature;
+    private axisSignature;
+    private resizeObserver;
+    private destroyed;
+    /** 抑制对外事件的重入深度（跨图联动时避免 A→B→A 的回环）。 */
+    private silenceDepth;
+    private a11yMirror;
+    /**
+     * 更新动画期间的坐标轴数据域过渡。
+     *
+     * 数据更新时 y 轴数据域常常会变（例如最大值从 50 掉到 40），如果域瞬跳，
+     * 柱子会在动画**开始的那一帧**整体位移一下，值插值反而看不见。
+     * 所以域要和系列的值一起插值：每帧按同一进度重算域与坐标，动画结束时再回到常规路径。
+     */
+    private domainTransition;
+    private domainFrameHandler;
+    constructor(target: any, option: ChartOption, chartOptions?: ICEChartOptions);
+    /** 更新配置。默认保留当前缩放窗口，可用 resetZoom 恢复。 */
+    setOption(option: ChartOption, options?: ApplyOptionOptions): this;
+    /** 取当前配置（函数字段保留；持久化请用 toJSON）。 */
+    getOption(): ChartOption;
+    /**
+     * 函数绘图 / 参数曲线的表达式诊断（**回答「用户是不是写错了公式」**）。
+     *
+     * 三类都覆盖：
+     * - `error`：语法错误（带位置）、未定义的变量、在当前区间内没有任何可绘制的值；
+     * - `warning`：参数定义了没用上、输出恒定（画出来是一条水平线）。
+     *
+     * 表达式来自用户输入，写错**不会**让图表崩掉（那会让表单很难用），
+     * 但错误必须能被拿到：表单据此标红 / 提示，控制台不必猜。
+     */
+    expressionDiagnostics(): Array<{
+        seriesId: string;
+        diagnostics: NonNullable<InternalSeries['expressionDiagnostics']>;
+    }>;
+    /** 只取错误（标红用）。需要警告（提示用）请用 `expressionDiagnostics()`。 */
+    expressionErrors(): Array<{
+        seriesId: string;
+        message: string;
+    }>;
+    /** 更新单个系列的数据。 */
+    setData(seriesIdOrIndex: string | number, data: DataItem[]): this;
+    /**
+     * **追加**数据（实时数据流专用）：把新点接到系列末尾，超出 `maxPoints` 时从头裁掉，
+     * 形成滑动窗口。相对 `setData` 的两点差别：
+     *
+     * 1. **不做值插值**（`animate` 默认 false）：窗口滑动会让下标整体前移，
+     *    插值会把「这一点」插向「下一点的值」，看起来像被拖住。
+     *    流畅度由推送频率决定（60Hz 推送就是 60fps 的平滑滚动）；
+     * 2. 只重算被追加的系列所在的那条链路（走 `applyOption` 的常规更新路径，`preserveView` 保持缩放窗口）。
+     *
+     * ```ts
+     * chart.appendData('cpu', [[t, value]], { maxPoints: 180 });
+     * ```
+     */
+    appendData(seriesIdOrIndex: string | number, items: DataItem[], options?: {
+        maxPoints?: number;
+        animate?: boolean;
+    }): this;
+    /** 设置数据域（缩放 / 联动入口）。 */
+    setDomain(axis: 'x' | 'y', domain: any[], source?: string): this;
+    /** 恢复完整数据域。 */
+    resetZoom(): this;
+    /** 切换系列显隐（图例点击、程序化控制都走这里）。 */
+    toggleSeries(seriesId: string, forceSelected?: boolean): this;
+    isSeriesSelected(seriesId: string): boolean;
+    /**
+     * 切换饼图扇区显隐（极坐标图例点击走这里）。
+     * 扇区键是 `seriesId#dataIndex`，与系列显隐彼此独立。
+     */
+    toggleSlice(seriesId: string, dataIndex: number, forceSelected?: boolean): this;
+    /** 键盘 / 程序化焦点：把悬停定位到某个数据点。 */
+    showHoverAt(seriesId: string, dataIndex: number): this;
+    /** 跨图联动：按 x 数据值显示悬停。 */
+    showHoverAtValue(xValue: any): this;
+    clearHover(): this;
+    getSelection(): any[];
+    clearSelection(): this;
+    /** 当前数据域。 */
+    getDomain(axis: 'x' | 'y'): any[];
+    /** 指定 y 轴的数据域（多轴叠加时按 index 区分）。 */
+    getAxisDomain(index: number): any[];
+    /** 设置指定 y 轴的数据域（多轴叠加时的程序化控制）。 */
+    setAxisDomain(index: number, domain: any[], source?: string): this;
+    /** 完整数据域（未缩放）。 */
+    fullDomain(axis: 'x' | 'y'): any[];
+    /** canvas 元素（无障碍镜像等 DOM 相关能力需要）。 */
+    get canvasElement(): any;
+    /** 数据表：屏幕阅读器可直接读取的「图表等价文本」。 */
+    getDataTable(): DataTable;
+    /**
+     * 无障碍节点树：引擎的组件树 + 逐数据点的虚拟节点。
+     * 应用层可据此构建自己的 DOM 镜像（焦点环、行内提示等）。
+     */
+    getA11yTree(options?: A11yTreeOptions): any[];
+    /**
+     * 在 canvas 旁挂载视觉隐藏的数据表 + aria-live 播报区，
+     * 让屏幕阅读器既能读到整张数据表，也能听到当前悬停/键盘导航到的数据点。
+     */
+    attachA11yMirror(): boolean;
+    detachA11yMirror(): void;
+    get a11yMirrorAttached(): boolean;
+    /** 手动播报一段无障碍文本（自定义交互时用）。 */
+    announceA11y(text: string): void;
+    on(event: string, fn: (payload: any) => void, scope?: any): this;
+    once(event: string, fn: (payload: any) => void, scope?: any): this;
+    off(event: string, fn?: (payload: any) => void, scope?: any): this;
+    emit(event: string, payload?: any): boolean;
+    /**
+     * 在「静默」状态下执行一段操作：期间抛出的事件不会对外广播。
+     * 跨图联动用它打断 A→B→A 的事件回环，同时保留内部的视觉更新。
+     */
+    silent<T>(fn: () => T): T;
+    /** 手动重排（响应式容器变化时调用）。不传尺寸则读取 canvas 的内容盒尺寸。 */
+    resize(cssWidth?: number, cssHeight?: number): this;
+    destroy(): void;
+    /** 等待下一帧渲染完成（测试与截图场景很有用）。 */
+    nextFrame(): Promise<void>;
+    /** 便捷方法：立即标脏并等待一帧（等价于 requestRender + nextFrame）。 */
+    render(): Promise<void>;
+    /** 文本格式化（坐标轴 / 提示框共用）。 */
+    formatAxisValue(axis: 'x' | 'y', value: any): string;
+    /** 导出成图片（透传引擎的 canvas 能力）：常用于「保存为 PNG」。 */
+    toDataURL(type?: string, quality?: any): string;
+    /** 导出成 Blob（浏览器环境）。 */
+    toBlob(callback: (blob: any) => void, type?: string, quality?: any): void;
+    /**
+     * 从快照还原一个图表（静态工厂，等价于先 new 再 fromJSONObject）。
+     *
+     * ```ts
+     * const json = chart.toJSONString();
+     * const restored = ICEChart.restore('canvas-2', json);
+     * ```
+     */
+    static restore(target: any, snapshot: ChartSnapshot | string, options?: SnapshotRestoreOptions & {
+        chartOptions?: ICEChartOptions;
+        initialOption?: ChartOption;
+    }): ICEChart;
+    /**
+     * 导出图表快照（可 JSON 化）。
+     *
+     * 序列化的**唯一事实来源是 option**（声明式规格），不是引擎的组件树：
+     * 组件树只是 option 的渲染投影，里面没有数据语义（比例尺、数据点、命中缓存），
+     * 反序列化一棵组件树只会得到一个空壳。所以这里存的是
+     * 「option + 视图窗口 + 图例/扇区显隐」，这三样足以完整重建图形。
+     *
+     * 注意：函数字段（formatter 等）无法进 JSON，导出时会被丢弃；
+     * 还原时用 `restore(target, snapshot, { optionPatch })` 或 `fromJSONObject(snapshot, { patch })` 补回来。
+     */
+    toJSON(): {
+        version: number;
+        option: ChartOption;
+        view: {
+            x: [any, any] | null;
+            y: [any, any] | null;
+            yAxes: Array<[any, any] | null>;
+        };
+        hidden: Record<string, boolean>;
+        hiddenSlices: Record<string, boolean>;
+    };
+    toJSONString(): string;
+    fromJSONString(json: string, options?: SnapshotRestoreOptions): this;
+    fromJSONObject(snapshot: any, options?: SnapshotRestoreOptions): this;
+    private loadSnapshot;
+    private applyOption;
+    /** dataZoom 的 start/end 只影响初始窗口。 */
+    private initialWindow;
+    /** 用当前 viewState 重新归一化 → 布局 → 同步组件。 */
+    /** 启动数据域过渡：每帧按系列动画进度插值 y 轴数据域。 */
+    private startDomainTransition;
+    private stepDomainTransition;
+    private stopDomainTransition;
+    private rebuild;
+    private buildScales;
+    private syncComponents;
+    /** 当前 x 数据域在完整数据域中的比例窗口（0~1），供 dataZoom 滑块显示。 */
+    domainFractions(): [number, number];
+    /** 由 dataZoom 滑块的比例窗口反推数据域。 */
+    setDomainFromFractions(start: number, end: number, source?: string): this;
+    /** 让 y 轴组件数量 / 位置与 norm.yAxes 保持一致（轴数量变化时增删组件）。 */
+    private syncAxisComponents;
+    private syncSeries;
+    /**
+     * 让引擎的 AnimationManager 把 progress 从 0 推到 1。
+     *
+     * 实测（`hitTest` 逐帧采样）：引擎在补间期间把 `interactive` 置 false 只发生在
+     * 同一帧的同步块内（保存→置 false→补间→恢复），事件处理与命中检测看不到，
+     * 所以动画期间交互照常可用 —— 不需要额外的「驱动组件」绕开它。
+     */
+    playStage(seriesComponent: SeriesBase, stage: {
+        duration?: number;
+        delay?: number;
+        easing?: string;
+        stagger?: number;
+        kind?: 'enter' | 'update';
+    }): void;
+    /** 兼容旧 API：按「入场」阶段播放。 */
+    playEnter(seriesComponent: SeriesBase, duration: number, easing: string): void;
+    /** 把当前所有未完成的动画一次性推到终态（截图 / 测试 / 无障碍瞬时模式用）。 */
+    finishAnimations(): this;
+    private currentRange;
+    private clampDomain;
+    /** index = -1 表示 x 轴，>=0 表示对应的 y 轴。 */
+    private clampAxisDomain;
+    private canvasRect;
+    private observeResize;
+    private registerTypes;
+}
+/** 计算分组柱形的槽位：同 stack 的系列共用一个槽，其余各自一槽。 */
+export declare function computeBarSlots(series: InternalSeries[]): Record<string, {
+    index: number;
+    count: number;
+}>;
+/** 某个饼图系列里被隐藏的扇区下标。 */
+export declare function hiddenSliceIndexes(norm: NormalizedOption, seriesId: string): number[];
+/**
+ * 工厂函数：第二个参数既可以是声明式 option，也可以是 `toJSON()` 产出的快照。
+ *
+ * ```ts
+ * const chart = createChart('canvas-1', option);
+ * const snapshot = chart.toJSONString();
+ * const restored = createChart('canvas-2', snapshot);   // 直接吃快照
+ * ```
+ */
+export declare function createChart(target: any, optionOrSnapshot: ChartOption | ChartSnapshot | string, chartOptions?: ICEChartOptions): ICEChart;