@quantlife/qlchart 0.0.1

package/src/core/PaneManager.ts

@@ -0,0 +1,121 @@
+import type { IChartApi, ISeriesApi, SeriesType as LWCSeriesType } from 'lightweight-charts';
+import { HistogramSeries } from 'lightweight-charts';
+import { EventManager, ChartEvent } from './EventManager.js';
+
+/** 面板信息 */
+export interface PaneInfo {
+  index: number;
+  heightPercent: number;
+  seriesIds: string[];
+  label: string;
+}
+
+/**
+ * 多面板管理器
+ * 管理 LWC v5 的 pane 系统，用于副图指标
+ */
+export class PaneManager {
+  private chart: IChartApi | null = null;
+  private eventManager: EventManager;
+  private panes: Map<number, PaneInfo> = new Map();
+  private nextPaneIndex = 1; // 0 是主图
+
+  constructor(eventManager: EventManager) {
+    this.eventManager = eventManager;
+  }
+
+  /** 设置图表实例 */
+  setChart(chart: IChartApi): void {
+    this.chart = chart;
+    this.dispose();
+  }
+
+  /** 获取主图 pane 信息 */
+  getMainPane(): PaneInfo {
+    return { index: 0, heightPercent: 70, seriesIds: [], label: '主图' };
+  }
+
+  /**
+   * 添加成交量叠加层
+   * 在主图底部用 HistogramSeries + priceScaleMargins 实现
+   */
+  addVolumeOverlay(heightPercent = 20): ISeriesApi<LWCSeriesType> | null {
+    if (!this.chart) return null;
+
+    const volumeSeries = this.chart.addSeries(HistogramSeries, {
+      priceFormat: { type: 'volume' },
+      priceScaleId: 'volume',
+    });
+
+    this.chart.priceScale('volume').applyOptions({
+      scaleMargins: { top: 1 - heightPercent / 100, bottom: 0 },
+    });
+
+    return volumeSeries as ISeriesApi<LWCSeriesType>;
+  }
+
+  /**
+   * 添加指标面板（副图）
+   * 使用独立的 priceScaleId 创建新 pane
+   */
+  addIndicatorPane(indicatorName: string, heightPercent = 20): string {
+    if (!this.chart) throw new Error('Chart not initialized');
+
+    const priceScaleId = `pane_${this.nextPaneIndex}_${indicatorName}`;
+    const paneInfo: PaneInfo = {
+      index: this.nextPaneIndex,
+      heightPercent,
+      seriesIds: [],
+      label: indicatorName,
+    };
+
+    this.panes.set(this.nextPaneIndex, paneInfo);
+    this.nextPaneIndex++;
+
+    this.eventManager.emit(ChartEvent.SeriesAdded, {
+      id: priceScaleId,
+      type: 'pane',
+      paneIndex: paneInfo.index,
+    });
+
+    return priceScaleId;
+  }
+
+  /** 移除面板 */
+  removePane(paneIndex: number): void {
+    const pane = this.panes.get(paneIndex);
+    if (!pane) return;
+
+    // 移除该面板上的所有序列（通过 seriesManager 管理）
+    this.eventManager.emit(ChartEvent.SeriesRemoved, {
+      id: `pane_${paneIndex}`,
+      paneIndex,
+    });
+
+    this.panes.delete(paneIndex);
+  }
+
+  /** 设置面板高度 */
+  setPaneHeight(paneIndex: number, heightPercent: number): void {
+    const pane = this.panes.get(paneIndex);
+    if (pane) {
+      pane.heightPercent = heightPercent;
+    }
+  }
+
+  /** 获取所有面板 */
+  getPanes(): PaneInfo[] {
+    return [this.getMainPane(), ...Array.from(this.panes.values())];
+  }
+
+  /** 根据 priceScaleId 获取面板信息 */
+  getPaneByIndex(index: number): PaneInfo | undefined {
+    return this.panes.get(index);
+  }
+
+  /** 清理所有面板 */
+  dispose(): void {
+    this.panes.clear();
+    this.nextPaneIndex = 1;
+  }
+}

package/src/core/RealtimeDataFeed.ts

@@ -0,0 +1,110 @@
+import type { ISeriesApi, SeriesType as LWCSeriesType, UTCTimestamp } from 'lightweight-charts';
+
+/**
+ * 实时K线数据格式（秒级时间戳，与LWC对齐）
+ */
+export interface RealtimeCandle {
+  /** K线时间戳（秒级，与LWC一致） */
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+
+/**
+ * 实时数据馈送管理器
+ *
+ * 接收外部推送的增量K线数据，通过 LWC 的 series.update() 实时更新图表。
+ *
+ * LWC update() 自动判断：
+ * - time === 最新K线time → 更新该K线
+ * - time > 最新K线time → 追加新K线
+ * - time < 最新K线time → 忽略
+ */
+export class RealtimeDataFeed {
+  private mainSeries: ISeriesApi<LWCSeriesType> | null = null;
+  private volumeSeries: ISeriesApi<LWCSeriesType> | null = null;
+  private lastTime: number = 0;
+
+  /**
+   * 绑定到图表序列
+   */
+  attach(
+    mainSeries: ISeriesApi<LWCSeriesType>,
+    volumeSeries?: ISeriesApi<LWCSeriesType> | null,
+  ): void {
+    this.mainSeries = mainSeries;
+    this.volumeSeries = volumeSeries ?? null;
+    this.lastTime = 0;
+  }
+
+  /**
+   * 解绑
+   */
+  detach(): void {
+    this.mainSeries = null;
+    this.volumeSeries = null;
+    this.lastTime = 0;
+  }
+
+  /**
+   * 推送单条增量数据
+   */
+  push(data: RealtimeCandle): void {
+    if (!this.mainSeries) {
+      console.warn('[RealtimeDataFeed] Not attached, ignoring push');
+      return;
+    }
+
+    const candle = {
+      time: data.time as UTCTimestamp,
+      open: data.open,
+      high: data.high,
+      low: data.low,
+      close: data.close,
+    };
+
+    this.mainSeries.update(candle);
+
+    if (this.volumeSeries && data.volume !== undefined) {
+      this.volumeSeries.update({
+        time: data.time as UTCTimestamp,
+        value: data.volume,
+        color: data.close >= data.open
+          ? 'rgba(38, 166, 154, 0.35)'
+          : 'rgba(239, 83, 80, 0.35)',
+      });
+    }
+
+    this.lastTime = data.time;
+  }
+
+  /**
+   * 批量推送
+   */
+  pushBatch(datas: RealtimeCandle[]): void {
+    const sorted = [...datas].sort((a, b) => a.time - b.time);
+    for (const data of sorted) {
+      this.push(data);
+    }
+  }
+
+  /**
+   * 获取最后推送的time
+   */
+  getLastTime(): number {
+    return this.lastTime;
+  }
+
+  /**
+   * 更新绑定的series引用（chart重建后调用）
+   */
+  updateSeries(
+    mainSeries: ISeriesApi<LWCSeriesType>,
+    volumeSeries?: ISeriesApi<LWCSeriesType> | null,
+  ): void {
+    this.attach(mainSeries, volumeSeries);
+  }
+}

package/src/core/SeriesManager.ts

@@ -0,0 +1,210 @@
+import {
+  type IChartApi,
+  type ISeriesApi,
+  type SeriesType as LWCSeriesType,
+  CandlestickSeries,
+  BarSeries,
+  LineSeries,
+  AreaSeries,
+  BaselineSeries,
+  HistogramSeries,
+} from 'lightweight-charts';
+import { SeriesType } from '../types/index.js';
+import { EventManager, ChartEvent } from './EventManager.js';
+import { HollowCandlestickSeries } from '../plugins/series/HollowCandlestickSeries.js';
+import { RenkoSeries } from '../plugins/series/RenkoSeries.js';
+import { VolumeCandlestickSeries } from '../plugins/series/VolumeCandlestickSeries.js';
+
+/** LWC series definition map */
+const SERIES_DEFINITIONS: Record<SeriesType, unknown> = {
+  [SeriesType.Candlestick]: CandlestickSeries,
+  [SeriesType.Bar]: BarSeries,
+  [SeriesType.Line]: LineSeries,
+  [SeriesType.Area]: AreaSeries,
+  [SeriesType.Baseline]: BaselineSeries,
+  [SeriesType.Histogram]: HistogramSeries,
+  // 自定义Series
+  [SeriesType.HollowCandlestick]: HollowCandlestickSeries,
+  [SeriesType.Renko]: RenkoSeries,
+  [SeriesType.VolumeCandlestick]: VolumeCandlestickSeries,
+  // 复用LWC蜡烛图（数据预处理）
+  [SeriesType.HeikinAshi]: CandlestickSeries,
+  [SeriesType.LineBreak]: CandlestickSeries,
+};
+
+/**
+ * 序列管理器
+ * 管理图表上所有的序列（K线、指标、成交量等）
+ */
+export class SeriesManager {
+  private seriesMap = new Map<string, ISeriesApi<LWCSeriesType>>();
+  private chart: IChartApi | null = null;
+  private eventManager: EventManager;
+
+  constructor(chart: IChartApi, eventManager: EventManager) {
+    this.chart = chart;
+    this.eventManager = eventManager;
+  }
+
+  /** 更新chart实例（chart重建时调用） */
+  setChart(chart: IChartApi): void {
+    this.chart = chart;
+    this.seriesMap.clear();
+  }
+
+  /** 添加主序列（K线等） */
+  addMainSeries(
+    type: SeriesType,
+    options?: Record<string, unknown>,
+  ): ISeriesApi<LWCSeriesType> | null {
+    if (!this.chart) return null;
+    const definition = SERIES_DEFINITIONS[type];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const series = this.chart.addSeries(definition as any, options as any);
+    const id = `main_${type}_${Date.now()}`;
+    this.seriesMap.set(id, series as ISeriesApi<LWCSeriesType>);
+    this.eventManager.emit(ChartEvent.SeriesAdded, { id, type });
+    return series as ISeriesApi<LWCSeriesType>;
+  }
+
+  /** 添加叠加序列（指标、成交量等） */
+  addOverlaySeries(
+    type: SeriesType,
+    options?: Record<string, unknown>,
+    priceScaleId?: string,
+  ): ISeriesApi<LWCSeriesType> | null {
+    if (!this.chart) return null;
+    const definition = SERIES_DEFINITIONS[type];
+    const seriesOpts = priceScaleId
+      ? { ...options, priceScaleId }
+      : options;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const series = this.chart.addSeries(definition as any, seriesOpts as any);
+    const id = `overlay_${type}_${Date.now()}`;
+    this.seriesMap.set(id, series as ISeriesApi<LWCSeriesType>);
+    this.eventManager.emit(ChartEvent.SeriesAdded, { id, type });
+    return series as ISeriesApi<LWCSeriesType>;
+  }
+
+  /** 设置序列数据 */
+  setData(seriesId: string, data: unknown[]): void {
+    const series = this.seriesMap.get(seriesId);
+    if (series) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (series as any).setData(data);
+    }
+  }
+
+  /** 更新序列最新数据点 */
+  update(seriesId: string, data: unknown): void {
+    const series = this.seriesMap.get(seriesId);
+    if (series) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (series as any).update(data);
+    }
+  }
+
+  /** 移除序列 */
+  removeSeries(seriesId: string): void {
+    const series = this.seriesMap.get(seriesId);
+    if (series) {
+      this.chart?.removeSeries(series);
+      this.seriesMap.delete(seriesId);
+      this.eventManager.emit(ChartEvent.SeriesRemoved, { id: seriesId });
+    }
+  }
+
+  /** 切换序列类型 */
+  switchType(seriesId: string, newType: SeriesType, data?: unknown[]): string | null {
+    if (!this.chart) return null;
+
+    this.removeSeries(seriesId);
+
+    const definition = SERIES_DEFINITIONS[newType];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const newSeries = this.chart.addSeries(definition as any);
+    const newId = `main_${newType}_${Date.now()}`;
+    this.seriesMap.set(newId, newSeries as ISeriesApi<LWCSeriesType>);
+
+    if (data) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (newSeries as any).setData(data);
+    }
+
+    return newId;
+  }
+
+  /** 获取序列 */
+  getSeries(seriesId: string): ISeriesApi<LWCSeriesType> | undefined {
+    return this.seriesMap.get(seriesId);
+  }
+
+  /** 获取第一个主序列（用于DrawingAdapter attach） */
+  getFirstMainSeries(): ISeriesApi<LWCSeriesType> | null {
+    for (const [id, series] of this.seriesMap) {
+      if (id.startsWith('main_')) return series;
+    }
+    return null;
+  }
+
+  /** 获取第一个任何类型的序列 */
+  getFirstSeries(): ISeriesApi<LWCSeriesType> | null {
+    const first = this.seriesMap.values().next();
+    return first.done ? null : first.value;
+  }
+
+  /** 清除所有序列 */
+  clearAll(): void {
+    this.seriesMap.forEach((series) => {
+      this.chart?.removeSeries(series);
+    });
+    this.seriesMap.clear();
+  }
+
+  /** 添加叠加品种（对比模式） */
+  addComparisonSeries(
+    type: SeriesType,
+    data: any[],
+    options?: Record<string, unknown>,
+  ): string | null {
+    if (!this.chart) return null;
+
+    // 使用独立 priceScaleId，右侧Y轴
+    const priceScaleId = 'comparison';
+    const definition = SERIES_DEFINITIONS[type];
+    const seriesOpts = {
+      ...options,
+      priceScaleId,
+    };
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const series = this.chart.addSeries(definition as any, seriesOpts as any);
+    const id = `comparison_${type}_${Date.now()}`;
+    this.seriesMap.set(id, series as ISeriesApi<LWCSeriesType>);
+
+    // 设置右侧Y轴
+    this.chart.priceScale(priceScaleId).applyOptions({
+      scaleMargins: { top: 0.1, bottom: 0.2 },
+    });
+
+    // 设置数据
+    if (data.length > 0) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (series as any).setData(data);
+    }
+
+    this.eventManager.emit(ChartEvent.SeriesAdded, { id, type });
+    return id;
+  }
+
+  /** 移除所有对比序列 */
+  clearComparisonSeries(): void {
+    const toRemove: string[] = [];
+    this.seriesMap.forEach((_series, id) => {
+      if (id.startsWith('comparison_')) {
+        toRemove.push(id);
+      }
+    });
+    toRemove.forEach((id) => this.removeSeries(id));
+  }
+}

package/src/core/ThemeManager.ts

@@ -0,0 +1,59 @@
+import type { DeepPartial, ChartOptions as LWCChartOptions } from 'lightweight-charts';
+import type { ThemeConfig, ThemePreset } from '../types/index.js';
+import { darkPreset, lightPreset } from '../utils/themePresets.js';
+import { EventManager, ChartEvent } from './EventManager.js';
+
+/**
+ * 主题管理器
+ * 管理图表主题的切换与配置
+ */
+export class ThemeManager {
+  private currentTheme: ThemePreset = 'dark';
+  private eventManager: EventManager;
+  private presets: Record<ThemePreset, ThemeConfig>;
+
+  constructor(eventManager: EventManager) {
+    this.eventManager = eventManager;
+    this.presets = { dark: darkPreset, light: lightPreset };
+  }
+
+  /** 设置主题 */
+  setTheme(theme: ThemePreset): void {
+    this.currentTheme = theme;
+    this.eventManager.emit(ChartEvent.ThemeChanged, { theme });
+  }
+
+  /** 获取当前主题名称 */
+  getCurrentTheme(): ThemePreset {
+    return this.currentTheme;
+  }
+
+  /** 获取当前主题配置 */
+  getCurrentConfig(): ThemeConfig {
+    return this.presets[this.currentTheme];
+  }
+
+  /** 获取映射到LWC的图表选项 */
+  getChartOptions(theme?: ThemePreset): DeepPartial<LWCChartOptions> {
+    const config = this.presets[theme ?? this.currentTheme];
+    return {
+      layout: config.chart.layout,
+      grid: config.chart.grid,
+    };
+  }
+
+  /** 获取涨色 */
+  getUpColor(): string {
+    return this.presets[this.currentTheme].upColor;
+  }
+
+  /** 获取跌色 */
+  getDownColor(): string {
+    return this.presets[this.currentTheme].downColor;
+  }
+
+  /** 注册自定义主题预设 */
+  registerPreset(name: ThemePreset, config: ThemeConfig): void {
+    this.presets[name] = config;
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export { EventManager, ChartEvent } from './EventManager.js';
+export type { EventHandler } from './EventManager.js';
+export { ChartManager } from './ChartManager.js';
+export type { ChartManagerCreateOptions } from './ChartManager.js';
+export { SeriesManager } from './SeriesManager.js';
+export { DataManager } from './DataManager.js';
+export type { FetchFn } from './DataManager.js';
+export { ThemeManager } from './ThemeManager.js';
+export { PaneManager } from './PaneManager.js';
+export type { PaneInfo } from './PaneManager.js';

package/src/css.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+  const content: string;
+  export default content;
+}

package/src/hooks/useChart.ts

@@ -0,0 +1,62 @@
+import { useRef, useEffect, useState } from 'react';
+import { EventManager } from '../core/EventManager.js';
+import { ChartManager } from '../core/ChartManager.js';
+import { SeriesManager } from '../core/SeriesManager.js';
+
+export interface UseChartReturn {
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  chartManager: ChartManager | null;
+  seriesManager: SeriesManager | null;
+}
+
+/**
+ * 图表Hook
+ * 创建ChartManager + SeriesManager，管理生命周期
+ * 使用 useState 触发重渲染，确保下游 effects 能拿到非null的 managers
+ */
+export function useChart(): UseChartReturn {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const eventManagerRef = useRef<EventManager>(new EventManager());
+  const [managers, setManagers] = useState<{
+    chartManager: ChartManager | null;
+    seriesManager: SeriesManager | null;
+  }>({ chartManager: null, seriesManager: null });
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const em = eventManagerRef.current;
+    const cm = new ChartManager(em);
+    const chart = cm.create(container);
+    const sm = new SeriesManager(chart, em);
+
+    // 使用 useState 触发重渲染，让依赖 chartManager/seriesManager 的 effects 正确执行
+    setManagers({ chartManager: cm, seriesManager: sm });
+
+    // ResizeObserver 监听容器大小变化
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const { width, height } = entry.contentRect;
+        if (width > 0 && height > 0) {
+          cm.resize(width, height);
+        }
+      }
+    });
+    observer.observe(container);
+
+    return () => {
+      observer.disconnect();
+      sm.clearAll();
+      cm.dispose();
+      em.clear();
+      setManagers({ chartManager: null, seriesManager: null });
+    };
+  }, []);
+
+  return {
+    containerRef,
+    chartManager: managers.chartManager,
+    seriesManager: managers.seriesManager,
+  };
+}

package/src/hooks/useCrosshairSync.ts

@@ -0,0 +1,109 @@
+import { useEffect, useRef, type RefObject } from 'react';
+import type { IChartApi, ISeriesApi, SeriesType as LWCSeriesType } from 'lightweight-charts';
+import { usePanelRegistry } from '../store/usePanelRegistry.js';
+
+/**
+ * 多图表光标十字线联动 Hook
+ * 监听每个 chart 的 crosshairMove 事件，同步到其他 chart
+ *
+ * 修复点：
+ * 1. setCrosshairPosition 第三参数从 IChartApi 改为 ISeriesApi（通过 PanelRegistry 获取）
+ * 2. 依赖数组增加 panelIds.join(',')，面板变化时重新订阅
+ */
+export function useCrosshairSync(
+  chartRefs: RefObject<(IChartApi | null)[]>,
+  panelIds: string[] = [],
+): void {
+  const isSyncingRef = useRef(false);
+  const rafIdRef = useRef<number | null>(null);
+  const lastTimeRef = useRef<number>(0);
+
+  const chartsLength = chartRefs.current?.length ?? 0;
+  const panelIdsKey = panelIds.join(',');
+
+  useEffect(() => {
+    const charts = chartRefs.current;
+    if (!charts || charts.length <= 1) return;
+
+    const subscriptions: (() => void)[] = [];
+
+    charts.forEach((sourceChart, sourceIndex) => {
+      if (!sourceChart) return;
+
+      const handler = (param: any) => {
+        if (isSyncingRef.current) return;
+        if (!param.time) return;
+
+        // 16ms 节流
+        const now = performance.now();
+        if (now - lastTimeRef.current < 16) {
+          return;
+        }
+        lastTimeRef.current = now;
+
+        isSyncingRef.current = true;
+
+        if (rafIdRef.current !== null) {
+          cancelAnimationFrame(rafIdRef.current);
+        }
+
+        const time = param.time;
+
+        rafIdRef.current = requestAnimationFrame(() => {
+          charts.forEach((targetChart, targetIndex) => {
+            if (targetIndex === sourceIndex || !targetChart) return;
+
+            // 通过 PanelRegistry 获取目标面板的 series
+            const targetPanelId = panelIds[targetIndex];
+            if (!targetPanelId) return;
+
+            const handle = usePanelRegistry.getState().getHandle(targetPanelId);
+            const targetSeries = handle?.seriesManager?.getFirstMainSeries();
+            if (!targetSeries) return;
+
+            try {
+              // 获取源 chart 上对应 series 的价格
+              const seriesData = param.seriesData;
+              let price: number | null = null;
+
+              if (seriesData && seriesData.size > 0) {
+                const entries = Array.from(seriesData.values());
+                if (entries.length > 0) {
+                  const data = entries[0] as any;
+                  price = data.value ?? data.close ?? null;
+                }
+              }
+
+              const finalPrice = price ?? 0;
+
+              targetChart.setCrosshairPosition(
+                finalPrice,
+                time,
+                targetSeries as ISeriesApi<LWCSeriesType>,
+              );
+            } catch {
+              // 静默处理同步错误（time 在目标 chart 上不存在等情况）
+            }
+          });
+
+          isSyncingRef.current = false;
+          rafIdRef.current = null;
+        });
+      };
+
+      sourceChart.subscribeCrosshairMove(handler);
+      subscriptions.push(() => {
+        sourceChart!.unsubscribeCrosshairMove(handler);
+      });
+    });
+
+    return () => {
+      subscriptions.forEach((unsub) => unsub());
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+      isSyncingRef.current = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chartRefs, chartsLength, panelIdsKey]);
+}