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

package/src/foundation/reactivity/signal.ts

@@ -0,0 +1,361 @@
+/**
+ * 轻量 push-based 响应式原语，零外部依赖。
+ *
+ * @remarks
+ * 设计约束:
+ *
+ * 1. 非 batch 模式下 set 同步通知（无微任务调度）
+ * 2. batch() 将所有通知推迟到最外层 batch 退出时
+ * 3. 无 Proxy / 无深度追踪 —— 仅顶层读/写
+ * 4. 相等性通过 Object.is 短路
+ * 5. subscribe 返回取消订阅函数；可安全用于 React useSyncExternalStore、
+ *    Vue effect、Angular toSignal
+ * 6. effect 在其内部读取的任何 signal 重新发出值时自动重跑
+ */
+
+/**
+ * 只读 signal —— 所有派生状态的公开面。
+ *
+ * @remarks
+ * 消费者（renderers、UI bindings、framework adapters）收到的是
+ * ReadonlySignal，可以读取/订阅但不能写入。
+ * TypeScript 编译器阻止在该类型上调用 .set()，以此强制 StateKernel
+ * 的不变性：状态变更只能通过 Actions 流转。
+ *
+ * WritableSignal 通过 set() 扩展此形状，因此接受 ReadonlySignal
+ * 的函数也可以传入 writable signal，但反过来被结构类型系统禁止。
+ */
+export type ReadonlySignal<T> = {
+  /**
+   * 读取当前值；在 effect 内部调用时会被追踪
+   */
+  (): T
+  /**
+   * 读取当前值，不触发追踪
+   */
+  peek: () => T
+  /**
+   * 订阅变更通知；返回取消订阅函数
+   */
+  subscribe: (listener: () => void) => () => void
+}
+
+/**
+ * 可写 signal —— 仅限 StateKernel 子状态内部使用。
+ *
+ * @remarks
+ * .set() 方法是唯一的变更入口。将字段声明为 private 并对外暴露
+ * ReadonlySignal，即可在生产方（Actions）与消费方（renderers/UI）
+ * 之间建立编译时边界。
+ */
+export type WritableSignal<T> = ReadonlySignal<T> & {
+  /**
+   * 写入新值；当与当前值 Object.is 不等时通知订阅者
+   */
+  set: (next: T) => void
+}
+
+/**
+ * 为向后兼容保留的别名。
+ *
+ * @remarks Signal 等价于 WritableSignal，即 createSignal 返回的完整读/写形状。
+ * 已有的 import 继续可用。
+ */
+export type Signal<T> = WritableSignal<T>
+
+/**
+ * 为向后兼容保留的别名。
+ *
+ * @remarks Computed 等价于 ReadonlySignal，即 computed() 返回的只读形状。
+ */
+export type Computed<T> = ReadonlySignal<T>
+
+/**
+ * 可写 ref：kernel 内部对一段状态的句柄。
+ *
+ * @remarks 与 WritableSignal 完全等同；命名上镜像 Vue 的 shallowRef / writableRef
+ * 惯例，使子状态定义中的迁移读起来更自然。
+ */
+export type WritableRef<T> = WritableSignal<T>
+
+/**
+ * writable ref 的只读面 —— 对外暴露给消费者的类型。
+ *
+ * @remarks 形状与 ReadonlySignal 相同。
+ */
+export type ReadonlyRef<T> = ReadonlySignal<T>
+
+type Tracker = {
+  deps: Set<Set<() => void>>
+  run: () => void
+}
+
+let activeTracker: Tracker | null = null
+
+let batchDepth = 0
+const pendingBatch = new Set<() => void>()
+
+/**
+ * 创建一个 writable signal（别名：writableRef）。
+ *
+ * @param initial - 初始值
+ * @returns WritableSignal，内部可变更，外部可通过赋值或返回类型注解降级为 ReadonlySignal
+ */
+export function createSignal<T>(initial: T): WritableSignal<T> {
+  let value = initial
+  const subscribers = new Set<() => void>()
+
+  const read = (): T => {
+    if (activeTracker !== null) {
+      subscribers.add(activeTracker.run)
+      activeTracker.deps.add(subscribers)
+    }
+    return value
+  }
+
+  const peek = (): T => value
+
+  const set = (next: T): void => {
+    if (Object.is(value, next)) return
+    value = next
+    if (batchDepth > 0) {
+      for (const listener of subscribers) pendingBatch.add(listener)
+    } else {
+      // copy to allow listener self-unsubscribe during notify
+      for (const listener of [...subscribers]) listener()
+    }
+  }
+
+  const subscribe = (listener: () => void): (() => void) => {
+    subscribers.add(listener)
+    return () => {
+      subscribers.delete(listener)
+    }
+  }
+
+  return Object.assign(read, { peek, set, subscribe }) as WritableSignal<T>
+}
+
+/**
+ * createSignal 的别名，镜像 Vue 的 writableRef 惯例。
+ *
+ * @remarks 在 kernel 子状态定义中使用，如 signals.scrollLeft = writableRef(0)。
+ */
+export const writableRef = createSignal
+
+/**
+ * 创建一个自动追踪依赖的 effect。
+ *
+ * @param fn - 副作用函数，其中读取的 signal 被自动追踪
+ * @returns 清理函数，调用后取消 effect 及其所有订阅
+ */
+export function effect(fn: () => void): () => void {
+  const tracker: Tracker = {
+    deps: new Set(),
+    run: () => {
+      // tear down previous subscriptions before re-tracking
+      for (const dep of tracker.deps) dep.delete(tracker.run)
+      tracker.deps.clear()
+      const prev = activeTracker
+      activeTracker = tracker
+      try {
+        fn()
+      } finally {
+        activeTracker = prev
+      }
+    },
+  }
+  tracker.run()
+  return () => {
+    for (const dep of tracker.deps) dep.delete(tracker.run)
+    tracker.deps.clear()
+  }
+}
+
+/**
+ * 创建一个派生（只读）signal。
+ *
+ * @remarks
+ * computed(fn) 立即执行 fn 一次，之后每当 fn 中读取的 signal 变更时自动重跑。
+ * 返回的 ReadonlySignal 没有 .set() 方法，调用方无法写回，以此强制单向数据流：
+ * source signals 到 computed 到 consumers。
+ *
+ * @param fn - 派生函数
+ * @returns 只读的派生 signal
+ */
+export function computed<T>(fn: () => T): ReadonlySignal<T> {
+  const inner = createSignal<T>(undefined as unknown as T)
+  let initialized = false
+  effect(() => {
+    const next = fn()
+    if (!initialized) {
+      initialized = true
+      // bypass equality check on first run
+      ;(inner as unknown as { set: (v: T) => void }).set(next)
+      return
+    }
+    inner.set(next)
+  })
+  const read = (): T => inner()
+  return Object.assign(read, { peek: inner.peek, subscribe: inner.subscribe }) as ReadonlySignal<T>
+}
+
+/**
+ * 将多个 signal 写入合并为一次通知周期。
+ *
+ * @remarks
+ * 在 batch(fn) 内部，所有 signal.set() 调用将订阅者入队而非立即通知。
+ * 最外层 batch 退出时，每个累积的订阅者恰好触发一次（已去重）。
+ * 支持嵌套 —— 仅最外层 batch 触发 flush。
+ *
+ * @example
+ * batch(() => {
+ *   signalA.set(1)
+ *   signalB.set('x')
+ *   // subscribers haven't fired yet
+ * })
+ * // all subscribers fire once, deduped
+ *
+ * @param fn - 批量写入函数
+ * @returns fn 的返回值
+ */
+export function batch<T>(fn: () => T): T {
+  batchDepth++
+  try {
+    return fn()
+  } finally {
+    batchDepth--
+    if (batchDepth === 0 && pendingBatch.size > 0) {
+      const toNotify = [...pendingBatch]
+      pendingBatch.clear()
+      for (const listener of toNotify) listener()
+    }
+  }
+}
+
+/**
+ * 从初始状态对象创建一组相关 signal。
+ *
+ * @typeParam T - 状态对象的形状
+ * @param initial - 初始状态
+ * @returns 包含 signals、set、snapshot 的结构，消除大量 signal 类中
+ * 重复的 private xxxSignal + get xxx() 样板代码。
+ *
+ * @remarks
+ * 使用示例：
+ *
+ * const state = createStateStore({ count: 0, name: '' })
+ * // 读: state.signals.count()
+ * // 写: state.signals.count.set(5)
+ * // 批量: state.set.count(5); state.set.name('foo')
+ * // 快照: state.snapshot() // { count: 5, name: 'foo' }
+ */
+export function createStateStore<T extends Record<string, unknown>>(initial: T) {
+  const signals = {} as { [K in keyof T]: WritableSignal<T[K]> }
+  const set = {} as { [K in keyof T]: (v: T[K]) => void }
+  for (const key of Object.keys(initial) as (keyof T)[]) {
+    const sig = createSignal<T[typeof key]>(initial[key])
+    signals[key] = sig
+    set[key] = (v: T[typeof key]) => sig.set(v)
+  }
+  return {
+    signals,
+    set,
+    snapshot: () => {
+      const s: Record<string, unknown> = {}
+      for (const k of Object.keys(initial) as (keyof T)[]) s[k as string] = signals[k].peek()
+      return s as T
+    },
+  }
+}
+
+/**
+ * ReadonlySignal 包装器 —— 抹除 .set 方法。
+ *
+ * @remarks 对 createSignal 返回值调用 Object.assign 始终保留了 .set 引用
+ * （即使类型系统已将其遮蔽），运行时通过 `in` 操作符或 `.set` 访问仍然可见。
+ * 此函数显式构造一个不包含 .set 的新对象，保证运行时与类型签名保持一致。
+ */
+function asReadonlySignal<T>(sig: WritableSignal<T>): ReadonlySignal<T> {
+  const read = (() => sig()) as ReadonlySignal<T>
+  return Object.assign(read, {
+    peek: sig.peek,
+    subscribe: sig.subscribe,
+  })
+}
+
+/**
+ * StateKernel 子状态工厂。
+ *
+ * @typeParam T - 可写状态字段的类型
+ * @typeParam C - 派生计算字段的类型
+ * @param initial - 初始状态值
+ * @param computedFns - 可选的派生计算函数表，每个函数接收源信号的只读视图
+ * @returns 包含 signals（可写句柄）、readonly（只读视图）、snapshot（快照）的结构
+ *
+ * @remarks
+ * 从 initial 创建一组 writable signals，然后暴露:
+ *  - signals   — 私有可写句柄（有 .set()）
+ *  - readonly  — 同一组 signal，类型提升为 ReadonlySignal（无 .set()）
+ *  - computed  — 通过 computedFns 选项注册的派生 signal
+ *
+ * 子状态模块调用此工厂，私有保存 signals，向 kernel 返回 readonly + actions。
+ * WritableSignal 与 ReadonlySignal 之间的 TypeScript 边界阻止外部消费者写入，
+ * 同时保持内部变更的便利性。
+ *
+ * @example
+ * function createViewportState() {
+ *   const { signals, readonly } = createSubState(
+ *     { scrollLeft: 0, viewWidth: 0 },
+ *     {
+ *       scrollLeftLogical: (s) => s.scrollLeft() - s.viewWidth(),
+ *     },
+ *   )
+ *   return {
+ *     readonly,
+ *     actions: {
+ *       scrollTo: (v: number) => signals.scrollLeft.set(Math.max(0, v)),
+ *     },
+ *   }
+ * }
+ */
+export function createSubState<
+  T extends Record<string, unknown>,
+  C extends Record<string, unknown>,
+>(
+  initial: T,
+  computedFns?: {
+    [K in keyof C]: (state: { [K2 in keyof T]: ReadonlySignal<T[K2]> }) => C[K]
+  },
+) {
+  const signals = {} as { [K in keyof T]: WritableSignal<T[K]> }
+  const readonly = {} as { [K in keyof T]: ReadonlySignal<T[K]> }
+  for (const key of Object.keys(initial) as (keyof T)[]) {
+    const sig = createSignal<T[typeof key]>(initial[key])
+    signals[key] = sig
+    readonly[key] = asReadonlySignal(sig)
+  }
+
+  const computedReadonly = {} as Record<string, ReadonlySignal<unknown>>
+  if (computedFns) {
+    for (const key of Object.keys(computedFns) as string[]) {
+      const fn = (computedFns as Record<string, (state: typeof readonly) => unknown>)[key]!
+      computedReadonly[key] = computed(() => fn(readonly))
+    }
+  }
+
+  return {
+    /** 私有可写句柄 —— 仅传递给 actions */
+    signals,
+    /** 只读视图 —— 可安全暴露给外部消费者 */
+    readonly: { ...readonly, ...computedReadonly } as {
+      [K in keyof T]: ReadonlySignal<T[K]>
+    } & { [K in keyof C]: ReadonlySignal<C[K]> },
+    /** 只读快照（peek 所有 source signals） */
+    snapshot: () => {
+      const s: Record<string, unknown> = {}
+      for (const k of Object.keys(initial) as (keyof T)[]) s[k as string] = signals[k].peek()
+      return s as T
+    },
+  }
+}

package/src/foundation/tokens/theme-china.ts

@@ -0,0 +1,132 @@
+/**
+ * Asia-market (Chinese) colour convention helper.
+ *
+ * Asian markets traditionally use **red for "up"** (bull) and **green
+ * for "down"** (bear) — the reverse of the Western convention.
+ *
+ * {@link withAsiaMarketColors} takes any {@link Theme} and returns a new
+ * Theme with all bull/bear colour pairs swapped, so the caller only needs
+ * a single boolean (`isAsiaMarket`) to switch conventions at runtime.
+ *
+ * {@link resolveThemeColors} is a convenience for renderers that currently
+ * hard-code `theme === 'dark' ? darkTheme.colors : lightTheme.colors`.
+ *
+ * Usage:
+ * ```ts
+ * import { resolveThemeColors } from '.'
+ *
+ * const colors = resolveThemeColors(context.theme, context.isAsiaMarket)
+ * ```
+ */
+
+import { applyColorPresetOverrides, type ColorPresetSettings } from './colorPresetSettings'
+import { darkTheme } from './theme-dark'
+import { lightTheme } from './theme-light'
+import type { ColorTokens, Theme } from './types'
+
+/**
+ * Swap all bull/bear colour pairs in a Theme so that "up" (bull) uses
+ * the formerly "down" (bear) colour and vice versa.
+ *
+ * @param theme — the base Theme (Western convention)
+ * @returns a **new** Theme object; the original is not mutated.
+ */
+export function withAsiaMarketColors(theme: Theme): Theme {
+  return {
+    ...theme,
+    colors: {
+      ...theme.colors,
+
+      // ── Candle / OHLC ──
+      candleUpBody: theme.colors.candleDownBody,
+      candleDownBody: theme.colors.candleUpBody,
+      candleUpBorder: theme.colors.candleDownBorder,
+      candleDownBorder: theme.colors.candleUpBorder,
+      candleUpWick: theme.colors.candleDownWick,
+      candleDownWick: theme.colors.candleUpWick,
+
+      // ── Time-share area fill ──
+      timeShareAreaUp: theme.colors.timeShareAreaDown,
+      timeShareAreaDown: theme.colors.timeShareAreaUp,
+
+      // ── Volume bars ──
+      volumeUp: theme.colors.volumeDown,
+      volumeDown: theme.colors.volumeUp,
+
+      // ── Footprint (ask = buy = bull, bid = sell = bear) ──
+      footprintAsk: theme.colors.footprintBid,
+      footprintBid: theme.colors.footprintAsk,
+
+      // ── Nested: price accents ──
+      price: {
+        ...theme.colors.price,
+      },
+
+      // ── Nested: MACD histogram bars ──
+      macd: {
+        ...theme.colors.macd,
+        barUp: theme.colors.macd.barDown,
+        barDown: theme.colors.macd.barUp,
+        barUpLight: theme.colors.macd.barDownLight,
+        barDownLight: theme.colors.macd.barUpLight,
+      },
+
+      // ── Nested: SMC structure (HH/HL = bull, LH/LL = bear) ──
+      structure: {
+        ...theme.colors.structure,
+        hh: theme.colors.structure.ll,
+        ll: theme.colors.structure.hh,
+        hl: theme.colors.structure.lh,
+        lh: theme.colors.structure.hl,
+      },
+
+      // ── Nested: Zones / FVG / Order Block ──
+      zones: {
+        ...theme.colors.zones,
+        fvgBullFill: theme.colors.zones.fvgBearFill,
+        fvgBearFill: theme.colors.zones.fvgBullFill,
+        fvgBullBorder: theme.colors.zones.fvgBearBorder,
+        fvgBearBorder: theme.colors.zones.fvgBullBorder,
+        obBullFill: theme.colors.zones.obBearFill,
+        obBearFill: theme.colors.zones.obBullFill,
+      },
+
+      // ── Nested: CCI overbought (bull) / oversold (bear) ──
+      cci: {
+        ...theme.colors.cci,
+        overbought: theme.colors.cci.oversold,
+        oversold: theme.colors.cci.overbought,
+      },
+
+      // ── Nested: WMSR overbought / oversold ──
+      wmsr: {
+        ...theme.colors.wmsr,
+        overbought: theme.colors.wmsr.oversold,
+        oversold: theme.colors.wmsr.overbought,
+      },
+    },
+  }
+}
+
+/**
+ * Resolve a theme name + optional Asia-market flag into concrete
+ * {@link ColorTokens}.
+ *
+ * Renderers replace this pattern:
+ * ```ts
+ * const colors = theme === 'dark' ? darkTheme.colors : lightTheme.colors
+ * ```
+ * with:
+ * ```ts
+ * const colors = resolveThemeColors(theme, isAsiaMarket)
+ * ```
+ */
+export function resolveThemeColors(
+  themeName: 'light' | 'dark',
+  isAsiaMarket?: boolean,
+  colorPresetSettings?: ColorPresetSettings,
+): ColorTokens {
+  const base = themeName === 'dark' ? darkTheme : lightTheme
+  const active = isAsiaMarket ? withAsiaMarketColors(base) : base
+  return applyColorPresetOverrides(active.colors, themeName, colorPresetSettings)
+}

package/src/foundation/tokens/themeToCssVars.ts

@@ -0,0 +1,139 @@
+import { KLineChartError } from '../../errors'
+
+/**
+ * Theme → CSS custom-property emitter.
+ *
+ * Bridges the typed tokens in `theme-light.ts` / `theme-dark.ts` to the
+ * actual stylesheet, so any framework can apply a theme by inserting a
+ * `:root { ... }` block or attaching a `style="..."` attribute.
+ *
+ * Naming convention (kebab-case, dot-paths flattened with `-`):
+ *
+ *   Theme key                                CSS variable
+ *   ───────────────────────────────────────  ────────────────────────────
+ *   colors.background                        `--klc-color-background`
+ *   colors.candleUpBody                      `--klc-color-candle-up-body`
+ *   colors.palette.i1                        `--klc-color-palette-i1`
+ *   spacing.md                               `--klc-spacing-md`
+ *   typography.fontFamily                    `--klc-typography-font-family`
+ *   typography.fontWeightRegular             `--klc-typography-font-weight-regular`
+ *   motion.durationFast                      `--klc-motion-duration-fast`
+ *
+ * Numeric tokens (font weights, line heights) emit as strings — CSS doesn't
+ * care, and consumers consume them through `var(...)` so the type tag is
+ * lost in the round-trip anyway.
+ *
+ * Prefix is configurable. Default `--klc-` (KLineChart Quant) is short
+ * enough to type and unique enough to coexist with other token systems
+ * (Tailwind, MUI, Radix) on the same page.
+ */
+
+import type { Theme } from './types'
+
+export interface ThemeToCssVarsOptions {
+  /**
+   * CSS custom-property prefix. Default `'--klc-'`. Must start with `--`.
+   * Including the trailing dash is recommended (kebab-case continues
+   * cleanly from there).
+   */
+  readonly prefix?: string
+}
+
+const DEFAULT_PREFIX = '--klc-'
+
+/**
+ * camelCase → kebab-case.
+ *
+ *   'candleUpBody'        → 'candle-up-body'
+ *   'fontWeightRegular'   → 'font-weight-regular'
+ *   'i1'                  → 'i1'   (already kebab-safe)
+ */
+export function camelToKebab(s: string): string {
+  return s.replace(/[A-Z]/g, (m, i) => (i === 0 ? m.toLowerCase() : '-' + m.toLowerCase()))
+}
+
+function flattenColors(colors: Theme['colors'], prefix: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(colors)) {
+    if (typeof v === 'object' && v !== null) {
+      const ns = camelToKebab(k)
+      for (const [nk, nv] of Object.entries(v as Record<string, string>)) {
+        out[`${prefix}color-${ns}-${camelToKebab(nk)}`] = nv
+      }
+    } else {
+      out[`${prefix}color-${camelToKebab(k)}`] = v as string
+    }
+  }
+  return out
+}
+
+function flattenFamily(
+  family: Record<string, string | number>,
+  prefix: string,
+  namespace: string,
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(family)) {
+    out[`${prefix}${namespace}-${camelToKebab(k)}`] = String(v)
+  }
+  return out
+}
+
+/**
+ * Emit a `{ [cssVarName]: value }` map for the given theme.
+ *
+ * Hand the result to:
+ *
+ *   - React: `<div style={vars as React.CSSProperties}>...`
+ *   - Vue:   `:style="vars"`
+ *   - Angular: `[ngStyle]="vars"`
+ *   - Vanilla: `Object.assign(el.style, vars)` or emit
+ *              `':root { ... }'` directly via {@link toCssDeclarationBlock}.
+ *
+ * The shape is stable: the same theme produces the same map across calls,
+ * and `mergeTheme(base, override)` produces a superset emit (keys are the
+ * same; values may differ).
+ */
+export function themeToCssVars(theme: Theme, opts?: ThemeToCssVarsOptions): Record<string, string> {
+  const prefix = opts?.prefix ?? DEFAULT_PREFIX
+  if (!prefix.startsWith('--')) {
+    // Misuse caught here is much friendlier than the silent no-op CSS
+    // would give downstream.
+    throw new KLineChartError(
+      'INVALID_PARAM',
+      `themeToCssVars: prefix must start with '--', got ${JSON.stringify(prefix)}`,
+    )
+  }
+  return {
+    ...flattenColors(theme.colors, prefix),
+    ...flattenFamily(theme.spacing as unknown as Record<string, string>, prefix, 'spacing'),
+    ...flattenFamily(
+      theme.typography as unknown as Record<string, string | number>,
+      prefix,
+      'typography',
+    ),
+    ...flattenFamily(theme.motion as unknown as Record<string, string>, prefix, 'motion'),
+  }
+}
+
+/**
+ * Render the emitted map as a `:root { ... }` CSS declaration block.
+ * Useful for SSR scenarios where you want to inject a `<style>` element
+ * server-side so the first paint already carries the theme.
+ *
+ *   const css = toCssDeclarationBlock(themeToCssVars(darkTheme))
+ *   // → ":root {\n  --klc-color-background: #0E1116;\n  ...\n}"
+ *
+ * The selector defaults to `:root` but can be overridden — common
+ * alternatives are `[data-theme="dark"]` for runtime theme switching
+ * or `.klc-theme-dark` for scoped overrides.
+ */
+export function toCssDeclarationBlock(
+  vars: Record<string, string>,
+  selector: string = ':root',
+): string {
+  const decls = Object.entries(vars)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join('\n')
+  return `${selector} {\n${decls}\n}`
+}

package/src/foundation/types/kLine.ts

@@ -0,0 +1,16 @@
+import type { KLineData } from './price'
+
+export type kLineTrend = 'up' | 'down' | 'flat'
+
+export function getKLineTrend(KLineData: KLineData, preClose?: number): kLineTrend {
+  if (KLineData.close > KLineData.open) return 'up'
+  if (KLineData.close < KLineData.open) return 'down'
+
+  // 一字板 / doji: close === open → use preClose to determine direction
+  if (preClose !== undefined) {
+    if (KLineData.close === KLineData.open && KLineData.open > preClose) return 'up'
+    if (KLineData.close === KLineData.open && KLineData.open < preClose) return 'down'
+  }
+
+  return 'flat'
+}