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

package/src/foundation/reactivity/frameTransaction.ts

@@ -10,6 +10,17 @@
  * 一帧固定走 capture → derive → seal → render → publish → complete。
  * render 或 publish 期间的 writeInput 一律进入下一代 pending。
  * 非 idle 时调用 flush 不会嵌套发布，仅保留 dirty 供外层完成后调度。
+ *
+ * @remarks 适用范围
+ * 这是一个半通用的 rAF 合帧器（semi-general frame coalescer），
+ * 专为 ChartRenderer 的绘制管线设计，并非全场景通用的高频处理方案。
+ *
+ * @Todo 如需在其他场景（WebSocket 消息合并、键盘事件批处理）复用，需补充：
+ * - 深层合并 / 自定义 merge 策略（目前 mergeInput 仅浅合并）
+ * - 快照深层不可变保证（目前 sealSnapshotRoot 只冻根对象）
+ * - 超时/失帧策略（目前纯乐观逐帧）
+ * - 背压与优先级集成（FrameBudget 在 scheduler 层但未在此集成）
+ * - 非 Record 输入类型支持（目前 TInput 约束为 Record）
  */
 
 import { createSignal, type ReadonlySignal } from './signal'
@@ -88,10 +99,9 @@ export interface FrameTransaction<TInput extends Record<string, unknown>, TSnaps
  * @typeParam TInput - 可合并的输入形状（浅层 Partial 合并）
  * @typeParam TSnapshot - derive 产出的不可变快照类型
  */
-export function createFrameTransaction<
-  TInput extends Record<string, unknown>,
-  TSnapshot,
->(options: FrameTransactionOptions<TInput, TSnapshot>): FrameTransaction<TInput, TSnapshot> {
+export function createFrameTransaction<TInput extends Record<string, unknown>, TSnapshot>(
+  options: FrameTransactionOptions<TInput, TSnapshot>,
+): FrameTransaction<TInput, TSnapshot> {
   const { derive, render } = options
   const schedule =
     options.schedule ??
@@ -145,24 +155,27 @@ export function createFrameTransaction<
     }
 
     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)
@@ -191,6 +204,7 @@ export function createFrameTransaction<
   }
 
   function scheduleFlush(): void {
+    // 已有 raf 帧，
     if (scheduleQueued) return
     if (!dirty && nextPending === null) return
     scheduleQueued = true

package/src/foundation/utils/__tests__/sessionTimeLabels.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  ASHARE_MARKET_SESSION,
+  HK_MARKET_SESSION,
+  US_MARKET_SESSION,
+  computeSessionTimeLabels,
+  countSessionSlots,
+  minuteOfDayToTimestamp,
+  resolveMarketSessionSlots,
+  type MarketSessionConfig,
+  type OpenTimeRange,
+} from '../sessionTimeLabels'
+
+function hm(h: number, m: number): number {
+  return h * 60 + m
+}
+
+describe('countSessionSlots / resolveMarketSessionSlots', () => {
+  it('A-share is 240 one-minute slots', () => {
+    expect(countSessionSlots(ASHARE_MARKET_SESSION.sessions)).toBe(240)
+    expect(resolveMarketSessionSlots(ASHARE_MARKET_SESSION)).toBe(240)
+  })
+
+  it('HK is 330, US is 390 (not maxed to 240)', () => {
+    expect(resolveMarketSessionSlots(HK_MARKET_SESSION)).toBe(330)
+    expect(resolveMarketSessionSlots(US_MARKET_SESSION)).toBe(390)
+  })
+
+  it('respects slotMinutes (e.g. 5-min bars)', () => {
+    const cfg: MarketSessionConfig = {
+      ...ASHARE_MARKET_SESSION,
+      slotMinutes: 5,
+    }
+    // 240 分钟 / 5 = 48
+    expect(resolveMarketSessionSlots(cfg)).toBe(48)
+  })
+
+  it('does not expand slots by arrived data length (sessions are SSOT)', () => {
+    expect(resolveMarketSessionSlots(ASHARE_MARKET_SESSION, 300)).toBe(240)
+    expect(resolveMarketSessionSlots(HK_MARKET_SESSION, 100)).toBe(330)
+  })
+})
+
+describe('computeSessionTimeLabels multi-market', () => {
+  it('A-share closed-side endpoints only', () => {
+    const labels = computeSessionTimeLabels(ASHARE_MARKET_SESSION.sessions, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(9, 30), hm(13, 0), hm(15, 0)])
+  })
+
+  it('HK endpoints: 09:30 / 13:00 / 16:00', () => {
+    const labels = computeSessionTimeLabels(HK_MARKET_SESSION.sessions, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(9, 30), hm(13, 0), hm(16, 0)])
+    expect(labels.map((l) => l.slotIndex)).toEqual([0, 150, 329])
+  })
+
+  it('US single continuous session endpoints: 09:30 / 16:00', () => {
+    const labels = computeSessionTimeLabels(US_MARKET_SESSION.sessions, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(9, 30), hm(16, 0)])
+    expect(labels.map((l) => l.slotIndex)).toEqual([0, 389])
+  })
+
+  it('accepts arbitrary sessions via config.sessions', () => {
+    const night: OpenTimeRange[] = [
+      { open: hm(21, 0), close: hm(23, 0) },
+      { open: hm(0, 0), close: hm(2, 30) },
+    ]
+    // 两段同日分钟：21:00-23:00 (120) + 0:00-2:30 (150) = 270
+    // 闭侧端点：21:00, 0:00, 2:30
+    const labels = computeSessionTimeLabels(night, { axisWidth: 800 })
+    expect(labels.map((l) => l.minuteOfDay)).toEqual([hm(21, 0), hm(0, 0), hm(2, 30)])
+    expect(countSessionSlots(night)).toBe(270)
+  })
+})
+
+describe('minuteOfDayToTimestamp timeZone', () => {
+  it('maps wall clock in Asia/Shanghai independently of host local TZ', () => {
+    // 任意 UTC 锚点落在 2026-07-21 上海日历日
+    const base = Date.UTC(2026, 6, 21, 4, 0, 0) // 12:00 CST
+    const ts = minuteOfDayToTimestamp(base, hm(9, 30), 'Asia/Shanghai')
+    // 2026-07-21 09:30 Asia/Shanghai = 01:30 UTC
+    expect(ts).toBe(Date.UTC(2026, 6, 21, 1, 30, 0))
+  })
+
+  it('maps wall clock in America/New_York for US session open', () => {
+    // 2026-07-21 是美东夏令时 EDT (UTC-4)
+    const base = Date.UTC(2026, 6, 21, 16, 0, 0) // 12:00 EDT
+    const ts = minuteOfDayToTimestamp(base, hm(9, 30), 'America/New_York')
+    expect(ts).toBe(Date.UTC(2026, 6, 21, 13, 30, 0)) // 09:30 EDT
+  })
+})

package/src/foundation/utils/kLineDraw/axis.ts

@@ -12,6 +12,14 @@ import {
   findDayBoundaries,
 } from '../dateFormat'
 import { priceToY, yToPrice } from '../priceToY'
+import {
+  ASHARE_MARKET_SESSION,
+  computeTimeShareTimeLabels,
+  minuteOfDayToTimestamp,
+  resolveMarketSessionSlots,
+  timeShareSlotCenterX,
+  type MarketSessionConfig,
+} from '../timeShareAxisLabels'
 
 const textWidthCache = new Map<string, number>()
 const TEXT_WIDTH_CACHE_LIMIT = 512
@@ -63,6 +71,8 @@ export interface TimeAxisOptions {
   monthKeys?: Int32Array
   /** 预计算的日期键值数组（year*366+dayOfYear），与 data 长度一致 */
   dayKeys?: Int32Array
+  /** 分时市场 session；默认 A 股 */
+  marketSession?: MarketSessionConfig
 }
 
 export interface LastPriceLineOptions {
@@ -362,16 +372,47 @@ export function drawTimeAxis(
   let labelFn: (ts: number) => { text: string; isYear: boolean }
 
   if (isTimeShare) {
-    const visibleCount = endIndex - startIndex
-    const maxLabels = Math.max(2, Math.min(8, Math.floor(visibleCount / 2) || 1))
-    const step = Math.max(1, Math.floor(visibleCount / maxLabels))
-    boundaries = []
-    for (let i = 0; i <= maxLabels; i++) {
-      const idx = startIndex + Math.min(i * step, Math.max(0, visibleCount - 1))
-      boundaries.push(idx)
+    // 只画各区间闭侧端点；全天首/末槽贴边 left/right 对齐
+    const market = opts.marketSession ?? ASHARE_MARKET_SESSION
+    const sessionSlots = resolveMarketSessionSlots(market)
+    const labels = computeTimeShareTimeLabels({
+      axisWidth: width,
+      marketSession: market,
+      minLabelSpacingPx: 56,
+    })
+    const baseTs = data[0]?.timestamp ?? Date.now()
+    setCanvasFont(ctx, regularFont)
+    ctx.textBaseline = 'middle'
+    const edgePad = 2
+    const lastSlot = Math.max(0, sessionSlots - 1)
+    for (const label of labels) {
+      const ts = minuteOfDayToTimestamp(baseTs, label.minuteOfDay, market.timeZone)
+      const text = formatTimeLabel(ts)
+      const isDayStart = label.slotIndex === 0
+      const isDayEnd = label.slotIndex === lastSlot
+
+      let align: CanvasTextAlign = 'center'
+      let drawX: number
+      if (isDayStart) {
+        align = 'left'
+        drawX = x + edgePad
+      } else if (isDayEnd) {
+        align = 'right'
+        drawX = x + width - edgePad
+      } else {
+        const centerX = timeShareSlotCenterX(label.slotIndex, width, sessionSlots, dpr)
+        drawX = centerX - scrollLeft
+        if (drawX < edgePad || drawX > width - edgePad) continue
+      }
+
+      ctx.textAlign = align
+      ctx.fillText(text, roundToPhysicalPixel(drawX, dpr), alignToPhysicalPixelCenter(textY, dpr))
     }
-    labelFn = (ts) => ({ text: formatTimeLabel(ts), isYear: false })
-  } else if (isMinuteData) {
+    ctx.textAlign = 'center'
+    return
+  }
+
+  if (isMinuteData) {
     boundaries = findDayBoundaries(data, opts.dayKeys)
     labelFn = formatDay
   } else {

package/src/foundation/utils/sessionTimeLabels.ts

@@ -0,0 +1,237 @@
+/**
+ * 开盘时段：minuteOfDay 为自 0 点起的分钟数（交易所本地墙钟）。
+ * sessions[0..n-2] 左闭右开 [open, close)；sessions[n-1] 左闭右闭 [open, close]。
+ * 只打印闭侧端点：半开段不展示 close。
+ */
+export type OpenTimeRange = {
+  open: number
+  close: number
+}
+
+/** 市场分时 session 配置（几何 / 标签共用） */
+export type MarketSessionConfig = {
+  /** IANA 时区，如 Asia/Shanghai */
+  timeZone: string
+  sessions: ReadonlyArray<OpenTimeRange>
+  /** 每个 bar 槽对应的分钟数，默认 1 */
+  slotMinutes?: number
+}
+
+export type SessionTimeLabel = {
+  /** 自 0 点起的分钟数（交易所墙钟） */
+  minuteOfDay: number
+  /** 在展开后的槽序列中的索引（0-based） */
+  slotIndex: number
+  /** 是否为闭侧端点 */
+  isEndpoint: boolean
+}
+
+export type SessionTimeLabelOptions = {
+  axisWidth: number
+  /** 保留字段，端点-only 模式下不参与密度计算 */
+  minLabelSpacingPx?: number
+}
+
+function hm(h: number, m: number): number {
+  return h * 60 + m
+}
+
+/** A 股默认 */
+export const ASHARE_OPEN_SESSIONS: readonly OpenTimeRange[] = [
+  { open: hm(9, 30), close: hm(11, 30) },
+  { open: hm(13, 0), close: hm(15, 0) },
+]
+
+export const ASHARE_MARKET_SESSION: MarketSessionConfig = {
+  timeZone: 'Asia/Shanghai',
+  sessions: ASHARE_OPEN_SESSIONS,
+  slotMinutes: 1,
+}
+
+/** 港股 */
+export const HK_MARKET_SESSION: MarketSessionConfig = {
+  timeZone: 'Asia/Hong_Kong',
+  sessions: [
+    { open: hm(9, 30), close: hm(12, 0) },
+    { open: hm(13, 0), close: hm(16, 0) },
+  ],
+  slotMinutes: 1,
+}
+
+/** 美股（常规盘，无午休） */
+export const US_MARKET_SESSION: MarketSessionConfig = {
+  timeZone: 'America/New_York',
+  sessions: [{ open: hm(9, 30), close: hm(16, 0) }],
+  slotMinutes: 1,
+}
+
+/**
+ * 只输出各区间闭侧端点。
+ * - 非末段 [open, close)：仅 open
+ * - 末段 [open, close]：open 与 close
+ * close 标签映射到 close-1 槽（bar 序列为各段 [open, close)）。
+ */
+export function computeSessionTimeLabels(
+  sessions: ReadonlyArray<OpenTimeRange>,
+  options: SessionTimeLabelOptions,
+): SessionTimeLabel[] {
+  if (!(options.axisWidth > 0) || sessions.length === 0) return []
+
+  const labels: SessionTimeLabel[] = []
+  let slotOffset = 0
+
+  for (let s = 0; s < sessions.length; s++) {
+    const range = sessions[s]!
+    if (!(range.close > range.open)) continue
+    const slotCount = range.close - range.open
+    const isLast = s === sessions.length - 1
+
+    labels.push({
+      minuteOfDay: range.open,
+      slotIndex: slotOffset,
+      isEndpoint: true,
+    })
+
+    if (isLast) {
+      labels.push({
+        minuteOfDay: range.close,
+        slotIndex: slotOffset + slotCount - 1,
+        isEndpoint: true,
+      })
+    }
+
+    slotOffset += slotCount
+  }
+
+  const bySlot = new Map<number, SessionTimeLabel>()
+  for (const label of labels) {
+    bySlot.set(label.slotIndex, label)
+  }
+  return [...bySlot.values()].sort((a, b) => a.slotIndex - b.slotIndex)
+}
+
+/** 槽总数（各段 [open, close) 分钟数之和；未除 slotMinutes） */
+export function countSessionSlots(sessions: ReadonlyArray<OpenTimeRange>): number {
+  let n = 0
+  for (const r of sessions) {
+    if (r.close > r.open) n += r.close - r.open
+  }
+  return n
+}
+
+/**
+ * 全天 bar 槽数 = 分钟总和 / slotMinutes。
+ * sessions 为 SSOT，不因 arrivedCount 放大。
+ */
+export function resolveMarketSessionSlots(
+  config: MarketSessionConfig,
+  _arrivedCount?: number,
+): number {
+  const minutes = countSessionSlots(config.sessions)
+  const step = config.slotMinutes && config.slotMinutes > 0 ? config.slotMinutes : 1
+  return Math.max(0, Math.floor(minutes / step))
+}
+
+/**
+ * 将交易所墙钟 minuteOfDay 转为 UTC 毫秒。
+ * baseTimestamp 用于确定「哪一天」（按 timeZone 日历日）。
+ */
+export function minuteOfDayToTimestamp(
+  baseTimestamp: number,
+  minuteOfDay: number,
+  timeZone: string = 'Asia/Shanghai',
+): number {
+  const { year, month, day } = getCalendarPartsInTimeZone(baseTimestamp, timeZone)
+  return zonedWallTimeToUtc(year, month, day, minuteOfDay, timeZone)
+}
+
+/** 槽中心 X */
+export function sessionSlotCenterX(
+  slotIndex: number,
+  axisWidth: number,
+  sessionSlots: number,
+  dpr: number,
+): number {
+  if (!(axisWidth > 0) || !(sessionSlots > 0)) return 0
+  const step = axisWidth / sessionSlots
+  return Math.round((slotIndex + 0.5) * step * dpr) / dpr
+}
+
+// ── 时区工具（无第三方依赖，Intl） ──
+
+function getCalendarPartsInTimeZone(
+  timestamp: number,
+  timeZone: string,
+): { year: number; month: number; day: number } {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).formatToParts(new Date(timestamp))
+  let year = 0
+  let month = 1
+  let day = 1
+  for (const p of parts) {
+    if (p.type === 'year') year = Number(p.value)
+    else if (p.type === 'month') month = Number(p.value)
+    else if (p.type === 'day') day = Number(p.value)
+  }
+  return { year, month, day }
+}
+
+/**
+ * 将某时区墙钟 (y-m-d + minuteOfDay) 转为 UTC epoch。
+ * 用迭代修正 UTC 猜测，覆盖 DST。
+ */
+function zonedWallTimeToUtc(
+  year: number,
+  month: number,
+  day: number,
+  minuteOfDay: number,
+  timeZone: string,
+): number {
+  const hour = Math.floor(minuteOfDay / 60)
+  const minute = minuteOfDay % 60
+  // 初值：当作 UTC 墙钟
+  let utc = Date.UTC(year, month - 1, day, hour, minute, 0, 0)
+  for (let i = 0; i < 4; i++) {
+    const wall = getWallClockInTimeZone(utc, timeZone)
+    const desiredMin = hour * 60 + minute
+    const actualMin = wall.hour * 60 + wall.minute
+    const dayDelta =
+      Date.UTC(year, month - 1, day) - Date.UTC(wall.year, wall.month - 1, wall.day)
+    const minDelta = desiredMin - actualMin + dayDelta / 60_000
+    if (minDelta === 0) break
+    utc += minDelta * 60_000
+  }
+  return utc
+}
+
+function getWallClockInTimeZone(
+  timestamp: number,
+  timeZone: string,
+): { year: number; month: number; day: number; hour: number; minute: number } {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(new Date(timestamp))
+  let year = 0
+  let month = 1
+  let day = 1
+  let hour = 0
+  let minute = 0
+  for (const p of parts) {
+    if (p.type === 'year') year = Number(p.value)
+    else if (p.type === 'month') month = Number(p.value)
+    else if (p.type === 'day') day = Number(p.value)
+    else if (p.type === 'hour') hour = Number(p.value)
+    else if (p.type === 'minute') minute = Number(p.value)
+  }
+  return { year, month, day, hour, minute }
+}

package/src/foundation/utils/timeShareAxisLabels.ts

@@ -0,0 +1,94 @@
+import {
+  ASHARE_MARKET_SESSION,
+  ASHARE_OPEN_SESSIONS,
+  computeSessionTimeLabels,
+  countSessionSlots,
+  minuteOfDayToTimestamp,
+  resolveMarketSessionSlots,
+  sessionSlotCenterX,
+  type MarketSessionConfig,
+  type SessionTimeLabel,
+} from './sessionTimeLabels'
+
+/** A 股默认全天 1 分钟槽位数（兼容旧导出） */
+export const ASHARE_TIMESHARE_SESSION_SLOTS = resolveMarketSessionSlots(ASHARE_MARKET_SESSION)
+
+/** 分时时间标签最小水平间距（逻辑像素） */
+export const TIMESHARE_MIN_LABEL_SPACING_PX = 56
+
+export type TimeShareTimeLabelInput = {
+  axisWidth: number
+  /** 市场 session；默认 A 股 */
+  marketSession?: MarketSessionConfig
+  minLabelSpacingPx?: number
+}
+
+/**
+ * 分时时间标签索引（委托 computeSessionTimeLabels）。
+ * 默认 A 股；传入 marketSession 可换港股/美股等。
+ */
+export function computeTimeShareTimeLabelIndices(input: TimeShareTimeLabelInput): number[] {
+  return computeTimeShareTimeLabels(input).map((l) => l.slotIndex)
+}
+
+/** 完整标签（含 minuteOfDay / isEndpoint） */
+export function computeTimeShareTimeLabels(input: TimeShareTimeLabelInput): SessionTimeLabel[] {
+  const market = input.marketSession ?? ASHARE_MARKET_SESSION
+  return computeSessionTimeLabels(market.sessions, {
+    axisWidth: input.axisWidth,
+    minLabelSpacingPx: input.minLabelSpacingPx ?? TIMESHARE_MIN_LABEL_SPACING_PX,
+  })
+}
+
+export function timeShareSlotCenterX(
+  slotIndex: number,
+  axisWidth: number,
+  sessionSlots: number,
+  dpr: number,
+): number {
+  return sessionSlotCenterX(slotIndex, axisWidth, sessionSlots, dpr)
+}
+
+/**
+ * 由开盘日基准时间戳 + slot 索引推算标签时间（按 market session）。
+ */
+export function resolveTimeShareSlotTimestamp(
+  baseTimestamp: number,
+  slotIndex: number,
+  marketSession: MarketSessionConfig = ASHARE_MARKET_SESSION,
+): number {
+  const step = marketSession.slotMinutes && marketSession.slotMinutes > 0 ? marketSession.slotMinutes : 1
+  let remaining = slotIndex * step
+  for (const range of marketSession.sessions) {
+    const len = range.close - range.open
+    if (remaining < len) {
+      return minuteOfDayToTimestamp(
+        baseTimestamp,
+        range.open + remaining,
+        marketSession.timeZone,
+      )
+    }
+    remaining -= len
+  }
+  const last = marketSession.sessions[marketSession.sessions.length - 1]
+  if (last) {
+    return minuteOfDayToTimestamp(baseTimestamp, last.close, marketSession.timeZone)
+  }
+  return baseTimestamp
+}
+
+export {
+  ASHARE_MARKET_SESSION,
+  ASHARE_OPEN_SESSIONS,
+  computeSessionTimeLabels,
+  countSessionSlots,
+  minuteOfDayToTimestamp,
+  resolveMarketSessionSlots,
+  sessionSlotCenterX,
+}
+export type {
+  MarketSessionConfig,
+  OpenTimeRange,
+  SessionTimeLabel,
+} from './sessionTimeLabels'
+export { HK_MARKET_SESSION, US_MARKET_SESSION } from './sessionTimeLabels'