@damoqiongqiu/ice-chart 0.17.0

package/dist/types/internal.d.mts

@@ -0,0 +1,232 @@
+import type { AxisOption, ChartOption, FunnelOption, GaugeOption, LiquidOption, GraphOption, LegendOption, RadarOption, SankeyOption, SeriesOption, SeriesType, TreemapOption, ChartTheme } from './types.mjs';
+import type { Scale } from './scale.mjs';
+/** 归一化后的数据点（数据域，不含像素）。 */
+export interface DataPoint {
+    /** 系列内下标。 */
+    index: number;
+    /** x 原始值：类目轴为类目，数值轴为数字，时间轴为时间戳。 */
+    xValue: any;
+    /** y 数值；null 表示断点。 */
+    y: number | null;
+    /** 原始数据项。 */
+    raw: any;
+    /** 堆叠基线（未堆叠时为 0）。 */
+    base: number;
+    /** 堆叠顶端（未堆叠时等于 y）。 */
+    top: number;
+    /** 类目名 / 扇区名（饼图、类目轴对象数据的 name 字段）。 */
+    name?: string;
+    /** 该数据点自身的颜色（饼图的每个扇区各有一色）。 */
+    color?: string;
+    /** 第三维数值（气泡图的尺寸）。 */
+    size?: number;
+    /** K 线的 [open, close, low, high]。 */
+    ohlc?: [number, number, number, number];
+    /** 箱线图的 [min, Q1, median, Q3, max]。 */
+    boxplot?: [number, number, number, number, number];
+}
+/** 极坐标布局：圆心与半径（图表坐标系）。 */
+export interface PolarLayout {
+    cx: number;
+    cy: number;
+    radius: number;
+}
+export interface InternalSeries {
+    id: string;
+    index: number;
+    type: SeriesType;
+    name: string;
+    color: string;
+    option: SeriesOption;
+    points: DataPoint[];
+    /** 数据里是否显式提供了 x（决定类目轴的类目来源）。 */
+    hasExplicitX: boolean;
+    /** 该系列是否被图例隐藏。 */
+    hidden: boolean;
+    /** 绑定的 y 轴下标。 */
+    axisIndex: number;
+    /**
+     * 数据域采样值（函数绘图用）。
+     *
+     * 函数图的 y 轴不该被 1/x 的尖峰拉到 ±2500，这里直接给出**稳健范围**，
+     * 由 buildYDomain 采纳；给了它就不再逐点取 y（点的 y 仍然是真值，供提示框使用）。
+     */
+    domainValues?: number[];
+    /**
+     * x 轴的取值集合（参数曲线用）。
+     *
+     * 参数曲线的 `xValue` 是参数 t，不是横坐标 —— x 轴数据域必须来自 `x(t)`，
+     * 否则坐标轴会按 t 的范围来画（李萨如曲线会整条错位）。
+     */
+    domainXValues?: number[];
+    /** 表达式编译失败时的原因（图表不崩，但要把错误暴露给表单 / 调用方）。 */
+    expressionError?: string;
+    /** 表达式诊断（语法 / 未定义变量 / 整段画不出来 / 输出恒定），交给表单去标红与提示。 */
+    expressionDiagnostics?: Array<{
+        code: string;
+        severity: 'error' | 'warning';
+        message: string;
+        position?: number;
+    }>;
+}
+export interface InternalAxis {
+    option: AxisOption;
+    type: 'linear' | 'category' | 'time' | 'log';
+    domain: any[];
+    scale: Scale | null;
+    /** 轴下标：x 轴恒为 0；y 轴对应 option.yAxis 数组下标。 */
+    index: number;
+    /** y 轴位置（x 轴为 left，不使用）。 */
+    position: 'left' | 'right';
+}
+export interface NormalizedOption {
+    /** 场景类型：直角坐标 / 极坐标（饼图）/ 雷达图 / 桑基图。 */
+    kind: 'cartesian' | 'polar' | 'radar' | 'sankey' | 'funnel' | 'gauge' | 'liquid' | 'treemap' | 'graph';
+    /**
+     * 直角坐标的排布方向。
+     * vertical：类目在 x 轴（普通柱状/折线）；horizontal：类目在 y 轴（横向柱状，排行榜场景）。
+     */
+    orientation: 'vertical' | 'horizontal';
+    /** 雷达图配置（存在雷达系列时非空）。 */
+    radar: RadarOption | null;
+    /** 桑基图配置（存在桑基系列时非空）。 */
+    sankey: SankeyOption | null;
+    /** 漏斗图配置。 */
+    funnel: FunnelOption | null;
+    /** 仪表盘配置。 */
+    gauge: GaugeOption | null;
+    /** 水位图配置（kind === 'liquid' 时非空）。 */
+    liquid: LiquidOption | null;
+    /** 矩形树图配置。 */
+    treemap: TreemapOption | null;
+    /** 关系图配置。 */
+    graph: GraphOption | null;
+    /** 每个雷达指标轴的数据域。 */
+    radarDomains: Array<[number, number]>;
+    /** 合并默认值之后的原始 option（函数字段保留）。 */
+    option: ChartOption & {
+        legend: LegendOption;
+        margin: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    theme: ChartTheme;
+    series: InternalSeries[];
+    xAxis: InternalAxis;
+    /** 全部 y 轴（yAxes[0] 是主 y 轴）。 */
+    yAxes: InternalAxis[];
+    /** 主 y 轴别名，等价于 yAxes[0]。 */
+    yAxis: InternalAxis;
+    /** 类目轴的类目列表（数值轴为空数组）。 */
+    categories: any[];
+    /** 参与渲染的系列（未被图例隐藏）。 */
+    visibleSeries: InternalSeries[];
+    hiddenIds: Record<string, boolean>;
+    /** 被隐藏的扇区，key 为 `seriesId#dataIndex`。 */
+    hiddenSlices: Record<string, boolean>;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AxisLayout {
+    /** 刻度值。 */
+    ticks: any[];
+    /** 刻度标签文本。 */
+    labels: string[];
+    /** 该轴相对绘图区边缘外扩的像素距离（多轴时同侧的轴逐层外移）。 */
+    offset: number;
+    /** 刻度标签的最大宽度 / 高度（像素）。 */
+    labelWidth: number;
+    labelHeight: number;
+    /** 轴名称文本宽度 / 高度。 */
+    nameWidth: number;
+    nameHeight: number;
+}
+export interface ChartLayout {
+    canvas: Rect;
+    plot: Rect;
+    titleRect: Rect | null;
+    legendRect: Rect | null;
+    legend: LegendLayout | null;
+    title: TitleLayout | null;
+    /** 极坐标圆心与半径；直角坐标场景为 null。 */
+    polar: PolarLayout | null;
+    /** dataZoom 滑块占用的矩形；未启用时为 null。 */
+    slider: Rect | null;
+    xAxisLayout: AxisLayout;
+    /** 每个 y 轴的刻度布局，与 norm.yAxes 一一对应。 */
+    yAxes: AxisLayout[];
+    /** 主 y 轴的刻度布局（yAxes[0] 的别名）。 */
+    yAxisLayout: AxisLayout;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+export interface LegendItemLayout {
+    seriesId: string;
+    seriesIndex: number;
+    name: string;
+    color: string;
+    hidden: boolean;
+    /** 饼图图例项对应的数据下标（直角坐标场景为 undefined）。 */
+    dataIndex?: number;
+    /** 可点击区域。 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LegendLayout {
+    position: 'top' | 'bottom' | 'left' | 'right';
+    items: LegendItemLayout[];
+}
+export interface TitleLayout {
+    text: string;
+    subtext: string;
+    /** 文本锚点。 */
+    x: number;
+    y: number;
+    align: 'left' | 'center' | 'right';
+    textStyle: {
+        color: string;
+        fontSize: number;
+        fontWeight: string | number;
+    };
+    subtextStyle: {
+        color: string;
+        fontSize: number;
+    };
+}
+/** 活动数据项（悬停 / 选中 / 键盘导航的共用描述）。 */
+export interface ActiveItem {
+    series: InternalSeries;
+    point: DataPoint;
+    /** 画布坐标（CSS 像素）。 */
+    screen: [number, number];
+    /** 图表坐标系内的像素位置（相对画布左上角）。 */
+    pixel: [number, number];
+}
+/** axis 触发器的悬停列：同一 x 上的所有系列数据点。 */
+export interface ActiveColumn {
+    dataIndex: number;
+    xValue: any;
+    /** 图表坐标系内的 x 像素。 */
+    pixelX: number;
+    items: ActiveItem[];
+}
+export type HoverState = {
+    kind: 'item';
+    item: ActiveItem;
+} | {
+    kind: 'axis';
+    column: ActiveColumn;
+} | null;

package/dist/types/internal.d.ts

@@ -0,0 +1,232 @@
+import type { AxisOption, ChartOption, FunnelOption, GaugeOption, LiquidOption, GraphOption, LegendOption, RadarOption, SankeyOption, SeriesOption, SeriesType, TreemapOption, ChartTheme } from './types';
+import type { Scale } from './scale';
+/** 归一化后的数据点（数据域，不含像素）。 */
+export interface DataPoint {
+    /** 系列内下标。 */
+    index: number;
+    /** x 原始值：类目轴为类目，数值轴为数字，时间轴为时间戳。 */
+    xValue: any;
+    /** y 数值；null 表示断点。 */
+    y: number | null;
+    /** 原始数据项。 */
+    raw: any;
+    /** 堆叠基线（未堆叠时为 0）。 */
+    base: number;
+    /** 堆叠顶端（未堆叠时等于 y）。 */
+    top: number;
+    /** 类目名 / 扇区名（饼图、类目轴对象数据的 name 字段）。 */
+    name?: string;
+    /** 该数据点自身的颜色（饼图的每个扇区各有一色）。 */
+    color?: string;
+    /** 第三维数值（气泡图的尺寸）。 */
+    size?: number;
+    /** K 线的 [open, close, low, high]。 */
+    ohlc?: [number, number, number, number];
+    /** 箱线图的 [min, Q1, median, Q3, max]。 */
+    boxplot?: [number, number, number, number, number];
+}
+/** 极坐标布局：圆心与半径（图表坐标系）。 */
+export interface PolarLayout {
+    cx: number;
+    cy: number;
+    radius: number;
+}
+export interface InternalSeries {
+    id: string;
+    index: number;
+    type: SeriesType;
+    name: string;
+    color: string;
+    option: SeriesOption;
+    points: DataPoint[];
+    /** 数据里是否显式提供了 x（决定类目轴的类目来源）。 */
+    hasExplicitX: boolean;
+    /** 该系列是否被图例隐藏。 */
+    hidden: boolean;
+    /** 绑定的 y 轴下标。 */
+    axisIndex: number;
+    /**
+     * 数据域采样值（函数绘图用）。
+     *
+     * 函数图的 y 轴不该被 1/x 的尖峰拉到 ±2500，这里直接给出**稳健范围**，
+     * 由 buildYDomain 采纳；给了它就不再逐点取 y（点的 y 仍然是真值，供提示框使用）。
+     */
+    domainValues?: number[];
+    /**
+     * x 轴的取值集合（参数曲线用）。
+     *
+     * 参数曲线的 `xValue` 是参数 t，不是横坐标 —— x 轴数据域必须来自 `x(t)`，
+     * 否则坐标轴会按 t 的范围来画（李萨如曲线会整条错位）。
+     */
+    domainXValues?: number[];
+    /** 表达式编译失败时的原因（图表不崩，但要把错误暴露给表单 / 调用方）。 */
+    expressionError?: string;
+    /** 表达式诊断（语法 / 未定义变量 / 整段画不出来 / 输出恒定），交给表单去标红与提示。 */
+    expressionDiagnostics?: Array<{
+        code: string;
+        severity: 'error' | 'warning';
+        message: string;
+        position?: number;
+    }>;
+}
+export interface InternalAxis {
+    option: AxisOption;
+    type: 'linear' | 'category' | 'time' | 'log';
+    domain: any[];
+    scale: Scale | null;
+    /** 轴下标：x 轴恒为 0；y 轴对应 option.yAxis 数组下标。 */
+    index: number;
+    /** y 轴位置（x 轴为 left，不使用）。 */
+    position: 'left' | 'right';
+}
+export interface NormalizedOption {
+    /** 场景类型：直角坐标 / 极坐标（饼图）/ 雷达图 / 桑基图。 */
+    kind: 'cartesian' | 'polar' | 'radar' | 'sankey' | 'funnel' | 'gauge' | 'liquid' | 'treemap' | 'graph';
+    /**
+     * 直角坐标的排布方向。
+     * vertical：类目在 x 轴（普通柱状/折线）；horizontal：类目在 y 轴（横向柱状，排行榜场景）。
+     */
+    orientation: 'vertical' | 'horizontal';
+    /** 雷达图配置（存在雷达系列时非空）。 */
+    radar: RadarOption | null;
+    /** 桑基图配置（存在桑基系列时非空）。 */
+    sankey: SankeyOption | null;
+    /** 漏斗图配置。 */
+    funnel: FunnelOption | null;
+    /** 仪表盘配置。 */
+    gauge: GaugeOption | null;
+    /** 水位图配置（kind === 'liquid' 时非空）。 */
+    liquid: LiquidOption | null;
+    /** 矩形树图配置。 */
+    treemap: TreemapOption | null;
+    /** 关系图配置。 */
+    graph: GraphOption | null;
+    /** 每个雷达指标轴的数据域。 */
+    radarDomains: Array<[number, number]>;
+    /** 合并默认值之后的原始 option（函数字段保留）。 */
+    option: ChartOption & {
+        legend: LegendOption;
+        margin: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    theme: ChartTheme;
+    series: InternalSeries[];
+    xAxis: InternalAxis;
+    /** 全部 y 轴（yAxes[0] 是主 y 轴）。 */
+    yAxes: InternalAxis[];
+    /** 主 y 轴别名，等价于 yAxes[0]。 */
+    yAxis: InternalAxis;
+    /** 类目轴的类目列表（数值轴为空数组）。 */
+    categories: any[];
+    /** 参与渲染的系列（未被图例隐藏）。 */
+    visibleSeries: InternalSeries[];
+    hiddenIds: Record<string, boolean>;
+    /** 被隐藏的扇区，key 为 `seriesId#dataIndex`。 */
+    hiddenSlices: Record<string, boolean>;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AxisLayout {
+    /** 刻度值。 */
+    ticks: any[];
+    /** 刻度标签文本。 */
+    labels: string[];
+    /** 该轴相对绘图区边缘外扩的像素距离（多轴时同侧的轴逐层外移）。 */
+    offset: number;
+    /** 刻度标签的最大宽度 / 高度（像素）。 */
+    labelWidth: number;
+    labelHeight: number;
+    /** 轴名称文本宽度 / 高度。 */
+    nameWidth: number;
+    nameHeight: number;
+}
+export interface ChartLayout {
+    canvas: Rect;
+    plot: Rect;
+    titleRect: Rect | null;
+    legendRect: Rect | null;
+    legend: LegendLayout | null;
+    title: TitleLayout | null;
+    /** 极坐标圆心与半径；直角坐标场景为 null。 */
+    polar: PolarLayout | null;
+    /** dataZoom 滑块占用的矩形；未启用时为 null。 */
+    slider: Rect | null;
+    xAxisLayout: AxisLayout;
+    /** 每个 y 轴的刻度布局，与 norm.yAxes 一一对应。 */
+    yAxes: AxisLayout[];
+    /** 主 y 轴的刻度布局（yAxes[0] 的别名）。 */
+    yAxisLayout: AxisLayout;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+export interface LegendItemLayout {
+    seriesId: string;
+    seriesIndex: number;
+    name: string;
+    color: string;
+    hidden: boolean;
+    /** 饼图图例项对应的数据下标（直角坐标场景为 undefined）。 */
+    dataIndex?: number;
+    /** 可点击区域。 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LegendLayout {
+    position: 'top' | 'bottom' | 'left' | 'right';
+    items: LegendItemLayout[];
+}
+export interface TitleLayout {
+    text: string;
+    subtext: string;
+    /** 文本锚点。 */
+    x: number;
+    y: number;
+    align: 'left' | 'center' | 'right';
+    textStyle: {
+        color: string;
+        fontSize: number;
+        fontWeight: string | number;
+    };
+    subtextStyle: {
+        color: string;
+        fontSize: number;
+    };
+}
+/** 活动数据项（悬停 / 选中 / 键盘导航的共用描述）。 */
+export interface ActiveItem {
+    series: InternalSeries;
+    point: DataPoint;
+    /** 画布坐标（CSS 像素）。 */
+    screen: [number, number];
+    /** 图表坐标系内的像素位置（相对画布左上角）。 */
+    pixel: [number, number];
+}
+/** axis 触发器的悬停列：同一 x 上的所有系列数据点。 */
+export interface ActiveColumn {
+    dataIndex: number;
+    xValue: any;
+    /** 图表坐标系内的 x 像素。 */
+    pixelX: number;
+    items: ActiveItem[];
+}
+export type HoverState = {
+    kind: 'item';
+    item: ActiveItem;
+} | {
+    kind: 'axis';
+    column: ActiveColumn;
+} | null;

package/dist/types/layout/force.d.mts

@@ -0,0 +1,48 @@
+import type { Rect } from '../internal.mjs';
+import type { GraphLinkOption, GraphNodeOption, GraphOption } from '../types.mjs';
+export interface ForceNodeLayout {
+    id: number;
+    name: string;
+    x: number;
+    y: number;
+    /** 力布局开始前的位置（环形铺开）——入场动画从它收敛到最终位置。 */
+    initialX: number;
+    initialY: number;
+    /** 由权重映射出的直径。 */
+    size: number;
+    value: number;
+    /** 度数（连了几条边），提示框与调试都用得上。 */
+    degree: number;
+    color: string;
+    category: string | number | undefined;
+    fixed: boolean;
+}
+export interface ForceLinkLayout {
+    id: number;
+    source: number;
+    target: number;
+    value: number;
+    width: number;
+    color: string;
+}
+export interface ForceLayoutResult {
+    nodes: ForceNodeLayout[];
+    links: ForceLinkLayout[];
+}
+/**
+ * 力导向布局（纯函数）。
+ *
+ * 与 sankey / treemap 一样，布局独立于渲染：输入节点与连线，输出坐标，
+ * 绘制与命中判定消费同一份结果。
+ *
+ * 三个力：
+ * - **斥力**（所有节点两两之间，∝ 1/d²）把节点推开；
+ * - **弹力**（沿连线，∝ d − edgeLength）把有关系的节点拉到理想距离；
+ * - **向心力**（∝ 中心 − 位置）防止孤立子图飘走。
+ *
+ * 初始位置用**环形均匀铺开**而不是随机：结果可复现，测试才能断言，
+ * 用户每次刷新看到的图也一致（随机初始位置会让同一份数据每次长得都不一样）。
+ */
+export declare function forceLayout(nodes: GraphNodeOption[], links: GraphLinkOption[], rect: Rect, options?: GraphOption, palette?: string[]): ForceLayoutResult;
+/** 顶点/连线的曲线控制点（绘制与命中判定共用）。 */
+export declare function sampleGraphLink(link: ForceLinkLayout, nodes: ForceNodeLayout[], curve: boolean, samples?: number): Array<[number, number]>;

package/dist/types/layout/force.d.ts

@@ -0,0 +1,48 @@
+import type { Rect } from '../internal';
+import type { GraphLinkOption, GraphNodeOption, GraphOption } from '../types';
+export interface ForceNodeLayout {
+    id: number;
+    name: string;
+    x: number;
+    y: number;
+    /** 力布局开始前的位置（环形铺开）——入场动画从它收敛到最终位置。 */
+    initialX: number;
+    initialY: number;
+    /** 由权重映射出的直径。 */
+    size: number;
+    value: number;
+    /** 度数（连了几条边），提示框与调试都用得上。 */
+    degree: number;
+    color: string;
+    category: string | number | undefined;
+    fixed: boolean;
+}
+export interface ForceLinkLayout {
+    id: number;
+    source: number;
+    target: number;
+    value: number;
+    width: number;
+    color: string;
+}
+export interface ForceLayoutResult {
+    nodes: ForceNodeLayout[];
+    links: ForceLinkLayout[];
+}
+/**
+ * 力导向布局（纯函数）。
+ *
+ * 与 sankey / treemap 一样，布局独立于渲染：输入节点与连线，输出坐标，
+ * 绘制与命中判定消费同一份结果。
+ *
+ * 三个力：
+ * - **斥力**（所有节点两两之间，∝ 1/d²）把节点推开；
+ * - **弹力**（沿连线，∝ d − edgeLength）把有关系的节点拉到理想距离；
+ * - **向心力**（∝ 中心 − 位置）防止孤立子图飘走。
+ *
+ * 初始位置用**环形均匀铺开**而不是随机：结果可复现，测试才能断言，
+ * 用户每次刷新看到的图也一致（随机初始位置会让同一份数据每次长得都不一样）。
+ */
+export declare function forceLayout(nodes: GraphNodeOption[], links: GraphLinkOption[], rect: Rect, options?: GraphOption, palette?: string[]): ForceLayoutResult;
+/** 顶点/连线的曲线控制点（绘制与命中判定共用）。 */
+export declare function sampleGraphLink(link: ForceLinkLayout, nodes: ForceNodeLayout[], curve: boolean, samples?: number): Array<[number, number]>;

package/dist/types/layout/layout.d.mts

@@ -0,0 +1,9 @@
+import type { ChartLayout, NormalizedOption, Rect } from '../internal.mjs';
+/**
+ * 计算图表布局（标题 / 图例 / 绘图区 / 坐标轴）。
+ *
+ * 顺序：先用「临时比例尺」拿刻度值（刻度只取决于数据域，与像素范围无关），
+ * 量出坐标轴占用的空间；再排标题与图例；最后推出绘图区矩形。
+ * 真正的比例尺由 Chart 拿到 plot rect 之后创建，保证刻度与布局严格一致。
+ */
+export declare function computeLayout(norm: NormalizedOption, ctx: any, canvas: Rect): ChartLayout;

package/dist/types/layout/layout.d.ts

@@ -0,0 +1,9 @@
+import type { ChartLayout, NormalizedOption, Rect } from '../internal';
+/**
+ * 计算图表布局（标题 / 图例 / 绘图区 / 坐标轴）。
+ *
+ * 顺序：先用「临时比例尺」拿刻度值（刻度只取决于数据域，与像素范围无关），
+ * 量出坐标轴占用的空间；再排标题与图例；最后推出绘图区矩形。
+ * 真正的比例尺由 Chart 拿到 plot rect 之后创建，保证刻度与布局严格一致。
+ */
+export declare function computeLayout(norm: NormalizedOption, ctx: any, canvas: Rect): ChartLayout;

package/dist/types/layout/sankey.d.mts

@@ -0,0 +1,47 @@
+import type { Rect } from '../internal.mjs';
+import type { SankeyLinkOption, SankeyNodeOption, SankeyOption } from '../types.mjs';
+export interface SankeyNodeLayout {
+    id: number;
+    name: string;
+    depth: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 节点总流量（入/出取大者）。 */
+    value: number;
+    color: string;
+}
+export interface SankeyLinkLayout {
+    id: number;
+    source: number;
+    target: number;
+    value: number;
+    /** 连线在源/目标处的厚度。 */
+    width: number;
+    /** 源端上沿 y。 */
+    sy: number;
+    /** 目标端上沿 y。 */
+    ty: number;
+    color: string;
+}
+export interface SankeyLayoutResult {
+    nodes: SankeyNodeLayout[];
+    links: SankeyLinkLayout[];
+}
+/**
+ * 桑基图布局（分层 + 纵向松弛）。
+ *
+ * 这里是 ice-chart 唯一一个「不是坐标系、而是图布局」的模块，因此刻意做成**纯函数**：
+ * 输入节点/连线与可用矩形，输出每个节点的矩形与每条连线的厚度/端点，
+ * 渲染与命中判定都消费同一份结果（和饼图扇形几何的处理方式一致）。
+ *
+ * 算法（简化版 d3-sankey）：
+ * 1. 按最长路径给节点分层（有环时用 Kahn 拓扑，环上的节点退化为同层）；
+ * 2. 每层先均匀铺开，再按邻居位置做几轮加权松弛，最后按顺序打包，保证不重叠；
+ * 3. 连线厚度 = 流量 × 端点节点「流量→像素」比例（取两端较小值），
+ *    并依次堆叠在节点的出入侧，保证同侧连线不重叠。
+ */
+export declare function layoutSankey(nodes: SankeyNodeOption[], links: SankeyLinkOption[], rect: Rect, options?: SankeyOption, palette?: string[]): SankeyLayoutResult;
+/** 连线中心线的采样点（命中判定与绘制共用）。 */
+export declare function sampleLinkPath(link: SankeyLinkLayout, sourceX: number, targetX: number, yOffset?: number, samples?: number): Array<[number, number]>;

package/dist/types/layout/sankey.d.ts

@@ -0,0 +1,47 @@
+import type { Rect } from '../internal';
+import type { SankeyLinkOption, SankeyNodeOption, SankeyOption } from '../types';
+export interface SankeyNodeLayout {
+    id: number;
+    name: string;
+    depth: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 节点总流量（入/出取大者）。 */
+    value: number;
+    color: string;
+}
+export interface SankeyLinkLayout {
+    id: number;
+    source: number;
+    target: number;
+    value: number;
+    /** 连线在源/目标处的厚度。 */
+    width: number;
+    /** 源端上沿 y。 */
+    sy: number;
+    /** 目标端上沿 y。 */
+    ty: number;
+    color: string;
+}
+export interface SankeyLayoutResult {
+    nodes: SankeyNodeLayout[];
+    links: SankeyLinkLayout[];
+}
+/**
+ * 桑基图布局（分层 + 纵向松弛）。
+ *
+ * 这里是 ice-chart 唯一一个「不是坐标系、而是图布局」的模块，因此刻意做成**纯函数**：
+ * 输入节点/连线与可用矩形，输出每个节点的矩形与每条连线的厚度/端点，
+ * 渲染与命中判定都消费同一份结果（和饼图扇形几何的处理方式一致）。
+ *
+ * 算法（简化版 d3-sankey）：
+ * 1. 按最长路径给节点分层（有环时用 Kahn 拓扑，环上的节点退化为同层）；
+ * 2. 每层先均匀铺开，再按邻居位置做几轮加权松弛，最后按顺序打包，保证不重叠；
+ * 3. 连线厚度 = 流量 × 端点节点「流量→像素」比例（取两端较小值），
+ *    并依次堆叠在节点的出入侧，保证同侧连线不重叠。
+ */
+export declare function layoutSankey(nodes: SankeyNodeOption[], links: SankeyLinkOption[], rect: Rect, options?: SankeyOption, palette?: string[]): SankeyLayoutResult;
+/** 连线中心线的采样点（命中判定与绘制共用）。 */
+export declare function sampleLinkPath(link: SankeyLinkLayout, sourceX: number, targetX: number, yOffset?: number, samples?: number): Array<[number, number]>;