@damoqiongqiu/ice-chart 0.17.0

package/dist/types/components/series/SeriesBase.d.ts

@@ -0,0 +1,214 @@
+import { ChartComponent } from '../ChartComponent';
+import type { ChartTheme, SeriesType } from '../../types';
+import type { DataPoint, InternalSeries, Rect } from '../../internal';
+import type { Scale } from '../../scale';
+export interface SeriesCoord {
+    plot: Rect;
+    canvas: Rect;
+    xScale: Scale;
+    yScale: Scale;
+    /** 该系列绑定的 y 轴下标。 */
+    yAxisIndex?: number;
+    theme: ChartTheme;
+}
+export interface BarSlot {
+    index: number;
+    count: number;
+}
+/**
+ * 系列基类：数据 → 像素的缓存、动画插值、命中判定都收敛在这里。
+ *
+ * 三件事值得注意：
+ *
+ * 1. **像素缓存**：数据点的像素坐标只在数据 / 比例尺 / 尺寸变化时重算一次，
+ *    render 与命中判定共用同一份缓存 —— 保证「画出来的样子」和「点得到的位置」必然一致。
+ *
+ * 2. **命中判定进引擎**：`containsLocalPoint` 由子类实现为「按数据语义判定」，
+ *    于是 `ice.hitTest()` / 引擎事件派发天然就能分辨「点在折线上」还是「点在空白处」，
+ *    不需要在图表外面再写一套坐标反查。
+ *
+ * 3. **动画走引擎的 AnimationManager**：`state.progress` 由引擎逐帧写入，
+ *    本组件按 progress 在「上一份数据的有效值」与「新数据」之间插值。
+ */
+export declare abstract class SeriesBase extends ChartComponent {
+    abstract seriesType: SeriesType;
+    series: InternalSeries;
+    /** 图表主题（由 Chart 注入，供绘制标签 / 文本使用）。 */
+    chartTheme: ChartTheme | null;
+    /** 被隐藏的数据项下标（饼图扇区 / 漏斗阶段）。 */
+    hiddenSlices: number[];
+    coord: SeriesCoord | null;
+    /** 分组柱形的位置（由 Chart 计算）。 */
+    barSlot: BarSlot;
+    /** 每个点的像素坐标，2n 长度，[x0,y0,x1,y1,...]；缺失点为 NaN。 */
+    protected pixels: Float64Array;
+    /** 每个点的有效数据值 [base, top]，用于动画插值与柱形绘制。 */
+    protected effective: Float64Array;
+    /** 上一帧的有效值，作为动画起点。 */
+    protected fromEffective: Float64Array | null;
+    /** 实际参与绘制的点下标（降采样后可能少于总点数）；null 表示全部点。 */
+    protected renderIndices: number[] | null;
+    /** 像素 x 是否单调递增（降采样与二分查找的前提）。 */
+    protected xMonotonic: boolean;
+    /** 第三维（气泡尺寸）的取值范围，映射到 symbolSizeRange。 */
+    protected sizeExtent: [number, number];
+    /** 每个数据项各自的动画进度（错峰入场用），0~1。 */
+    protected itemProgress: Float64Array;
+    /** 错峰比例：0 = 所有项同时动画。 */
+    protected stagger: number;
+    /** 当前动画阶段：enter 可以「画出来」，update 只能「动起来」。 */
+    protected animationKind: 'enter' | 'update';
+    /** 当前悬停的数据项（0 表示没有）。 */
+    hoverIndex: number | null;
+    private cacheKey;
+    /** 散点等「每个点都必须画」的系列不参与降采样。 */
+    protected supportsSampling: boolean;
+    /**
+     * 是否把绘制裁剪到组件盒（= 本场景的绘图区）。
+     *
+     * 直角坐标系列必须开：缩放后落在窗口外的数据点会被映射到很远的位置，
+     * 不裁剪就会一路画到 y 轴标签、图例甚至画布外面去（用户实测反馈的问题）。
+     * 折线要的是「被绘图区边缘裁掉」，而不是「在边界处断开」，所以只能靠 clip，不能靠过滤点。
+     */
+    protected clipToBox: boolean;
+    private localBoxScratch;
+    constructor(series: InternalSeries, props: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        zIndex?: number;
+    });
+    /** 组件本地盒向四周外扩，容纳线宽、标记与阴影。 */
+    protected __localBox(): number[];
+    protected paintPad(): number;
+    /**
+     * 数据点尺寸：三种来源按优先级解析。
+     * 1. `symbolSize` 是函数 → 交给调用方决定；
+     * 2. 数据项带第三维（气泡图的 `[x, y, size]`）→ 按 series 内的取值范围映射到 `symbolSizeRange`；
+     * 3. 固定数值 `symbolSize`。
+     */
+    symbolSizeAt(index: number): number;
+    /** 本系列的最大标记尺寸（脏矩形留白与命中容差要用）。 */
+    protected maxSymbolSize(): number;
+    setCoord(coord: SeriesCoord): this;
+    /** 设置被隐藏的数据项（图表层在每次同步时写入）。 */
+    setHiddenSlices(indexes: number[]): this;
+    /** 图表层在每次播放动画前注入该阶段的配置（错峰比例会存下来供逐项计算）。 */
+    setAnimationStage(stage: {
+        stagger?: number;
+        kind?: 'enter' | 'update';
+    } | null | undefined): this;
+    /** 是否正在播「入场」动画（用于「画出来」这类只在入场成立的动效）。 */
+    protected isEntering(): boolean;
+    /** 单个数据项的动画进度：把整体进度按「波浪」拆到每一项。 */
+    protected progressFor(index: number, total: number): number;
+    /** 每项进度的缓存（数据量变化时重建）。 */
+    protected computeItemProgress(): void;
+    /** 当前动画状态（测试与调试用；不参与序列化）。 */
+    getAnimationState(): {
+        progress: number;
+        kind: 'enter' | 'update';
+        stagger: number;
+        itemProgress: number[];
+    };
+    /**
+     * 设置/清除悬停项，并用引擎动画把 `highlightT` 从 0 推到 1（或反向）。
+     *
+     * 反馈动画由组件自己启动：它持有 `ice.animationManager`，不需要图表层代劳，
+     * 这样「悬停哪个图元」这件事就完全收敛在系列内部。
+     */
+    setHoverIndex(index: number | null): void;
+    /** 悬停反馈的进度（0~1）。 */
+    highlightT(): number;
+    /** 某个数据项当前的高亮强度：只有被悬停的那一项 > 0。 */
+    protected hoverBoost(index: number, amount?: number, t?: number): number;
+    /** 悬停叠加层的强度（0~1）：只有被悬停的那一项 > 0。 */
+    protected hoverAlpha(index: number): number;
+    /**
+     * 在被悬停的矩形上叠一层「提亮 + 描边」。
+     *
+     * 刻意**只叠加、不改几何**：像热力图 / 树图 / K 线这种相邻图元紧挨着的类型，
+     * 改宽高会让命中区域与渲染区域分叉（指针停在边缘会来回抖），
+     * 叠加描边既能表达强调，又完全不动命中判定。
+     */
+    protected drawHoverOverlay(index: number, rect: Rect, options?: {
+        radius?: number;
+        fill?: string;
+        stroke?: string;
+        lineWidth?: number;
+    }): void;
+    /**
+     * 派生几何的缓存键。
+     *
+     * **必须**把参与动画的 state 字段一起放进来（progress / 阶段 / 错峰），
+     * 否则动画期间键不变、缓存命中，几何会冻结在动画开始的那一帧。
+     * 子类覆写 `rebuildPixels` 时用自己的几何参数组键，请一律走这个方法。
+     */
+    protected buildSeriesKey(parts: Array<any>): string;
+    /**
+     * 坐标系指纹：绘图区矩形 + 各比例尺的数据域。
+     *
+     * 子类自己拼键时最容易漏的就是数据域 —— 表面看不出来，实际后果是
+     * **像素缓存不失效**：缩放 / 平移 / 数据域过渡之后 `pixels` 还是旧位置，
+     * 「看得见的点」与「点得到的点」就此分叉（悬停高亮画在别处、命中判空）。
+     * 只在键里放域的**端点 + 长度**，因为这个函数动画期间每帧都会被调用，不能全量 join。
+     */
+    private coordKey;
+    /**
+     * 替换数据。`animate` 为真时，把当前有效值记为动画起点（首次进入时从 0 开始），
+     * 由 Chart 触发引擎动画把 state.progress 从 0 推到 1。
+     */
+    updateSeries(series: InternalSeries, animate: boolean, preserveAnimation?: boolean): this;
+    /** 与当前绘制一致的像素位置；缺失点返回 null。 */
+    pixelAt(index: number): [number, number] | null;
+    /** 数据点的像素矩形（柱形用）。 */
+    barRectAt(_index: number): Rect | null;
+    /** 命中判定：返回数据下标，-1 表示未命中。入参是组件本地像素坐标。 */
+    abstract hitTestIndex(localX: number, localY: number): number;
+    protected containsLocalPoint(localX: number, localY: number): boolean;
+    protected progress(): number;
+    /** 计算每个点的有效数据值（含动画插值）。 */
+    protected computeEffective(): void;
+    /** 数据 → 像素（带缓存）。 */
+    protected rebuildPixels(force?: boolean): void;
+    /**
+     * 计算实际绘制的点下标。
+     *
+     * 默认策略：点数超过「绘图区宽度 × 3」时用 LTTB 抽稀 —— 一个像素宽度画 3 个点已经过剩，
+     * 继续画只是白白光栅化。首尾点与极值点一定保留，所以看起来仍然「像原曲线」。
+     * 命中判定不受影响，它始终读全量像素缓存。
+     */
+    protected buildRenderIndices(n: number, plotWidth: number): number[] | null;
+    /** 实际参与绘制的点数。 */
+    protected renderCount(): number;
+    /** 第 k 个参与绘制的点对应的原始下标。 */
+    protected renderIndexAt(k: number): number;
+    /**
+     * 按 x 像素找最近的数据下标。
+     *
+     * 单调数据用二分查找（大点数下每次 mousemove 都是 O(n) 会直接掉帧），
+     * 非单调数据退化为线性扫描。
+     */
+    nearestIndexAtX(localX: number): number;
+    private buildCacheKey;
+    /** 遍历像素点，跳过缺失点形成的断点。 */
+    protected eachSegment(fn: (x0: number, y0: number, x1: number, y1: number, i: number) => void): void;
+    protected pointColor(_index: number): string;
+    protected lineWidthDevice(): number;
+    protected opacity(): number;
+    protected beginDraw(): void;
+    protected endDraw(): void;
+    protected drawSymbol(x: number, y: number, shape: string, size: number, fill: string, stroke: string): void;
+    protected pointByIndex(index: number): DataPoint | null;
+}
+/**
+ * LTTB（Largest Triangle Three Buckets）抽稀。
+ *
+ * 输入是渲染用的像素点集（x/y 交错，含 NaN 断点），返回保留下来的下标数组。
+ * 首点与末点一定保留；每个桶内取「与前后桶均值构成三角形面积最大」的点，
+ * 因此尖峰不会被抹平 —— 这正是它比等间隔抽样更适合行情/监控曲线的原因。
+ */
+export declare function lttbIndices(pixels: Float64Array, n: number, threshold: number): number[];
+/** 数据点第三维的取值范围（气泡尺寸映射用）。 */
+export declare function computeSizeExtent(points: DataPoint[]): [number, number];

package/dist/types/components/series/TreemapSeries.d.mts

@@ -0,0 +1,48 @@
+import { SeriesBase } from './SeriesBase.mjs';
+import type { SeriesType, TreemapOption } from '../../types.mjs';
+import type { Rect } from '../../internal.mjs';
+import type { TreemapNodeLayout } from '../../layout/treemap.mjs';
+export interface TreemapSeriesCoord {
+    plot: Rect;
+    canvas: Rect;
+    /** 布局结果（图表坐标系）。 */
+    layout: TreemapNodeLayout[];
+    options: TreemapOption;
+}
+/**
+ * 矩形树图：用嵌套矩形表达层级数据的构成。
+ *
+ * 布局是纯函数（`layoutTreemap`），这里只负责绘制与命中。
+ * 命中返回**最深的那个节点**（点在大类目里的小类目上，命中的是小类目）。
+ */
+export declare class TreemapSeries extends SeriesBase {
+    seriesType: SeriesType;
+    treemap: TreemapSeriesCoord | null;
+    protected clipToBox: boolean;
+    private treemapKey;
+    /** 更新动画的起点布局（按「层级:名称」索引，跨数据更新仍能对上同一个节点）。 */
+    private morphFrom;
+    private morphing;
+    /**
+     * 数据更新时记下当前布局，下一次渲染按进度在「旧矩形 → 新矩形」之间插值。
+     * 这是 treemap 最值钱的动画：布局一变，矩形是「长大/挪过去」而不是瞬间跳。
+     */
+    updateSeries(series: any, animate: boolean, preserveAnimation?: boolean): this;
+    /** 节点的当前矩形：更新动画期间在旧布局与新布局之间插值。 */
+    private rectCache;
+    /**
+     * 节点当前矩形。
+     *
+     * 关键点：**子节点在父节点的插值结果内部按相对位置缩放**，而不是各自独立插值。
+     * 独立插值会让兄弟矩形在中途拼不满父矩形（露出父色形成缺口/错位），
+     * 这是树图布局过渡最容易被忽略的视觉缺陷。
+     */
+    private rectOf;
+    setCoord(coord: any): this;
+    protected paintPad(): number;
+    highlightRectAt(index: number): Rect | null;
+    /** 像素缓存 = 每个节点的矩形中心。 */
+    protected rebuildPixels(): void;
+    hitTestIndex(localX: number, localY: number): number;
+    protected doRender(): void;
+}

package/dist/types/components/series/TreemapSeries.d.ts

@@ -0,0 +1,48 @@
+import { SeriesBase } from './SeriesBase';
+import type { SeriesType, TreemapOption } from '../../types';
+import type { Rect } from '../../internal';
+import type { TreemapNodeLayout } from '../../layout/treemap';
+export interface TreemapSeriesCoord {
+    plot: Rect;
+    canvas: Rect;
+    /** 布局结果（图表坐标系）。 */
+    layout: TreemapNodeLayout[];
+    options: TreemapOption;
+}
+/**
+ * 矩形树图：用嵌套矩形表达层级数据的构成。
+ *
+ * 布局是纯函数（`layoutTreemap`），这里只负责绘制与命中。
+ * 命中返回**最深的那个节点**（点在大类目里的小类目上，命中的是小类目）。
+ */
+export declare class TreemapSeries extends SeriesBase {
+    seriesType: SeriesType;
+    treemap: TreemapSeriesCoord | null;
+    protected clipToBox: boolean;
+    private treemapKey;
+    /** 更新动画的起点布局（按「层级:名称」索引，跨数据更新仍能对上同一个节点）。 */
+    private morphFrom;
+    private morphing;
+    /**
+     * 数据更新时记下当前布局，下一次渲染按进度在「旧矩形 → 新矩形」之间插值。
+     * 这是 treemap 最值钱的动画：布局一变，矩形是「长大/挪过去」而不是瞬间跳。
+     */
+    updateSeries(series: any, animate: boolean, preserveAnimation?: boolean): this;
+    /** 节点的当前矩形：更新动画期间在旧布局与新布局之间插值。 */
+    private rectCache;
+    /**
+     * 节点当前矩形。
+     *
+     * 关键点：**子节点在父节点的插值结果内部按相对位置缩放**，而不是各自独立插值。
+     * 独立插值会让兄弟矩形在中途拼不满父矩形（露出父色形成缺口/错位），
+     * 这是树图布局过渡最容易被忽略的视觉缺陷。
+     */
+    private rectOf;
+    setCoord(coord: any): this;
+    protected paintPad(): number;
+    highlightRectAt(index: number): Rect | null;
+    /** 像素缓存 = 每个节点的矩形中心。 */
+    protected rebuildPixels(): void;
+    hitTestIndex(localX: number, localY: number): number;
+    protected doRender(): void;
+}

package/dist/types/components/series/WaterfallSeries.d.mts

@@ -0,0 +1,17 @@
+import { BarSeries } from './BarSeries.mjs';
+import type { SeriesType } from '../../types.mjs';
+/**
+ * 瀑布图：在柱状图之上做两件事 ——
+ * 1. 每根柱子的颜色按「增 / 减 / 合计」区分；
+ * 2. 相邻柱子之间画一条连接虚线，标出累计值的传递。
+ *
+ * base/top 的累计在归一化阶段算好（见 applyWaterfall），所以几何直接复用柱状图。
+ */
+export declare class WaterfallSeries extends BarSeries {
+    seriesType: SeriesType;
+    private isTotalItem;
+    private isIncrease;
+    /** 每根柱子的颜色：增（success）/ 减（danger）/ 合计（primary），可配置。 */
+    protected barColorAt(index: number): string;
+    protected doRender(): void;
+}

package/dist/types/components/series/WaterfallSeries.d.ts

@@ -0,0 +1,17 @@
+import { BarSeries } from './BarSeries';
+import type { SeriesType } from '../../types';
+/**
+ * 瀑布图：在柱状图之上做两件事 ——
+ * 1. 每根柱子的颜色按「增 / 减 / 合计」区分；
+ * 2. 相邻柱子之间画一条连接虚线，标出累计值的传递。
+ *
+ * base/top 的累计在归一化阶段算好（见 applyWaterfall），所以几何直接复用柱状图。
+ */
+export declare class WaterfallSeries extends BarSeries {
+    seriesType: SeriesType;
+    private isTotalItem;
+    private isIncrease;
+    /** 每根柱子的颜色：增（success）/ 减（danger）/ 合计（primary），可配置。 */
+    protected barColorAt(index: number): string;
+    protected doRender(): void;
+}

package/dist/types/components/series/createSeries.d.mts

@@ -0,0 +1,10 @@
+import type { InternalSeries } from '../../internal.mjs';
+import { SeriesBase } from './SeriesBase.mjs';
+/** 按系列类型创建对应的渲染组件（工厂，便于后续扩展 candlestick / pie 等）。 */
+export declare function createSeriesComponent(series: InternalSeries, props: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    zIndex?: number;
+}): SeriesBase;

package/dist/types/components/series/createSeries.d.ts

@@ -0,0 +1,10 @@
+import type { InternalSeries } from '../../internal';
+import { SeriesBase } from './SeriesBase';
+/** 按系列类型创建对应的渲染组件（工厂，便于后续扩展 candlestick / pie 等）。 */
+export declare function createSeriesComponent(series: InternalSeries, props: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    zIndex?: number;
+}): SeriesBase;

package/dist/types/components/series/index.d.mts

@@ -0,0 +1,29 @@
+export { SeriesBase } from './SeriesBase.mjs';
+export type { SeriesCoord, BarSlot } from './SeriesBase.mjs';
+export { LineSeries } from './LineSeries.mjs';
+export { AreaSeries } from './AreaSeries.mjs';
+export { ScatterSeries } from './ScatterSeries.mjs';
+export { PieSeries } from './PieSeries.mjs';
+export type { PolarSeriesCoord } from './PieSeries.mjs';
+export { RadarSeries } from './RadarSeries.mjs';
+export type { RadarSeriesCoord } from './RadarSeries.mjs';
+export { CandlestickSeries } from './CandlestickSeries.mjs';
+export { HeatmapSeries, mixColors } from './HeatmapSeries.mjs';
+export { SankeySeries } from './SankeySeries.mjs';
+export type { SankeySeriesCoord } from './SankeySeries.mjs';
+export { FunnelSeries } from './FunnelSeries.mjs';
+export type { FunnelSeriesCoord } from './FunnelSeries.mjs';
+export { GaugeSeries } from './GaugeSeries.mjs';
+export type { GaugeSeriesCoord } from './GaugeSeries.mjs';
+export { BoxplotSeries } from './BoxplotSeries.mjs';
+export { WaterfallSeries } from './WaterfallSeries.mjs';
+export { TreemapSeries } from './TreemapSeries.mjs';
+export type { TreemapSeriesCoord } from './TreemapSeries.mjs';
+export { GraphSeries } from './GraphSeries.mjs';
+export type { GraphSeriesCoord } from './GraphSeries.mjs';
+export { CurveSeriesBase } from './CurveSeriesBase.mjs';
+export { FunctionSeries } from './FunctionSeries.mjs';
+export { ParametricSeries } from './ParametricSeries.mjs';
+export { LiquidSeries } from './LiquidSeries.mjs';
+export type { LiquidSeriesCoord } from './LiquidSeries.mjs';
+export { BarSeries } from './BarSeries.mjs';

package/dist/types/components/series/index.d.ts

@@ -0,0 +1,29 @@
+export { SeriesBase } from './SeriesBase';
+export type { SeriesCoord, BarSlot } from './SeriesBase';
+export { LineSeries } from './LineSeries';
+export { AreaSeries } from './AreaSeries';
+export { ScatterSeries } from './ScatterSeries';
+export { PieSeries } from './PieSeries';
+export type { PolarSeriesCoord } from './PieSeries';
+export { RadarSeries } from './RadarSeries';
+export type { RadarSeriesCoord } from './RadarSeries';
+export { CandlestickSeries } from './CandlestickSeries';
+export { HeatmapSeries, mixColors } from './HeatmapSeries';
+export { SankeySeries } from './SankeySeries';
+export type { SankeySeriesCoord } from './SankeySeries';
+export { FunnelSeries } from './FunnelSeries';
+export type { FunnelSeriesCoord } from './FunnelSeries';
+export { GaugeSeries } from './GaugeSeries';
+export type { GaugeSeriesCoord } from './GaugeSeries';
+export { BoxplotSeries } from './BoxplotSeries';
+export { WaterfallSeries } from './WaterfallSeries';
+export { TreemapSeries } from './TreemapSeries';
+export type { TreemapSeriesCoord } from './TreemapSeries';
+export { GraphSeries } from './GraphSeries';
+export type { GraphSeriesCoord } from './GraphSeries';
+export { CurveSeriesBase } from './CurveSeriesBase';
+export { FunctionSeries } from './FunctionSeries';
+export { ParametricSeries } from './ParametricSeries';
+export { LiquidSeries } from './LiquidSeries';
+export type { LiquidSeriesCoord } from './LiquidSeries';
+export { BarSeries } from './BarSeries';

package/dist/types/expr/diagnostics.d.mts

@@ -0,0 +1,45 @@
+/**
+ * 表达式诊断：回答「用户是不是胡乱输入了公式」这个问题。
+ *
+ * 编译错误只是第一层。真实场景里更常见、也更难自己发现的是**能编译但画不出来**：
+ * `b*x`（b 没定义）、`sqrt(-x)`（整段都是 NaN）、`sin(0)`（画出来是一条常数线
+ * ——不一定是错，但通常不是本意）。这些以前都是静默的，用户只看到「一片空白」。
+ *
+ * 这里把三层检查合成一份结构化结果，交给表单去标红 / 提示：
+ * 1. **语法层**：编译失败（含位置），由 `ExpressionError.code` 分类；
+ * 2. **静态层**：变量没定义（对比「自变量 + params」）、参数定义了却没用上；
+ * 3. **运行层**：在当前区间内没有任何有限值、输出恒定。
+ *
+ * 纯函数、不依赖 DOM，因此可以被完整单测。
+ */
+export type ExpressionDiagnosticCode = 'empty' | 'syntax' | 'unknown-character' | 'unknown-function' | 'arity' | 'unknown-variable' | 'unused-parameter' | 'no-finite-values' | 'constant-value';
+export interface ExpressionDiagnostic {
+    code: ExpressionDiagnosticCode;
+    /** error = 画不出来；warning = 画出来了但多半不是本意。 */
+    severity: 'error' | 'warning';
+    /** 人类可读的说明（含「怎么改」）。 */
+    message: string;
+    /** 出错字符位置（仅语法类）。 */
+    position?: number;
+}
+export interface DiagnoseExpressionOptions {
+    /** 自变量名：`function` 图是 `x`，参数曲线是 `t`。 */
+    variable: string;
+    /** 表达式里可以引用的参数（来自 `series.params`）。 */
+    params?: Record<string, number>;
+    /**
+     * 同一条系列里其它表达式用到的变量（参数曲线的 x(t) / y(t) 是两条表达式，
+     * 参数只要被任意一条用到就不该报「没用上」）。
+     */
+    additionalVariables?: string[];
+    /**
+     * 当前区间内的采样值（用于运行层检查）。
+     * 不传就只做静态检查；传了才有「整段画不出来 / 输出恒定」这两条。
+     */
+    values?: number[];
+}
+export declare function diagnoseExpression(source: string, options: DiagnoseExpressionOptions): ExpressionDiagnostic[];
+/** 只取错误（表单标红用）。 */
+export declare function errorsOf(diagnostics: ExpressionDiagnostic[]): ExpressionDiagnostic[];
+/** 只取警告（表单提示用）。 */
+export declare function warningsOf(diagnostics: ExpressionDiagnostic[]): ExpressionDiagnostic[];

package/dist/types/expr/diagnostics.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 表达式诊断：回答「用户是不是胡乱输入了公式」这个问题。
+ *
+ * 编译错误只是第一层。真实场景里更常见、也更难自己发现的是**能编译但画不出来**：
+ * `b*x`（b 没定义）、`sqrt(-x)`（整段都是 NaN）、`sin(0)`（画出来是一条常数线
+ * ——不一定是错，但通常不是本意）。这些以前都是静默的，用户只看到「一片空白」。
+ *
+ * 这里把三层检查合成一份结构化结果，交给表单去标红 / 提示：
+ * 1. **语法层**：编译失败（含位置），由 `ExpressionError.code` 分类；
+ * 2. **静态层**：变量没定义（对比「自变量 + params」）、参数定义了却没用上；
+ * 3. **运行层**：在当前区间内没有任何有限值、输出恒定。
+ *
+ * 纯函数、不依赖 DOM，因此可以被完整单测。
+ */
+export type ExpressionDiagnosticCode = 'empty' | 'syntax' | 'unknown-character' | 'unknown-function' | 'arity' | 'unknown-variable' | 'unused-parameter' | 'no-finite-values' | 'constant-value';
+export interface ExpressionDiagnostic {
+    code: ExpressionDiagnosticCode;
+    /** error = 画不出来；warning = 画出来了但多半不是本意。 */
+    severity: 'error' | 'warning';
+    /** 人类可读的说明（含「怎么改」）。 */
+    message: string;
+    /** 出错字符位置（仅语法类）。 */
+    position?: number;
+}
+export interface DiagnoseExpressionOptions {
+    /** 自变量名：`function` 图是 `x`，参数曲线是 `t`。 */
+    variable: string;
+    /** 表达式里可以引用的参数（来自 `series.params`）。 */
+    params?: Record<string, number>;
+    /**
+     * 同一条系列里其它表达式用到的变量（参数曲线的 x(t) / y(t) 是两条表达式，
+     * 参数只要被任意一条用到就不该报「没用上」）。
+     */
+    additionalVariables?: string[];
+    /**
+     * 当前区间内的采样值（用于运行层检查）。
+     * 不传就只做静态检查；传了才有「整段画不出来 / 输出恒定」这两条。
+     */
+    values?: number[];
+}
+export declare function diagnoseExpression(source: string, options: DiagnoseExpressionOptions): ExpressionDiagnostic[];
+/** 只取错误（表单标红用）。 */
+export declare function errorsOf(diagnostics: ExpressionDiagnostic[]): ExpressionDiagnostic[];
+/** 只取警告（表单提示用）。 */
+export declare function warningsOf(diagnostics: ExpressionDiagnostic[]): ExpressionDiagnostic[];

package/dist/types/expr/expr.d.mts

@@ -0,0 +1,44 @@
+/**
+ * 数学表达式引擎（迷你 MATLAB 的核心）。
+ *
+ * 为什么不用 `eval` / `new Function`：表达式是**用户输入**，而且可能来自 URL / 存盘配置。
+ * 这里用「词法 → 递归下降语法分析 → 编译成闭包」三步，既不依赖 eval（CSP 安全），
+ * 也能在编译期把错误位置报出来（`sin(x` 会告诉你缺右括号、在第几个字符）。
+ *
+ * 支持：
+ * - 运算符 `+ - * / % ^`（`^` 右结合），一元正负，括号；
+ * - 常量 `pi / e / tau`；
+ * - 函数：三角 / 反三角 / 双曲 / 指数对数 / 取整 / 绝对值 / min / max / pow / mod / hypot / clamp；
+ * - 变量：调用方通过 scope 提供（`x`、`t`、以及用户自定义参数 `a`、`k`…）；
+ * - **隐式乘法**：`2x`、`3sin(x)`、`2(x+1)`、`2pi`（MATLAB 习惯）。
+ */
+/** 编译失败的原因分类：调用方可以据此做不同的提示（不用解析错误文本）。 */
+export type ExpressionErrorCode = 'empty' | 'syntax' | 'unknown-character' | 'unknown-function' | 'arity';
+export declare class ExpressionError extends Error {
+    position: number;
+    code: ExpressionErrorCode;
+    constructor(message: string, position: number, source: string, code?: ExpressionErrorCode);
+}
+export interface CompiledExpression {
+    /** 原始表达式。 */
+    source: string;
+    /** 表达式里出现的自由变量（不含常量与函数名），例如 ['x', 'a']。 */
+    variables: string[];
+    /** 求值；scope 里缺少的变量按 NaN 处理（曲线断开，而不是静默算成 0）。 */
+    evaluate(scope?: Record<string, number>): number;
+}
+/** 编译表达式（带缓存：同一串表达式在参数扫动时每帧都会用到）。 */
+export declare function compileExpression(source: string): CompiledExpression;
+/** 一次性求值（少量调用用这个；高频采样请先 compileExpression 再复用）。 */
+export declare function evaluateExpression(source: string, scope?: Record<string, number>): number;
+export interface CompiledSampler {
+    /** 更新参数（复用内部 scope，参数扫动时每帧调用）。 */
+    setParams(params: Record<string, number>): void;
+    /** 求值：`name` 是自变量名（function 图是 'x'，参数曲线是 't'）。 */
+    evaluate(variableName: string, value: number): number;
+}
+/**
+ * 生成一个采样器：绑定表达式与参数，复用内部 scope。
+ * 采样是每帧上万次的热路径，这里既不能每次新建对象，也不能每次重新编译。
+ */
+export declare function compileSampler(source: string, baseScope?: Record<string, number>): CompiledSampler;

package/dist/types/expr/expr.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 数学表达式引擎（迷你 MATLAB 的核心）。
+ *
+ * 为什么不用 `eval` / `new Function`：表达式是**用户输入**，而且可能来自 URL / 存盘配置。
+ * 这里用「词法 → 递归下降语法分析 → 编译成闭包」三步，既不依赖 eval（CSP 安全），
+ * 也能在编译期把错误位置报出来（`sin(x` 会告诉你缺右括号、在第几个字符）。
+ *
+ * 支持：
+ * - 运算符 `+ - * / % ^`（`^` 右结合），一元正负，括号；
+ * - 常量 `pi / e / tau`；
+ * - 函数：三角 / 反三角 / 双曲 / 指数对数 / 取整 / 绝对值 / min / max / pow / mod / hypot / clamp；
+ * - 变量：调用方通过 scope 提供（`x`、`t`、以及用户自定义参数 `a`、`k`…）；
+ * - **隐式乘法**：`2x`、`3sin(x)`、`2(x+1)`、`2pi`（MATLAB 习惯）。
+ */
+/** 编译失败的原因分类：调用方可以据此做不同的提示（不用解析错误文本）。 */
+export type ExpressionErrorCode = 'empty' | 'syntax' | 'unknown-character' | 'unknown-function' | 'arity';
+export declare class ExpressionError extends Error {
+    position: number;
+    code: ExpressionErrorCode;
+    constructor(message: string, position: number, source: string, code?: ExpressionErrorCode);
+}
+export interface CompiledExpression {
+    /** 原始表达式。 */
+    source: string;
+    /** 表达式里出现的自由变量（不含常量与函数名），例如 ['x', 'a']。 */
+    variables: string[];
+    /** 求值；scope 里缺少的变量按 NaN 处理（曲线断开，而不是静默算成 0）。 */
+    evaluate(scope?: Record<string, number>): number;
+}
+/** 编译表达式（带缓存：同一串表达式在参数扫动时每帧都会用到）。 */
+export declare function compileExpression(source: string): CompiledExpression;
+/** 一次性求值（少量调用用这个；高频采样请先 compileExpression 再复用）。 */
+export declare function evaluateExpression(source: string, scope?: Record<string, number>): number;
+export interface CompiledSampler {
+    /** 更新参数（复用内部 scope，参数扫动时每帧调用）。 */
+    setParams(params: Record<string, number>): void;
+    /** 求值：`name` 是自变量名（function 图是 'x'，参数曲线是 't'）。 */
+    evaluate(variableName: string, value: number): number;
+}
+/**
+ * 生成一个采样器：绑定表达式与参数，复用内部 scope。
+ * 采样是每帧上万次的热路径，这里既不能每次新建对象，也不能每次重新编译。
+ */
+export declare function compileSampler(source: string, baseScope?: Record<string, number>): CompiledSampler;

package/dist/types/expr/sample.d.mts

@@ -0,0 +1,34 @@
+/**
+ * 曲线采样：均匀打底 + 按曲率自适应细分。
+ *
+ * 为什么不能只均匀采样：`tan(x)` 在极点附近、`exp(-x^2)` 在峰顶附近，
+ * 均匀采样的折线要么「削平峰顶」要么「漏掉极点」。自适应细分只在折线与真实曲线
+ * 偏差大的地方加点，点数可控（有 maxSamples 上限，不会因为奇异点爆掉）。
+ *
+ * 非有限值（NaN / ±Inf / 过大）一律写成 `[x, NaN]` 作为**断点**，
+ * 渲染时按断点分段 —— 这样 `tan(x)`、`1/x` 会画出真正的渐近线缺口，而不是连一条竖线。
+ */
+export interface SampleOptions {
+    /** 基础均匀采样点数（至少 2），默认 240。 */
+    base?: number;
+    /** 是否做自适应细分，默认 true。 */
+    adaptive?: boolean;
+    /** 相对 y 跨度的偏差阈值：越小越精细，默认 0.0025。 */
+    tolerance?: number;
+    /** 采样点总数上限，默认 6000（奇异点附近会疯狂细分，必须有闸）。 */
+    maxSamples?: number;
+    /** 递归深度上限，默认 7。 */
+    maxDepth?: number;
+}
+export type CurvePoint = [number, number];
+/**
+ * 稳健取值范围：用四分位距（IQR）丢掉离群点。
+ *
+ * 为什么不用 min/max：`1/x`、`tan(x)` 的尖峰能把 y 轴拉到 ±2500，
+ * 整条曲线会被压成一条直线。用 IQR 之外的数值剪掉之后，画面才像 MATLAB。
+ */
+export declare function robustRange(values: number[], k?: number): [number, number];
+/** 采样 y = f(x)。返回按 x 升序的点列，断点用 y = NaN 表示。 */
+export declare function sampleFunctionCurve(fn: (x: number) => number, x0: number, x1: number, options?: SampleOptions): CurvePoint[];
+/** 采样参数曲线 (x(t), y(t))：偏差按平面距离算（曲线可能拐回来，不能只看 y）。 */
+export declare function sampleParametricCurve(fx: (t: number) => number, fy: (t: number) => number, t0: number, t1: number, options?: SampleOptions): CurvePoint[];