@quantlife/qlchart 0.0.1

package/doc/examples/data-format-guide.md

@@ -0,0 +1,119 @@
+# 数据格式指南
+
+本文档详细说明 QLChart 中使用的各种数据格式及转换规则。
+
+## 数据格式总览
+
+| 格式 | 使用场景 | time单位 | 定义位置 |
+|------|---------|---------|---------|
+| `CandlestickRawData` | API返回 / setData输入 | 毫秒 | `types/series.ts` |
+| LWC CandlestickData | 内部图表渲染 | 秒 | lightweight-charts |
+| `RealtimeCandle` | 实时增量推送 | 秒 | `core/RealtimeDataFeed.ts` |
+
+## CandlestickRawData（API格式）
+
+API返回和 `setData()` 接受的数据格式，**time 为毫秒级时间戳**：
+
+```typescript
+interface CandlestickRawData {
+  /** 毫秒级时间戳（UNIX milliseconds） */
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+```
+
+**示例：**
+
+```json
+[
+  { "time": 1700000000000, "open": 42000, "high": 42500, "low": 41800, "close": 42300, "volume": 1200 },
+  { "time": 1700003600000, "open": 42300, "high": 42800, "low": 42100, "close": 42600, "volume": 1500 }
+]
+```
+
+### 数据要求
+
+1. **升序排列：** 必须按 time 升序排列
+2. **时间对齐：** time 应与周期对齐（如1h周期，time应为整点时间戳）
+3. **OHLC完整性：** open/high/low/close 不可缺失
+
+## LWC 内部格式
+
+`transformCandlestickData()` 将 CandlestickRawData 转换为 LWC 内部格式：
+
+```typescript
+// 转换前（毫秒）
+{ time: 1700000000000, open: 42000, high: 42500, ... }
+
+// 转换后（秒）
+{ time: 1700000000, open: 42000, high: 42500, ... }  // UTCTimestamp
+```
+
+转换规则：
+- `time / 1000` → 秒级 UTCTimestamp
+- 数据类型保持不变
+
+## RealtimeCandle（增量格式）
+
+实时数据推送使用秒级时间戳：
+
+```typescript
+interface RealtimeCandle {
+  time: number;  // 秒级
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+```
+
+## 时间戳转换速查
+
+```
+API返回时间戳:     1700000000000 (毫秒)
+                  ↓ ÷ 1000
+LWC内部时间戳:     1700000000 (秒)
+                  ↓
+RealtimeCandle:    1700000000 (秒)
+```
+
+## 数据预处理
+
+QLChart 支持多种K线类型预处理：
+
+| 类型 | 函数 | 说明 |
+|------|------|------|
+| 标准K线 | `transformCandlestickData` | 直接转换 |
+| 成交量K线 | `transformVolumeCandlestickData` | 按成交量加权 |
+| HeikinAshi | `transformToHeikinAshi` | 平均K线 |
+| LineBreak | `transformToLineBreak` | 三线突破 |
+
+## Whitespace 数据
+
+`generateFutureWhitespace()` 在K线末尾注入未来时间点，为实时数据预留位置：
+
+```typescript
+const lastTime = 1700000000;  // 秒
+const whitespace = generateFutureWhitespace(lastTime, '1h', 100);
+// 生成 1700003600, 1700007200, ... 共100个空白点
+```
+
+这确保图表在接收实时数据时不会因为时间超出范围而报错。
+
+## 成交量数据
+
+`transformVolumeData()` 提取成交量并格式化为 LWC Histogram 数据：
+
+```typescript
+// 输入
+{ time: 1700000000000, volume: 1200, close: 42300, open: 42000, ... }
+
+// 输出
+{ time: 1700000000, value: 1200, color: 'rgba(38, 166, 154, 0.35)' }
+//                                  绿色（收涨）或 红色（收跌）
+```

package/doc/examples/drawing-tools.md

@@ -0,0 +1,30 @@
+# 绘图工具示例
+
+```tsx
+import { QLChartProvider, QLChartPanel } from '@quantlife/qlchart'
+
+function App() {
+  return (
+    <QLChartProvider config={{ fetchFn, defaultTheme: 'dark' }}>
+      <QLChartPanel
+        pairId="BTCUSDT"
+        product="digital_currency"
+        showToolbar
+      />
+    </QLChartProvider>
+  )
+}
+```
+
+## 使用步骤
+
+1. 点击图表右上角的 🔧 绘图按钮展开工具栏
+2. 选择绘图工具（趋势线、水平线、矩形等）
+3. 在图表上点击放置锚点
+4. 按 Esc 取消创建
+5. 右键菜单可快速切换最近工具
+6. 右下角属性面板可修改选中绘图的颜色/线宽/样式
+
+## 磁铁吸附
+
+绘图工具支持磁铁吸附功能，开启后锚点会自动吸附到最近的K线收盘价。

package/doc/examples/indicator-properties.md

@@ -0,0 +1,34 @@
+# 指标属性编辑示例
+
+```tsx
+import { IndicatorPropertyPanel } from '@quantlife/qlchart'
+
+function IndicatorSettings({ indicatorKey, currentStyle }) {
+  const [style, setStyle] = useState(currentStyle)
+
+  return (
+    <IndicatorPropertyPanel
+      indicatorKey={indicatorKey}
+      values={style}
+      onStyleChange={(key, value) => {
+        setStyle(prev => ({ ...prev, [key]: value }))
+      }}
+      onClose={() => setOpen(false)}
+    />
+  )
+}
+```
+
+## MACD属性
+
+MACD指标支持修改以下属性：
+- DIF颜色
+- DEA颜色
+- 柱状涨色
+- 柱状跌色
+
+## Volume属性
+
+成交量支持修改：
+- 涨色（默认 rgba(38,166,154,0.35)）
+- 跌色（默认 rgba(239,83,80,0.35)）

package/doc/examples/multi-pane.md

@@ -0,0 +1,24 @@
+# 多副图示例
+
+```tsx
+import { QLChartProvider, QLChartPanel } from '@quantlife/qlchart'
+
+function App() {
+  return (
+    <QLChartProvider config={{ fetchFn, defaultTheme: 'dark' }}>
+      <QLChartPanel
+        pairId="BTCUSDT"
+        product="digital_currency"
+        showToolbar
+      />
+    </QLChartProvider>
+  )
+}
+```
+
+添加MACD和RSI指标后，QLChartPanel会自动通过LWC v5原生pane系统创建副图：
+- pane 0: 主图（K线 + 成交量）
+- pane 1: MACD（DIF/DEA/HIST）
+- pane 2: RSI
+
+所有pane共享同一时间轴，光标自动同步。

package/doc/examples/multi-panel.md

@@ -0,0 +1,23 @@
+# 多面板布局示例
+
+```tsx
+import { QLChartProvider, QLChartPanel } from '@quantlife/qlchart'
+
+function App() {
+  return (
+    <QLChartProvider config={{ fetchFn, defaultTheme: 'dark' }}>
+      <QLChartLayout mode="2">
+        <QLChartPanel pairId="BTCUSDT" product="digital_currency" panelId="p1" panelIndex={0} />
+        <QLChartPanel pairId="ETHUSDT" product="digital_currency" panelId="p2" panelIndex={1} />
+      </QLChartLayout>
+    </QLChartProvider>
+  )
+}
+```
+
+## 效果
+
+- 左右分屏对比两个交易对
+- 光标同步移动
+- 点击面板切换活跃面板
+- 绘图工具仅作用于活跃面板

package/doc/examples/realtime-data.md

@@ -0,0 +1,147 @@
+# 实时数据更新
+
+QLChart 支持通过 WebSocket 或轮询方式接收实时K线数据，并通过 `series.update()` 实现增量更新。
+
+## 数据格式
+
+### RealtimeCandle
+
+实时数据使用秒级时间戳（与 lightweight-charts 内部格式一致）：
+
+```typescript
+interface RealtimeCandle {
+  time: number;      // 秒级时间戳（UNIX seconds）
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+```
+
+> **重要：** WebSocket 推送的毫秒级时间戳需要转换为秒级：`Math.floor(timestamp / 1000)`
+
+## React 中使用
+
+### 方式一：通过 ref 直接推送
+
+```tsx
+import { useRef, useEffect } from 'react';
+import {
+  QLChartProvider,
+  QLChartPanel,
+  type QLChartPanelRef,
+  type RealtimeCandle,
+} from '@quantlife/qlchart';
+
+function App() {
+  const chartRef = useRef<QLChartPanelRef>(null);
+
+  useEffect(() => {
+    const ws = new WebSocket('wss://api.example.com/ws/kline');
+
+    ws.onmessage = (event) => {
+      const msg = JSON.parse(event.data);
+      const candle: RealtimeCandle = {
+        time: Math.floor(msg.timestamp / 1000),  // ms → s
+        open: msg.open,
+        high: msg.high,
+        low: msg.low,
+        close: msg.close,
+        volume: msg.volume,
+      };
+      chartRef.current?.pushRealtimeData(candle);
+    };
+
+    return () => ws.close();
+  }, []);
+
+  return (
+    <QLChartProvider config={{ fetchFn: async (params) => { /* ... */ } }}>
+      <QLChartPanel
+        ref={chartRef}
+        pairId="BTCUSDT"
+        product="digital_currency"
+      />
+    </QLChartProvider>
+  );
+}
+```
+
+### 方式二：通过 config.realtimeSubscribe 订阅
+
+```tsx
+const config: QLChartConfig = {
+  fetchFn: async (params) => { /* 全量数据获取 */ },
+  cacheEnabled: true,
+  cacheTTL: 5 * 60 * 1000,
+
+  realtimeSubscribe: ({ pairId, product, period, onUpdate }) => {
+    const ws = new WebSocket(`wss://api.example.com/ws/${pairId}_${period}`);
+
+    ws.onmessage = (event) => {
+      const msg = JSON.parse(event.data);
+      onUpdate({
+        time: Math.floor(msg.timestamp / 1000),
+        open: msg.open,
+        high: msg.high,
+        low: msg.low,
+        close: msg.close,
+        volume: msg.volume,
+      });
+    };
+
+    // 返回 unsubscribe 函数（组件卸载或切换period时调用）
+    return () => ws.close();
+  },
+};
+```
+
+### 方式三：批量推送
+
+```tsx
+// 一次推送多条数据（如断线重连后补偿）
+chartRef.current?.pushRealtimeBatch([
+  { time: 1700000000, open: 42000, high: 42100, low: 41900, close: 42050, volume: 100 },
+  { time: 1700003600, open: 42050, high: 42200, low: 42000, close: 42150, volume: 120 },
+  { time: 1700007200, open: 42150, high: 42300, low: 42100, close: 42280, volume: 90 },
+]);
+```
+
+## 纯 JS 中使用（Standalone）
+
+```javascript
+var chart = QLChart.create('container', { theme: 'dark' });
+chart.setData(initialData);
+
+// WebSocket 接收实时数据
+var ws = new WebSocket('wss://api.example.com/ws/btcusdt_1h');
+ws.onmessage = function(event) {
+  var msg = JSON.parse(event.data);
+  chart.update({
+    time: Math.floor(msg.timestamp / 1000),
+    open: msg.open,
+    high: msg.high,
+    low: msg.low,
+    close: msg.close,
+    volume: msg.volume,
+  });
+};
+```
+
+## 增量更新机制
+
+QLChart 使用 lightweight-charts 原生的 `series.update()` 方法处理增量数据：
+
+| 场景 | 行为 |
+|------|------|
+| `time === 最新K线time` | 更新该K线的 OHLCV |
+| `time > 最新K线time` | 追加新K线 |
+| `time < 最新K线time` | 忽略（LWC自动处理） |
+
+## 注意事项
+
+1. **推送频率：** 建议不超过每秒10次，过高频率可能导致渲染瓶颈
+2. **切换周期：** 需要重新订阅对应周期的数据源
+3. **数据连续性：** 断线重连后使用 `pushRealtimeBatch` 补偿缺失数据
+4. **时间戳单位：** API返回毫秒级，实时推送使用秒级，注意转换

package/doc/examples/standalone-js.md

@@ -0,0 +1,333 @@
+# Standalone JS 使用指南
+
+QLChart 提供纯 JavaScript 的 Standalone API，无需 React 即可在任何 HTML 页面中使用。
+
+## 安装
+
+### 方式一：本地构建
+
+```bash
+pnpm build:standalone
+```
+
+生成的文件在 `dist/qlchart.standalone.js`，CSS 已内联到 JS 中。
+
+### 方式二：直接引入
+
+```html
+<script src="path/to/qlchart.standalone.js"></script>
+```
+
+## 快速开始
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>QLChart Demo</title>
+</head>
+<body>
+  <div id="chart" style="width: 100%; height: 400px;"></div>
+  <script src="qlchart.standalone.js"></script>
+  <script>
+    var chart = QLChart.create('chart', {
+      theme: 'dark',
+      showVolume: true,
+    });
+
+    var data = QLChart.generateMockData(500, 42000);
+    chart.setData(data);
+  </script>
+</body>
+</html>
+```
+
+## API 参考
+
+### `QLChart.create(container, options)`
+
+创建图表实例。
+
+**参数：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `container` | `HTMLElement \| string` | — | 容器元素或元素ID |
+| `options.width` | `number \| string` | `'100%'` | 宽度 |
+| `options.height` | `number \| string` | `400` | 高度 |
+| `options.theme` | `'dark' \| 'light'` | `'dark'` | 主题 |
+| `options.seriesType` | `'candlestick' \| 'line' \| 'area' \| 'bar'` | `'candlestick'` | 序列类型 |
+| `options.showVolume` | `boolean` | `true` | 显示成交量 |
+| `options.enableDrawing` | `boolean` | `false` | 启用绘图工具 |
+| `options.period` | `string` | `'1h'` | 初始周期（如 `'1m'` `'5m'` `'1h'` `'1d'`） |
+| `options.onDataReload` | `(period: string) => void` | — | 周期切换时的数据加载回调 |
+| `options.visibleBars` | `number` | `80` | 初始可见K线数量 |
+
+**返回：** `StandaloneChart` 实例
+
+---
+
+### `chart.setData(data)`
+
+设置全量K线数据。`time` 使用毫秒级时间戳。
+
+```javascript
+chart.setData([
+  { time: 1700000000000, open: 42000, high: 42500, low: 41800, close: 42300, volume: 1200 },
+  { time: 1700003600000, open: 42300, high: 42800, low: 42100, close: 42600, volume: 1500 },
+]);
+```
+
+---
+
+### `chart.update(data)`
+
+推送增量数据（实时更新）。`time` 使用秒级时间戳。
+
+```javascript
+chart.update({
+  time: 1700003600,
+  open: 42300, high: 42800, low: 42100, close: 42600, volume: 1500,
+});
+```
+
+---
+
+### `chart.updateBatch(data)`
+
+批量推送增量数据。
+
+---
+
+### `chart.setPeriod(period)` / `chart.getPeriod()`
+
+切换/获取当前周期。`setPeriod` 会触发 `onDataReload` 回调。
+
+```javascript
+chart.setPeriod('4h');
+var currentPeriod = chart.getPeriod(); // '4h'
+```
+
+---
+
+### `chart.setTheme(theme)`
+
+切换主题。会自动应用完整的主题预设（含网格线、十字线等），并同步 `data-theme` 属性到容器元素。
+
+```javascript
+chart.setTheme('light');
+```
+
+---
+
+### `chart.screenshot()`
+
+截图，返回 data URL。
+
+```javascript
+var url = chart.screenshot();
+var link = document.createElement('a');
+link.download = 'chart.png';
+link.href = url;
+link.click();
+```
+
+---
+
+### `chart.getChart()` / `chart.getMainSeries()`
+
+获取底层 lightweight-charts 的 `IChartApi` 和 `ISeriesApi` 实例，用于高级自定义。
+
+---
+
+### `chart.drawing.*` — 绘图工具API
+
+当 `enableDrawing: true` 时可用，否则为 `null`。
+
+#### `chart.drawing.setDrawingTool(tool)`
+
+设置当前绘图工具。
+
+```javascript
+chart.drawing.setDrawingTool('trend-line');
+chart.drawing.setDrawingTool('cursor'); // 切回光标模式
+```
+
+可用工具类型参见 `QLChart.drawingTools`。
+
+#### `chart.drawing.getDrawingTool()`
+
+获取当前激活的工具。
+
+#### `chart.drawing.clearDrawings()`
+
+清空所有绘图。
+
+#### `chart.drawing.exportDrawings()` / `chart.drawing.importDrawings(data)`
+
+导出/导入绘图数据（用于持久化）。
+
+```javascript
+// 保存
+var saved = chart.drawing.exportDrawings();
+
+// 恢复
+chart.drawing.importDrawings(saved);
+```
+
+#### `chart.drawing.setCandleData(data)`
+
+手动设置K线数据给绘图模块（用于磁铁吸附功能）。通常 `setData()` 会自动调用。
+
+#### `chart.drawing.destroyDrawing()`
+
+销毁绘图模块。
+
+---
+
+### `QLChart.generateMockData(count, startPrice, period)`
+
+生成模拟K线数据。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `count` | `number` | `500` | K线数量 |
+| `startPrice` | `number` | `42000` | 起始价格 |
+| `period` | `string` | `'1h'` | 周期（影响时间间隔和波动幅度） |
+
+---
+
+### `QLChart.drawingTools`
+
+所有绘图工具配置数组（21种工具），包含 `type`、`label`、`icon`、`category`、`anchorCount`、`priority`。
+
+### `QLChart.drawingCategories`
+
+绘图工具分类标签（中文）。
+
+### `QLChart.getDrawingToolsByCategory()`
+
+按分类获取绘图工具，返回 `Map<category, DrawingToolConfig[]>`。
+
+```javascript
+var categories = QLChart.getDrawingToolsByCategory();
+categories.forEach(function(tools, category) {
+  console.log(QLChart.drawingCategories[category] + ':', tools.map(function(t) { return t.label; }));
+});
+```
+
+---
+
+### `chart.destroy()`
+
+销毁图表实例，释放所有资源（含绘图模块）。
+
+## 示例
+
+### 示例1：基础K线图
+
+```html
+<div id="chart" style="width:100%;height:400px;"></div>
+<script src="qlchart.standalone.js"></script>
+<script>
+  var chart = QLChart.create('chart', { theme: 'dark', showVolume: true });
+  chart.setData(QLChart.generateMockData(500, 42000));
+</script>
+```
+
+### 示例2：绘图工具
+
+```javascript
+var chart = QLChart.create('container', {
+  enableDrawing: true,
+});
+
+chart.setData(QLChart.generateMockData(500, 42000));
+
+// 设置绘图工具
+chart.drawing.setDrawingTool('trend-line');
+
+// 清空所有绘图
+chart.drawing.clearDrawings();
+
+// 持久化
+var saved = chart.drawing.exportDrawings();
+// ... 恢复
+chart.drawing.importDrawings(saved);
+```
+
+### 示例3：多Panel
+
+```javascript
+var chart1 = QLChart.create('chart1', { period: '15m', showVolume: false });
+var chart2 = QLChart.create('chart2', { period: '1d', showVolume: false });
+
+chart1.setData(QLChart.generateMockData(300, 42000, '15m'));
+chart2.setData(QLChart.generateMockData(300, 42000, '1d'));
+```
+
+### 示例4：周期切换
+
+```javascript
+var chart = QLChart.create('container', {
+  period: '1h',
+  onDataReload: function(period) {
+    chart.setData(QLChart.generateMockData(500, 42000, period));
+  },
+});
+
+// 切换周期 — 自动触发 onDataReload 回调
+chart.setPeriod('4h');
+```
+
+### 示例5：主题切换
+
+```javascript
+var chart = QLChart.create('container', { theme: 'dark' });
+
+// 切换到亮色主题
+chart.setTheme('light');
+
+// 同步页面CSS变量
+document.documentElement.setAttribute('data-theme', 'light');
+```
+
+## 能力边界与限制
+
+Standalone JS 版本提供了核心的图表展示和绘图功能，但相比 React 组件版有一些限制：
+
+### ✅ 支持的功能
+
+- K线图、线性图、面积图、柱状图
+- 成交量显示
+- 21种绘图工具（趋势线、水平线、矩形、斐波那契等）
+- 绘图持久化（导出/导入）
+- 多图表实例（多Panel）
+- 周期切换
+- 主题切换（含完整网格线/十字线）
+- 截图
+- 实时数据更新
+- 磁铁吸附
+
+### ❌ 不支持的功能（React版独有）
+
+| 功能 | 说明 |
+|------|------|
+| 指标面板 | 需要SeriesManager/PaneManager/IndicatorDataProcessor |
+| K线回放 | 需要ReplayController组件 |
+| 多周期联动 | 需要zustand store驱动 |
+| 光标同步 | 需要ChartSyncManager |
+| 右键菜单 | 需要ChartContextMenu组件 |
+| 绘图属性面板 | 需要DrawingPropertyPanel组件 |
+
+如需以上功能，请使用 React 组件版（`QLChartProvider` + 相关组件）。
+
+## 注意事项
+
+- 打包体积约 435KB（gzip 101KB），包含 lightweight-charts + 绘图库
+- CSS 已内联到 JS 中，无需额外引入样式文件
+- 浏览器兼容性：Chrome 88+, Firefox 85+, Safari 14+
+- `time` 字段：`setData()` 使用毫秒级，`update()` 使用秒级
+- 切换K线类型需要销毁重建图表实例（lightweight-charts 限制）
+- 完整 Demo 参见 `demo/standalone-demo.html`