@363045841yyt/klinechart-core 0.8.14 → 0.9.0-alpha.0

package/src/features/replay/createReplayController.ts

@@ -0,0 +1,295 @@
+import { KLineChartError } from '../../errors'
+/**
+ * createReplayController — framework-agnostic Bar Replay state machine.
+ *
+ * Owns: position, mode, pacing, speed, [start, end] range.
+ * Doesn't own: the data series, the calendar, the frame loop. Those are
+ * supplied by the surrounding chart adapter.
+ *
+ * Why we expose it via a single `state` signal (rather than five separate
+ * signals): every replay mutation is a transaction over the playhead — the
+ * mode flip on auto-pause, the clamp on `setRange`, etc. Emitting a single
+ * snapshot keeps subscribers (React/Vue) from rendering intermediate states.
+ *
+ * Open design question (deferred from v1):
+ *   Should "reverse play" (speed < 0) be supported in v2?
+ *   The cleanest extension is to drop the `speed <= 0` guard, accept negative
+ *   multipliers in `tick()` math (already symmetric), and add an
+ *   `autoStartReached` clamp that mirrors `autoEndReached`. The on-disk
+ *   contract (the `ReplayState` shape) does not need to change. We defer it
+ *   because reverse playback is meaningless for live-data sessions and the
+ *   indicator runtime currently assumes monotonic time — flipping that
+ *   assumption is a larger cross-package change than this PR.
+ */
+
+import { createSignal, type Signal } from '../../foundation/reactivity/signal'
+
+import type {
+  ReplayController,
+  ReplayControllerInit,
+  ReplayMode,
+  ReplayPacing,
+  ReplayState,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default bar interval used by wall-clock pacing when the host did not
+ *  supply one via `init.barIntervalMs`. Picked to match the most common
+ *  intraday chart (1-minute bars). */
+const DEFAULT_BAR_INTERVAL_MS = 60_000
+
+/** For `tick` pacing, this is the nominal wall-time spent on one bar at
+ *  speed=1. 100ms means a 60-bar tick replay takes 6 seconds at 1x — fast
+ *  enough to feel like "tick playback", slow enough to follow visually. */
+const TICK_PACING_MS_PER_BAR = 100
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function clamp(value: number, lo: number, hi: number): number {
+  if (value < lo) return lo
+  if (value > hi) return hi
+  return value
+}
+
+function assertValidRange(start: number, end: number): void {
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new KLineChartError(
+      'REPLAY_CONFIG_INVALID',
+      `Replay range must be finite numbers: got start=${String(start)}, end=${String(end)}`,
+    )
+  }
+  if (end < start) {
+    throw new KLineChartError(
+      'REPLAY_CONFIG_INVALID',
+      `Replay range end (${end}) must be >= start (${start})`,
+    )
+  }
+}
+
+function assertValidSpeed(speed: number): void {
+  if (!Number.isFinite(speed) || speed <= 0) {
+    // Reverse playback (negative speed) is deliberately rejected in v1.
+    // See the header comment for the extension path.
+    throw new KLineChartError(
+      'REPLAY_CONFIG_INVALID',
+      `Replay speed must be a positive finite number; got ${String(speed)}`,
+    )
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createReplayController(init?: ReplayControllerInit): ReplayController {
+  // -------------------------------------------------------------------
+  // Initial state — validate eagerly so misconfiguration surfaces at
+  // construction rather than on first tick.
+  // -------------------------------------------------------------------
+  const start = init?.start ?? 0
+  const end = init?.end ?? 0
+  assertValidRange(start, end)
+
+  const pacing: ReplayPacing = init?.pacing ?? 'bar'
+  const speed = init?.speed ?? 1
+  assertValidSpeed(speed)
+
+  const barIntervalMs = init?.barIntervalMs ?? DEFAULT_BAR_INTERVAL_MS
+  if (!Number.isFinite(barIntervalMs) || barIntervalMs <= 0) {
+    throw new KLineChartError(
+      'REPLAY_CONFIG_INVALID',
+      `barIntervalMs must be a positive finite number; got ${String(barIntervalMs)}`,
+    )
+  }
+
+  const state: Signal<ReplayState> = createSignal<ReplayState>({
+    position: start,
+    start,
+    end,
+    mode: 'paused',
+    pacing,
+    speed,
+  })
+
+  // -------------------------------------------------------------------
+  // Internal commit helper. All mutations funnel through here so the
+  // immutability invariant and auto-pause check live in one place.
+  // -------------------------------------------------------------------
+  function commit(patch: Partial<ReplayState>): void {
+    const prev = state.peek()
+    const next: ReplayState = { ...prev, ...patch }
+
+    // Re-clamp position whenever it or the range changed.
+    if (patch.position !== undefined || patch.start !== undefined || patch.end !== undefined) {
+      next.position = clamp(next.position, next.start, next.end)
+    }
+
+    // Auto-pause when the playhead arrives at the right edge while
+    // playing. This is the natural end-of-tape transition; without it,
+    // the frame loop would happily tick forever against a clamped
+    // value and waste battery.
+    if (next.mode === 'playing' && next.position >= next.end) {
+      next.position = next.end
+      next.mode = 'paused'
+    }
+
+    // Object.is short-circuits identical structural snapshots so a
+    // no-op commit (e.g. seekTo(currentPosition)) doesn't notify.
+    if (
+      prev.position === next.position &&
+      prev.start === next.start &&
+      prev.end === next.end &&
+      prev.mode === next.mode &&
+      prev.pacing === next.pacing &&
+      prev.speed === next.speed
+    ) {
+      return
+    }
+
+    state.set(next)
+  }
+
+  // -------------------------------------------------------------------
+  // Public mutators
+  // -------------------------------------------------------------------
+  function setRange(nextStart: number, nextEnd: number): void {
+    assertValidRange(nextStart, nextEnd)
+    commit({ start: nextStart, end: nextEnd })
+  }
+
+  function seekTo(position: number): void {
+    if (!Number.isFinite(position)) return
+    commit({ position })
+  }
+
+  function seekBy(delta: number): void {
+    if (!Number.isFinite(delta)) return
+    const cur = state.peek().position
+    commit({ position: cur + delta })
+  }
+
+  function stepForward(): void {
+    seekBy(1)
+  }
+
+  function stepBackward(): void {
+    seekBy(-1)
+  }
+
+  function play(): void {
+    const cur = state.peek()
+    // If we're already at the end, calling play() should not flip to
+    // 'playing' only to immediately auto-pause — that would be a
+    // confusing observable transition for subscribers. Stay paused.
+    if (cur.position >= cur.end) return
+    commit({ mode: 'playing' })
+  }
+
+  function pause(): void {
+    commit({ mode: 'paused' })
+  }
+
+  function toggle(): void {
+    const cur = state.peek()
+    if (cur.mode === 'playing') {
+      pause()
+    } else {
+      play()
+    }
+  }
+
+  function setPacing(p: ReplayPacing): void {
+    commit({ pacing: p })
+  }
+
+  function setSpeed(s: number): void {
+    assertValidSpeed(s)
+    commit({ speed: s })
+  }
+
+  // -------------------------------------------------------------------
+  // Frame-loop driver
+  //
+  // `tick()` is deliberately stateless w.r.t. internal clock
+  // accumulation: each call applies the full advance derived from
+  // `deltaMs` directly to `position`. We DO carry fractional position
+  // values forward through the signal itself, so sub-bar progress is
+  // visible to subscribers (useful for smooth scrubbing animations and
+  // for sub-bar interpolation in the renderer).
+  //
+  // Rationale: a stateful internal accumulator would hide state from
+  // the signal, defeating the "fully observable" property that
+  // distinguishes us from TradingView. Anyone driving the controller
+  // can save/restore the entire replay session by snapshotting the
+  // state signal — no hidden bookkeeping.
+  // -------------------------------------------------------------------
+  function tick(deltaMs: number): boolean {
+    if (!Number.isFinite(deltaMs) || deltaMs <= 0) return false
+
+    const cur = state.peek()
+    if (cur.mode !== 'playing') return false
+
+    let advance = 0
+    switch (cur.pacing) {
+      case 'bar':
+        // Bar pacing is keyboard-driven: tick() never auto-advances.
+        return false
+      case 'wallclock':
+        advance = (deltaMs / barIntervalMs) * cur.speed
+        break
+      case 'tick':
+        advance = (deltaMs / TICK_PACING_MS_PER_BAR) * cur.speed
+        break
+    }
+
+    if (advance === 0) return false
+
+    const prevPosition = cur.position
+    commit({ position: cur.position + advance })
+    // commit() may have clamped or auto-paused; the only way position
+    // genuinely did not change is if we were already at end and the
+    // clamp swallowed the advance.
+    return state.peek().position !== prevPosition
+  }
+
+  // -------------------------------------------------------------------
+  // Disposal — same guard pattern as createIndicatorSelectorController.
+  // -------------------------------------------------------------------
+  let disposed = false
+
+  function dispose(): void {
+    if (disposed) return
+    disposed = true
+  }
+
+  function guard<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R {
+    return (...args: A): R => {
+      if (disposed) return undefined as R
+      return fn(...args)
+    }
+  }
+
+  return {
+    state,
+    setRange: guard(setRange),
+    seekTo: guard(seekTo),
+    seekBy: guard(seekBy),
+    stepForward: guard(stepForward),
+    stepBackward: guard(stepBackward),
+    play: guard(play),
+    pause: guard(pause),
+    toggle: guard(toggle),
+    setPacing: guard(setPacing),
+    setSpeed: guard(setSpeed),
+    tick: (deltaMs: number): boolean => {
+      if (disposed) return false
+      return tick(deltaMs)
+    },
+    dispose,
+  }
+}

package/src/features/replay/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Bar Replay — public types.
+ *
+ * The replay subsystem models a playhead that scrubs through a finite bar
+ * series. Three pacing strategies are supported:
+ *
+ *   - `bar`       step-by-bar; `tick()` is a no-op, callers drive position
+ *                 via `stepForward` / `stepBackward` (keyboard-driven).
+ *   - `wallclock` real-time playback; `tick(deltaMs)` advances by
+ *                 `(deltaMs / msPerBar) * speed` bars. `speed` is a
+ *                 multiplier (1 = realtime, 10 = 10x).
+ *   - `tick`      synthetic tick replay; `tick(deltaMs)` advances by
+ *                 `(deltaMs / 100) * speed` bars (100ms per nominal step).
+ *
+ * Why this matters: TradingView's Bar Replay is wall-clock only and hides its
+ * state. Ours is observable via the `state` signal — any backtest engine,
+ * recording session, or sibling controller can subscribe and react to
+ * playhead changes deterministically.
+ */
+
+import type { Signal } from '../../foundation/reactivity/signal'
+
+export type ReplayMode = 'paused' | 'playing'
+export type ReplayPacing = 'bar' | 'wallclock' | 'tick'
+
+export interface ReplayState {
+  /** Position in the full data series; fractional values are allowed and
+   *  represent sub-bar progress for wall-clock / tick pacing. Callers that
+   *  need an integer bar index should `Math.floor(position)`. */
+  position: number
+  /** Inclusive lower bound of the playhead (clamp floor). */
+  start: number
+  /** Inclusive upper bound of the playhead (clamp ceiling). Typically
+   *  `totalBars - 1`. */
+  end: number
+  mode: ReplayMode
+  pacing: ReplayPacing
+  /** Pacing-dependent rate:
+   *  - `wallclock`: multiplier (1.0 = realtime).
+   *  - `bar`:       reserved; ignored by `tick()`.
+   *  - `tick`:      multiplier (1.0 = 1 bar per 100ms). */
+  speed: number
+}
+
+export interface ReplayControllerInit {
+  start?: number
+  end?: number
+  pacing?: ReplayPacing
+  speed?: number
+  /** Bar interval in milliseconds. Used by wall-clock pacing to compute
+   *  how many bars one wall-second represents. Defaults to 60_000 (1m). */
+  barIntervalMs?: number
+}
+
+export interface ReplayController {
+  /** Reactive view of the entire replay state. Subscribers fire after any
+   *  mutation that changes the state object (Object.is equality). */
+  readonly state: Signal<ReplayState>
+
+  /** Set the inclusive `[start, end]` range. The current position is
+   *  re-clamped into the new range. Throws if `end < start`. */
+  setRange(start: number, end: number): void
+
+  /** Seek the playhead to an absolute position; clamped to `[start, end]`. */
+  seekTo(position: number): void
+  /** Seek by a relative delta; clamped to `[start, end]`. */
+  seekBy(delta: number): void
+  /** Advance exactly one bar (`position += 1`), clamped to `end`. If the
+   *  step lands on `end`, mode transitions to `paused`. */
+  stepForward(): void
+  /** Retreat exactly one bar (`position -= 1`), clamped to `start`. */
+  stepBackward(): void
+
+  /** Begin playback from the current position using the configured
+   *  pacing/speed. If already at `end`, this is a no-op. */
+  play(): void
+  pause(): void
+  /** Toggle between `playing` and `paused`. */
+  toggle(): void
+
+  setPacing(p: ReplayPacing): void
+  /** Set the speed multiplier. Throws on `speed <= 0` (reverse play not
+   *  supported in v1 — see Open Question in the controller header). */
+  setSpeed(s: number): void
+
+  /** Frame-loop hook. The chart's render loop calls this with the elapsed
+   *  wall-clock time since the last frame; the controller decides whether
+   *  to advance `position` based on `mode`, `pacing`, and `speed`.
+   *
+   *  Returns `true` if `position` (and therefore `state`) changed, so the
+   *  caller can request a re-render. Returns `false` for no-op frames
+   *  (paused, bar-pacing, or sub-bar accumulation that didn't cross a
+   *  whole-bar boundary — though in this v1 we keep `tick()` stateless and
+   *  always commit the fractional advance, so any non-zero advance returns
+   *  `true`). */
+  tick(deltaMs: number): boolean
+
+  /** Tear down. After `dispose()`, all mutators become silent no-ops and
+   *  the `state` signal stops emitting. */
+  dispose(): void
+}
+
+/** Factory shape — matches the exported function. Re-stated here so callers
+ *  importing only the types file can type-check controller construction. */
+export type CreateReplayController = (init?: ReplayControllerInit) => ReplayController

package/src/features/semantic/controller.ts

@@ -0,0 +1,232 @@
+import type { KLineData, DataFetcher, SymbolSpec } from '../../controllers/types'
+import { getRegisteredIndicatorDefinition } from '../../engine/indicators/indicatorDefinitionRegistry'
+import type { IndicatorMetadata } from '../../engine/indicators/indicatorMetadata'
+import { getBuiltinIndicatorDefinitions } from '../../engine/indicators/registerBuiltins'
+import type { CustomMarkerEntity } from '../../engine/marker/registry'
+import type { SubIndicatorType as CoreSubIndicatorType } from '../../engine/renderers/Indicator'
+import { EventBus } from '../../foundation/plugin/EventBus'
+
+import type {
+  SemanticChartConfig,
+  ApplyResult,
+  MainIndicatorConfig,
+  SubIndicatorConfig,
+  CustomMarker,
+  DataConfig,
+} from './types'
+import { SemanticConfigValidator } from './validator'
+
+export type SemanticEventType = 'config:loading' | 'config:ready' | 'config:error'
+export type { DataFetcher, SymbolSpec } from '../../controllers/types'
+
+function normalizeIndicatorId(id: string): string {
+  return id
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '')
+}
+
+function getSemanticIndicatorDefinition(type: string): IndicatorMetadata | undefined {
+  const registered = getRegisteredIndicatorDefinition(type)
+  if (registered) return registered
+
+  const normalizedType = normalizeIndicatorId(type)
+  return getBuiltinIndicatorDefinitions().find((definition) => {
+    const candidates = [definition.name, definition.displayName, ...(definition.aliases ?? [])]
+    return candidates.some((candidate) => normalizeIndicatorId(candidate) === normalizedType)
+  })
+}
+
+export interface SemanticChartAdapter {
+  setSymbols(specs: ReadonlyArray<SymbolSpec>): void
+  updateData(data: ReadonlyArray<KLineData>): void
+  updateRendererConfig(name: string, config: Record<string, unknown>): void
+  addIndicator?(
+    definitionId: string,
+    role: 'main' | 'sub',
+    params?: Record<string, unknown>,
+  ): string | null
+  removeIndicator?(instanceId: string): boolean
+  enableMainIndicator?(
+    indicatorId: string,
+    params?: Record<string, number | boolean | string>,
+  ): boolean
+  disableMainIndicator?(indicatorId: string): boolean
+  clearSubPanes(): void
+  createSubPane(
+    paneId: string,
+    indicatorId: CoreSubIndicatorType,
+    params?: Record<string, unknown>,
+  ): boolean
+  clearCustomMarkers(): void
+  updateCustomMarkers(markers: ReadonlyArray<CustomMarkerEntity>): void
+}
+
+export class SemanticChartController {
+  private chart: SemanticChartAdapter
+  private validator: SemanticConfigValidator
+  private events: EventBus
+
+  constructor(chart: SemanticChartAdapter) {
+    this.chart = chart
+    this.validator = new SemanticConfigValidator()
+    this.events = new EventBus()
+  }
+
+  async applyConfig(config: SemanticChartConfig): Promise<ApplyResult> {
+    const validation = await this.validator.validate(config)
+    if (!validation.valid) {
+      return { success: false, errors: validation.errors }
+    }
+
+    const security = this.validator.securityCheck(config)
+    if (!security.passed) {
+      return { success: false, errors: security.violations }
+    }
+
+    this.events.emit('config:loading', undefined)
+    try {
+      await this.doApplyConfig(config)
+      this.events.emit('config:ready', undefined)
+      return { success: true }
+    } catch (error) {
+      this.events.emit('config:error', error)
+      return {
+        success: false,
+        errors: [error instanceof Error ? error.message : String(error)],
+      }
+    }
+  }
+
+  on(event: SemanticEventType, handler: (data?: unknown) => void): void {
+    this.events.on(event, handler)
+  }
+
+  off(event: SemanticEventType, handler: (data?: unknown) => void): void {
+    this.events.off(event, handler)
+  }
+
+  private async doApplyConfig(config: SemanticChartConfig): Promise<void> {
+    // 先注册指标（同步），确保 scheduler 首次 applyResults 时指标已在 registry
+    if (config.indicators) {
+      this.applyIndicators(config.indicators.main, config.indicators.sub)
+    }
+
+    this.chart.setSymbols([
+      {
+        symbol: config.data.symbol,
+        exchange: config.data.exchange,
+        period: config.data.period,
+        adjust: config.data.adjust,
+        source: config.data.source,
+        startDate: config.data.startDate,
+        endDate: config.data.endDate,
+      },
+    ])
+
+    if (config.markers) {
+      this.applyMarkers(config.markers.customMarkers, config.data.period)
+    }
+
+    if (config.chart) {
+      this.applyChartOptions(config.chart)
+    }
+  }
+
+  private applyIndicators(main?: MainIndicatorConfig[], sub?: SubIndicatorConfig[]): void {
+    if (main) {
+      for (const indicator of main) {
+        if (!indicator.enabled) {
+          if (!this.chart.removeIndicator?.(indicator.type)) {
+            this.chart.disableMainIndicator?.(indicator.type)
+          }
+          continue
+        }
+        const added = this.chart.addIndicator?.(
+          indicator.type,
+          'main',
+          indicator.params as Record<string, unknown>,
+        )
+        if (added) {
+          continue
+        }
+        const enabled = this.chart.enableMainIndicator?.(
+          indicator.type,
+          indicator.params as Record<string, number | boolean | string>,
+        )
+        if (enabled) {
+          continue
+        }
+        getSemanticIndicatorDefinition(indicator.type)?.semantic?.apply?.(this.chart, indicator)
+      }
+    }
+
+    this.chart.clearSubPanes()
+
+    if (sub) {
+      for (const indicator of sub) {
+        this.applySubIndicator(indicator)
+      }
+    }
+  }
+
+  private applySubIndicator(indicator: SubIndicatorConfig): void {
+    if (!indicator.enabled) return
+    const { type, params } = indicator
+    const paneId = `${type}_0`
+    const indicatorId = type
+    const success = this.chart.createSubPane(paneId, indicatorId as CoreSubIndicatorType, params)
+    if (!success) {
+      console.warn(`[Semantic] Failed to create sub pane for ${type}`)
+    }
+  }
+
+  private applyMarkers(markers?: CustomMarker[], period?: DataConfig['period']): void {
+    if (!markers || markers.length === 0) {
+      this.chart.clearCustomMarkers()
+      return
+    }
+    const entities: CustomMarkerEntity[] = markers.map((marker) => ({
+      id: marker.id,
+      date: marker.date,
+      timestamp: parseDateToTimestamp(marker.date, period || 'daily'),
+      shape: marker.shape,
+      groupKey: marker.groupKey,
+      offset: marker.offset,
+      style: marker.style,
+      label: marker.label,
+      metadata: marker.metadata,
+    }))
+    this.chart.updateCustomMarkers(entities)
+  }
+
+  private applyChartOptions(options: {
+    kWidth?: number
+    kGap?: number
+    autoScrollToRight?: boolean
+  }): void {
+    if (options.autoScrollToRight !== undefined) {
+    }
+  }
+}
+
+function parseDateToTimestamp(dateStr: string, _period: DataConfig['period']): number {
+  const hasTime = dateStr.includes(' ')
+  if (hasTime) {
+    const [datePart, timePart] = dateStr.split(' ')
+    const parts = datePart!.split('-').map(Number)
+    const year = parts[0]!
+    const month = parts[1]!
+    const day = parts[2]!
+    const timeParts = timePart!.split(':').map(Number)
+    const hour = timeParts[0]!
+    const minute = timeParts[1]!
+    return Date.UTC(year, month - 1, day, hour - 8, minute, 0, 0)
+  } else {
+    const parts = dateStr.split('-').map(Number)
+    const year = parts[0]!
+    const month = parts[1]!
+    const day = parts[2]!
+    return Date.UTC(year, month - 1, day, 0 - 8, 0, 0, 0)
+  }
+}

package/src/features/semantic/index.ts

@@ -0,0 +1,36 @@
+export type {
+  SemanticChartConfig,
+  AdjustType,
+  DataConfig,
+  IndicatorsConfig,
+  MainIndicatorConfig,
+  SubIndicatorConfig,
+  SubIndicatorType,
+  MAParams,
+  BOLLParams,
+  MarkersConfig,
+  CustomMarker,
+  MarkerShapeType,
+  MarkerStyle,
+  MarkerLabel,
+  LegendConfig,
+  ChartOptions,
+  ThemeConfig,
+  ApplyResult,
+  ValidationResult,
+  SecurityResult,
+} from './types'
+
+export { SemanticChartController, type SemanticEventType } from './controller'
+export type { SemanticChartAdapter } from './controller'
+export type { DataFetcher, SymbolSpec } from '../../controllers/types'
+
+export {
+  SemanticConfigValidator,
+  sanitizeParams,
+  sanitizeColor,
+  validateColor,
+  validateSymbol,
+} from './validator'
+
+export { drawShape, drawLabel, hitTestShape } from './drawShape'