@363045841yyt/klinechart-core 0.7.3

package/src/controllers/createChartController.ts

@@ -0,0 +1,665 @@
+/**
+ * createChartController — production ChartControllerFactory.
+ *
+ * Wraps the legacy chart engine (`src/core/chart.ts`) behind the
+ * framework-agnostic `ChartController` signal surface. Adapters
+ * (React / Vue / Angular) consume this.
+ *
+ * Boundaries owned here:
+ *   - Construct the inner DOM scaffold the legacy `Chart` expects.
+ *   - Bridge Chart's facade signals into controller-owned signals.
+ *   - Delegate zoom / interaction / indicator / drawing methods to Chart.
+ *   - Tear down DOM + listeners on dispose().
+ */
+
+import { createSignal, type Signal } from '../reactivity'
+import type {
+    ChartController,
+    ChartMountOptions,
+    ChartViewport,
+    DrawingToolType,
+    DrawingObject,
+    SubPaneInfo,
+    IndicatorInstance,
+    InteractionSnapshot,
+    DrawingControllerCallbacks,
+    IndicatorDefinition,
+    KLineData,
+} from './types'
+import type { CustomMarkerEntity } from '../engine/marker/registry'
+import {
+    Chart,
+    type ChartOptions,
+    type Viewport as LegacyViewport,
+    type ViewportState as LegacyViewportState,
+    type IndicatorInstance as LegacyIndicatorInstance,
+    type SubPaneInfo as LegacySubPaneInfo,
+    type DrawingObject as LegacyDrawingObject,
+    type DrawingToolType as LegacyDrawingToolType,
+    type InteractionSnapshot as LegacyInteractionSnapshot,
+} from '../engine/chart'
+import { zoomLevelToKWidth, kGapFromKWidth } from '../engine/utils/zoom'
+
+// Plugin-backed drawings expose `kind` instead of legacy `type`.
+type PluginBackedDrawingObject = {
+    id: string
+    kind: string
+}
+ 
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+
+const DEFAULT_OPTS = {
+    yPaddingPx: 20,
+    minKWidth: 1,
+    maxKWidth: 50,
+    rightAxisWidth: 0,
+    bottomAxisHeight: 24,
+    priceLabelWidth: 60,
+    zoomLevels: 20,
+    initialZoomLevel: 3,
+} as const
+
+const INITIAL_INTERACTION: InteractionSnapshot = {
+    crosshairPos: null,
+    crosshairIndex: null,
+    crosshairPrice: null,
+    hoveredIndex: null,
+    activePaneId: null,
+    tooltipPos: { x: 0, y: 0 },
+    tooltipAnchorPlacement: 'right-bottom',
+    hoveredMarkerData: null,
+    hoveredCustomMarker: null,
+    isDragging: false,
+    isResizingPaneBoundary: false,
+    isHoveringPaneBoundary: false,
+    hoveredPaneBoundaryId: null,
+    isHoveringRightAxis: false,
+}
+
+// ---------------------------------------------------------------------------
+// Indicator catalog (mirrors renderer ids registered in the engine)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_INDICATOR_CATALOG: ReadonlyArray<IndicatorDefinition> = [
+    { id: 'MA', label: 'MA', name: '移动平均线', role: 'main', params: [] },
+    { id: 'BOLL', label: 'BOLL', name: '布林带', role: 'main', params: [] },
+    { id: 'EXPMA', label: 'EXPMA', name: '指数平均线', role: 'main', params: [] },
+    { id: 'ENE', label: 'ENE', name: '轨道线', role: 'main', params: [] },
+    { id: 'SAR', label: 'SAR', name: '抛物线', role: 'main', params: [] },
+    { id: 'SUPERTREND', label: 'SuperTrend', name: '超级趋势', role: 'main', params: [] },
+    { id: 'STRUCTURE', label: 'Structure', name: 'SMC 结构', role: 'main', params: [] },
+    { id: 'ZONES', label: 'Zones', name: 'SMC 区域', role: 'main', params: [] },
+    { id: 'VOLUME', label: 'VOL', name: '成交量', role: 'sub', params: [] },
+    { id: 'MACD', label: 'MACD', name: 'MACD', role: 'sub', params: [] },
+    { id: 'RSI', label: 'RSI', name: '相对强弱', role: 'sub', params: [] },
+    { id: 'CCI', label: 'CCI', name: '顺势指标', role: 'sub', params: [] },
+    { id: 'STOCH', label: 'KDJ/STOCH', name: '随机指标', role: 'sub', params: [] },
+    { id: 'MOM', label: 'MOM', name: '动量', role: 'sub', params: [] },
+    { id: 'WMSR', label: 'WMSR', name: '威廉指标', role: 'sub', params: [] },
+    { id: 'KST', label: 'KST', name: 'KST 振荡器', role: 'sub', params: [] },
+    { id: 'FASTK', label: 'FASTK', name: '快速 K', role: 'sub', params: [] },
+    { id: 'OBV', label: 'OBV', name: '能量潮', role: 'sub', params: [] },
+    { id: 'VWAP', label: 'VWAP', name: '成交量加权均价', role: 'sub', params: [] },
+    { id: 'VOLUME_PROFILE', label: 'VP', name: '成交量分布', role: 'sub', params: [] },
+]
+
+// ---------------------------------------------------------------------------
+// DOM scaffolding
+// ---------------------------------------------------------------------------
+
+interface MountedDom {
+    container: HTMLDivElement
+    canvasLayer: HTMLDivElement
+    rightAxisLayer: HTMLDivElement
+    xAxisCanvas: HTMLCanvasElement
+    cleanup: () => void
+}
+
+function mapViewportState(vp: LegacyViewportState): ChartViewport {
+    return {
+        zoomLevel: vp.zoomLevel,
+        plotWidth: vp.plotWidth,
+        plotHeight: vp.plotHeight,
+        dpr: vp.dpr,
+        visibleFrom: vp.visibleFrom,
+        visibleTo: vp.visibleTo,
+        desiredScrollLeft: vp.desiredScrollLeft,
+        kWidth: vp.kWidth,
+        kGap: vp.kGap,
+    }
+}
+
+function mapIndicatorInstance(indicator: LegacyIndicatorInstance): IndicatorInstance {
+    return {
+        id: indicator.id,
+        definitionId: indicator.definitionId,
+        label: indicator.label,
+        name: indicator.name,
+        role: indicator.role,
+        paneId: indicator.paneId,
+        params: { ...indicator.params },
+    }
+}
+
+function mapSubPaneInfo(subPane: LegacySubPaneInfo): SubPaneInfo {
+    return {
+        paneId: subPane.paneId,
+        indicatorId: subPane.indicatorId,
+        params: { ...subPane.params },
+        ratio: subPane.ratio,
+    }
+}
+
+function mapDrawingTool(tool: LegacyDrawingToolType | null): DrawingToolType | null {
+    return tool
+}
+
+function mapPluginDrawingKind(kind: PluginBackedDrawingObject['kind']): DrawingToolType {
+    switch (kind) {
+        case 'trend-line':
+        case 'ray':
+        case 'extended-line':
+            return 'trendline'
+        case 'horizontal-line':
+        case 'horizontal-ray':
+        case 'flat-line':
+            return 'horizontal'
+        default:
+            return 'trendline'
+    }
+}
+
+function mapDrawingObject(drawing: LegacyDrawingObject | PluginBackedDrawingObject): DrawingObject {
+    return {
+        id: drawing.id,
+        type: 'type' in drawing
+            ? (mapDrawingTool(drawing.type) ?? drawing.type)
+            : mapPluginDrawingKind(drawing.kind),
+    }
+}
+
+function mapPaneRatios(ratios: Readonly<Record<string, number>>): Readonly<Record<string, number>> {
+    return { ...ratios }
+}
+
+function mapInteractionRecord(
+    value: Record<string, any> | null | undefined,
+): Record<string, unknown> | null {
+    if (!value) {
+        return null
+    }
+
+    return { ...value }
+}
+
+function mapInteractionSnapshot(snapshot: LegacyInteractionSnapshot): InteractionSnapshot {
+    return {
+        crosshairPos: snapshot.crosshairPos ? { ...snapshot.crosshairPos } : null,
+        crosshairIndex: snapshot.crosshairIndex,
+        crosshairPrice: snapshot.crosshairPrice,
+        hoveredIndex: snapshot.hoveredIndex,
+        activePaneId: snapshot.activePaneId,
+        tooltipPos: { ...snapshot.tooltipPos },
+        tooltipAnchorPlacement: snapshot.tooltipAnchorPlacement,
+        hoveredMarkerData: mapInteractionRecord(snapshot.hoveredMarkerData),
+        hoveredCustomMarker: mapInteractionRecord(snapshot.hoveredCustomMarker),
+        isDragging: snapshot.isDragging,
+        isResizingPaneBoundary: snapshot.isResizingPaneBoundary,
+        isHoveringPaneBoundary: snapshot.isHoveringPaneBoundary,
+        hoveredPaneBoundaryId: snapshot.hoveredPaneBoundaryId,
+        isHoveringRightAxis: snapshot.isHoveringRightAxis,
+    }
+}
+
+function buildDom(container: HTMLElement): MountedDom {
+    const ownerDoc = container.ownerDocument
+    if (!ownerDoc) {
+        throw new Error(
+            '[createChartController] container has no ownerDocument; cannot build DOM scaffold',
+        )
+    }
+
+    let chartContainer: HTMLDivElement
+    let containerCreatedByUs = false
+    if (container instanceof HTMLDivElement) {
+        chartContainer = container
+    } else {
+        chartContainer = ownerDoc.createElement('div')
+        chartContainer.style.width = '100%'
+        chartContainer.style.height = '100%'
+        chartContainer.style.position = 'relative'
+        chartContainer.style.overflow = 'auto'
+        container.appendChild(chartContainer)
+        containerCreatedByUs = true
+    }
+
+    const scrollContent = ownerDoc.createElement('div')
+    scrollContent.className = 'klc-scroll-content'
+    scrollContent.style.position = 'relative'
+
+    const canvasLayer = ownerDoc.createElement('div')
+    canvasLayer.className = 'klc-canvas-layer'
+    canvasLayer.style.position = 'sticky'
+    canvasLayer.style.top = '0'
+    canvasLayer.style.left = '0'
+
+    const xAxisCanvas = ownerDoc.createElement('canvas')
+    xAxisCanvas.className = 'klc-x-axis-canvas'
+
+    canvasLayer.appendChild(xAxisCanvas)
+    scrollContent.appendChild(canvasLayer)
+    chartContainer.appendChild(scrollContent)
+
+    const rightAxisLayer = ownerDoc.createElement('div')
+    rightAxisLayer.className = 'klc-right-axis-host'
+    rightAxisLayer.style.position = 'absolute'
+    rightAxisLayer.style.top = '0'
+    rightAxisLayer.style.right = '0'
+    chartContainer.appendChild(rightAxisLayer)
+
+    const cleanup = (): void => {
+        try {
+            scrollContent.remove()
+            rightAxisLayer.remove()
+            if (containerCreatedByUs) {
+                chartContainer.remove()
+            }
+        } catch {
+            /* DOM may already be gone — best effort */
+        }
+    }
+
+    return { container: chartContainer, canvasLayer, rightAxisLayer, xAxisCanvas, cleanup }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createChartController(opts: ChartMountOptions): ChartController {
+    if (!opts) {
+        throw new Error('[createChartController] opts is required')
+    }
+    if (!opts.container) {
+        throw new Error('[createChartController] opts.container must be a non-null HTMLElement')
+    }
+
+    const mounted = buildDom(opts.container)
+    const initialZoomLevel = opts.initialZoomLevel ?? DEFAULT_OPTS.initialZoomLevel
+    const zoomLevelCount = opts.zoomLevels ?? DEFAULT_OPTS.zoomLevels
+
+    const chartOptions: ChartOptions = {
+        yPaddingPx: DEFAULT_OPTS.yPaddingPx,
+        rightAxisWidth: DEFAULT_OPTS.rightAxisWidth,
+        bottomAxisHeight: DEFAULT_OPTS.bottomAxisHeight,
+        minKWidth: DEFAULT_OPTS.minKWidth,
+        maxKWidth: DEFAULT_OPTS.maxKWidth,
+        priceLabelWidth: DEFAULT_OPTS.priceLabelWidth,
+        panes: [{ id: 'main', ratio: 1 }],
+        paneGap: 0,
+        zoomLevels: zoomLevelCount,
+        initialZoomLevel,
+    }
+
+    const chart = new Chart(
+        {
+            container: mounted.container,
+            canvasLayer: mounted.canvasLayer,
+            rightAxisLayer: mounted.rightAxisLayer,
+            xAxisCanvas: mounted.xAxisCanvas,
+        },
+        chartOptions,
+    )
+
+    const currentDpr = typeof window !== 'undefined' && window.devicePixelRatio > 0
+        ? window.devicePixelRatio
+        : 1
+    const currentKWidth = zoomLevelToKWidth(initialZoomLevel, {
+        minKWidth: DEFAULT_OPTS.minKWidth,
+        maxKWidth: DEFAULT_OPTS.maxKWidth,
+        zoomLevelCount,
+        dpr: currentDpr,
+    })
+    const currentKGap = kGapFromKWidth(currentKWidth, currentDpr)
+
+    // -------------------------------------------------------------------
+    // Controller signals (bridge mode: subscribe to Chart's signals)
+    // -------------------------------------------------------------------
+
+    const viewport: Signal<ChartViewport> = createSignal<ChartViewport>({
+        zoomLevel: initialZoomLevel,
+        plotWidth: 0,
+        plotHeight: 0,
+        dpr: currentDpr,
+        visibleFrom: 0,
+        visibleTo: 0,
+        desiredScrollLeft: undefined,
+        kWidth: currentKWidth,
+        kGap: currentKGap,
+    })
+
+    const data: Signal<ReadonlyArray<KLineData>> = createSignal(opts.data)
+
+    const themeSignal: Signal<'light' | 'dark'> = createSignal(opts.theme ?? 'light')
+
+    const indicators: Signal<ReadonlyArray<IndicatorInstance>> = createSignal<
+        ReadonlyArray<IndicatorInstance>
+    >([])
+    const subPanes: Signal<ReadonlyArray<SubPaneInfo>> = createSignal<ReadonlyArray<SubPaneInfo>>([])
+    const drawingTool: Signal<DrawingToolType | null> = createSignal<DrawingToolType | null>(null)
+    const drawings: Signal<ReadonlyArray<DrawingObject>> = createSignal<ReadonlyArray<DrawingObject>>([])
+    const paneRatios: Signal<Readonly<Record<string, number>>> = createSignal<
+        Readonly<Record<string, number>>
+    >({})
+    const interactionState: Signal<InteractionSnapshot> = createSignal(INITIAL_INTERACTION)
+
+    // -------------------------------------------------------------------
+    // Apply initial render state + seed data
+    // -------------------------------------------------------------------
+
+    try {
+        chart.applyRenderState(currentKWidth, currentKGap, initialZoomLevel)
+    } catch {
+        /* tolerate jsdom */
+    }
+
+    try {
+        chart.setData([...opts.data])
+    } catch {
+        /* tolerate first-paint racing */
+    }
+
+    // Apply initial theme if non-default
+    if (opts.theme && opts.theme !== 'light') {
+        chart.setTheme(opts.theme)
+    }
+
+    // -------------------------------------------------------------------
+    // Signal bridges — subscribe to Chart's facade signals and forward
+    // -------------------------------------------------------------------
+
+    const unsubs: Array<() => void> = []
+
+    // viewport: after zoom/scroll through facade methods
+    unsubs.push(
+        chart.viewport.subscribe(() => {
+            viewport.set(mapViewportState(chart.viewport.peek()))
+        }),
+    )
+
+    // data
+    unsubs.push(
+        chart.data.subscribe(() => data.set(chart.data.peek())),
+    )
+
+    // theme
+    unsubs.push(
+        chart.theme.subscribe(() => themeSignal.set(chart.theme.peek())),
+    )
+
+    // indicators
+    unsubs.push(
+        chart.indicators.subscribe(() =>
+            indicators.set(chart.indicators.peek().map(mapIndicatorInstance)),
+        ),
+    )
+
+    // subPanes
+    unsubs.push(
+        chart.subPanes.subscribe(() =>
+            subPanes.set(chart.subPanes.peek().map(mapSubPaneInfo)),
+        ),
+    )
+
+    // drawingTool
+    unsubs.push(
+        chart.drawingTool.subscribe(() =>
+            drawingTool.set(mapDrawingTool(chart.drawingTool.peek())),
+        ),
+    )
+
+    // drawings
+    unsubs.push(
+        chart.drawings.subscribe(() =>
+            drawings.set(chart.drawings.peek().map(mapDrawingObject)),
+        ),
+    )
+
+    // paneRatios
+    unsubs.push(
+        chart.paneRatios.subscribe(() => paneRatios.set(mapPaneRatios(chart.paneRatios.peek()))),
+    )
+
+    // interactionState
+    unsubs.push(
+        chart.interactionState.subscribe(() =>
+            interactionState.set(mapInteractionSnapshot(chart.interactionState.peek())),
+        ),
+    )
+
+    // -------------------------------------------------------------------
+    // Legacy callback for resize (chart's viewport signal doesn't fire
+    // on resize — only on zoom/scroll through facade methods)
+    // -------------------------------------------------------------------
+
+    chart.setOnViewportChange((vp: LegacyViewport) => {
+        const current = viewport.peek()
+        viewport.set({
+            ...current,
+            plotWidth: vp.plotWidth,
+            plotHeight: vp.plotHeight,
+            dpr: vp.dpr > 0 ? vp.dpr : current.dpr,
+        })
+    })
+
+    // -------------------------------------------------------------------
+    // Lifecycle guard
+    // -------------------------------------------------------------------
+
+    let disposed = false
+
+    // -------------------------------------------------------------------
+    // Public methods — delegate to Chart facade
+    // -------------------------------------------------------------------
+
+    function setData(next: ReadonlyArray<KLineData>): void {
+        if (disposed) return
+        try {
+            chart.setData([...next])
+        } catch {
+            data.set([...next])
+        }
+    }
+
+    function appendData(next: ReadonlyArray<KLineData>): void {
+        if (disposed) return
+        const current = data.peek()
+        const merged = [...current, ...next]
+        setData(merged)
+    }
+
+    function setTheme(nextTheme: 'light' | 'dark'): void {
+        if (disposed) return
+        chart.setTheme(nextTheme)
+    }
+
+    function zoomToLevel(level: number, anchorX?: number): void {
+        if (disposed) return
+        chart.zoomToLevel(level, anchorX)
+    }
+
+    function zoomIn(anchorX?: number): void {
+        if (disposed) return
+        chart.zoomIn(anchorX)
+    }
+
+    function zoomOut(anchorX?: number): void {
+        if (disposed) return
+        chart.zoomOut(anchorX)
+    }
+
+    function handlePointerEvent(
+        e: PointerEvent,
+        drawingController?: DrawingControllerCallbacks,
+    ): boolean {
+        if (disposed) return false
+        return chart.handlePointerEvent(e, drawingController)
+    }
+
+    function handleWheelEvent(e: WheelEvent): void {
+        if (disposed) return
+        chart.handleWheelEvent(e)
+    }
+
+    function handleScrollEvent(): void {
+        if (disposed) return
+        chart.handleScrollEvent()
+    }
+
+    function handlePinchZoom(delta: number, centerClientX: number): void {
+        if (disposed) return
+        chart.handlePinchZoom(delta, centerClientX)
+    }
+
+    function addIndicator(
+        definitionId: string,
+        role: 'main' | 'sub',
+        params?: Record<string, unknown>,
+    ): string | null {
+        if (disposed) return null
+        return chart.addIndicator(definitionId, role, params)
+    }
+
+    function removeIndicator(instanceId: string): boolean {
+        if (disposed) return false
+        return chart.removeIndicator(instanceId)
+    }
+
+    function updateIndicatorParams(
+        instanceId: string,
+        params: Record<string, unknown>,
+    ): boolean {
+        if (disposed) return false
+        return chart.updateIndicatorParams(instanceId, params)
+    }
+
+    function updateRendererConfig(name: string, config: Record<string, unknown>): void {
+        if (disposed) return
+        chart.updateRendererConfig(name, config)
+    }
+
+    function setDrawingTool(tool: DrawingToolType | null): void {
+        if (disposed) return
+        chart.setDrawingTool(tool)
+    }
+
+    function clearDrawings(): void {
+        if (disposed) return
+        chart.clearDrawings()
+    }
+
+    function removeDrawing(drawingId: string): void {
+        if (disposed) return
+        chart.removeDrawing(drawingId)
+    }
+
+    function createSubPane(paneId: string, indicatorId: string, params?: Record<string, unknown>): boolean {
+        if (disposed) return false
+        return chart.createSubPane(paneId, indicatorId as never, params as Record<string, string | number | boolean> | undefined)
+    }
+
+    function clearSubPanes(): void {
+        if (disposed) return
+        chart.clearSubPanes()
+    }
+
+    function resizeSubPane(paneId: string, deltaY: number): boolean {
+        if (disposed) return false
+        return chart.resizeSubPane(paneId, deltaY)
+    }
+
+    function updateCustomMarkers(markers: ReadonlyArray<CustomMarkerEntity>): void {
+        if (disposed) return
+        chart.updateCustomMarkers([...markers])
+    }
+
+    function clearCustomMarkers(): void {
+        if (disposed) return
+        chart.clearCustomMarkers()
+    }
+
+    function updateSettingsFacade(settings: Record<string, unknown>): void {
+        if (disposed) return
+        chart.updateSettingsFacade(settings)
+    }
+
+    function updateOptionsFacade(options: Record<string, unknown>): void {
+        if (disposed) return
+        chart.updateOptionsFacade(options)
+    }
+
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+        // Unsubscribe all signal bridges first
+        for (const unsub of unsubs) {
+            try {
+                unsub()
+            } catch {
+                /* best-effort */
+            }
+        }
+        try {
+            void chart.destroy()
+        } catch {
+            /* best-effort */
+        }
+        try {
+            mounted.cleanup()
+        } catch {
+            /* best-effort */
+        }
+    }
+
+    return {
+        viewport,
+        data,
+        theme: themeSignal,
+        indicators,
+        subPanes,
+        drawingTool,
+        drawings,
+        paneRatios,
+        interactionState,
+        catalog: DEFAULT_INDICATOR_CATALOG,
+        setData,
+        appendData,
+        updateData: setData,
+        setTheme,
+        zoomToLevel,
+        zoomIn,
+        zoomOut,
+        handlePointerEvent,
+        handleWheelEvent,
+        handleScrollEvent,
+        handlePinchZoom,
+        addIndicator,
+        removeIndicator,
+        updateIndicatorParams,
+        updateRendererConfig,
+        setDrawingTool,
+        clearDrawings,
+        removeDrawing,
+        createSubPane,
+        clearSubPanes,
+        resizeSubPane,
+        updateCustomMarkers,
+        clearCustomMarkers,
+        updateSettingsFacade,
+        updateOptionsFacade,
+        dispose,
+    }
+}