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

package/src/foundation/reactivity/__tests__/frameTransaction.test.ts

@@ -0,0 +1,306 @@
+import { describe, it, expect, vi } from 'vitest'
+
+import { createFrameTransaction } from '../frameTransaction'
+
+type Input = { x: number; y: number }
+type Snapshot = { generation: number; x: number; y: number; sum: number }
+
+describe('createFrameTransaction', () => {
+  it('coalesces many writeInput into one published snapshot on flush', () => {
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    const listener = vi.fn()
+    ft.published$.subscribe(listener)
+
+    ft.writeInput({ x: 1 })
+    ft.writeInput({ x: 2, y: 3 })
+    ft.writeInput({ x: 10 })
+    expect(listener).not.toHaveBeenCalled()
+
+    const snap = ft.flush()
+    expect(snap).toEqual({ generation: 1, x: 10, y: 3, sum: 13 })
+    expect(ft.published$.peek()).toEqual(snap)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('bumps generation only on successful flush', () => {
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    expect(ft.generation).toBe(0)
+    ft.writeInput({ x: 1 })
+    ft.flush()
+    expect(ft.generation).toBe(1)
+    ft.writeInput({ y: 2 })
+    ft.flush()
+    expect(ft.generation).toBe(2)
+  })
+
+  it('does not publish when derive throws; generation stays', () => {
+    let fail = false
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => {
+        if (fail) throw new Error('derive-fail')
+        return { generation, x: input.x, y: input.y, sum: input.x + input.y }
+      },
+    })
+    fail = true
+    ft.writeInput({ x: 5 })
+    expect(() => ft.flush()).toThrow('derive-fail')
+    expect(ft.generation).toBe(0)
+    expect(ft.published$.peek().generation).toBe(0)
+
+    fail = false
+    // 失败帧应保留 pending，无需再次 write 也能重试
+    const snap = ft.flush()
+    expect(snap.generation).toBe(1)
+    expect(snap.x).toBe(5)
+  })
+
+  it('routes writeInput during render into next generation only', () => {
+    const seen: number[] = []
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+      render: (snapshot) => {
+        seen.push(snapshot.x)
+        // re-entrant high-frequency write during paint
+        ft.writeInput({ x: 99 })
+      },
+    })
+    ft.writeInput({ x: 1 })
+    const first = ft.flush()
+    expect(first.x).toBe(1)
+    expect(seen).toEqual([1])
+    // re-entrant write not published yet
+    expect(ft.published$.peek().x).toBe(1)
+    const second = ft.flush()
+    expect(second.x).toBe(99)
+    expect(second.generation).toBe(2)
+  })
+
+  it('flush with no pending input returns published snapshot without notify', () => {
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 1, y: 2 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    // seed first publish
+    ft.writeInput({ x: 1, y: 2 })
+    ft.flush()
+    const listener = vi.fn()
+    ft.published$.subscribe(listener)
+    const again = ft.flush()
+    expect(again.generation).toBe(1)
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('select publishes only when selected value changes by equality', () => {
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    const selected = ft.select((s) => s.x)
+    const listener = vi.fn()
+    selected.subscribe(listener)
+
+    ft.writeInput({ x: 1, y: 0 })
+    ft.flush()
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(selected.peek()).toBe(1)
+
+    ft.writeInput({ x: 1, y: 9 })
+    ft.flush()
+    // x unchanged
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    ft.writeInput({ x: 2 })
+    ft.flush()
+    expect(listener).toHaveBeenCalledTimes(2)
+    expect(selected.peek()).toBe(2)
+  })
+
+  it('scheduleFlush coalesces to one raf-style runner', () => {
+    const runners: Array<() => void> = []
+    const schedule = (run: () => void) => {
+      runners.push(run)
+      return 1
+    }
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+      schedule,
+    })
+    ft.writeInput({ x: 1 })
+    ft.scheduleFlush()
+    ft.writeInput({ x: 2 })
+    ft.scheduleFlush()
+    expect(runners).toHaveLength(1)
+    runners[0]!()
+    expect(ft.published$.peek().x).toBe(2)
+    expect(ft.generation).toBe(1)
+  })
+
+  it('advances generation before notifying published subscribers', () => {
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    let seenGeneration = -1
+    ft.published$.subscribe(() => {
+      seenGeneration = ft.generation
+    })
+    ft.writeInput({ x: 1 })
+    ft.flush()
+    expect(seenGeneration).toBe(1)
+    expect(ft.published$.peek().generation).toBe(1)
+  })
+
+  it('defers re-entrant flush during publish to next generation only', () => {
+    const order: number[] = []
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    ft.published$.subscribe(() => {
+      const snap = ft.published$.peek()
+      order.push(snap.x)
+      if (snap.x === 1) {
+        ft.writeInput({ x: 2 })
+        // re-entrant flush must not publish x=2 before remaining listeners of gen1
+        ft.flush()
+      }
+    })
+    const late = vi.fn()
+    ft.published$.subscribe(late)
+
+    ft.writeInput({ x: 1 })
+    ft.flush()
+    expect(order).toEqual([1])
+    expect(late).toHaveBeenCalledTimes(1)
+    expect(ft.published$.peek().x).toBe(1)
+    expect(ft.generation).toBe(1)
+
+    // deferred work runs on next idle flush
+    const second = ft.flush()
+    expect(second.x).toBe(2)
+    expect(second.generation).toBe(2)
+  })
+
+  it('freezes generation-0 published snapshot root', () => {
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+    })
+    const snap = ft.published$.peek() as Snapshot & { x: number }
+    expect(Object.isFrozen(snap)).toBe(true)
+    expect(() => {
+      ;(snap as { x: number }).x = 99
+    }).toThrow()
+  })
+
+  it('reschedules after scheduled flush throws', () => {
+    const runners: Array<() => void> = []
+    let failNextRealFrame = false
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => {
+        // generation 0 是构造占位，不可失败
+        if (generation > 0 && failNextRealFrame) {
+          failNextRealFrame = false
+          throw new Error('boom')
+        }
+        return {
+          generation,
+          x: input.x,
+          y: input.y,
+          sum: input.x + input.y,
+        }
+      },
+      schedule: (run) => {
+        runners.push(run)
+        return 1
+      },
+    })
+    failNextRealFrame = true
+    ft.writeInput({ x: 3 })
+    ft.scheduleFlush()
+    expect(runners).toHaveLength(1)
+    expect(() => runners[0]!()).toThrow('boom')
+    // dirty retained → another schedule registered
+    expect(runners.length).toBeGreaterThanOrEqual(2)
+    runners[runners.length - 1]!()
+    expect(ft.published$.peek().x).toBe(3)
+    expect(ft.generation).toBe(1)
+  })
+
+  it('resets scheduleQueued when schedule() throws', () => {
+    let shouldThrow = true
+    const ft = createFrameTransaction<Input, Snapshot>({
+      initialInput: { x: 0, y: 0 },
+      derive: (input, generation) => ({
+        generation,
+        x: input.x,
+        y: input.y,
+        sum: input.x + input.y,
+      }),
+      schedule: () => {
+        if (shouldThrow) throw new Error('no-raf')
+        return 1
+      },
+    })
+    ft.writeInput({ x: 1 })
+    expect(() => ft.scheduleFlush()).toThrow('no-raf')
+    shouldThrow = false
+    // must not be permanently stuck
+    expect(() => ft.scheduleFlush()).not.toThrow()
+  })
+})

package/src/foundation/reactivity/frameTransaction.ts

@@ -0,0 +1,239 @@
+/**
+ * 帧事务：高频输入集中写入，每帧最多发布一次不可变快照。
+ *
+ * @remarks
+ * 解决两类问题：
+ * 1. pointermove 等事件若直接写普通 Signal，会按事件频率广播订阅者。
+ * 2. latest 与 published 双视图会让不同模块读到不同代际状态。
+ *
+ * 本原语只暴露 pending 写入与 published 快照，不暴露公开 latest。
+ * 一帧固定走 capture → derive → seal → render → publish → complete。
+ * render 或 publish 期间的 writeInput 一律进入下一代 pending。
+ * 非 idle 时调用 flush 不会嵌套发布，仅保留 dirty 供外层完成后调度。
+ */
+
+import { createSignal, type ReadonlySignal } from './signal'
+
+/** 帧事务所处阶段；用于隔离重入写入 */
+export type FramePhase = 'idle' | 'capturing' | 'deriving' | 'sealing' | 'rendering' | 'publishing'
+
+/**
+ * 浅合并输入补丁。
+ * 仅顶层键覆盖，不递归合并嵌套对象。
+ */
+function mergeInput<T extends Record<string, unknown>>(base: T, patch: Partial<T>): T {
+  return { ...base, ...patch }
+}
+
+/** 浅冻结快照根对象；大数组字段由 derive 侧结构共享，禁止深拷贝 */
+function sealSnapshotRoot<T>(snapshot: T): T {
+  if (typeof snapshot === 'object' && snapshot !== null) {
+    Object.freeze(snapshot)
+  }
+  return snapshot
+}
+
+export interface FrameTransactionOptions<TInput extends Record<string, unknown>, TSnapshot> {
+  /** 初始 pending 输入；也会用于生成 generation 0 的占位 published */
+  initialInput: TInput
+  /**
+   * 由封存输入纯推导快照。
+   * 不得写外部 kernel / DOM；失败则本帧不发布。
+   */
+  derive: (input: Readonly<TInput>, generation: number) => TSnapshot
+  /**
+   * 可选：使用本帧快照绘制或执行副作用。
+   * 此阶段 writeInput 进入下一代，不得假定能改当前快照。
+   */
+  render?: (snapshot: Readonly<TSnapshot>) => void
+  /**
+   * 调度 flush 的宿主。默认 requestAnimationFrame；测试可注入同步队列。
+   * 返回值可忽略（兼容 rAF handle）。
+   */
+  schedule?: (run: () => void) => unknown
+}
+
+export interface FrameTransaction<TInput extends Record<string, unknown>, TSnapshot> {
+  /** 最近一次成功发布的快照（只读 Signal） */
+  readonly published$: ReadonlySignal<Readonly<TSnapshot>>
+  /** 已成功发布的帧代际；失败 flush 不增加 */
+  readonly generation: number
+  /** 当前阶段，调试与不变量检查用 */
+  readonly phase: FramePhase
+  /**
+   * 合并高频输入。idle 写入当前 pending；非 idle 写入 nextPending。
+   * 不触发订阅通知。
+   */
+  writeInput(patch: Partial<TInput>): void
+  /**
+   * 同步执行一帧事务。无 pending 时返回当前 published，且不通知。
+   * 非 idle 调用不会嵌套发布，返回当前 published。
+   * @returns 本帧使用的快照（成功时等于 published$.peek()）
+   */
+  flush(): Readonly<TSnapshot>
+  /**
+   * 请求在宿主调度器上合并 flush；多次调用在同一 pending 调度内只注册一次。
+   */
+  scheduleFlush(): void
+  /**
+   * 从 published 投影只读 Signal。
+   * 仅当 select 结果相对上一值 Object.is 不等时通知。
+   */
+  select<T>(selector: (snapshot: Readonly<TSnapshot>) => T): ReadonlySignal<T>
+}
+
+/**
+ * 创建帧事务控制器。
+ *
+ * @typeParam TInput - 可合并的输入形状（浅层 Partial 合并）
+ * @typeParam TSnapshot - derive 产出的不可变快照类型
+ */
+export function createFrameTransaction<
+  TInput extends Record<string, unknown>,
+  TSnapshot,
+>(options: FrameTransactionOptions<TInput, TSnapshot>): FrameTransaction<TInput, TSnapshot> {
+  const { derive, render } = options
+  const schedule =
+    options.schedule ??
+    ((run: () => void) => {
+      if (typeof requestAnimationFrame === 'function') {
+        return requestAnimationFrame(run)
+      }
+      return setTimeout(run, 0)
+    })
+
+  /** 当前代可写入的输入（仅 idle 时接收 writeInput） */
+  let pending: TInput = { ...options.initialInput }
+  /** 事务进行中产生的输入，complete 后并入下一代 */
+  let nextPending: TInput | null = null
+  /** 是否存在尚未 flush 的 pending 变更 */
+  let dirty = false
+  let generation = 0
+  let phase: FramePhase = 'idle'
+  let scheduleQueued = false
+
+  // generation 0：用初始输入 derive 一次，作为 published 占位，避免订阅者读到 undefined
+  const initialSnapshot = sealSnapshotRoot(derive({ ...pending }, 0))
+  const published = createSignal<TSnapshot>(initialSnapshot)
+
+  function writeInput(patch: Partial<TInput>): void {
+    if (phase === 'idle') {
+      pending = mergeInput(pending, patch)
+      dirty = true
+      return
+    }
+    // capturing 之后当前输入已封存；重入写入只能进下一代
+    const base = nextPending ?? pending
+    nextPending = mergeInput(base, patch)
+  }
+
+  function flush(): Readonly<TSnapshot> {
+    // 禁止嵌套发布：订阅者 / render 中 flush 只保留 dirty，由外层 complete 后再调度
+    if (phase !== 'idle') {
+      return published.peek()
+    }
+
+    if (!dirty && nextPending === null) {
+      return published.peek()
+    }
+
+    // 若仅有 nextPending（例如上一帧 render 中写入），提升为当前 pending
+    if (!dirty && nextPending !== null) {
+      pending = nextPending
+      nextPending = null
+      dirty = true
+    }
+
+    let sealedInput: TInput | undefined
+    phase = 'capturing'
+    try {
+      sealedInput = pending
+      dirty = false
+      // 本帧 capture 之后的新写入进入 nextPending，不得污染 sealedInput
+      pending = { ...sealedInput }
+
+      phase = 'deriving'
+      const nextGeneration = generation + 1
+      const snapshot = derive(sealedInput, nextGeneration)
+
+      phase = 'sealing'
+      sealSnapshotRoot(snapshot)
+
+      phase = 'rendering'
+      render?.(snapshot)
+
+      // 先推进代际再发布，保证订阅者读 generation 与 snapshot.generation 一致
+      phase = 'publishing'
+      generation = nextGeneration
+      published.set(snapshot)
+
+      return snapshot
+    } catch (err) {
+      // derive/render 失败：不推进 generation（若已推进则回滚），保留 sealed 输入供重试
+      if (sealedInput !== undefined) {
+        pending = sealedInput
+        dirty = true
+      }
+      throw err
+    } finally {
+      phase = 'idle'
+      // 事务中累积的 nextPending 与重试 pending 合并
+      if (nextPending !== null) {
+        pending = mergeInput(pending, nextPending)
+        nextPending = null
+        dirty = true
+      }
+      // 有残留 dirty 时挂下一代调度（含 re-entrant write / 失败重试）
+      if (dirty) {
+        scheduleFlush()
+      }
+    }
+  }
+
+  function scheduleFlush(): void {
+    if (scheduleQueued) return
+    if (!dirty && nextPending === null) return
+    scheduleQueued = true
+    try {
+      schedule(() => {
+        scheduleQueued = false
+        // flush 的 finally 已在失败时保留 dirty 并 scheduleFlush；此处继续抛出供测试/诊断
+        flush()
+      })
+    } catch (err) {
+      // schedule 本身失败：复位标志，允许后续 scheduleFlush 重试
+      scheduleQueued = false
+      throw err
+    }
+  }
+
+  function select<T>(selector: (snapshot: Readonly<TSnapshot>) => T): ReadonlySignal<T> {
+    const selected = createSignal(selector(published.peek()))
+    published.subscribe(() => {
+      const next = selector(published.peek())
+      selected.set(next)
+    })
+    const read = (): T => selected()
+    return Object.assign(read, {
+      peek: selected.peek,
+      subscribe: selected.subscribe,
+    }) as ReadonlySignal<T>
+  }
+
+  return {
+    published$: Object.assign((() => published()) as ReadonlySignal<Readonly<TSnapshot>>, {
+      peek: published.peek,
+      subscribe: published.subscribe,
+    }),
+    get generation() {
+      return generation
+    },
+    get phase() {
+      return phase
+    },
+    writeInput,
+    flush,
+    scheduleFlush,
+    select,
+  }
+}

package/src/foundation/reactivity/index.ts

@@ -4,6 +4,7 @@ export {
   computed,
   effect,
   batch,
+  selectSignal,
   createStateStore,
   createSubState,
 } from './signal'
@@ -14,4 +15,11 @@ export type {
   WritableRef,
   ReadonlyRef,
   Computed,
+  SelectedSignal,
 } from './signal'
+export { createFrameTransaction } from './frameTransaction'
+export type {
+  FramePhase,
+  FrameTransaction,
+  FrameTransactionOptions,
+} from './frameTransaction'

package/src/foundation/reactivity/signal.ts

@@ -233,6 +233,45 @@ export function batch<T>(fn: () => T): T {
   }
 }
 
+/**
+ * selectSignal 返回值：只读投影 + 解除对 source 的订阅。
+ */
+export type SelectedSignal<U> = ReadonlySignal<U> & {
+  /** 取消对 source 的订阅；之后不再随 source 更新 */
+  dispose: () => void
+}
+
+/**
+ * 从源 Signal 投影只读 Signal。
+ * 仅当 selector 结果相对上一值 equal 判定为不等时通知。
+ *
+ * @remarks
+ * 用于框架桥接：避免整包 snapshot 变化时无关字段也触发 UI 更新。
+ * 默认 equal 为 Object.is；对 {x,y} 等可传入结构相等函数。
+ * 短生命周期投影必须调用 dispose，否则会永久订阅 source。
+ *
+ * @typeParam T - 源快照类型
+ * @typeParam U - 投影结果类型
+ */
+export function selectSignal<T, U>(
+  source: ReadonlySignal<T>,
+  selector: (value: T) => U,
+  equal: (a: U, b: U) => boolean = Object.is,
+): SelectedSignal<U> {
+  const selected = createSignal(selector(source.peek()))
+  const unsubSource = source.subscribe(() => {
+    const next = selector(source.peek())
+    if (equal(selected.peek(), next)) return
+    selected.set(next)
+  })
+  const read = (): U => selected()
+  return Object.assign(read, {
+    peek: selected.peek,
+    subscribe: selected.subscribe,
+    dispose: unsubSource,
+  }) as SelectedSignal<U>
+}
+
 /**
  * 从初始状态对象创建一组相关 signal。
  *

package/src/foundation/tokens/__tests__/__snapshots__/baseline.test.ts.snap

@@ -71,7 +71,7 @@ exports[`theme baseline — dark > CSS declaration block (snapshot) 1`] = `
   --klc-color-tag-bg-transparent: transparent;
   --klc-color-tag-bg-active: #1890ff;
   --klc-color-tag-bg-active-hover: #40a9ff;
-  --klc-color-tag-bg-hover: #262C36;
+  --klc-color-tag-bg-hover: #2D3544;
   --klc-color-border-dark: rgba(255, 255, 255, 0.15);
   --klc-color-border-medium: rgba(255, 255, 255, 0.12);
   --klc-color-border-light: rgba(255, 255, 255, 0.08);
@@ -271,7 +271,7 @@ exports[`theme baseline — light > CSS declaration block (snapshot) 1`] = `
   --klc-color-tag-bg-transparent: transparent;
   --klc-color-tag-bg-active: #1890ff;
   --klc-color-tag-bg-active-hover: #40a9ff;
-  --klc-color-tag-bg-hover: #f0f0f0;
+  --klc-color-tag-bg-hover: #E5E7EB;
   --klc-color-border-dark: rgba(0, 0, 0, 0.12);
   --klc-color-border-medium: rgba(0, 0, 0, 0.10);
   --klc-color-border-light: rgba(0, 0, 0, 0.08);

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

@@ -117,7 +117,8 @@ export const darkTheme: Theme = {
       transparent: 'transparent',
       active: '#1890ff',
       activeHover: '#40a9ff',
-      hover: '#262C36',
+      // 相对 background #111827 提高悬停对比，列表项 hover 更易辨认
+      hover: '#2D3544',
     },
     border: {
       dark: 'rgba(255, 255, 255, 0.15)',

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

@@ -123,7 +123,8 @@ export const lightTheme: Theme = {
       transparent: 'transparent',
       active: '#1890ff',
       activeHover: '#40a9ff',
-      hover: '#f0f0f0',
+      // 相对 background #FAFAFA 提高悬停对比，避免与底色糊成一片
+      hover: '#E5E7EB',
     },
     border: {
       dark: 'rgba(0, 0, 0, 0.12)',