@damoqiongqiu/ice-chart 0.30.12 → 0.30.13

package/dist/types/ICEChart.d.mts

@@ -1,6 +1,7 @@
 import { ICE, ICEGroup } from 'ice-render';
 import type { AnnotationDiagnostic, ChartMarkHandle, ChartMarkSpec, ChartOption, DataItem } from './types.mjs';
 import type { ChartLayout, InternalSeries, NormalizedOption } from './internal.mjs';
+import { type Scale } from './scale.mjs';
 import { GridLines } from './components/GridLines.mjs';
 import { Annotation } from './components/Annotation.mjs';
 import { PlotArea } from './components/PlotArea.mjs';
@@ -81,6 +82,17 @@ export declare class ICEChart {
     axisX: Axis;
     /** y 轴组件，与 norm.yAxes 一一对应（axisYList[0] 是主 y 轴）。 */
     axisYList: Axis[];
+    /** 每个面板一份网格（`grids[0]` 就是 `this.grid`；单面板时长度为 1）。 */
+    grids: GridLines[];
+    /** 每列一份 x 轴（面板矩阵的外圈轴；`panelAxisX[0]` 就是 `this.axisX`）。 */
+    panelAxisX: Axis[];
+    /** 每行一份 y 轴（面板矩阵的外圈轴；`panelAxisY[0]` 就是 `this.axisYList[0]`）。 */
+    panelAxisY: Axis[];
+    /** 每个面板的比例尺：域共享、range 按各自面板矩形。`panelScales[0]` 即 `norm.*.scale`。 */
+    panelScales: Array<{
+        x: Scale;
+        ys: Scale[];
+    }>;
     legend: Legend | null;
     titleComponent: Title | null;
     tooltip: Tooltip | null;
@@ -465,6 +477,35 @@ export declare class ICEChart {
      * 表达式系列 / 等比坐标由 `canApplyView` 挡下来，照旧整条重跑。
      */
     private rebuild;
+    /** 系列所属面板下标（没有 matrix、或下标越界时都退回 0）。 */
+    private panelIndexOf;
+    /** 系列所属面板的矩形（图表坐标系）。非直角坐标 / 单面板时就是整块绘图区。 */
+    private panelRectOf;
+    /** 系列所属面板的组件盒（`createSeriesComponent` 的入参形状）。 */
+    private panelBoxOf;
+    /** 系列所属面板的比例尺（域共享、range 按面板）。 */
+    private panelScalesOf;
+    /** 数据坐标图元所属的面板下标（`spec.panel`，默认 0；越界夹回）。 */
+    private markPanelIndex;
+    /**
+     * 同步一份网格线到给定矩形 / 比例尺。
+     *
+     * 单面板时就是从前那段代码逐字搬过来；多面板时每个面板各来一遍。
+     *
+     * 抽稀后的竖线位置是**同一批**（域共享），所以 `xTicks` 直接从布局那张表取，各面板不必重算。
+     */
+    private syncGrid;
+    /**
+     * 面板矩阵的组件池：每个面板一份网格、每行一份 y 轴、每列一份 x 轴。
+     *
+     * 三条纪律：
+     * 1. **`matrix` 缺席时全部退回单实例**（`grids[0]` 就是 `this.grid`、`panelAxisX[0]` 就是
+     *    `this.axisX`），旧路径一行都不用改，也不会多建组件；
+     * 2. 多出来的组件**按需创建、用完回收**（`setOption` 从矩阵切回单图时不留孤儿）；
+     * 3. 外圈轴的刻度表**只算一次**：域共享 → 每行/每列的刻度与标签完全相同，
+     *    这里只是把同一条轴画到不同的矩形上（`Axis.plot`）。
+     */
+    private syncPanelComponents;
     private buildScales;
     private syncComponents;
     /** 当前 x 数据域在完整数据域中的比例窗口（0~1），供 dataZoom 滑块显示。 */

package/dist/types/ICEChart.d.ts

@@ -1,6 +1,7 @@
 import { ICE, ICEGroup } from 'ice-render';
 import type { AnnotationDiagnostic, ChartMarkHandle, ChartMarkSpec, ChartOption, DataItem } from './types';
 import type { ChartLayout, InternalSeries, NormalizedOption } from './internal';
+import { type Scale } from './scale';
 import { GridLines } from './components/GridLines';
 import { Annotation } from './components/Annotation';
 import { PlotArea } from './components/PlotArea';
@@ -81,6 +82,17 @@ export declare class ICEChart {
     axisX: Axis;
     /** y 轴组件，与 norm.yAxes 一一对应（axisYList[0] 是主 y 轴）。 */
     axisYList: Axis[];
+    /** 每个面板一份网格（`grids[0]` 就是 `this.grid`；单面板时长度为 1）。 */
+    grids: GridLines[];
+    /** 每列一份 x 轴（面板矩阵的外圈轴；`panelAxisX[0]` 就是 `this.axisX`）。 */
+    panelAxisX: Axis[];
+    /** 每行一份 y 轴（面板矩阵的外圈轴；`panelAxisY[0]` 就是 `this.axisYList[0]`）。 */
+    panelAxisY: Axis[];
+    /** 每个面板的比例尺：域共享、range 按各自面板矩形。`panelScales[0]` 即 `norm.*.scale`。 */
+    panelScales: Array<{
+        x: Scale;
+        ys: Scale[];
+    }>;
     legend: Legend | null;
     titleComponent: Title | null;
     tooltip: Tooltip | null;
@@ -465,6 +477,35 @@ export declare class ICEChart {
      * 表达式系列 / 等比坐标由 `canApplyView` 挡下来，照旧整条重跑。
      */
     private rebuild;
+    /** 系列所属面板下标（没有 matrix、或下标越界时都退回 0）。 */
+    private panelIndexOf;
+    /** 系列所属面板的矩形（图表坐标系）。非直角坐标 / 单面板时就是整块绘图区。 */
+    private panelRectOf;
+    /** 系列所属面板的组件盒（`createSeriesComponent` 的入参形状）。 */
+    private panelBoxOf;
+    /** 系列所属面板的比例尺（域共享、range 按面板）。 */
+    private panelScalesOf;
+    /** 数据坐标图元所属的面板下标（`spec.panel`，默认 0；越界夹回）。 */
+    private markPanelIndex;
+    /**
+     * 同步一份网格线到给定矩形 / 比例尺。
+     *
+     * 单面板时就是从前那段代码逐字搬过来；多面板时每个面板各来一遍。
+     *
+     * 抽稀后的竖线位置是**同一批**（域共享），所以 `xTicks` 直接从布局那张表取，各面板不必重算。
+     */
+    private syncGrid;
+    /**
+     * 面板矩阵的组件池：每个面板一份网格、每行一份 y 轴、每列一份 x 轴。
+     *
+     * 三条纪律：
+     * 1. **`matrix` 缺席时全部退回单实例**（`grids[0]` 就是 `this.grid`、`panelAxisX[0]` 就是
+     *    `this.axisX`），旧路径一行都不用改，也不会多建组件；
+     * 2. 多出来的组件**按需创建、用完回收**（`setOption` 从矩阵切回单图时不留孤儿）；
+     * 3. 外圈轴的刻度表**只算一次**：域共享 → 每行/每列的刻度与标签完全相同，
+     *    这里只是把同一条轴画到不同的矩形上（`Axis.plot`）。
+     */
+    private syncPanelComponents;
     private buildScales;
     private syncComponents;
     /** 当前 x 数据域在完整数据域中的比例窗口（0~1），供 dataZoom 滑块显示。 */

package/dist/types/components/Axis.d.mts

@@ -1,6 +1,7 @@
 import { ChartComponent } from './ChartComponent.mjs';
 import type { ChartTheme } from '../types.mjs';
 import type { ChartLayout, InternalAxis } from '../internal.mjs';
+import type { Rect } from '../internal.mjs';
 /** 刻度平滑过渡时长：缩放 / 平移 / 数据更新时，标签滑动到新位置而不是瞬间跳。 */
 export declare const AXIS_MORPH_DURATION = 240;
 /**
@@ -17,6 +18,11 @@ export declare class Axis extends ChartComponent {
     /** y 轴下标（对应 norm.yAxes）；x 轴恒为 0。 */
     axisIndex: number;
     position: 'left' | 'right';
+    /**
+     * 这条轴负责的绘图区矩形；`null` = 用图表整体的 `layout.plot`（默认路径，逐像素不变）。
+     * 面板矩阵里给每条外圈轴指定它该负责的那一块面板。
+     */
+    plot: Rect | null;
     axis: InternalAxis | null;
     layout: ChartLayout | null;
     theme: ChartTheme | null;
@@ -33,6 +39,13 @@ export declare class Axis extends ChartComponent {
     });
     /** y 轴轴线的 x 坐标（含同侧多层偏移）。 */
     private edgeX;
+    /**
+     * 这条轴要画的绘图区矩形。
+     *
+     * 默认就是图表的绘图区（与从前逐字一致）；面板矩阵里由 Chart 给每条外圈轴指定
+     * **它该负责的那一块面板** —— 同一个组件画到不同矩形上，不再为每个面板复制一份轴逻辑。
+     */
+    private plotRect;
     private axisLayoutOf;
     /** 当前刻度 + 目标位置 + 标签（抽稀规则见 `buildAxisLayout`，那边是唯一来源）。 */
     private tickEntries;

package/dist/types/components/Axis.d.ts

@@ -1,6 +1,7 @@
 import { ChartComponent } from './ChartComponent';
 import type { ChartTheme } from '../types';
 import type { ChartLayout, InternalAxis } from '../internal';
+import type { Rect } from '../internal';
 /** 刻度平滑过渡时长：缩放 / 平移 / 数据更新时，标签滑动到新位置而不是瞬间跳。 */
 export declare const AXIS_MORPH_DURATION = 240;
 /**
@@ -17,6 +18,11 @@ export declare class Axis extends ChartComponent {
     /** y 轴下标（对应 norm.yAxes）；x 轴恒为 0。 */
     axisIndex: number;
     position: 'left' | 'right';
+    /**
+     * 这条轴负责的绘图区矩形；`null` = 用图表整体的 `layout.plot`（默认路径，逐像素不变）。
+     * 面板矩阵里给每条外圈轴指定它该负责的那一块面板。
+     */
+    plot: Rect | null;
     axis: InternalAxis | null;
     layout: ChartLayout | null;
     theme: ChartTheme | null;
@@ -33,6 +39,13 @@ export declare class Axis extends ChartComponent {
     });
     /** y 轴轴线的 x 坐标（含同侧多层偏移）。 */
     private edgeX;
+    /**
+     * 这条轴要画的绘图区矩形。
+     *
+     * 默认就是图表的绘图区（与从前逐字一致）；面板矩阵里由 Chart 给每条外圈轴指定
+     * **它该负责的那一块面板** —— 同一个组件画到不同矩形上，不再为每个面板复制一份轴逻辑。
+     */
+    private plotRect;
     private axisLayoutOf;
     /** 当前刻度 + 目标位置 + 标签（抽稀规则见 `buildAxisLayout`，那边是唯一来源）。 */
     private tickEntries;

package/dist/types/components/Crosshair.d.mts

@@ -1,6 +1,6 @@
 import { ChartComponent } from './ChartComponent.mjs';
 import type { ChartTheme, CrosshairOption } from '../types.mjs';
-import type { ChartLayout } from '../internal.mjs';
+import type { ChartLayout, Rect } from '../internal.mjs';
 /**
  * 准星跟随时长：**距离越大走得越快**，上限 `maxDuration`（0 = 立即跟随）。
  *
@@ -14,6 +14,12 @@ export declare function crosshairGlideDuration(distance: number, maxDuration: nu
 /** 十字准星：跟随活动数据列的辅助线 + 坐标轴数值标签。 */
 export declare class Crosshair extends ChartComponent {
     layout: ChartLayout | null;
+    /**
+     * 准星画在哪块绘图区里；`null` = 图表整体的 `layout.plot`（默认路径）。
+     * 面板矩阵里由 InteractionController 设成**指针所在面板** —— 准星只在那块里画，
+     * 否则一条线会横穿所有面板，指代不清。
+     */
+    plot: Rect | null;
     theme: ChartTheme | null;
     option: CrosshairOption;
     pixelX: number | null;

package/dist/types/components/Crosshair.d.ts

@@ -1,6 +1,6 @@
 import { ChartComponent } from './ChartComponent';
 import type { ChartTheme, CrosshairOption } from '../types';
-import type { ChartLayout } from '../internal';
+import type { ChartLayout, Rect } from '../internal';
 /**
  * 准星跟随时长：**距离越大走得越快**，上限 `maxDuration`（0 = 立即跟随）。
  *
@@ -14,6 +14,12 @@ export declare function crosshairGlideDuration(distance: number, maxDuration: nu
 /** 十字准星：跟随活动数据列的辅助线 + 坐标轴数值标签。 */
 export declare class Crosshair extends ChartComponent {
     layout: ChartLayout | null;
+    /**
+     * 准星画在哪块绘图区里；`null` = 图表整体的 `layout.plot`（默认路径）。
+     * 面板矩阵里由 InteractionController 设成**指针所在面板** —— 准星只在那块里画，
+     * 否则一条线会横穿所有面板，指代不清。
+     */
+    plot: Rect | null;
     theme: ChartTheme | null;
     option: CrosshairOption;
     pixelX: number | null;

package/dist/types/components/Tooltip.d.mts

@@ -1,6 +1,6 @@
 import { ChartComponent } from './ChartComponent.mjs';
 import type { ChartTheme, TooltipOption } from '../types.mjs';
-import type { ChartLayout } from '../internal.mjs';
+import type { ChartLayout, Rect } from '../internal.mjs';
 export interface TooltipRow {
     name: string;
     value: string;
@@ -18,6 +18,11 @@ export declare class Tooltip extends ChartComponent {
     theme: ChartTheme | null;
     option: TooltipOption;
     layout: ChartLayout | null;
+    /**
+     * 提示框的避让边界；`null` = 整块绘图区（默认路径）。
+     * 面板矩阵里由 InteractionController 设成指针所在的那块面板。
+     */
+    plot: Rect | null;
     content: TooltipContent | null;
     anchor: [number, number];
     /** 是否让提示框跟随指针（axis 触发器常关掉，让它固定在数据列上方）。 */

package/dist/types/components/Tooltip.d.ts

@@ -1,6 +1,6 @@
 import { ChartComponent } from './ChartComponent';
 import type { ChartTheme, TooltipOption } from '../types';
-import type { ChartLayout } from '../internal';
+import type { ChartLayout, Rect } from '../internal';
 export interface TooltipRow {
     name: string;
     value: string;
@@ -18,6 +18,11 @@ export declare class Tooltip extends ChartComponent {
     theme: ChartTheme | null;
     option: TooltipOption;
     layout: ChartLayout | null;
+    /**
+     * 提示框的避让边界；`null` = 整块绘图区（默认路径）。
+     * 面板矩阵里由 InteractionController 设成指针所在的那块面板。
+     */
+    plot: Rect | null;
     content: TooltipContent | null;
     anchor: [number, number];
     /** 是否让提示框跟随指针（axis 触发器常关掉，让它固定在数据列上方）。 */

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

@@ -0,0 +1,23 @@
+import { SeriesBase } from './SeriesBase.mjs';
+import type { SeriesType } from '../../types.mjs';
+/**
+ * 蜂群图（抖动条带）：每个观测一个点，同一类目里挤在一起的点横向错开。
+ *
+ * 与散点图的关系：数据形态、绘制、命中判定都是散点那一套（逐点 `[x, y]`），
+ * 唯一的区别是 x 不是直接映射出来的，而是**在 band 内避让之后**的位置。
+ * 避让发生在像素空间，所以算在 `rebuildPixels()` 里 —— 归一化阶段没有比例尺。
+ */
+export declare class BeeswarmSeries extends SeriesBase {
+    seriesType: SeriesType;
+    protected supportsSampling: boolean;
+    protected clipToBox: boolean;
+    private swarmKey;
+    /** 标记的形状与配色（与散点同一套字段，别各写一份）。 */
+    private symbolStyle;
+    /**
+     * 像素缓存 = 避让后的点位置，**绘制与命中共用这一份**（铁律 2）。
+     */
+    protected rebuildPixels(): void;
+    hitTestIndex(localX: number, localY: number): number;
+    protected doRender(): void;
+}

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

@@ -0,0 +1,23 @@
+import { SeriesBase } from './SeriesBase';
+import type { SeriesType } from '../../types';
+/**
+ * 蜂群图（抖动条带）：每个观测一个点，同一类目里挤在一起的点横向错开。
+ *
+ * 与散点图的关系：数据形态、绘制、命中判定都是散点那一套（逐点 `[x, y]`），
+ * 唯一的区别是 x 不是直接映射出来的，而是**在 band 内避让之后**的位置。
+ * 避让发生在像素空间，所以算在 `rebuildPixels()` 里 —— 归一化阶段没有比例尺。
+ */
+export declare class BeeswarmSeries extends SeriesBase {
+    seriesType: SeriesType;
+    protected supportsSampling: boolean;
+    protected clipToBox: boolean;
+    private swarmKey;
+    /** 标记的形状与配色（与散点同一套字段，别各写一份）。 */
+    private symbolStyle;
+    /**
+     * 像素缓存 = 避让后的点位置，**绘制与命中共用这一份**（铁律 2）。
+     */
+    protected rebuildPixels(): void;
+    hitTestIndex(localX: number, localY: number): number;
+    protected doRender(): void;
+}

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

@@ -0,0 +1,34 @@
+import { SeriesBase } from './SeriesBase.mjs';
+import type { SeriesType } from '../../types.mjs';
+/**
+ * 小提琴图：每个数据项是**一组原始观测值**，轮廓由核密度曲线镜像而来。
+ *
+ * 几何口径：
+ * - 密度曲线在**数据空间**算（归一化里的 `computeKdeProfile`，纯函数可单测），
+ *   组件只做「数据空间 → 像素」的映射 —— 与函数绘图同一条思路：几何来自公式，不是逐点数据；
+ * - 轮廓宽度按密度**归一化**到「band 内的半宽」，所以峰值贴着最宽处、尾巴收成一条线；
+ * - 命中就是**这片轮廓的内部**（与渲染共用同一份多边形，铁律 1 + 铁律 2）。
+ */
+export declare class ViolinSeries extends SeriesBase {
+    seriesType: SeriesType;
+    protected supportsSampling: boolean;
+    protected clipToBox: boolean;
+    private geometryKey;
+    private pixelKey;
+    private polygons;
+    /** 轮廓的半宽（像素）：`barWidth` 与箱线同口径，0~1 的小数是 band 占比。 */
+    private halfWidth;
+    /**
+     * 每条轮廓的像素几何（本地坐标）。
+     *
+     * 缓存键必须带坐标系指纹与绘图区尺寸（走 `buildSeriesKey`）：缩放 / 平移 / 数据域过渡
+     * 之后密度曲线的像素位置全变，键不变就会拿旧轮廓去命中。
+     */
+    private ensureGeometry;
+    /** 某一组的轮廓（本地像素坐标，闭合多边形）；没有密度时返回 null。 */
+    violinPolygonAt(index: number): Array<[number, number]> | null;
+    /** 像素缓存 = 轮廓的「最宽处中心」（高亮与提示框锚点）。 */
+    protected rebuildPixels(): void;
+    hitTestIndex(localX: number, localY: number): number;
+    protected doRender(): void;
+}

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

@@ -0,0 +1,34 @@
+import { SeriesBase } from './SeriesBase';
+import type { SeriesType } from '../../types';
+/**
+ * 小提琴图：每个数据项是**一组原始观测值**，轮廓由核密度曲线镜像而来。
+ *
+ * 几何口径：
+ * - 密度曲线在**数据空间**算（归一化里的 `computeKdeProfile`，纯函数可单测），
+ *   组件只做「数据空间 → 像素」的映射 —— 与函数绘图同一条思路：几何来自公式，不是逐点数据；
+ * - 轮廓宽度按密度**归一化**到「band 内的半宽」，所以峰值贴着最宽处、尾巴收成一条线；
+ * - 命中就是**这片轮廓的内部**（与渲染共用同一份多边形，铁律 1 + 铁律 2）。
+ */
+export declare class ViolinSeries extends SeriesBase {
+    seriesType: SeriesType;
+    protected supportsSampling: boolean;
+    protected clipToBox: boolean;
+    private geometryKey;
+    private pixelKey;
+    private polygons;
+    /** 轮廓的半宽（像素）：`barWidth` 与箱线同口径，0~1 的小数是 band 占比。 */
+    private halfWidth;
+    /**
+     * 每条轮廓的像素几何（本地坐标）。
+     *
+     * 缓存键必须带坐标系指纹与绘图区尺寸（走 `buildSeriesKey`）：缩放 / 平移 / 数据域过渡
+     * 之后密度曲线的像素位置全变，键不变就会拿旧轮廓去命中。
+     */
+    private ensureGeometry;
+    /** 某一组的轮廓（本地像素坐标，闭合多边形）；没有密度时返回 null。 */
+    violinPolygonAt(index: number): Array<[number, number]> | null;
+    /** 像素缓存 = 轮廓的「最宽处中心」（高亮与提示框锚点）。 */
+    protected rebuildPixels(): void;
+    hitTestIndex(localX: number, localY: number): number;
+    protected doRender(): void;
+}

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

@@ -15,6 +15,8 @@ export type { FunnelSeriesCoord } from './FunnelSeries.mjs';
 export { GaugeSeries } from './GaugeSeries.mjs';
 export type { GaugeSeriesCoord } from './GaugeSeries.mjs';
 export { BoxplotSeries } from './BoxplotSeries.mjs';
+export { ViolinSeries } from './ViolinSeries.mjs';
+export { BeeswarmSeries } from './BeeswarmSeries.mjs';
 export { WaterfallSeries } from './WaterfallSeries.mjs';
 export { TreemapSeries } from './TreemapSeries.mjs';
 export type { TreemapSeriesCoord } from './TreemapSeries.mjs';

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

@@ -15,6 +15,8 @@ export type { FunnelSeriesCoord } from './FunnelSeries';
 export { GaugeSeries } from './GaugeSeries';
 export type { GaugeSeriesCoord } from './GaugeSeries';
 export { BoxplotSeries } from './BoxplotSeries';
+export { ViolinSeries } from './ViolinSeries';
+export { BeeswarmSeries } from './BeeswarmSeries';
 export { WaterfallSeries } from './WaterfallSeries';
 export { TreemapSeries } from './TreemapSeries';
 export type { TreemapSeriesCoord } from './TreemapSeries';

package/dist/types/index.d.mts

@@ -48,6 +48,8 @@ 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 { ViolinSeries } from './components/series/ViolinSeries.mjs';
+export { BeeswarmSeries } from './components/series/BeeswarmSeries.mjs';
 export { WaterfallSeries } from './components/series/WaterfallSeries.mjs';
 export { TreemapSeries } from './components/series/TreemapSeries.mjs';
 export type { TreemapSeriesCoord } from './components/series/TreemapSeries.mjs';

package/dist/types/index.d.ts

@@ -48,6 +48,8 @@ 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 { ViolinSeries } from './components/series/ViolinSeries';
+export { BeeswarmSeries } from './components/series/BeeswarmSeries';
 export { WaterfallSeries } from './components/series/WaterfallSeries';
 export { TreemapSeries } from './components/series/TreemapSeries';
 export type { TreemapSeriesCoord } from './components/series/TreemapSeries';

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

@@ -1,4 +1,4 @@
-import type { ActiveColumn, ActiveItem, ChartLayout, InternalSeries, NormalizedOption } from '../internal.mjs';
+import type { ActiveColumn, ActiveItem, ChartLayout, InternalSeries, NormalizedOption, Rect } from '../internal.mjs';
 import type { DataPointParams } from '../types.mjs';
 import type { SeriesBase } from '../components/series/SeriesBase.mjs';
 export interface HitHost {
@@ -30,12 +30,29 @@ export declare class HitResolver {
     constructor(host: HitHost);
     resolveTarget(screenX: number, screenY: number): TargetInfo;
     isInsidePlot(chartX: number, chartY: number): boolean;
+    /**
+     * 指针落在第几个面板里（-1 = 不在任何面板内）。
+     *
+     * 面板矩阵下这是交互的总入口：悬停、框选、缩放、键盘都要先问「在哪块面板」。
+     * 没有 `matrix` 时 `layout.panels` 只有一个矩形，等价于从前的 `isInsidePlot`。
+     */
+    panelAt(chartX: number, chartY: number): number;
+    /** 第几个面板的矩形（越界退回绘图区）。 */
+    panelRect(index: number): Rect;
     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;
+    /**
+     * 「同一列」的活动项：轴触发提示框 / 十字准星都按它取数。
+     *
+     * 面板矩阵下**只收指针所在面板的系列**：否则在第 6 块面板上悬停，提示框会把另外五块的
+     * 数据一起列出来（它们 x 值相同但根本不是同一张图）。
+     */
+    pickColumn(chartX: number, chartY: number): ActiveColumn | null;
+    /** 系列所属面板（越界退回 0）。 */
+    seriesPanelOf(series: InternalSeries): number;
     nearestIndexByX(component: SeriesBase, localX: number): number;
     /** 按数据值找最近的点（跨图联动用）。 */
     nearestByXValue(xValue: any): ActiveItem | null;

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

@@ -1,4 +1,4 @@
-import type { ActiveColumn, ActiveItem, ChartLayout, InternalSeries, NormalizedOption } from '../internal';
+import type { ActiveColumn, ActiveItem, ChartLayout, InternalSeries, NormalizedOption, Rect } from '../internal';
 import type { DataPointParams } from '../types';
 import type { SeriesBase } from '../components/series/SeriesBase';
 export interface HitHost {
@@ -30,12 +30,29 @@ export declare class HitResolver {
     constructor(host: HitHost);
     resolveTarget(screenX: number, screenY: number): TargetInfo;
     isInsidePlot(chartX: number, chartY: number): boolean;
+    /**
+     * 指针落在第几个面板里（-1 = 不在任何面板内）。
+     *
+     * 面板矩阵下这是交互的总入口：悬停、框选、缩放、键盘都要先问「在哪块面板」。
+     * 没有 `matrix` 时 `layout.panels` 只有一个矩形，等价于从前的 `isInsidePlot`。
+     */
+    panelAt(chartX: number, chartY: number): number;
+    /** 第几个面板的矩形（越界退回绘图区）。 */
+    panelRect(index: number): Rect;
     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;
+    /**
+     * 「同一列」的活动项：轴触发提示框 / 十字准星都按它取数。
+     *
+     * 面板矩阵下**只收指针所在面板的系列**：否则在第 6 块面板上悬停，提示框会把另外五块的
+     * 数据一起列出来（它们 x 值相同但根本不是同一张图）。
+     */
+    pickColumn(chartX: number, chartY: number): ActiveColumn | null;
+    /** 系列所属面板（越界退回 0）。 */
+    seriesPanelOf(series: InternalSeries): number;
     nearestIndexByX(component: SeriesBase, localX: number): number;
     /** 按数据值找最近的点（跨图联动用）。 */
     nearestByXValue(xValue: any): ActiveItem | null;

package/dist/types/internal.d.mts

@@ -3,6 +3,7 @@ import type { Scale } from './scale.mjs';
 import type { SeriesRing } from './util/ring.mjs';
 import type { SeriesChunks } from './util/chunks.mjs';
 import type { ChartLabels } from './types.mjs';
+import type { ResolvedMatrix } from './layout/panels.mjs';
 /** 归一化后的数据点（数据域，不含像素）。 */
 export interface DataPoint {
     /** 系列内下标。 */
@@ -25,6 +26,26 @@ export interface DataPoint {
     size?: number;
     /** 箱线图的 [min, Q1, median, Q3, max]。 */
     boxplot?: [number, number, number, number, number];
+    /** 小提琴图的密度轮廓（归一化阶段算好，组件只做像素映射）。 */
+    violin?: ViolinProfile;
+}
+/**
+ * 小提琴图的密度轮廓。
+ *
+ * `grid` / `density` 都在**数据空间**里（y 是观测值，密度单位 1/y）；
+ * 组件负责把它映射成像素轮廓，所以归一化里不需要比例尺 —— 这也是它能单测的原因。
+ */
+export interface ViolinProfile {
+    /** 原始观测值（提示框报观测数、与蜂群叠画都读它）。 */
+    values: number[];
+    /** 实际使用的带宽。 */
+    bandwidth: number;
+    /** 评估网格（升序）。 */
+    grid: number[];
+    /** 与 `grid` 一一对应的密度值。 */
+    density: number[];
+    /** [min, Q1, median, Q3, max]，与箱线图同一口径（提示框复用）。 */
+    summary: [number, number, number, number, number];
 }
 /** 极坐标布局：圆心与半径（图表坐标系）。 */
 export interface PolarLayout {
@@ -218,6 +239,11 @@ export interface InternalSeries {
     hidden: boolean;
     /** 绑定的 y 轴下标。 */
     axisIndex: number;
+    /**
+     * 所属面板下标（行优先）。没有 `option.matrix` 时恒为 0 ——
+     * 归一化阶段已夹到合法范围，后续按面板取几何的地方可以直接下下标。
+     */
+    panel: number;
     /**
      * 归一化后的瀑布图配置（系列级优先，其次顶层 `option.waterfall`）。
      *
@@ -367,6 +393,8 @@ export interface InternalAxis {
     categoryOffset?: number;
 }
 export interface NormalizedOption {
+    /** 面板矩阵（小倍数）：null = 单绘图区（现有行为）。 */
+    matrix: ResolvedMatrix | null;
     /** 场景类型：直角坐标 / 极坐标（饼图）/ 雷达图 / 桑基图。 */
     kind: 'cartesian' | 'polar' | 'radar' | 'sankey' | 'funnel' | 'gauge' | 'liquid' | 'treemap' | 'graph';
     /**
@@ -461,6 +489,9 @@ export interface AxisLayout {
 }
 export interface ChartLayout {
     canvas: Rect;
+    /** 面板矩阵的各面板矩形（行优先）。没有 `option.matrix` 时就是 `[plot]`。 */
+    panels: Rect[];
+    /** 绘图区；有面板矩阵时是**面板的并集**（无 matrix 时与 `panels[0]` 逐像素相同）。 */
     plot: Rect;
     titleRect: Rect | null;
     legendRect: Rect | null;
@@ -532,6 +563,8 @@ export interface ActiveColumn {
     xValue: any;
     /** 图表坐标系内的 x 像素。 */
     pixelX: number;
+    /** 这一列属于哪个面板（没有面板矩阵时恒为 0）。 */
+    panel: number;
     items: ActiveItem[];
 }
 export type HoverState = {