@damoqiongqiu/ice-chart 0.17.0

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

@@ -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[];

package/dist/types/index.d.mts

@@ -0,0 +1,80 @@
+/**
+ * ice-chart —— 构建在 ice-render 之上的交互式图表库。
+ *
+ * 与「把数据画成图」的图表库不同，ice-chart 把 ice-render 的事件系统、命中测试、
+ * 嵌套坐标系与脏矩形局部重绘当作一等能力：悬停、点击下钻、框选、缩放平移、
+ * 图例联动、跨图联动、键盘导航都是内建能力。
+ */
+export { ICEChart, createChart, computeBarSlots, isChartSnapshot, mergeOptionPatch, SNAPSHOT_VERSION, setMotionPreference, getMotionPreference, shouldAnimate, } from './ICEChart.mjs';
+export type { ICEChartOptions, ApplyOptionOptions, ChartSnapshot, SnapshotRestoreOptions, MotionPreference, } from './ICEChart.mjs';
+export type { ChartOption, ChartEventName, ChartEventHandler, ChartEventPayloads, ChartTheme, ChartLinkOption, AxisOption, SeriesOption, SeriesType, ScaleType, LegendOption, TooltipOption, TooltipParams, CrosshairOption, GridOption, DataZoomOption, InteractionOption, AnimationOption, AnimationStageOption, DataPointParams, BrushRange, ZoomRange, LegendToggleParams, DataItem, SweepOption, LiquidOption, PolarGridOption, } from './types.mjs';
+export { LIGHT_CHART_THEME, DARK_CHART_THEME, BOOTSTRAP_CHART_THEME, BOOTSTRAP_DARK_CHART_THEME, BOOTSTRAP_TOKENS, resolveChartTheme, } from './theme/chartTheme.mjs';
+export { createScale, formatTick, formatNumberTick, LinearScale, BandScale, TimeScale, LogScale } from './scale.mjs';
+export type { Scale, CreateScaleOptions } from './scale.mjs';
+export { normalizeOption, toSerializableOption, normalizeAnimation, DEFAULT_ANIMATION_STAGES } from './option/normalize.mjs';
+export type { NormalizeContext } from './option/normalize.mjs';
+export { computeLayout } from './layout/layout.mjs';
+export type { DataPoint, InternalSeries, InternalAxis, NormalizedOption, ChartLayout, Rect, LegendItemLayout } from './internal.mjs';
+export { ChartComponent } from './components/ChartComponent.mjs';
+export { PlotArea } from './components/PlotArea.mjs';
+export { GridLines } from './components/GridLines.mjs';
+export { Axis } from './components/Axis.mjs';
+export { Legend, roundRect } from './components/Legend.mjs';
+export { Title } from './components/Title.mjs';
+export { Tooltip } from './components/Tooltip.mjs';
+export { Crosshair } from './components/Crosshair.mjs';
+export { Highlight } from './components/Highlight.mjs';
+export { Brush } from './components/Brush.mjs';
+export { SeriesBase } from './components/series/SeriesBase.mjs';
+export type { SeriesCoord, BarSlot } from './components/series/SeriesBase.mjs';
+export { LineSeries } from './components/series/LineSeries.mjs';
+export { AreaSeries } from './components/series/AreaSeries.mjs';
+export { BarSeries } from './components/series/BarSeries.mjs';
+export { ScatterSeries } from './components/series/ScatterSeries.mjs';
+export { PieSeries } from './components/series/PieSeries.mjs';
+export type { PolarSeriesCoord } from './components/series/PieSeries.mjs';
+export { RadarSeries } from './components/series/RadarSeries.mjs';
+export type { RadarSeriesCoord } from './components/series/RadarSeries.mjs';
+export { CandlestickSeries } from './components/series/CandlestickSeries.mjs';
+export { HeatmapSeries, mixColors } from './components/series/HeatmapSeries.mjs';
+export { SankeySeries } from './components/series/SankeySeries.mjs';
+export type { SankeySeriesCoord } from './components/series/SankeySeries.mjs';
+export { FunnelSeries } from './components/series/FunnelSeries.mjs';
+export type { FunnelSeriesCoord } from './components/series/FunnelSeries.mjs';
+export { GaugeSeries } from './components/series/GaugeSeries.mjs';
+export type { GaugeSeriesCoord } from './components/series/GaugeSeries.mjs';
+export { BoxplotSeries } from './components/series/BoxplotSeries.mjs';
+export { WaterfallSeries } from './components/series/WaterfallSeries.mjs';
+export { TreemapSeries } from './components/series/TreemapSeries.mjs';
+export type { TreemapSeriesCoord } from './components/series/TreemapSeries.mjs';
+export { layoutTreemap } from './layout/treemap.mjs';
+export type { TreemapNodeLayout, TreemapInputNode } from './layout/treemap.mjs';
+export { GraphSeries } from './components/series/GraphSeries.mjs';
+export type { GraphSeriesCoord } from './components/series/GraphSeries.mjs';
+export { CurveSeriesBase } from './components/series/CurveSeriesBase.mjs';
+export { FunctionSeries } from './components/series/FunctionSeries.mjs';
+export { ParametricSeries } from './components/series/ParametricSeries.mjs';
+export { LiquidSeries } from './components/series/LiquidSeries.mjs';
+export type { LiquidSeriesCoord } from './components/series/LiquidSeries.mjs';
+export { compileExpression, compileSampler, evaluateExpression, ExpressionError } from './expr/expr.mjs';
+export type { CompiledExpression, CompiledSampler, ExpressionErrorCode } from './expr/expr.mjs';
+export { diagnoseExpression, errorsOf, warningsOf } from './expr/diagnostics.mjs';
+export type { ExpressionDiagnostic, ExpressionDiagnosticCode, DiagnoseExpressionOptions } from './expr/diagnostics.mjs';
+export { sampleFunctionCurve, sampleParametricCurve, robustRange } from './expr/sample.mjs';
+export type { CurvePoint, SampleOptions } from './expr/sample.mjs';
+export { forceLayout, sampleGraphLink } from './layout/force.mjs';
+export type { ForceNodeLayout, ForceLinkLayout, ForceLayoutResult } from './layout/force.mjs';
+export { computeBoxplotSummary } from './option/normalize.mjs';
+export { layoutSankey, sampleLinkPath } from './layout/sankey.mjs';
+export type { SankeyNodeLayout, SankeyLinkLayout, SankeyLayoutResult } from './layout/sankey.mjs';
+export { RadarGrid } from './components/RadarGrid.mjs';
+export type { RadarGridCoord } from './components/RadarGrid.mjs';
+export { createSeriesComponent } from './components/series/createSeries.mjs';
+export { InteractionController } from './interaction/InteractionController.mjs';
+export type { InteractionHost } from './interaction/InteractionController.mjs';
+export { HitResolver } from './interaction/HitResolver.mjs';
+export { linkCharts } from './interaction/ChartLink.mjs';
+export type { ChartLinkHandle } from './interaction/ChartLink.mjs';
+export { Emitter } from './util/emitter.mjs';
+export { A11yMirror, buildDataTable, buildDataNodes, chartTitle, VISUALLY_HIDDEN_STYLE, SERIES_ROLE_HINT } from './a11y.mjs';
+export type { DataTable, A11yDataNode, A11yTreeOptions, A11yChartLike } from './a11y.mjs';

package/dist/types/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ice-chart —— 构建在 ice-render 之上的交互式图表库。
+ *
+ * 与「把数据画成图」的图表库不同，ice-chart 把 ice-render 的事件系统、命中测试、
+ * 嵌套坐标系与脏矩形局部重绘当作一等能力：悬停、点击下钻、框选、缩放平移、
+ * 图例联动、跨图联动、键盘导航都是内建能力。
+ */
+export { ICEChart, createChart, computeBarSlots, isChartSnapshot, mergeOptionPatch, SNAPSHOT_VERSION, setMotionPreference, getMotionPreference, shouldAnimate, } from './ICEChart';
+export type { ICEChartOptions, ApplyOptionOptions, ChartSnapshot, SnapshotRestoreOptions, MotionPreference, } from './ICEChart';
+export type { ChartOption, ChartEventName, ChartEventHandler, ChartEventPayloads, ChartTheme, ChartLinkOption, AxisOption, SeriesOption, SeriesType, ScaleType, LegendOption, TooltipOption, TooltipParams, CrosshairOption, GridOption, DataZoomOption, InteractionOption, AnimationOption, AnimationStageOption, DataPointParams, BrushRange, ZoomRange, LegendToggleParams, DataItem, SweepOption, LiquidOption, PolarGridOption, } from './types';
+export { LIGHT_CHART_THEME, DARK_CHART_THEME, BOOTSTRAP_CHART_THEME, BOOTSTRAP_DARK_CHART_THEME, BOOTSTRAP_TOKENS, resolveChartTheme, } from './theme/chartTheme';
+export { createScale, formatTick, formatNumberTick, LinearScale, BandScale, TimeScale, LogScale } from './scale';
+export type { Scale, CreateScaleOptions } from './scale';
+export { normalizeOption, toSerializableOption, normalizeAnimation, DEFAULT_ANIMATION_STAGES } from './option/normalize';
+export type { NormalizeContext } from './option/normalize';
+export { computeLayout } from './layout/layout';
+export type { DataPoint, InternalSeries, InternalAxis, NormalizedOption, ChartLayout, Rect, LegendItemLayout } from './internal';
+export { ChartComponent } from './components/ChartComponent';
+export { PlotArea } from './components/PlotArea';
+export { GridLines } from './components/GridLines';
+export { Axis } from './components/Axis';
+export { Legend, roundRect } from './components/Legend';
+export { Title } from './components/Title';
+export { Tooltip } from './components/Tooltip';
+export { Crosshair } from './components/Crosshair';
+export { Highlight } from './components/Highlight';
+export { Brush } from './components/Brush';
+export { SeriesBase } from './components/series/SeriesBase';
+export type { SeriesCoord, BarSlot } from './components/series/SeriesBase';
+export { LineSeries } from './components/series/LineSeries';
+export { AreaSeries } from './components/series/AreaSeries';
+export { BarSeries } from './components/series/BarSeries';
+export { ScatterSeries } from './components/series/ScatterSeries';
+export { PieSeries } from './components/series/PieSeries';
+export type { PolarSeriesCoord } from './components/series/PieSeries';
+export { RadarSeries } from './components/series/RadarSeries';
+export type { RadarSeriesCoord } from './components/series/RadarSeries';
+export { CandlestickSeries } from './components/series/CandlestickSeries';
+export { HeatmapSeries, mixColors } from './components/series/HeatmapSeries';
+export { SankeySeries } from './components/series/SankeySeries';
+export type { SankeySeriesCoord } from './components/series/SankeySeries';
+export { FunnelSeries } from './components/series/FunnelSeries';
+export type { FunnelSeriesCoord } from './components/series/FunnelSeries';
+export { GaugeSeries } from './components/series/GaugeSeries';
+export type { GaugeSeriesCoord } from './components/series/GaugeSeries';
+export { BoxplotSeries } from './components/series/BoxplotSeries';
+export { WaterfallSeries } from './components/series/WaterfallSeries';
+export { TreemapSeries } from './components/series/TreemapSeries';
+export type { TreemapSeriesCoord } from './components/series/TreemapSeries';
+export { layoutTreemap } from './layout/treemap';
+export type { TreemapNodeLayout, TreemapInputNode } from './layout/treemap';
+export { GraphSeries } from './components/series/GraphSeries';
+export type { GraphSeriesCoord } from './components/series/GraphSeries';
+export { CurveSeriesBase } from './components/series/CurveSeriesBase';
+export { FunctionSeries } from './components/series/FunctionSeries';
+export { ParametricSeries } from './components/series/ParametricSeries';
+export { LiquidSeries } from './components/series/LiquidSeries';
+export type { LiquidSeriesCoord } from './components/series/LiquidSeries';
+export { compileExpression, compileSampler, evaluateExpression, ExpressionError } from './expr/expr';
+export type { CompiledExpression, CompiledSampler, ExpressionErrorCode } from './expr/expr';
+export { diagnoseExpression, errorsOf, warningsOf } from './expr/diagnostics';
+export type { ExpressionDiagnostic, ExpressionDiagnosticCode, DiagnoseExpressionOptions } from './expr/diagnostics';
+export { sampleFunctionCurve, sampleParametricCurve, robustRange } from './expr/sample';
+export type { CurvePoint, SampleOptions } from './expr/sample';
+export { forceLayout, sampleGraphLink } from './layout/force';
+export type { ForceNodeLayout, ForceLinkLayout, ForceLayoutResult } from './layout/force';
+export { computeBoxplotSummary } from './option/normalize';
+export { layoutSankey, sampleLinkPath } from './layout/sankey';
+export type { SankeyNodeLayout, SankeyLinkLayout, SankeyLayoutResult } from './layout/sankey';
+export { RadarGrid } from './components/RadarGrid';
+export type { RadarGridCoord } from './components/RadarGrid';
+export { createSeriesComponent } from './components/series/createSeries';
+export { InteractionController } from './interaction/InteractionController';
+export type { InteractionHost } from './interaction/InteractionController';
+export { HitResolver } from './interaction/HitResolver';
+export { linkCharts } from './interaction/ChartLink';
+export type { ChartLinkHandle } from './interaction/ChartLink';
+export { Emitter } from './util/emitter';
+export { A11yMirror, buildDataTable, buildDataNodes, chartTitle, VISUALLY_HIDDEN_STYLE, SERIES_ROLE_HINT } from './a11y';
+export type { DataTable, A11yDataNode, A11yTreeOptions, A11yChartLike } from './a11y';

package/dist/types/interaction/ChartLink.d.mts

@@ -0,0 +1,16 @@
+import type { ChartLinkOption } from '../types.mjs';
+import type { ICEChart } from '../ICEChart.mjs';
+export interface ChartLinkHandle {
+    charts: ICEChart[];
+    unlink(): void;
+}
+/**
+ * 多图联动：一组图表共享「悬停列 / 缩放窗口 / 刷选范围」。
+ *
+ * 实现刻意只用**公开的语义事件**（item:hover / zoom:change / pan:change / brush:end），
+ * 因此：
+ * - 任何抛出这些事件的图表都能加入联动，不依赖内部实现细节；
+ * - 联动是应用层可组合的能力，不需要全局单例；
+ * - 按 x 数据值（而不是像素）联动，不同尺寸 / 不同数据范围的图表也能对齐。
+ */
+export declare function linkCharts(charts: ICEChart[], option?: ChartLinkOption): ChartLinkHandle;

package/dist/types/interaction/ChartLink.d.ts

@@ -0,0 +1,16 @@
+import type { ChartLinkOption } from '../types';
+import type { ICEChart } from '../ICEChart';
+export interface ChartLinkHandle {
+    charts: ICEChart[];
+    unlink(): void;
+}
+/**
+ * 多图联动：一组图表共享「悬停列 / 缩放窗口 / 刷选范围」。
+ *
+ * 实现刻意只用**公开的语义事件**（item:hover / zoom:change / pan:change / brush:end），
+ * 因此：
+ * - 任何抛出这些事件的图表都能加入联动，不依赖内部实现细节；
+ * - 联动是应用层可组合的能力，不需要全局单例；
+ * - 按 x 数据值（而不是像素）联动，不同尺寸 / 不同数据范围的图表也能对齐。
+ */
+export declare function linkCharts(charts: ICEChart[], option?: ChartLinkOption): ChartLinkHandle;

package/dist/types/interaction/HitResolver.d.mts

@@ -0,0 +1,44 @@
+import type { ActiveColumn, ActiveItem, ChartLayout, InternalSeries, NormalizedOption } from '../internal.mjs';
+import type { DataPointParams } from '../types.mjs';
+import type { SeriesBase } from '../components/series/SeriesBase.mjs';
+export interface HitHost {
+    ice: any;
+    norm: NormalizedOption;
+    layout: ChartLayout;
+    plotArea: any;
+    legend: any;
+    seriesComponents: SeriesBase[];
+}
+export interface TargetInfo {
+    kind: 'none' | 'plot' | 'series' | 'legend' | 'other';
+    component: any;
+    index: number;
+    /** 组件本地坐标。 */
+    local: [number, number];
+    /** 图表坐标系（画布左上角为原点）坐标。 */
+    chart: [number, number];
+}
+/**
+ * 命中解析：把「屏幕像素」翻译成「哪个组件的哪个数据项」。
+ *
+ * 关键点是**复用引擎的命中测试**（`ice.hitTest`）而不是自己遍历数据：
+ * 遮挡关系、zIndex、display:false、interactive:false 等语义全部由引擎统一保证，
+ * ice-chart 只负责把组件本地坐标进一步翻译成数据下标。
+ */
+export declare class HitResolver {
+    private host;
+    constructor(host: HitHost);
+    resolveTarget(screenX: number, screenY: number): TargetInfo;
+    isInsidePlot(chartX: number, chartY: number): boolean;
+    seriesComponentOf(series: InternalSeries): SeriesBase | null;
+    seriesOfComponent(component: any): InternalSeries | null;
+    buildActiveItem(series: InternalSeries, dataIndex: number): ActiveItem | null;
+    toParams(item: ActiveItem): DataPointParams;
+    /** 图表坐标系 x 像素 → 数据列（每个系列各取 x 最近的点）。 */
+    pickColumn(chartX: number): ActiveColumn | null;
+    nearestIndexByX(component: SeriesBase, localX: number): number;
+    /** 按数据值找最近的点（跨图联动用）。 */
+    nearestByXValue(xValue: any): ActiveItem | null;
+}
+/** 两个 x 数据值的距离；不可比时返回 null。 */
+export declare function valueDistance(a: any, b: any): number | null;

package/dist/types/interaction/HitResolver.d.ts

@@ -0,0 +1,44 @@
+import type { ActiveColumn, ActiveItem, ChartLayout, InternalSeries, NormalizedOption } from '../internal';
+import type { DataPointParams } from '../types';
+import type { SeriesBase } from '../components/series/SeriesBase';
+export interface HitHost {
+    ice: any;
+    norm: NormalizedOption;
+    layout: ChartLayout;
+    plotArea: any;
+    legend: any;
+    seriesComponents: SeriesBase[];
+}
+export interface TargetInfo {
+    kind: 'none' | 'plot' | 'series' | 'legend' | 'other';
+    component: any;
+    index: number;
+    /** 组件本地坐标。 */
+    local: [number, number];
+    /** 图表坐标系（画布左上角为原点）坐标。 */
+    chart: [number, number];
+}
+/**
+ * 命中解析：把「屏幕像素」翻译成「哪个组件的哪个数据项」。
+ *
+ * 关键点是**复用引擎的命中测试**（`ice.hitTest`）而不是自己遍历数据：
+ * 遮挡关系、zIndex、display:false、interactive:false 等语义全部由引擎统一保证，
+ * ice-chart 只负责把组件本地坐标进一步翻译成数据下标。
+ */
+export declare class HitResolver {
+    private host;
+    constructor(host: HitHost);
+    resolveTarget(screenX: number, screenY: number): TargetInfo;
+    isInsidePlot(chartX: number, chartY: number): boolean;
+    seriesComponentOf(series: InternalSeries): SeriesBase | null;
+    seriesOfComponent(component: any): InternalSeries | null;
+    buildActiveItem(series: InternalSeries, dataIndex: number): ActiveItem | null;
+    toParams(item: ActiveItem): DataPointParams;
+    /** 图表坐标系 x 像素 → 数据列（每个系列各取 x 最近的点）。 */
+    pickColumn(chartX: number): ActiveColumn | null;
+    nearestIndexByX(component: SeriesBase, localX: number): number;
+    /** 按数据值找最近的点（跨图联动用）。 */
+    nearestByXValue(xValue: any): ActiveItem | null;
+}
+/** 两个 x 数据值的距离；不可比时返回 null。 */
+export declare function valueDistance(a: any, b: any): number | null;

package/dist/types/interaction/InteractionController.d.mts

@@ -0,0 +1,147 @@
+import type { ActiveColumn, ActiveItem } from '../internal.mjs';
+import type { DataPointParams } from '../types.mjs';
+import type { Crosshair } from '../components/Crosshair.mjs';
+import type { Highlight } from '../components/Highlight.mjs';
+import type { Brush } from '../components/Brush.mjs';
+import type { DataZoomSlider } from '../components/DataZoomSlider.mjs';
+import type { Legend } from '../components/Legend.mjs';
+import type { PlotArea } from '../components/PlotArea.mjs';
+import type { Tooltip } from '../components/Tooltip.mjs';
+import { HitResolver, valueDistance, type HitHost, type TargetInfo } from './HitResolver.mjs';
+/** 交互层需要的图表宿主能力，由 ICEChart 实现。 */
+export interface InteractionHost extends HitHost {
+    tooltip: Tooltip | null;
+    crosshair: Crosshair | null;
+    highlight: Highlight | null;
+    brush: Brush | null;
+    legend: Legend | null;
+    plotArea: PlotArea;
+    emit(event: string, payload?: any): void;
+    setDomain(axis: 'x' | 'y', domain: any[], source?: string): void;
+    toggleSeries(seriesId: string, forceSelected?: boolean): void;
+    /** 切换饼图扇区显隐（极坐标图例）。 */
+    toggleSlice(seriesId: string, dataIndex: number, forceSelected?: boolean): void;
+    /** dataZoom 滑块（未启用时为 null）。 */
+    dataZoomSlider: DataZoomSlider | null;
+    /** 由滑块的 0~1 比例窗口反推数据域。 */
+    setDomainFromFractions(start: number, end: number, source?: string): void;
+    formatAxisValue(axis: 'x' | 'y', value: any): string;
+    /** 未经缩放的完整数据域（缩放约束用）。 */
+    fullDomain(axis: 'x' | 'y'): any[];
+}
+/**
+ * 交互控制器：ice-chart 所有指针 / 键盘行为**唯一**的入口。
+ *
+ * 三条设计约束：
+ * 1. 悬停命中不复用引擎移动事件的 component 缓存（移动事件为了性能不做命中检测），
+ *    而是显式调用 `ice.hitTest()` —— 保证「画出来的样子」与「点得到的位置」严格一致；
+ * 2. 数据项命中交给引擎：`ice.hitTest()` 返回命中的组件，控制器只把本地坐标翻译成数据下标；
+ * 3. 对外只抛语义事件（item:hover / select:change / brush:end / zoom:change ...），
+ *    业务层不需要理解像素、比例尺与坐标系。
+ *
+ * 所有公开的 handleXxx 方法都接受**画布 CSS 像素**坐标，因此可以在不合成 DOM 事件的情况下直接单测。
+ */
+export declare class InteractionController {
+    host: InteractionHost;
+    hover: {
+        kind: 'item';
+        item: ActiveItem;
+    } | {
+        kind: 'axis';
+        column: ActiveColumn;
+    } | null;
+    selection: Array<{
+        seriesId: string;
+        dataIndex: number;
+    }>;
+    resolver: HitResolver;
+    private drag;
+    private bound;
+    private lastDimmed;
+    private keyboardIndex;
+    constructor(host: InteractionHost);
+    bind(): this;
+    unbind(): void;
+    private pointOf;
+    /** 指针是否落在本图 canvas 的内容盒内（CSS 像素语义）。 */
+    isOverCanvas(screenX: number, screenY: number): boolean;
+    /**
+     * 阻止默认行为。
+     *
+     * 只对**原始 DOM 事件**调用：ice-render 的 ICEEvent 只是接口模拟（它的 preventDefault
+     * 会抛异常），而某些路径下事件对象上的 preventDefault 是未绑定的原生方法，
+     * 直接调用会抛 "Illegal invocation"。同样要容错 —— 被动监听器里调用会被浏览器拒绝。
+     */
+    private preventDefault;
+    private onBusMove;
+    private onBusDown;
+    private onBusUp;
+    private onBusClick;
+    private onBusDoubleClick;
+    private onBusWheel;
+    private onBusKeyDown;
+    /**
+     * 数据域变化（缩放 / 平移 / 滑块 / 数据更新 / 图例切换）后重新定位悬停。
+     *
+     * 为什么必须做：悬停状态里存的是**像素**（十字准星位置、高亮环、提示框锚点），
+     * 而缩放/平移后同一份数据的像素已经变了。不重新定位就会出现
+     * 「准星停在原地、和曲线脱开」这种一眼可见的错位。
+     */
+    refreshHover(): void;
+    resolveTarget(screenX: number, screenY: number): TargetInfo;
+    handlePointerMove(screenX: number, screenY: number, evt?: any): void;
+    updateHover(screenX: number, screenY: number): void;
+    private resetLegendHover;
+    setHover(next: {
+        kind: 'item';
+        item: ActiveItem;
+    } | {
+        kind: 'axis';
+        column: ActiveColumn;
+    } | null): void;
+    private setHoverState;
+    private applyHoverVisuals;
+    private buildTooltipContent;
+    private clearHoverVisuals;
+    /** 只清理数据层（高亮环 / 准星 / 提示框），不动图例悬停。 */
+    private clearDataVisuals;
+    /** 把「当前悬停的数据项」下发给系列：图元自己会做放大/外移等反馈动画。 */
+    private syncSeriesHover;
+    /** 生成高亮标记：数据点用圆环，柱形用矩形描边。 */
+    private markFor;
+    /**
+     * 未命中高亮时压低其他系列的不透明度。
+     * 只在「悬停系列发生变化」时写 state —— 每次 mousemove 都写会让所有系列每帧变脏，
+     * 脏矩形局部重绘的优势就没了。
+     */
+    private dimOthers;
+    handlePointerDown(screenX: number, screenY: number, evt?: any): boolean;
+    handlePointerUp(screenX: number, screenY: number, _evt?: any): void;
+    private updateDrag;
+    private shiftDomain;
+    handleClick(screenX: number, screenY: number, _evt?: any): void;
+    handleDoubleClick(screenX: number, screenY: number, _evt?: any): void;
+    toggleSelection(seriesId: string, dataIndex: number, mode: 'single' | 'multiple', toggle: boolean): void;
+    clearSelection(): void;
+    private refreshSelectionVisuals;
+    getSelectedParams(): DataPointParams[];
+    get brushRect(): import("../internal.mjs").Rect | null;
+    private brushRange;
+    /** 像素 → 数据值；类目轴取命中带（或最近类目），数值轴取精确反算。 */
+    private valueAtPixel;
+    private orderValues;
+    private applyRange;
+    handleWheel(screenX: number, screenY: number, deltaY: number, evt?: any): boolean;
+    private zoomDomain;
+    private currentRange;
+    handleKeyDown(key: string, evt?: any): boolean;
+    /** 外部（联动）驱动：在指定 x 数据值上显示悬停。 */
+    showHoverAtValue(xValue: any): void;
+    clearHover(): void;
+    /** 沿指定方向找到下一个「落在绘图区内」的数据下标；找不到返回 -1。 */
+    /** 关系图组件 → 对应的 InternalSeries。 */
+    private seriesOfGraphComponent;
+    private stepVisibleIndex;
+    destroy(): void;
+}
+export { valueDistance };

package/dist/types/interaction/InteractionController.d.ts

@@ -0,0 +1,147 @@
+import type { ActiveColumn, ActiveItem } from '../internal';
+import type { DataPointParams } from '../types';
+import type { Crosshair } from '../components/Crosshair';
+import type { Highlight } from '../components/Highlight';
+import type { Brush } from '../components/Brush';
+import type { DataZoomSlider } from '../components/DataZoomSlider';
+import type { Legend } from '../components/Legend';
+import type { PlotArea } from '../components/PlotArea';
+import type { Tooltip } from '../components/Tooltip';
+import { HitResolver, valueDistance, type HitHost, type TargetInfo } from './HitResolver';
+/** 交互层需要的图表宿主能力，由 ICEChart 实现。 */
+export interface InteractionHost extends HitHost {
+    tooltip: Tooltip | null;
+    crosshair: Crosshair | null;
+    highlight: Highlight | null;
+    brush: Brush | null;
+    legend: Legend | null;
+    plotArea: PlotArea;
+    emit(event: string, payload?: any): void;
+    setDomain(axis: 'x' | 'y', domain: any[], source?: string): void;
+    toggleSeries(seriesId: string, forceSelected?: boolean): void;
+    /** 切换饼图扇区显隐（极坐标图例）。 */
+    toggleSlice(seriesId: string, dataIndex: number, forceSelected?: boolean): void;
+    /** dataZoom 滑块（未启用时为 null）。 */
+    dataZoomSlider: DataZoomSlider | null;
+    /** 由滑块的 0~1 比例窗口反推数据域。 */
+    setDomainFromFractions(start: number, end: number, source?: string): void;
+    formatAxisValue(axis: 'x' | 'y', value: any): string;
+    /** 未经缩放的完整数据域（缩放约束用）。 */
+    fullDomain(axis: 'x' | 'y'): any[];
+}
+/**
+ * 交互控制器：ice-chart 所有指针 / 键盘行为**唯一**的入口。
+ *
+ * 三条设计约束：
+ * 1. 悬停命中不复用引擎移动事件的 component 缓存（移动事件为了性能不做命中检测），
+ *    而是显式调用 `ice.hitTest()` —— 保证「画出来的样子」与「点得到的位置」严格一致；
+ * 2. 数据项命中交给引擎：`ice.hitTest()` 返回命中的组件，控制器只把本地坐标翻译成数据下标；
+ * 3. 对外只抛语义事件（item:hover / select:change / brush:end / zoom:change ...），
+ *    业务层不需要理解像素、比例尺与坐标系。
+ *
+ * 所有公开的 handleXxx 方法都接受**画布 CSS 像素**坐标，因此可以在不合成 DOM 事件的情况下直接单测。
+ */
+export declare class InteractionController {
+    host: InteractionHost;
+    hover: {
+        kind: 'item';
+        item: ActiveItem;
+    } | {
+        kind: 'axis';
+        column: ActiveColumn;
+    } | null;
+    selection: Array<{
+        seriesId: string;
+        dataIndex: number;
+    }>;
+    resolver: HitResolver;
+    private drag;
+    private bound;
+    private lastDimmed;
+    private keyboardIndex;
+    constructor(host: InteractionHost);
+    bind(): this;
+    unbind(): void;
+    private pointOf;
+    /** 指针是否落在本图 canvas 的内容盒内（CSS 像素语义）。 */
+    isOverCanvas(screenX: number, screenY: number): boolean;
+    /**
+     * 阻止默认行为。
+     *
+     * 只对**原始 DOM 事件**调用：ice-render 的 ICEEvent 只是接口模拟（它的 preventDefault
+     * 会抛异常），而某些路径下事件对象上的 preventDefault 是未绑定的原生方法，
+     * 直接调用会抛 "Illegal invocation"。同样要容错 —— 被动监听器里调用会被浏览器拒绝。
+     */
+    private preventDefault;
+    private onBusMove;
+    private onBusDown;
+    private onBusUp;
+    private onBusClick;
+    private onBusDoubleClick;
+    private onBusWheel;
+    private onBusKeyDown;
+    /**
+     * 数据域变化（缩放 / 平移 / 滑块 / 数据更新 / 图例切换）后重新定位悬停。
+     *
+     * 为什么必须做：悬停状态里存的是**像素**（十字准星位置、高亮环、提示框锚点），
+     * 而缩放/平移后同一份数据的像素已经变了。不重新定位就会出现
+     * 「准星停在原地、和曲线脱开」这种一眼可见的错位。
+     */
+    refreshHover(): void;
+    resolveTarget(screenX: number, screenY: number): TargetInfo;
+    handlePointerMove(screenX: number, screenY: number, evt?: any): void;
+    updateHover(screenX: number, screenY: number): void;
+    private resetLegendHover;
+    setHover(next: {
+        kind: 'item';
+        item: ActiveItem;
+    } | {
+        kind: 'axis';
+        column: ActiveColumn;
+    } | null): void;
+    private setHoverState;
+    private applyHoverVisuals;
+    private buildTooltipContent;
+    private clearHoverVisuals;
+    /** 只清理数据层（高亮环 / 准星 / 提示框），不动图例悬停。 */
+    private clearDataVisuals;
+    /** 把「当前悬停的数据项」下发给系列：图元自己会做放大/外移等反馈动画。 */
+    private syncSeriesHover;
+    /** 生成高亮标记：数据点用圆环，柱形用矩形描边。 */
+    private markFor;
+    /**
+     * 未命中高亮时压低其他系列的不透明度。
+     * 只在「悬停系列发生变化」时写 state —— 每次 mousemove 都写会让所有系列每帧变脏，
+     * 脏矩形局部重绘的优势就没了。
+     */
+    private dimOthers;
+    handlePointerDown(screenX: number, screenY: number, evt?: any): boolean;
+    handlePointerUp(screenX: number, screenY: number, _evt?: any): void;
+    private updateDrag;
+    private shiftDomain;
+    handleClick(screenX: number, screenY: number, _evt?: any): void;
+    handleDoubleClick(screenX: number, screenY: number, _evt?: any): void;
+    toggleSelection(seriesId: string, dataIndex: number, mode: 'single' | 'multiple', toggle: boolean): void;
+    clearSelection(): void;
+    private refreshSelectionVisuals;
+    getSelectedParams(): DataPointParams[];
+    get brushRect(): import("../internal").Rect | null;
+    private brushRange;
+    /** 像素 → 数据值；类目轴取命中带（或最近类目），数值轴取精确反算。 */
+    private valueAtPixel;
+    private orderValues;
+    private applyRange;
+    handleWheel(screenX: number, screenY: number, deltaY: number, evt?: any): boolean;
+    private zoomDomain;
+    private currentRange;
+    handleKeyDown(key: string, evt?: any): boolean;
+    /** 外部（联动）驱动：在指定 x 数据值上显示悬停。 */
+    showHoverAtValue(xValue: any): void;
+    clearHover(): void;
+    /** 沿指定方向找到下一个「落在绘图区内」的数据下标；找不到返回 -1。 */
+    /** 关系图组件 → 对应的 InternalSeries。 */
+    private seriesOfGraphComponent;
+    private stepVisibleIndex;
+    destroy(): void;
+}
+export { valueDistance };