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

package/src/engine/state/paneState.ts

@@ -0,0 +1,99 @@
+import { batch, createSubState } from '../../foundation/reactivity/signal'
+import type { PaneSpec } from '../chartTypes'
+import type { ScaleType } from '../utils/tickPosition'
+import { immutableMap } from './immutable'
+
+function copyRatios(ratios: Readonly<Record<string, number>>): Record<string, number> {
+  return { ...ratios }
+}
+
+function copySpecs(specs: ReadonlyArray<PaneSpec>): PaneSpec[] {
+  return specs.map((spec) => ({
+    ...spec,
+    ...(spec.capabilities ? { capabilities: { ...spec.capabilities } } : {}),
+  }))
+}
+
+function scaleMapsEqual(
+  left: ReadonlyMap<string, ScaleType>,
+  right: ReadonlyMap<string, ScaleType>,
+): boolean {
+  if (left.size !== right.size) return false
+  for (const [id, type] of right) {
+    if (left.get(id) !== type) return false
+  }
+  return true
+}
+
+export function createPaneState() {
+  const { signals, readonly } = createSubState({
+    paneRatios: {} as Record<string, number>,
+    paneSpecs: [] as PaneSpec[],
+    paneScaleTypes: immutableMap(new Map<string, ScaleType>()),
+  })
+
+  const writeScaleTypes = (next: ReadonlyMap<string, ScaleType>) => {
+    if (scaleMapsEqual(signals.paneScaleTypes.peek(), next)) return
+    signals.paneScaleTypes.set(next)
+  }
+
+  return {
+    readonly,
+
+    actions: {
+      setPaneRatios(ratios: Record<string, number>) {
+        signals.paneRatios.set(copyRatios(ratios))
+      },
+
+      setPaneSpecs(specs: PaneSpec[]) {
+        signals.paneSpecs.set(copySpecs(specs))
+      },
+
+      /** ratios 与 specs 同批发布，避免中间态 */
+      commitLayout(ratios: Readonly<Record<string, number>>, specs: ReadonlyArray<PaneSpec>) {
+        batch(() => {
+          signals.paneRatios.set(copyRatios(ratios))
+          signals.paneSpecs.set(copySpecs(specs))
+          // 仅保留仍存在 pane 的 scale；缺失 id 由 Chart.ensurePaneScaleTypes 按 settings 补齐
+          const prev = signals.paneScaleTypes.peek()
+          const next = new Map<string, ScaleType>()
+          for (const spec of specs) {
+            const existing = prev.get(spec.id)
+            if (existing !== undefined) next.set(spec.id, existing)
+          }
+          writeScaleTypes(immutableMap(next))
+        })
+      },
+
+      setPaneScaleType(paneId: string, scaleType: ScaleType) {
+        const prev = signals.paneScaleTypes.peek()
+        if (prev.get(paneId) === scaleType) return
+        const next = new Map(prev)
+        next.set(paneId, scaleType)
+        writeScaleTypes(immutableMap(next))
+      },
+
+      replacePaneScaleTypes(types: ReadonlyMap<string, ScaleType>) {
+        writeScaleTypes(immutableMap(new Map(types)))
+      },
+
+      removePaneScaleType(paneId: string) {
+        const prev = signals.paneScaleTypes.peek()
+        if (!prev.has(paneId)) return
+        const next = new Map(prev)
+        next.delete(paneId)
+        writeScaleTypes(immutableMap(next))
+      },
+    },
+
+    dispose() {
+      batch(() => {
+        signals.paneRatios.set({})
+        signals.paneSpecs.set([])
+        signals.paneScaleTypes.set(immutableMap(new Map()))
+      })
+    },
+  }
+}
+
+export type PaneStateModule = ReturnType<typeof createPaneState>

package/src/engine/state/settingsState.ts

@@ -0,0 +1,55 @@
+import { batch, createSubState } from '../../foundation/reactivity/signal'
+import {
+  resolveSettings,
+  type ChartSettings,
+} from '../../foundation/config/chartSettings'
+import { deepFreezeSnapshot } from './immutable'
+
+function snapshotSettings(partial?: Partial<ChartSettings>): Readonly<ChartSettings> {
+  return deepFreezeSnapshot(resolveSettings(partial)) as Readonly<ChartSettings>
+}
+
+function settingsEqual(a: Readonly<ChartSettings>, b: Readonly<ChartSettings>): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const key of keys) {
+    if (key === 'colorPresetSettings') {
+      if (JSON.stringify(a.colorPresetSettings) !== JSON.stringify(b.colorPresetSettings)) {
+        return false
+      }
+      continue
+    }
+    if (!Object.is(a[key], b[key])) return false
+  }
+  return true
+}
+
+export function createSettingsState(initial?: Partial<ChartSettings>) {
+  const { signals, readonly } = createSubState({
+    settings: snapshotSettings(initial) as Readonly<ChartSettings>,
+  })
+
+  const write = (next: Readonly<ChartSettings>) => {
+    if (settingsEqual(signals.settings.peek(), next)) return
+    signals.settings.set(next)
+  }
+
+  return {
+    readonly,
+    actions: {
+      replace(partial?: Partial<ChartSettings>) {
+        write(snapshotSettings(partial))
+      },
+      patch(partial: Partial<ChartSettings>) {
+        const merged = { ...signals.settings.peek(), ...partial }
+        write(snapshotSettings(merged))
+      },
+    },
+    dispose() {
+      batch(() => {
+        signals.settings.set(snapshotSettings({}))
+      })
+    },
+  }
+}
+
+export type SettingsStateModule = ReturnType<typeof createSettingsState>

package/src/engine/state/stateKernel.ts

@@ -0,0 +1,79 @@
+/**
+ * StateKernel —— 图表集中式状态的 composition root（组合根）。
+ *
+ * @remarks
+ * 设计契约（由 TypeScript 结构类型系统强制保证）：
+ *
+ * 1. SSOT（单一可信源）—— 每一段状态有且仅有一个 writable signal。
+ *    不存在第二份缓存、shadow field（影子字段）或手动同步路径。
+ *
+ * 2. Computed 推导 —— 派生值存放于 computed() 中。
+ *    源 signal 变化后 computed 自动重求值。
+ *    禁止手写 syncXxx() 或 updateYyy() 等方法。
+ *
+ * 3. 读写边界 —— 外部消费者收到的是 ReadonlySignal（无 .set() 方法）。
+ *    内部变更必须通过仅在 Action 方法内可访问的 WritableSignal。
+ *    TypeScript 编译器会阻止从渲染或 UI 上下文中调用 .set()。
+ *
+ * 4. 仅 Action 变更 —— 所有状态变更流经语义化的 Action 方法
+ *    （scrollTo、zoomTo 等）。Actions 可在单一位置进行 batch（批处理）、
+ *    校验或触发 side-effect（副作用）。
+ *
+ * 子状态模块通过 createSubState() 构建并在此组合。
+ * Kernel 本身不含任何业务逻辑 —— 仅负责 wiring（编排连接）
+ * 子状态并暴露其 readonly 视图和 actions。
+ */
+
+import type { ReadonlySignal } from '../../foundation/reactivity/signal'
+
+/**
+ * 每个子状态模块需提供的基本形状（shape）。
+ *
+ * @typeParam R - readonly signal 的集合
+ * @typeParam A - action 方法的记录类型
+ *
+ * @remarks
+ * readonly 为公开的只读 signal 视图；
+ * actions 为语义化的变更方法（内部调用 .set()）。
+ * 子状态工厂返回该接口，kernel 负责组合它们。
+ */
+export interface SubStateModule<
+  R extends Record<string, ReadonlySignal<unknown>>,
+  A extends Record<string, (...args: any[]) => void>,
+> {
+  readonly: R
+  actions: A
+}
+
+/**
+ * StateKernel 持有子状态模块的引用，并将其 readonly signal + actions
+ * 暴露在单一的 bag（集合）中。
+ *
+ * @remarks
+ * 具体 kernel（如 ChartStateKernel）声明其组合了哪些子状态。
+ * 基类不提供任何运行时行为 —— 它仅用于记录组合模式，
+ * 并为消费者提供一个稳定的 import 入口点。
+ * 子类在其 constructor 中 wiring（编排连接）具体的子状态。
+ */
+export abstract class StateKernel {
+  /**
+   * 所有子状态的 readonly signals，合并为一个 bag。
+   *
+   * @remarks Framework adapter（Vue / React / Angular）直接消费此集合。
+   */
+  abstract readonly signals: Record<string, ReadonlySignal<unknown>>
+
+  /**
+   * 所有子状态的 action 方法，合并为一个 bag。
+   *
+   * @remarks 这些是唯一被许可的状态变更路径。
+   */
+  abstract readonly actions: Record<string, (...args: any[]) => void>
+
+  /**
+   * 清理钩子，释放所有子状态的 effect（副作用）和 subscription（订阅）。
+   *
+   * @remarks 在图表销毁时调用。
+   */
+  abstract dispose(): void
+}

package/src/engine/state/subPaneState.ts

@@ -0,0 +1,92 @@
+import { batch, createSubState } from '../../foundation/reactivity/signal'
+import { deepFreezeSnapshot } from './immutable'
+
+export interface SubPaneSpec {
+  readonly paneId: string
+  readonly indicatorId: string
+  readonly params: Readonly<Record<string, unknown>>
+}
+
+function snapshotEntry(entry: {
+  paneId: string
+  indicatorId: string
+  params: Readonly<Record<string, unknown>>
+}): SubPaneSpec {
+  return Object.freeze({
+    paneId: entry.paneId,
+    indicatorId: entry.indicatorId,
+    params: deepFreezeSnapshot(entry.params),
+  })
+}
+
+function entriesEqual(left: SubPaneSpec, right: SubPaneSpec): boolean {
+  if (left.paneId !== right.paneId || left.indicatorId !== right.indicatorId) return false
+  const leftKeys = Object.keys(left.params)
+  const rightKeys = Object.keys(right.params)
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => Object.is(left.params[key], right.params[key]))
+  )
+}
+
+function snapshotEntries(entries: ReadonlyArray<SubPaneSpec>): ReadonlyArray<SubPaneSpec> {
+  return Object.freeze(entries.map(snapshotEntry))
+}
+
+export function createSubPaneState() {
+  const { signals, readonly } = createSubState({
+    entries: Object.freeze([]) as ReadonlyArray<SubPaneSpec>,
+  })
+
+  const write = (entries: ReadonlyArray<SubPaneSpec>) => {
+    signals.entries.set(snapshotEntries(entries))
+  }
+
+  return {
+    readonly,
+    actions: {
+      upsert(entry: SubPaneSpec) {
+        const prev = signals.entries.peek()
+        const index = prev.findIndex((item) => item.paneId === entry.paneId)
+        const nextEntry = snapshotEntry(entry)
+        if (index >= 0 && entriesEqual(prev[index]!, nextEntry)) return
+        if (index < 0) {
+          write([...prev, nextEntry])
+          return
+        }
+        const next = [...prev]
+        next[index] = nextEntry
+        write(next)
+      },
+      remove(paneId: string) {
+        const prev = signals.entries.peek()
+        if (!prev.some((entry) => entry.paneId === paneId)) return
+        write(prev.filter((entry) => entry.paneId !== paneId))
+      },
+      setParams(paneId: string, params: Readonly<Record<string, unknown>>) {
+        const prev = signals.entries.peek()
+        const entry = prev.find((item) => item.paneId === paneId)
+        if (!entry) return
+        write(prev.map((item) => (item.paneId === paneId ? { ...entry, params } : item)))
+      },
+      replace(entry: SubPaneSpec) {
+        const prev = signals.entries.peek()
+        if (!prev.some((item) => item.paneId === entry.paneId)) return
+        write(prev.map((item) => (item.paneId === entry.paneId ? entry : item)))
+      },
+      replaceAll(entries: ReadonlyArray<SubPaneSpec>) {
+        write(entries)
+      },
+      clear() {
+        if (signals.entries.peek().length > 0) write([])
+      },
+    },
+    dispose() {
+      batch(() => {
+        signals.entries.set(Object.freeze([]))
+      })
+    },
+  }
+}
+
+export type SubPaneStateModule = ReturnType<typeof createSubPaneState>

package/src/engine/state/themeState.ts

@@ -0,0 +1,23 @@
+import { createSubState } from '../../foundation/reactivity/signal'
+
+export function createThemeState() {
+  const { signals, readonly } = createSubState({
+    theme: 'light' as 'light' | 'dark',
+  })
+
+  return {
+    readonly,
+
+    actions: {
+      setTheme(theme: 'light' | 'dark') {
+        signals.theme.set(theme)
+      },
+    },
+
+    dispose() {
+      signals.theme.set('light')
+    },
+  }
+}
+
+export type ThemeStateModule = ReturnType<typeof createThemeState>