transone-chart 0.1.2

package/README.md

@@ -0,0 +1,181 @@
+# transone-chart
+
+TransOne 生态的跨端图表库：**一份 TypeScript 源码，基于 Canvas 2D 渲染**，同时跑通 Web 与微信 / 阿里 / 字节小程序，并为未来原生 App（iOS / Android / 鸿蒙）预留扩展契约。
+
+一期内置四种常用图表：**折线图 / 柱状图 / 饼图（环形）/ 雷达图**。
+
+- 零运行时依赖（`transone` 仅组件集成为 optional peer）
+- OOP + 策略模式：`core（纯引擎）→ charts（图表策略）→ adapters（平台差异）→ factory（分发）→ component（声明式组件）`
+- 跨端唯一解耦边界是 `ICanvas2D` 契约（图表所需的最小 Canvas 2D 子集）
+- 与 `transone` 组件系统无缝集成：`<TcChart option={...} />` 一份代码编译到 Web / 小程序
+
+## 安装
+
+```bash
+bun add transone-chart          # 运行时（peer: transone >= 0.3.0）
+bun add -d transone-chart       # 仅引擎用法时
+```
+
+## 快速开始
+
+### 方式一：声明式组件（推荐，配合 transone）
+
+```tsx
+import { Component, createComponent } from 'transone';
+import { TcChart } from 'transone-chart';
+
+// 任意图表 Option
+const option = {
+  type: 'line',
+  title: { text: '城市指数趋势' },
+  xAxis: { labels: ['4月', '5月', '6月', '7月', '8月', '9月'] },
+  series: [
+    { name: '北京', data: [82, 85, 84, 88, 90, 92], smooth: true },
+    { name: '上海', data: [80, 83, 86, 85, 89, 91], smooth: true, area: true },
+  ],
+};
+
+class MyPage extends Component {
+  render() {
+    return createComponent({ component: TcChart, props: { option } });
+  }
+}
+```
+
+`TcChart` 是**受控组件**：`option` 由父级传入，数据变化自动 `setOption + render`；组件卸载自动销毁。
+
+### 方式二：引擎直用（无框架场景）
+
+```ts
+import { createWebChart, createMiniProgramChart } from 'transone-chart';
+
+// Web：canvas 元素
+const chart = createWebChart(canvasElement, option);
+chart.render();
+
+// 小程序：Canvas 2D 节点
+const chart2 = createMiniProgramChart(canvasNode, option);
+chart2.render();
+
+// 高级：自定义渲染上下文（如原生桥层实现 ICanvas2D 后）
+import { createChart } from 'transone-chart';
+const chart3 = createChart(context, option); // context 为 ChartRenderContext
+chart3.render();
+```
+
+## 图表 API 一览
+
+所有配置均为 `ECharts` 心智（`title / legend / xAxis / yAxis / series`），但零依赖纯 Canvas 绘制。
+
+| 图表 | Option 类型 | 核心配置 |
+|---|---|---|
+| 折线 | `LineChartOption` | `smooth` 平滑曲线、`area` 面积填充、`showSymbol` 数据点、`startFromZero` |
+| 柱状 | `BarChartOption` | `stack` 堆叠分组、`horizontal` 横向、`borderRadius` 圆角、`barWidth` |
+| 饼图 | `PieChartOption` | `radius / innerRadius`（环形）、`startAngle`、扇区百分比标签 |
+| 雷达 | `RadarChartOption` | `indicators[].max` 归一化、`splitCount` 网格层、`area` 多边形填充 |
+
+完整字段见 [`lib/types.ts`](./lib/types.ts)（每个字段均带中文注释）。
+
+## 跨端支持
+
+| 平台 | 支持 | 说明 |
+|---|---|---|
+| Web | ✅ | `HTMLCanvasElement.getContext('2d')` 直接满足 `ICanvas2D` |
+| 微信小程序 | ✅ | `<canvas type="2d">` + SelectorQuery 节点；CLI 已内置 canvas 标签映射 |
+| 阿里小程序 | ✅ | 同一适配层（安全取全局 `my` / `tt` / `wx`） |
+| 字节小程序 | ✅ | 同上 |
+| iOS / Android / 鸿蒙 App | 🔜 契约就绪 | 实现 `ICanvas2D`（约 20 个方法）即可接入，见下节 |
+
+> 小程序端 DPR 通过各端 `getSystemInfoSync()` 获取，像素比自动适配，无需手工处理。
+
+### 小程序端约束（写组件代码前必读）
+
+transone-cli 对小程序端模板/组件有静态编译约束，`TcChart` 已按其适配，使用方注意：
+
+- **option 请放在 `initState()` 的返回对象中**（经 data 序列化 + `wx:for` 数据绑定传给组件），
+  不要直接在 `render()` 里引用模块级常量对象——静态常量会被折叠为字符串属性，对象 props 会丢失。
+  参见 `playground/chart-demo/src/pages/home.ts` 的 `charts` 数组写法。
+- `initState()` 内只支持 `const` 声明与 `return`（小程序端需静态求值）；`render()` 内不支持调用
+  自定义辅助方法（请用 `each(...)` 展开），`each` 的 key 仅支持 `(item) => item.xxx` 或 `(item, index) => index`。
+- 小程序端 props 无法传函数（如 `option.format`），需要函数时请在端内判断分支。
+
+## 原生 App 扩展指南
+
+图表引擎与平台完全解耦，唯一的平台边界是 `ICanvas2D`（`lib/core/canvas.ts`）。
+原生端只需实现该契约（`beginPath / moveTo / lineTo / bezierCurveTo / arc / fill / stroke / measureText / createLinearGradient` 等），
+再通过 `adapters/native.ts` 的 `resolveNativeCanvas` 注入即可，图表层零改动。
+
+```ts
+import { createChart } from 'transone-chart';
+import { resolveNativeCanvas } from 'transone-chart/adapters';
+
+// 原生桥层：把原生画布上下文包装成 ICanvas2D，并实现 NativeCanvasHost
+const host = {
+  width: 375,
+  height: 260,
+  pixelRatio: 2,
+  getContext(type: '2d') {
+    return { beginPath() {}, moveTo() {}, /* ...实现 ICanvas2D */ };
+  },
+};
+const chart = createChart(resolveNativeCanvas(host), option);
+chart.render();
+```
+
+> `adapters/native.ts` 当前是契约占位：未实现时调用会显式抛错，**绝不静默降级**，
+> 保证原生端不会出现"看起来渲染了其实空白"的隐性故障。
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│ component.ts   TcChart 声明式组件（受控，自动生命周期）   │
+├─────────────────────────────────────────────────────┤
+│ factory.ts     createChart(option) 按 type 分发策略    │
+├─────────────────────────────────────────────────────┤
+│ charts/        LineChart / BarChart / PieChart /     │
+│                RadarChart（策略类，只依赖 core）       │
+├─────────────────────────────────────────────────────┤
+│ core/          canvas.ts(ICanvas2D 契约) · scale ·    │
+│                layout · axis · legend · chart(基类)   │
+├─────────────────────────────────────────────────────┤
+│ adapters/      web.ts · miniprogram.ts · native.ts   │
+└─────────────────────────────────────────────────────┘
+```
+
+渲染管线（`ChartBase`）：
+
+```
+save → scale(dpr) → clear → 背景 → 布局(title/legend/轴区逐层扣除)
+→ 标题 → 图例 → 坐标轴(仅笛卡尔类) → drawSeries → restore
+```
+
+- `seriesColor` 按索引取 `DEFAULT_PALETTE` 色板，显式 `color` 优先
+- 数值轴自动 nice 刻度；类目轴无标签不预留轴区
+- 图例：series 带 `name` 且未显式配置时，默认 `top` 显示
+
+## 开发
+
+```bash
+bun test                  # 46 个单测（mock canvas 断言绘制命令）
+bun run build             # tsc 声明 + Bun.build（minify, ESM）
+bun run --cwd ../../playground/chart-demo build:web   # 演示项目构建
+```
+
+## 目录结构
+
+```
+packages/transone-chart/
+├── lib/               # 源码（core / charts / adapters / factory / component / types）
+├── tests/             # 单测（scale / layout / line / bar / pie / radar / factory）
+├── scripts/build.ts   # 构建脚本
+└── playground 演示：playground/chart-demo（城市指数场景，五种图表卡片）
+```
+
+## 路线图
+
+- [x] 一期：折线 / 柱状 / 饼 / 雷达 + Web / 小程序 + 原生契约
+- [ ] 交互：tooltip / 高亮 / 点击事件（event 层）
+- [ ] 更多图表：散点 / 面积 / 漏斗 / 仪表盘
+- [ ] 原生 App 适配器实现（iOS / Android / 鸿蒙桥层）
+- [ ] 主题系统 / 动画过渡

package/dist/adapters/index.d.ts

@@ -0,0 +1,7 @@
+export type { ResolveCanvasOptions, ResolvedCanvas, } from './types';
+export { detectPixelRatio } from './types';
+export { resolveWebCanvas } from './web';
+export { getMiniProgramCanvasNode, getMiniProgramGlobal, resolveMiniProgramCanvas, detectMiniProgramPixelRatio, } from './miniprogram';
+export type { MiniProgramCanvasNode, MiniProgramGlobal } from './miniprogram';
+export { resolveNativeCanvas } from './native';
+export type { NativeCanvasHost } from './native';

package/dist/adapters/miniprogram.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 小程序适配器：微信 / 阿里 / 字节的 Canvas 2D 节点 → ChartRenderContext。
+ *
+ * 获取流程（各端一致，仅全局名不同）：
+ *   canvas type="2d" → 节点 node → node.getContext('2d') → ICanvas2D
+ *
+ * 节点获取依赖 SelectorQuery，属于组件生命周期职责，由
+ * getMiniProgramCanvasNode() 提供；本文件只负责「节点 → 上下文」，
+ * 以及 DPR 探测（pixelRatio 从各端系统信息接口读取）。
+ */
+import type { ChartRenderContext } from '../types';
+import { type ResolveCanvasOptions } from './types';
+/** 小程序 Canvas 2D 节点（各端 node 的公共形状）。 */
+export interface MiniProgramCanvasNode {
+    getContext(type: '2d'): unknown;
+    width: number;
+    height: number;
+}
+export type MiniProgramGlobal = 'wx' | 'my' | 'tt';
+/** 安全读取小程序全局（避免与官方类型定义冲突，模式同 transone request）。 */
+export declare function getMiniProgramGlobal(name: MiniProgramGlobal): Record<string, unknown> | null;
+/**
+ * 通过 SelectorQuery 获取 Canvas 2D 节点（组件/页面内调用）。
+ * 各端 API 形状一致：createSelectorQuery().in(instance).select(selector)
+ *   .fields({ node: true, size: true }).exec(callback)
+ */
+export declare function getMiniProgramCanvasNode(options: {
+    /** 端标识，缺省自动探测（wx → my → tt）。 */
+    platform?: MiniProgramGlobal;
+    /** 组件/页面实例（.in() 入参）。 */
+    instance?: unknown;
+    /** canvas 选择器，如 '#chart'。 */
+    selector: string;
+}): Promise<MiniProgramCanvasNode>;
+/** 探测当前小程序全局（wx → my → tt），均不存在返回 null。 */
+export declare function detectMiniProgramGlobal(): MiniProgramGlobal | null;
+/** 读取各端设备像素比（wx.getSystemInfoSync / my.getSystemInfoSync / tt.getSystemInfoSync）。 */
+export declare function detectMiniProgramPixelRatio(platform?: MiniProgramGlobal): number;
+/**
+ * 从 Canvas 2D 节点解析渲染上下文。
+ * 物理画布尺寸由节点自身管理（width/height 已在平台侧按像素比设置），
+ * 此处只做归一化返回。
+ */
+export declare function resolveMiniProgramCanvas(node: MiniProgramCanvasNode, options?: ResolveCanvasOptions): ChartRenderContext;

package/dist/adapters/native.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 原生 App 适配器（占位 / 契约声明）。
+ *
+ * 未来 iOS / Android / 鸿蒙 原生端接入路径：
+ * 1. 宿主提供原生 canvas 能力（Skia / ArkUI Canvas / WebView 桥），
+ *    把原生绘制 API 实现为 ICanvas2D（见 core/canvas.ts 契约）
+ * 2. 实现 resolveNativeCanvas()，返回 ChartRenderContext（含 DPR 与逻辑尺寸）
+ * 3. 之后引擎与四种图表零改动运行
+ *
+ * 本文件当前不导出可运行实现，仅保留类型契约与接入文档，防止
+ * 平台差异悄悄渗入引擎。
+ */
+import type { ChartRenderContext } from '../types';
+/** 未来原生端需实现的最小宿主接口。 */
+export interface NativeCanvasHost {
+    /** 逻辑尺寸（CSS px）。 */
+    width: number;
+    height: number;
+    /** 设备像素比。 */
+    pixelRatio: number;
+    /** 原生绘图上下文（宿主实现为 ICanvas2D 契约）。 */
+    getContext(type: '2d'): unknown;
+}
+/**
+ * 未来实现：原生 canvas 节点 → ChartRenderContext。
+ * 当前未接入任何原生端，调用会明确报错，避免静默降级。
+ */
+export declare function resolveNativeCanvas(_host: NativeCanvasHost): ChartRenderContext;

package/dist/adapters/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 平台适配层：把各端 Canvas 2D 上下文解析为统一渲染上下文
+ * （ICanvas2D + 逻辑尺寸 + DPR）。
+ *
+ * 适配器只负责三件事：
+ * 1. 拿到上下文（HTMLCanvasElement / 小程序 canvas node / 未来原生 canvas）
+ * 2. 计算设备像素比并设置物理画布尺寸
+ * 3. 返回引擎需要的 ChartRenderContext
+ *
+ * 引擎代码永远不直接接触 DOM / wx / native API。
+ */
+import type { ChartRenderContext } from '../types';
+export interface ResolveCanvasOptions {
+    /** 逻辑宽度（CSS px）；缺省取节点实际尺寸。 */
+    width?: number;
+    /** 逻辑高度（CSS px）；缺省取节点实际尺寸。 */
+    height?: number;
+    /** 设备像素比；缺省自动探测。 */
+    dpr?: number;
+    /** 自定义色板。 */
+    palette?: readonly string[];
+}
+export interface ResolvedCanvas {
+    context: ChartRenderContext;
+}
+/** 通用探测设备像素比（web 与小程序可用 globalThis 访问）。 */
+export declare function detectPixelRatio(): number;

package/dist/adapters/web.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Web 适配器：HTMLCanvasElement → ChartRenderContext。
+ *
+ * - 把物理画布尺寸设为 逻辑尺寸 × DPR，保证高分屏清晰
+ * - 上下文为标准 CanvasRenderingContext2D，天然满足 ICanvas2D 契约
+ */
+import type { ChartRenderContext } from '../types';
+import { type ResolveCanvasOptions } from './types';
+/**
+ * 从 HTMLCanvasElement 解析渲染上下文。
+ * 会就地修改 canvas.width / canvas.height 为物理像素尺寸。
+ */
+export declare function resolveWebCanvas(canvas: HTMLCanvasElement, options?: ResolveCanvasOptions): ChartRenderContext;

package/dist/charts/bar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 柱状图：纵向 / 横向，支持多系列分组与 stack 堆叠。
+ *
+ * 几何规则：
+ * - 分组：同一类目内多个系列并排，子柱宽 = 类目带宽 × (1 - gap) / 系列数 × 0.8
+ * - 堆叠：同名 stack 系列共用一根柱，后一个系列从前一个的顶端继续累加
+ * - 数值轴强制包含 0（柱形高度必须从零线起算才有意义）
+ */
+import type { ICanvas2D } from '../core/canvas';
+import { ChartBase } from '../core/chart';
+import type { LayoutResult } from '../core/layout';
+import type { LegendItem } from '../core/legend';
+import type { BarChartOption } from '../types';
+export declare class BarChart extends ChartBase<BarChartOption> {
+    protected isHorizontal(): boolean;
+    protected getValueDomain(): {
+        min: number;
+        max: number;
+    };
+    protected getCategoryLabels(): readonly string[];
+    protected getLegendItems(): LegendItem[];
+    protected drawSeries(ctx: ICanvas2D, layout: LayoutResult, option: BarChartOption): void;
+    private computeSlot;
+    private drawBar;
+}

package/dist/charts/index.d.ts

@@ -0,0 +1,4 @@
+export { LineChart } from './line';
+export { BarChart } from './bar';
+export { PieChart } from './pie';
+export { RadarChart } from './radar';

package/dist/charts/line.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 折线图：多系列 / 平滑曲线 / 面积填充 / 数据点标记。
+ * 类目 x 轴 + 数值 y 轴，复用 ChartBase 的笛卡尔管线。
+ */
+import type { ICanvas2D } from '../core/canvas';
+import { ChartBase } from '../core/chart';
+import type { LayoutResult } from '../core/layout';
+import type { LegendItem } from '../core/legend';
+import type { LineChartOption } from '../types';
+export declare class LineChart extends ChartBase<LineChartOption> {
+    protected getValueDomain(): {
+        min: number;
+        max: number;
+    };
+    protected getCategoryLabels(): readonly string[];
+    protected getLegendItems(): LegendItem[];
+    protected drawSeries(ctx: ICanvas2D, layout: LayoutResult, option: LineChartOption): void;
+    /** 折线路径：直线或 Catmull-Rom 平滑插值（三次贝塞尔）。 */
+    private tracePath;
+}

package/dist/charts/pie.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 饼图 / 环形图：扇区绘制、百分比标签、图例。
+ * 无笛卡尔坐标轴，全部几何在绘图区内按极坐标计算。
+ */
+import type { ICanvas2D } from '../core/canvas';
+import { ChartBase } from '../core/chart';
+import type { LayoutResult } from '../core/layout';
+import type { LegendItem } from '../core/legend';
+import type { PieChartOption } from '../types';
+export declare class PieChart extends ChartBase<PieChartOption> {
+    protected hasCartesianAxis(): boolean;
+    protected getLegendItems(): LegendItem[];
+    protected drawSeries(ctx: ICanvas2D, layout: LayoutResult, option: PieChartOption): void;
+}

package/dist/charts/radar.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 雷达图：多边形网格 + 指标轴 + 多系列区域/折线。
+ * 指标刻度按各 indicator.max（缺省取所有系列该指标最大值）归一化。
+ */
+import type { ICanvas2D } from '../core/canvas';
+import { ChartBase } from '../core/chart';
+import type { LayoutResult } from '../core/layout';
+import type { LegendItem } from '../core/legend';
+import type { RadarChartOption } from '../types';
+export declare class RadarChart extends ChartBase<RadarChartOption> {
+    protected hasCartesianAxis(): boolean;
+    protected getLegendItems(): LegendItem[];
+    protected drawSeries(ctx: ICanvas2D, layout: LayoutResult, option: RadarChartOption): void;
+    private indicatorMax;
+    private tracePolygon;
+}

package/dist/component.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 可选集成：基于 transone Component 的声明式图表组件 TcChart。
+ *
+ * 与 transone 组件系统集成，一份源码同时编译 Web 与小程序：
+ * - Web：canvas 元素由组件渲染，onMounted 后自动解析并渲染
+ * - 小程序：canvas 编译为 <canvas type="2d">，通过 SelectorQuery 获取节点
+ * - 未来原生：通过 resolve 注入自定义解析器
+ *
+ * 组件本身是薄壳：状态由父级以 option 传入（完全受控），
+ * 数据变化时自动 setOption + render。
+ */
+import { Component, type VNode } from 'transone';
+import type { ChartRenderContext, ChartOption } from './types';
+import type { ChartBase } from './core/chart';
+export interface TcChartProps {
+    /** 图表配置（line / bar / pie / radar）。 */
+    option: ChartOption;
+    /** 自定义解析器：把 canvas 元素/节点解析为渲染上下文。 */
+    resolve?: (element: unknown) => Promise<ChartRenderContext> | ChartRenderContext;
+    className?: string;
+}
+interface TcChartState {
+    canvasId: string;
+}
+export declare class TcChart extends Component<TcChartProps, TcChartState> {
+    private chart;
+    private destroyed;
+    protected initState(): TcChartState;
+    protected initStyles(): void;
+    protected render(): VNode;
+    protected onMounted(): void;
+    protected onUpdated(): void;
+    protected onUnmounted(): void;
+    /** 对外暴露图表实例（高级用法：手动 resize / 订阅事件）。 */
+    getChart(): ChartBase<ChartOption> | null;
+    private attachChart;
+    /** 组件根元素（canvas）。Web 端用于解析渲染上下文；小程序端经 SelectorQuery .in(实例) 查询，不依赖此方法。 */
+    getElement(): HTMLCanvasElement | null;
+    private resolveContext;
+}
+export {};

package/dist/core/axis.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 坐标轴绘制：数值轴（默认纵向居左、横向图居底）与类目轴（默认横向居底、
+ * 横向图居左）。网格线与刻度标签统一在这里绘制，数据系列只画在 plot 内。
+ *
+ * 位置计算全部基于布局结果与比例尺，与平台无关。
+ */
+import type { ICanvas2D } from './canvas';
+import type { Box } from './layout';
+import { CategoryScale, LinearScale } from './scale';
+export interface ValueAxisDrawOptions {
+    /** 绘图区。 */
+    plot: Box;
+    /** 数值比例尺：纵向图 range=[plot.bottom, plot.top]，横向图 range=[plot.left, plot.right]。 */
+    scale: LinearScale;
+    /** 刻度标签（长度需与 scale.ticks 一致）。 */
+    labels: readonly string[];
+    /** 横向图：数值轴位于底部。 */
+    horizontal?: boolean;
+    axisColor?: string;
+    labelFontSize?: number;
+    labelColor?: string;
+    gridColor?: string;
+    gridLineWidth?: number;
+    gridLineDash?: readonly number[];
+    showGrid?: boolean;
+}
+export interface CategoryAxisDrawOptions {
+    plot: Box;
+    scale: CategoryScale;
+    labels: readonly string[];
+    /** 横向图：类目轴位于左侧。 */
+    horizontal?: boolean;
+    axisColor?: string;
+    labelFontSize?: number;
+    labelColor?: string;
+    gridColor?: string;
+    gridLineWidth?: number;
+    showGrid?: boolean;
+}
+export declare class AxisDrawer {
+    private readonly ctx;
+    constructor(ctx: ICanvas2D);
+    /** 绘制数值轴：网格横线（或纵向图时） + 刻度标签。 */
+    drawValueAxis(options: ValueAxisDrawOptions): void;
+    /** 绘制类目轴：轴线 + 类目标签（可选竖网格）。 */
+    drawCategoryAxis(options: CategoryAxisDrawOptions): void;
+}

package/dist/core/canvas.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 跨端 Canvas 2D 契约（ICanvas2D）。
+ *
+ * 这是 transone-chart 与平台解耦的唯一边界：
+ * - Web：HTMLCanvasElement.getContext('2d') 天然满足，适配器薄封装
+ * - 小程序：微信 / 阿里 / 字节的 Canvas 2D（type="2d"）节点上下文与 Web 接口基本对齐
+ * - 未来原生 App：Skia / ArkUI 等原生 canvas 只需实现本接口即可接入同一套引擎
+ *
+ * 接口刻意收敛为图表实际需要的最小真子集，避免依赖平台各自的扩展 API；
+ * 绘制一律使用「beginPath → 路径命令 → fill()/stroke() 无参」形式，
+ * 不依赖 Path2D 等小程序端可能缺失的高级对象。
+ */
+export interface IGradient {
+    addColorStop(offset: number, color: string): void;
+}
+export type CanvasLineCap = 'butt' | 'round' | 'square';
+export type CanvasLineJoin = 'bevel' | 'round' | 'miter';
+export type CanvasTextAlign = 'left' | 'right' | 'center' | 'start' | 'end';
+export type CanvasTextBaseline = 'top' | 'hanging' | 'middle' | 'alphabetic' | 'ideographic' | 'bottom';
+export interface ICanvas2D {
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    scale(x: number, y: number): void;
+    rotate(angle: number): void;
+    fillStyle: string | IGradient;
+    strokeStyle: string | IGradient;
+    lineWidth: number;
+    lineCap: CanvasLineCap;
+    lineJoin: CanvasLineJoin;
+    globalAlpha: number;
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    beginPath(): void;
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    fill(): void;
+    stroke(): void;
+    fillRect(x: number, y: number, width: number, height: number): void;
+    clearRect(x: number, y: number, width: number, height: number): void;
+    clip(): void;
+    setLineDash(segments: readonly number[]): void;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): IGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): IGradient;
+    fillText(text: string, x: number, y: number, maxWidth?: number): void;
+    measureText(text: string): {
+        width: number;
+    };
+}
+/**
+ * ICanvas2D 的便捷判断：任意对象只要实现了最小方法集即视为满足契约。
+ * 用于适配器防御与测试 mock 的类型断言，不承担运行时校验。
+ */
+export declare function isCanvas2DLike(value: unknown): value is ICanvas2D;

package/dist/core/chart.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ChartBase：所有图表的抽象基类，负责统一渲染管线。
+ *
+ * 渲染管线（render）：
+ *   save → scale(dpr) → clear → 背景 → 布局计算
+ *     → 标题 → 图例 → 笛卡尔坐标轴（折线/柱状）
+ *     → drawSeries（子类策略） → restore
+ *
+ * 生命周期：setOption 增量更新 → render；resize 改逻辑尺寸 → render；
+ * destroy 释放。所有坐标均为逻辑像素（CSS px），DPR 由管线统一缩放。
+ */
+import type { ICanvas2D } from './canvas';
+import { type LayoutInput, type LayoutResult } from './layout';
+import { type LegendItem } from './legend';
+import { CategoryScale, LinearScale } from './scale';
+import { type CategoryAxisOption, type ChartOption, type ChartRenderContext, type LegendOption, type TitleOption, type ValueAxisOption } from '../types';
+export interface CartesianScales {
+    value: LinearScale;
+    category: CategoryScale;
+}
+/**
+ * 子类需要实现的钩子：
+ * - drawSeries：绘制数据系列（核心策略）
+ * - hasCartesianAxis：是否需要坐标轴（饼图/雷达返回 false）
+ * - getValueDomain：数值轴数据域（有轴时）
+ * - getCategoryLabels：类目轴标签（有轴时）
+ * - isHorizontal：横向布局（横向柱状图）
+ */
+export declare abstract class ChartBase<T extends ChartOption> {
+    protected readonly ctx: ICanvas2D;
+    protected option: T;
+    protected width: number;
+    protected height: number;
+    protected dpr: number;
+    protected readonly palette: readonly string[];
+    /** 每次 render 构建的笛卡尔比例尺，供 drawSeries 读取。 */
+    protected cartesian: CartesianScales | null;
+    private destroyed;
+    constructor(context: ChartRenderContext, option: T);
+    setOption(option: Partial<T>): this;
+    resize(width: number, height: number): this;
+    render(): this;
+    destroy(): void;
+    isDestroyed(): boolean;
+    protected abstract drawSeries(ctx: ICanvas2D, layout: LayoutResult, option: T): void;
+    protected hasCartesianAxis(): boolean;
+    protected getValueDomain(): {
+        min: number;
+        max: number;
+    };
+    protected getCategoryLabels(): readonly string[];
+    protected isHorizontal(): boolean;
+    protected getBackgroundColor(): string | undefined;
+    protected getTitle(): TitleOption | undefined;
+    protected getLegend(): LegendOption | undefined;
+    protected getLegendItems(): LegendItem[];
+    protected getValueAxis(): ValueAxisOption | undefined;
+    protected getCategoryAxis(): CategoryAxisOption | undefined;
+    protected computeLayout(): LayoutResult;
+    protected buildLayoutInput(): LayoutInput;
+    /** 用占位 range 预计算数值刻度标签（仅用于测量，不参与最终映射）。 */
+    protected computeValueLabels(): string[];
+    protected drawTitle(layout: LayoutResult): void;
+    protected drawLegend(layout: LayoutResult): void;
+    protected buildCartesianScales(layout: LayoutResult): CartesianScales;
+    protected drawCartesianAxis(layout: LayoutResult): void;
+    /** 系列取色：显式 color 优先，否则按索引取色板。 */
+    protected seriesColor(index: number, color?: string): string;
+}