@quantlife/qlchart 0.0.1

package/doc/hooks/use-chart.md

@@ -0,0 +1,20 @@
+# useChart
+
+管理 Chart 实例生命周期的核心 Hook。
+
+```typescript
+const { containerRef, chartManager, seriesManager } = useChart()
+```
+
+## 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `containerRef` | `RefObject<HTMLElement>` | 图表容器引用 |
+| `chartManager` | `ChartManager \| null` | Chart 管理器 |
+| `seriesManager` | `SeriesManager \| null` | Series 管理器 |
+
+## 生命周期
+
+1. 组件挂载 → 创建 `IChartApi` → 初始化 Managers
+2. 组件卸载 → 清理 Series → 销毁 Chart

package/doc/hooks/use-crosshair-sync.md

@@ -0,0 +1,14 @@
+# useCrosshairSync
+
+多面板光标同步 Hook，在多面板布局中同步光标位置。
+
+```typescript
+useCrosshairSync(charts, { enabled: true })
+```
+
+## 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `charts` | `IChartApi[]` | 需要同步的 Chart 实例列表 |
+| `enabled` | `boolean` | 是否启用同步 |

package/doc/hooks/use-drawing-module.md

@@ -0,0 +1,43 @@
+# useDrawingModule
+
+绘图模块集成 Hook，将 DrawingAdapter 与 React 状态管理对接。
+
+```typescript
+const {
+  drawingAdapterRef,
+  recentTools,
+  handleDrawingStyleChange,
+  handleDeleteDrawing,
+  handleContextMenuToolSelect,
+} = useDrawingModule(options)
+```
+
+## 参数
+
+```typescript
+interface UseDrawingModuleOptions {
+  chartManager: ChartManager | null
+  seriesManager: SeriesManager | null
+  containerRef: React.RefObject<HTMLElement | null>
+  pairId: string
+  product: string
+  period: string
+  panelId?: string
+  panelIndex?: number
+  dataLoaded: boolean
+}
+```
+
+## 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `drawingAdapterRef` | `RefObject<DrawingAdapter>` | DrawingAdapter 实例引用 |
+| `recentTools` | `DrawingToolType[]` | 最近使用的工具列表 |
+| `handleDrawingStyleChange` | `(id, style) => void` | 修改绘图样式 |
+| `handleDeleteDrawing` | `() => void` | 删除选中的绘图 |
+| `handleContextMenuToolSelect` | `(tool) => void` | 右键菜单选择工具 |
+
+## 单面板兼容
+
+当 `panelId` 未传入时（单面板场景），hook 会将 `activePanelId === null` 视为活跃状态，确保绘图工具在单面板中正常工作。

package/doc/hooks/use-theme.md

@@ -0,0 +1,15 @@
+# useTheme
+
+主题管理 Hook。
+
+```typescript
+const { theme, themeConfig, setTheme } = useTheme()
+```
+
+## 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `theme` | `'dark' \| 'light'` | 当前主题 |
+| `themeConfig` | `ThemeConfig` | 主题配置（颜色、图表选项等） |
+| `setTheme` | `(theme) => void` | 切换主题 |

package/doc/index.md

@@ -0,0 +1,33 @@
+---
+layout: home
+
+hero:
+  name: QLChart
+  text: 多功能图表库
+  tagline: 基于 lightweight-charts 的高性能金融图表库，支持绘图工具、指标系统、K线回放等
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /guide/getting-started
+    - theme: alt
+      text: 架构总览
+      link: /guide/architecture
+
+features:
+  - title: 高性能渲染
+    details: 基于 lightweight-charts，支持数万根K线流畅渲染
+  - title: 21种绘图工具
+    details: 趋势线、水平线、矩形、斐波那契等专业绘图工具
+  - title: 指标系统
+    details: 内置MA/EMA/MACD/RSI/KDJ等常用技术指标，支持自定义扩展
+  - title: K线回放
+    details: 支持历史行情逐根回放，模拟实盘交易练习
+  - title: 多面板布局
+    details: 灵活的多面板布局系统，支持光标同步
+  - title: 主题切换
+    details: 内置暗色/亮色主题，支持自定义主题配置
+  - title: 绘图持久化
+    details: 支持绘图数据后端存储和恢复
+  - title: 截图功能
+    details: 一键导出当前图表截图
+---

package/doc/plugins/drawing/overview.md

@@ -0,0 +1,36 @@
+# 绘图插件概览
+
+QLChart 通过 `DrawingAdapter` 桥接 `lightweight-charts-drawing` 库，提供专业的绘图工具。
+
+## 架构
+
+```
+DrawingModule (UI)
+    ↓
+useDrawingModule (Hook)
+    ↓
+DrawingAdapter (适配器)
+    ↓
+DrawingManager (lightweight-charts-drawing)
+    ↓
+ToolRegistry (工具注册表)
+```
+
+## DrawingAdapter 核心方法
+
+| 方法 | 说明 |
+|------|------|
+| `attach(chart, series, container, chartId)` | 绑定到图表 |
+| `detach()` | 解绑 |
+| `setActiveTool(toolType)` | 设置当前工具 |
+| `updateSeries(series)` | 更新主序列引用（数据重载后） |
+| `setCandleData(data)` | 设置K线数据（磁铁吸附用） |
+| `setMagnetEnabled(enabled)` | 开关磁铁吸附 |
+| `exportDrawings()` | 导出绘图数据 |
+| `importDrawings(data)` | 导入绘图数据 |
+
+## 单面板兼容
+
+DrawingAdapter 和 useDrawingModule 已内置单面板兼容逻辑：
+- 当 `panelId` 未传入时，`activePanelId === null` 视为活跃
+- 确保基础K线demo等单面板场景绘图工具正常工作

package/doc/plugins/drawing/persistence.md

@@ -0,0 +1,42 @@
+# 绘图持久化
+
+`DrawingPersistence` 提供绘图数据的后端存储和恢复功能。
+
+## 配置
+
+```typescript
+const persistence = new DrawingPersistence({
+  chartId: 'BTCUSDT',
+  pairId: 'BTCUSDT',
+  product: 'digital_currency',
+  period: '1h',
+  apiBaseUrl: 'https://api.example.com',
+})
+```
+
+## API
+
+| 方法 | 说明 |
+|------|------|
+| `load()` | 从后端加载已保存的绘图 |
+| `autoSave(drawings)` | 自动保存绘图数据 |
+| `dispose()` | 清理定时器和资源 |
+
+## 数据格式
+
+```typescript
+interface DrawingPersistData {
+  id: string
+  chartId: string
+  type: string
+  anchors: { time: number; price: number }[]
+  style: DrawingStyleConfig
+  options: Record<string, any>
+  createdAt: number
+  updatedAt: number
+}
+```
+
+## 自动保存
+
+DrawingAdapter 的 `onDrawingCreated` 和 `onDrawingRemoved` 回调会触发 `autoSave`，确保绘图修改实时持久化。

package/doc/plugins/drawing/tool-registry.md

@@ -0,0 +1,29 @@
+# 工具注册表
+
+QLChart 通过 `DrawingToolRegistry` 管理 21 种绘图工具。
+
+## 工具列表
+
+| 工具 | 枚举值 | 锚点数 | 说明 |
+|------|--------|--------|------|
+| 光标 | `cursor` | - | 取消绘图模式 |
+| 趋势线 | `trend_line` | 2 | 两点连线 |
+| 水平线 | `horizontal_line` | 1 | 水平参考线 |
+| 垂直线 | `vertical_line` | 1 | 垂直参考线 |
+| 射线 | `ray_line` | 2 | 单向延伸线 |
+| 矩形 | `rectangle` | 2 | 矩形区域 |
+| 三角形 | `triangle` | 3 | 三角形 |
+| 平行通道 | `parallel_channel` | 3 | 平行线通道 |
+| 斐波那契回撤 | `fib_retracement` | 2 | 黄金分割位 |
+| 斐波那契扩展 | `fib_extension` | 3 | 扩展位 |
+| 价格标注 | `price_note` | 1 | 价格标签 |
+| 文本标注 | `text_note` | 1 | 文本标签 |
+
+## 工具映射
+
+QLChart 使用 `mapToolTypeToLib` 将内部工具类型映射到 `lightweight-charts-drawing` 的工具类型。
+
+## 锚点机制
+
+- **固定锚点**：达到预设数量自动完成
+- **动态锚点**：双击完成（如自由绘制路径）

package/doc/plugins/hollow-candlestick.md

@@ -0,0 +1,18 @@
+# 空心蜡烛图
+
+QLChart 支持空心蜡烛图序列类型，与传统蜡烛图的区别在于涨跌表达方式。
+
+## 使用
+
+```tsx
+<QLChartPanel
+  pairId="BTCUSDT"
+  product="digital_currency"
+  seriesType={SeriesType.HollowCandlestick}
+/>
+```
+
+## 区别
+
+- **实心蜡烛图**：涨绿跌红，通过颜色区分
+- **空心蜡烛图**：实心表示下跌，空心表示上涨，更符合国际惯例

package/doc/plugins/indicators.md

@@ -0,0 +1,28 @@
+# 指标系统
+
+QLChart 通过 `IndicatorRenderer` 提供技术指标渲染能力。
+
+## 内置指标
+
+| 指标 | 类型 | 说明 |
+|------|------|------|
+| MA | 主图叠加 | 移动平均线 |
+| EMA | 主图叠加 | 指数移动平均线 |
+| BOLL | 主图叠加 | 布林带 |
+| MACD | 副图 | 异同移动平均线 |
+| RSI | 副图 | 相对强弱指标 |
+| KDJ | 副图 | 随机指标 |
+| CCI | 副图 | 商品通道指标 |
+
+## 使用
+
+通过 `useIndicatorStore` 管理指标状态：
+
+```typescript
+const { activeIndicators, addIndicator, removeIndicator } = useIndicatorStore()
+
+// 添加 MACD 指标
+addIndicator({ id: 'macd', name: 'MACD', visible: true, params: { fast: 12, slow: 26, signal: 9 } })
+```
+
+QLChartPanel 会自动监测活跃指标变化，主图指标叠加在K线上，副图指标自动创建副图面板。

package/doc/plugins/renko.md

@@ -0,0 +1,17 @@
+# 砖形图（Renko）
+
+QLChart 支持砖形图序列类型，过滤市场噪音，聚焦价格趋势。
+
+## 使用
+
+```tsx
+<QLChartPanel
+  pairId="BTCUSDT"
+  product="digital_currency"
+  seriesType={SeriesType.Bar}
+/>
+```
+
+## 说明
+
+砖形图不关心时间，只关心价格变动幅度。当价格变动超过设定阈值（brick size）时，生成新砖块。

package/doc/plugins/replay.md

@@ -0,0 +1,21 @@
+# K线回放
+
+`ReplayController` 提供历史K线逐根回放功能，用于模拟实盘交易练习。
+
+## 功能
+
+- **逐根前进/后退** — 手动控制K线推进
+- **自动回放** — 可调节速度（1x / 2x / 5x / 10x）
+- **暂停/继续** — 随时控制回放进度
+- **进度显示** — 当前回放位置和时间
+
+## 使用
+
+回放功能通过 `ReplayDemo` 或交易练习模块使用。
+
+## 技术实现
+
+回放通过控制 `timeScale` 的可见范围实现：
+1. 加载完整K线数据
+2. 设置初始可见范围为前N根
+3. 逐步推进可见范围的右边界

package/doc/plugins/screenshot.md

@@ -0,0 +1,20 @@
+# 截图
+
+QLChart 提供 `takeScreenshot` 方法导出当前图表截图。
+
+## 使用
+
+```typescript
+const chartManager = ... // 获取 ChartManager 实例
+const dataUrl = chartManager.takeScreenshot()
+
+// 下载截图
+const link = document.createElement('a')
+link.download = 'chart.png'
+link.href = dataUrl
+link.click()
+```
+
+## 说明
+
+截图基于 `lightweight-charts` 的 `takeScreenshot()` API，返回包含图片内容的 Canvas Data URL。

package/docs/api.md

@@ -0,0 +1,94 @@
+# QLChart API 文档
+
+## 组件
+
+### QLChartProvider
+
+全局配置提供者，所有图表组件必须包裹在此组件内。
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| fetchFn | `(params: FetchParams) => Promise<FetchResult>` | Yes | 数据获取函数 |
+| apiBaseUrl | `string` | No | API 基础地址（绘图持久化用） |
+| defaultTheme | `'dark' \| 'light'` | No | 默认主题（dark） |
+
+### QLChartPanel
+
+单图表面板组件。
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| pairId | `string` | Yes | - | 交易对 ID |
+| product | `string` | Yes | - | 产品名 |
+| period | `string` | No | `'1h'` | 初始周期 |
+| seriesType | `SeriesType` | No | `Candlestick` | K线类型 |
+| showToolbar | `boolean` | No | `true` | 显示内嵌工具栏 |
+| panelId | `string` | No | - | 面板 ID（多面板模式） |
+| isSinglePanel | `boolean` | No | `true` | 是否单面板模式 |
+
+### QLChartLayout
+
+多面板布局组件。
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| mode | `'1' \| '2h' \| '2v' \| '4'` | No | `'1'` | 布局模式 |
+| crosshairSync | `boolean` | No | `true` | 光标联动 |
+| panels | `PanelConfig[]` | No | - | 面板配置 |
+
+## SeriesType 枚举
+
+| 值 | 说明 |
+|----|------|
+| `candlestick` | 蜡烛图 |
+| `hollow-candlestick` | 空心蜡烛图 |
+| `bar` | 美国线 |
+| `line` | 折线图 |
+| `area` | 面积图 |
+| `baseline` | 基准线图 |
+| `heikin-ashi` | 平均K线 |
+| `volume-candlestick` | 成交量蜡烛图 |
+| `renko` | 砖形图 |
+| `line-break` | 线形反转 |
+
+## DrawingToolType
+
+| 分类 | 工具 |
+|------|------|
+| Lines | trend-line, horizontal-line, vertical-line, ray, cross-line |
+| Channels | parallel-channel |
+| Fibonacci | fib-retracement, fib-extension, fib-fan, fib-circles, fib-time-zone |
+| Shapes | rectangle, circle, ellipse, triangle, rotated-rectangle |
+| Annotations | path, brush, arrow, callout |
+| Positions | long-position, short-position |
+| Measure | date-price-range |
+
+## Store API
+
+### useChartStore
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| activePairId | `string \| null` | 当前交易对 |
+| activePeriod | `string` | 全局周期 |
+| activeSeriesType | `SeriesType` | K线类型 |
+| activePanelId | `string \| null` | 活跃面板 ID |
+| panelPeriods | `Record<string, string>` | 面板独立周期 |
+| layoutMode | `LayoutMode` | 布局模式 |
+
+### useDrawingStore
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| activeTool | `DrawingToolType` | 当前绘图工具 |
+| selectedDrawingId | `string \| null` | 选中绘图 ID |
+| selectedDrawingType | `string \| null` | 选中绘图类型 |
+| magnetEnabled | `boolean` | 磁铁吸附 |
+| drawingCount | `number` | 绘图数量 |
+
+## 工具函数
+
+```typescript
+import { generateFutureWhitespace, getPeriodInterval } from '@quantlife/qlchart';
+import { transformToHeikinAshi, transformToLineBreak } from '@quantlife/qlchart';
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@quantlife/qlchart",
+  "version": "0.0.1",
+  "description": "React chart library based on lightweight-charts",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/qlchart.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/qlchart.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/style.css": "./dist/style.css"
+  },
+  "scripts": {
+    "dev": "vite",
+    "demo": "vite --config demo/vite.config.demo.ts",
+    "build": "tsc && vite build",
+    "build:standalone": "vite build --config vite.config.standalone.ts",
+    "build:all": "tsc && vite build && vite build --config vite.config.standalone.ts",
+    "demo:standalone": "vite build --config vite.config.standalone.ts && echo 'Open demo/standalone-demo.html in browser'",
+    "docs:dev": "vitepress dev doc",
+    "docs:build": "vitepress build doc && cp -r doc/api-reference doc/.vitepress/dist/",
+    "docs:preview": "vitepress preview doc",
+    "docs:api": "typedoc",
+    "docs:all": "typedoc && vitepress build doc && cp -r doc/api-reference doc/.vitepress/dist/"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@headlessui/react": "^2.2.10",
+    "lightweight-charts": "5.2.0",
+    "lightweight-charts-drawing": "^0.1.1",
+    "zustand": "^4.5.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "@vitejs/plugin-react": "^4.7.0",
+    "react": "^18",
+    "react-dom": "^18",
+    "typedoc": "^0.27.0",
+    "typescript": "^5.4",
+    "vite": "^5",
+    "vite-plugin-dts": "^4",
+    "vitepress": "^1.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/python/qlchart/__init__.py

@@ -0,0 +1,9 @@
+"""QLChart Python HTML Generator
+
+生成独立HTML文件，内嵌 lightweight-charts + 数据JSON，可直接在浏览器中打开。
+"""
+
+from qlchart.chart import QLChartHTML
+
+__all__ = ["QLChartHTML"]
+__version__ = "0.1.0"