waveform-analysis 0.1.70 → 0.1.72

package/src/components/controls/useChartImageExport.ts

@@ -0,0 +1,155 @@
+import { nextTick, onBeforeUnmount, watch } from 'vue'
+import type {
+  WaveformImageExportError,
+  WaveformImageExportErrorCode,
+  WaveformImageExportOptions,
+} from '../../types/controls'
+import { updateMaximumTickVisibility } from '../rendering/yAxisTickVisibility'
+import { createChartSnapshot } from './chartSnapshot'
+export function imageExportError(code: WaveformImageExportErrorCode): WaveformImageExportError {
+  const messages = {
+    'export-invalid-options': '图片导出参数无效',
+    'export-unavailable': '图表尚未具备有效尺寸',
+    'export-busy': '已有导出正在执行',
+    'export-cancelled': '图表已卸载，导出取消',
+    'export-render-failed': '图片编码失败',
+    'export-stale': '图表已变化，请重新导出',
+    'export-timeout': '等待图表稳定超时，请重试',
+  }
+  return Object.assign(new Error(messages[code]), { code })
+}
+interface Context {
+  container: () => HTMLElement | undefined
+  svg: () => SVGSVGElement | undefined
+  size: () => { width: number; height: number; titleHeight: number }
+  version: () => unknown
+  ready: () => boolean
+}
+export function useChartImageExport(c: Context) {
+  let busy = false
+  let disposed = false
+  let revision = 0
+  let abort: ((error: WaveformImageExportError) => void) | undefined
+  watch(
+    c.version,
+    () => {
+      revision++
+      abort?.(imageExportError('export-stale'))
+    },
+    { flush: 'sync' },
+  )
+  onBeforeUnmount(() => {
+    disposed = true
+    abort?.(imageExportError('export-cancelled'))
+  })
+  async function exportImage(options: WaveformImageExportOptions = {}): Promise<Blob> {
+    const format = options.format ?? 'png'
+    const scale = options.scale ?? 1
+    if (
+      !['png', 'svg'].includes(format) ||
+      !Number.isFinite(scale) ||
+      scale <= 0 ||
+      scale > 4 ||
+      (format === 'svg' && scale !== 1) ||
+      (options.backgroundColor !== undefined &&
+        (typeof options.backgroundColor !== 'string' ||
+          !CSS.supports('color', options.backgroundColor)))
+    )
+      throw imageExportError('export-invalid-options')
+    if (disposed) throw imageExportError('export-cancelled')
+    if (busy) throw imageExportError('export-busy')
+    const container = c.container(),
+      svg = c.svg(),
+      size = c.size()
+    if (!container || !svg || size.width <= 0 || size.height <= 0)
+      throw imageExportError('export-unavailable')
+    busy = true
+    const captured = revision
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let poll: ReturnType<typeof setTimeout> | undefined
+    let url: string | undefined
+    let img: HTMLImageElement | undefined
+    let canvas: HTMLCanvasElement | undefined
+    let stopped = false
+    const check = () => {
+      if (disposed) throw imageExportError('export-cancelled')
+      if (captured !== revision) throw imageExportError('export-stale')
+      if (stopped) throw imageExportError('export-timeout')
+    }
+    const cancelled = new Promise<never>((_, reject) => {
+      abort = reject
+      timer = setTimeout(() => reject(imageExportError('export-timeout')), 5000)
+    })
+    const generate = async () => {
+      await nextTick()
+      check()
+      await new Promise<void>((resolve) => {
+        const test = () => {
+          if (stopped) return
+          if (c.ready()) resolve()
+          else poll = setTimeout(test, 16)
+        }
+        test()
+      })
+      await document.fonts?.ready
+      await nextTick()
+      check()
+      updateMaximumTickVisibility(svg)
+      const snapshot = createChartSnapshot(
+        container,
+        svg,
+        size.width,
+        size.height,
+        size.titleHeight,
+        options.backgroundColor,
+      )
+      const blob = new Blob([snapshot], { type: 'image/svg+xml' })
+      if (format === 'svg') return blob
+      url = URL.createObjectURL(blob)
+      img = new Image()
+      await new Promise<void>((resolve, reject) => {
+        img!.onload = () => resolve()
+        img!.onerror = () => reject(imageExportError('export-render-failed'))
+        img!.src = url!
+      })
+      check()
+      canvas = document.createElement('canvas')
+      canvas.width = Math.round(size.width * scale)
+      canvas.height = Math.round(size.height * scale)
+      const ctx = canvas.getContext('2d')
+      if (!ctx) throw imageExportError('export-render-failed')
+      ctx.drawImage(img, 0, 0, canvas.width, canvas.height)
+      const png = await new Promise<Blob>((resolve, reject) =>
+        canvas!.toBlob(
+          (result) => (result ? resolve(result) : reject(imageExportError('export-render-failed'))),
+          'image/png',
+        ),
+      )
+      check()
+      return png
+    }
+    try {
+      return await Promise.race([cancelled, generate()])
+    } catch (error) {
+      if (error instanceof Error && 'code' in error) throw error
+      throw imageExportError('export-render-failed')
+    } finally {
+      stopped = true
+      clearTimeout(timer)
+      clearTimeout(poll)
+      if (img) {
+        img.onload = null
+        img.onerror = null
+        img.src = ''
+      }
+      if (url) URL.revokeObjectURL(url)
+      if (canvas) {
+        canvas.width = 0
+        canvas.height = 0
+      }
+      abort = undefined
+      busy = false
+    }
+  }
+  return { exportImage }
+}

package/src/components/controls/useControlMode.ts

@@ -0,0 +1,30 @@
+import { computed, ref, watch } from 'vue'
+import type { WaveformControlResult } from '../../types/controls'
+import type { WaveformInteractionMode } from '../../types'
+import type { ResolvedWaveformChartProps, WaveformChartEmit } from '../core/waveformChartTypes'
+
+export function useControlMode(props: ResolvedWaveformChartProps, emit: WaveformChartEmit) {
+  const internalMode = ref<WaveformInteractionMode>('zoom')
+  const mode = computed(() => props.interactionMode ?? internalMode.value)
+  const canSetMode = (value: WaveformInteractionMode) =>
+    !props.presentationMode &&
+    (value === 'none' ||
+      (value === 'zoom' && props.zoomable) ||
+      (value === 'pan' && props.pannable) ||
+      (value === 'annotation' && props.annotationsVisible))
+  function setInteractionMode(value: WaveformInteractionMode): WaveformControlResult {
+    let status: Extract<WaveformControlResult, { kind: 'mode' }>['status']
+    if (!canSetMode(value)) status = 'disabled'
+    else if (mode.value === value) status = 'unchanged'
+    else if (props.interactionMode !== undefined) {
+      emit('update:interactionMode', value)
+      status = 'requested'
+    } else {
+      internalMode.value = value
+      status = 'applied'
+    }
+    return { kind: 'mode', status, targets: [] }
+  }
+  watch(mode, (value) => emit('interaction-mode-change', value))
+  return { mode, canSetMode, setInteractionMode }
+}

package/src/components/core/latestTaskScheduler.ts

@@ -26,7 +26,9 @@ interface ScheduledTask {
 }
 
 /** Runs at most one task at a time and retains only the newest pending task. */
-export function createLatestTaskScheduler() {
+export function createLatestTaskScheduler(
+  onError: (error: unknown, generation: number) => void = () => undefined,
+) {
   let generation = 0
   let running = false
   let pending: ScheduledTask | undefined
@@ -40,7 +42,17 @@ export function createLatestTaskScheduler() {
       while (pending && !disposed) {
         const task = pending
         pending = undefined
-        await task.run(task.generation)
+        try {
+          await task.run(task.generation)
+        } catch (error) {
+          if (!disposed && task.generation === generation) {
+            try {
+              onError(error, task.generation)
+            } catch {
+              /* Reporting must not stall the queue. */
+            }
+          }
+        }
       }
     } finally {
       running = false

package/src/components/core/layout.ts

@@ -1,5 +1,3 @@
-import { scaleLinear } from 'd3'
-
 import type { WaveformOverlayMode } from '../../types'
 import { formatScientificAxisLabel, formatScientificAxisExponent, paddedDomain } from '../../utils'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
@@ -10,6 +8,9 @@ import {
   resolveTrackFixedYDomain,
   type WaveformYDomain,
 } from './yDomain'
+import { resolveYAxisTicksECharts } from './niceScale'
+import { applyYAxisPadding, withMaximumTick, type YAxisPaddingOptions } from './yAxisPadding'
+import { resolveYAxisLabelBandWidth } from './yAxisLabelStyle'
 
 // 导出常量供外部使用
 export { MAX_MULTI_Y_AXIS_COUNT } from './constants'
@@ -37,21 +38,24 @@ export function resolveYAxisTicks(
   tickCount = 5,
   nice = true,
 ): ResolvedYAxisTicks {
-  const effectiveTickCount =
-    typeof tickCount === 'number' && Number.isFinite(tickCount)
-      ? Math.max(2, Math.floor(tickCount))
-      : 5
-  const scale = scaleLinear(domain, [1, 0])
-  if (nice) scale.nice(Math.max(1, effectiveTickCount - 1))
-  const resolvedDomain = scale.domain() as [number, number]
-  const [axisStart, axisEnd] = resolvedDomain
-  return {
-    domain: resolvedDomain,
-    values: Array.from(
-      { length: effectiveTickCount },
-      (_, index) => axisStart + ((axisEnd - axisStart) * index) / (effectiveTickCount - 1),
-    ),
+  if (!nice) {
+    // 如果不需要 nice，使用简单的线性分割
+    const effectiveTickCount =
+      typeof tickCount === 'number' && Number.isFinite(tickCount)
+        ? Math.max(2, Math.floor(tickCount))
+        : 5
+    const [axisStart, axisEnd] = domain
+    return {
+      domain,
+      values: Array.from(
+        { length: effectiveTickCount },
+        (_, index) => axisStart + ((axisEnd - axisStart) * index) / (effectiveTickCount - 1),
+      ),
+    }
   }
+
+  // 使用 ECharts 兼容的 1/2/5 系列算法
+  return resolveYAxisTicksECharts(domain, tickCount)
 }
 
 export function formatYAxisTickLabel(
@@ -71,7 +75,8 @@ export function formatYAxisTickLabel(
   })
   if (suffixMetadata) {
     const unitLabel = unit?.trim()
-    return [label, formatScientificAxisExponent(...domain), unitLabel ? `(${unitLabel})` : null]
+    const exponent = formatScientificAxisExponent(...domain)
+    return [label, exponent, !exponent && unitLabel ? `(${unitLabel})` : null]
       .filter(Boolean)
       .join(' ')
   }
@@ -96,6 +101,7 @@ export interface YAxisSeriesGroup {
   seriesList: DisplaySeries[]
   domain: [number, number]
   fixed: boolean
+  maximumTick?: number
 }
 
 export interface YAxisSlot {
@@ -183,7 +189,7 @@ export function resolveRenderedYAxisSeriesGroups(
   yDomain?: WaveformYDomain,
   yDomains?: Record<string, WaveformYDomain>,
   viewportYDomains?: Record<string, [number, number]>,
-  upperPaddingRatio = 0,
+  padding?: YAxisPaddingOptions | number,
 ): YAxisSeriesGroup[] {
   const viewportYDomain = viewportYDomains?.[track.id]
   const axisTrack =
@@ -191,17 +197,7 @@ export function resolveRenderedYAxisSeriesGroups(
       ? track
       : { ...track, visibleSeries: track.series }
   return resolveYAxisSeriesGroups(axisTrack, overlayMode, yDomain, yDomains).map((group) =>
-    !group.fixed && viewportYDomain
-      ? { ...group, domain: viewportYDomain }
-      : !group.fixed && Number.isFinite(upperPaddingRatio) && upperPaddingRatio > 0
-        ? {
-            ...group,
-            domain: [
-              group.domain[0],
-              group.domain[1] + (group.domain[1] - group.domain[0]) * upperPaddingRatio,
-            ] as WaveformYDomain,
-          }
-        : group,
+    applyYAxisPadding(group, viewportYDomain, padding),
   )
 }
 
@@ -213,11 +209,12 @@ export function axisTextMetrics(
   tickCount = 5,
   includeWithoutLastTick = false,
   measureTextWidth?: (text: string) => number,
+  maximumTick?: number,
 ): { tickTextWidth: number } {
   const resolvedTicks = tickValues
     ? { domain, values: tickValues }
     : resolveYAxisTicks(domain, tickCount, nice)
-  const tickValueSets = [resolvedTicks.values]
+  const tickValueSets = [withMaximumTick(resolvedTicks.values, maximumTick)]
   if (includeWithoutLastTick && resolvedTicks.values.length > 1) {
     tickValueSets.push(resolvedTicks.values.slice(0, -1))
   }
@@ -296,10 +293,13 @@ export function buildYAxisSlots(
   nice = true,
   includeWithoutLastTick = false,
   viewportYDomains?: Record<string, [number, number]>,
-  upperPaddingRatio = 0,
+  padding?: YAxisPaddingOptions | number,
   showUnits = true,
   measureTextWidth?: (text: string) => number,
 ): { slots: YAxisSlot[]; clearance: { left: number; right: number } } {
+  const labelBandWidth = resolveYAxisLabelBandWidth(
+    typeof padding === 'object' ? padding.labelTextStyle : undefined,
+  )
   const widths = new Map<string, number>()
   tracks.forEach((track) => {
     const sideIndexes = { left: 0, right: 0 }
@@ -309,7 +309,7 @@ export function buildYAxisSlots(
       yDomain,
       yDomains,
       viewportYDomains,
-      upperPaddingRatio,
+      padding,
     ).forEach((group) => {
       const sideIndex = sideIndexes[group.side]++
       const key = `${group.side}:${sideIndex}`
@@ -321,6 +321,7 @@ export function buildYAxisSlots(
         tickCount,
         includeWithoutLastTick,
         measureTextWidth,
+        group.maximumTick,
       ).tickTextWidth
       widths.set(key, Math.max(widths.get(key) ?? Y_AXIS_CHARACTER_WIDTH, width))
     })
@@ -337,13 +338,13 @@ export function buildYAxisSlots(
       const tickTextWidth = widths.get(`${side}:${sideIndex}`) ?? Y_AXIS_CHARACTER_WIDTH
       const axisOffset = side === 'left' && clearance.left > 0 ? -clearance.left : clearance[side]
       const labelDistance =
-        tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_LABEL_GAP + Y_AXIS_LABEL_BAND_WIDTH / 2
+        tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_LABEL_GAP + labelBandWidth / 2
       const labelOffset = axisOffset + labelDistance * (side === 'left' ? -1 : 1)
       const fullClearance =
         tickTextWidth +
         Y_AXIS_TICK_PADDING +
         Y_AXIS_LABEL_GAP +
-        Y_AXIS_LABEL_BAND_WIDTH +
+        labelBandWidth +
         Y_AXIS_OUTER_PADDING
       slots.push({ side, sideIndex, axisOffset, labelOffset, clearance: fullClearance })
       clearance[side] += fullClearance

package/src/components/core/niceScale.ts

@@ -0,0 +1,151 @@
+/**
+ * ECharts-compatible Nice Number algorithm for axis tick calculation
+ * Based on "Nice Numbers for Graph Labels" from Graphics Gems
+ *
+ * References:
+ * - https://github.com/cenfun/nice-ticks
+ * - https://github.com/qianfan-Zhao/nice_number
+ * - https://stackoverflow.com/questions/8506881/nice-label-algorithm-for-charts-with-minimum-ticks
+ */
+
+/**
+ * 将数字转换为"优雅"的数字（1, 2, 5 系列）
+ * @param value - 原始值
+ * @param round - 是否向上取整
+ * @returns 优雅的数字
+ */
+function niceNumber(value: number, round: boolean): number {
+  if (value === 0) return 0
+
+  const exponent = Math.floor(Math.log10(Math.abs(value)))
+  const fraction = Math.abs(value) / Math.pow(10, exponent)
+
+  let niceFraction: number
+  if (round) {
+    // 向上取整到 1, 2, 5, 10
+    if (fraction < 1.5) niceFraction = 1
+    else if (fraction < 3) niceFraction = 2
+    else if (fraction < 7) niceFraction = 5
+    else niceFraction = 10
+  } else {
+    // 向下取整到 1, 2, 5, 10
+    if (fraction <= 1) niceFraction = 1
+    else if (fraction <= 2) niceFraction = 2
+    else if (fraction <= 5) niceFraction = 5
+    else niceFraction = 10
+  }
+
+  return niceFraction * Math.pow(10, exponent) * Math.sign(value)
+}
+
+export interface NiceScaleResult {
+  /** 扩展后的最小值 */
+  niceMin: number
+  /** 扩展后的最大值 */
+  niceMax: number
+  /** 刻度间隔 */
+  tickSpacing: number
+  /** 刻度值数组 */
+  ticks: number[]
+}
+
+/**
+ * 计算 ECharts 风格的优雅刻度
+ * @param min - 数据最小值
+ * @param max - 数据最大值
+ * @param maxTicks - 期望的最大刻度数（类似 ECharts 的 splitNumber，默认 5）
+ * @returns 刻度计算结果
+ */
+export function calculateNiceScale(min: number, max: number, maxTicks = 5): NiceScaleResult {
+  // 处理边界情况
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    return { niceMin: 0, niceMax: 1, tickSpacing: 1, ticks: [0, 1] }
+  }
+
+  if (min === max) {
+    if (min === 0) {
+      // 特殊处理零点
+      return {
+        niceMin: -1,
+        niceMax: 1,
+        tickSpacing: 0.5,
+        ticks: [-1, -0.5, 0, 0.5, 1],
+      }
+    }
+    const value = min
+    const spacing = Math.abs(value) * 0.2
+    return {
+      niceMin: value - spacing,
+      niceMax: value + spacing,
+      tickSpacing: spacing,
+      ticks: [value - spacing, value, value + spacing],
+    }
+  }
+
+  // 确保 min < max
+  if (min > max) {
+    ;[min, max] = [max, min]
+  }
+
+  const range = max - min
+
+  // 计算优雅的刻度间隔
+  const roughTickSpacing = range / Math.max(1, maxTicks - 1)
+  const tickSpacing = niceNumber(roughTickSpacing, true)
+
+  // 计算优雅的边界
+  const niceMin = Math.floor(min / tickSpacing) * tickSpacing
+  const niceMax = Math.ceil(max / tickSpacing) * tickSpacing
+
+  // 生成刻度值
+  const ticks: number[] = []
+  const tickCount = Math.round((niceMax - niceMin) / tickSpacing) + 1
+
+  // 防止刻度过多（安全检查）
+  if (tickCount > 100) {
+    // 退回到简单的线性刻度
+    const safeTickCount = Math.min(maxTicks + 2, 10)
+    const safeSpacing = (max - min) / (safeTickCount - 1)
+    for (let i = 0; i < safeTickCount; i++) {
+      ticks.push(min + safeSpacing * i)
+    }
+    return {
+      niceMin: min,
+      niceMax: max,
+      tickSpacing: safeSpacing,
+      ticks,
+    }
+  }
+
+  // 生成刻度值（处理浮点数精度问题）
+  for (let i = 0; i < tickCount; i++) {
+    const tick = niceMin + tickSpacing * i
+    // 修正浮点数误差 - 使用更智能的四舍五入
+    // 确定合适的精度（基于刻度间隔的量级）
+    const precision = Math.max(0, -Math.floor(Math.log10(Math.abs(tickSpacing))) + 1)
+    const roundedTick = Number(tick.toFixed(precision))
+    ticks.push(roundedTick)
+  }
+
+  return {
+    // Keep floating-point multiplication from shrinking the enclosing data domain.
+    niceMin: Math.min(min, ticks[0] ?? niceMin),
+    niceMax: Math.max(max, ticks.at(-1) ?? niceMax),
+    tickSpacing,
+    ticks,
+  }
+}
+
+/**
+ * ECharts 兼容的刻度计算（与 resolveYAxisTicks 接口兼容）
+ */
+export function resolveYAxisTicksECharts(
+  domain: [number, number],
+  tickCount = 5,
+): { domain: [number, number]; values: number[] } {
+  const result = calculateNiceScale(domain[0], domain[1], tickCount)
+  return {
+    domain: [result.niceMin, result.niceMax],
+    values: result.ticks,
+  }
+}

package/src/components/core/pagination.ts

@@ -1,17 +1,4 @@
-/** Conservative Ant pagination sizing, including first/last pages and both ellipses. */
-export function resolveCompactPaginationBand(
-  visible: boolean,
-  width: number,
-  pageCount: number,
-  timeLabelCenter: number,
-  timeLabel: string,
-): 0 | 16 | 40 {
-  if (!visible) return 0
-  if (width <= 520) return 40
-  const controls = Math.min(pageCount, 9) + 2
-  const paginationWidth = controls * 32 + controls * 8
-  // A full 18px em per character also accommodates wide glyphs and Chinese labels.
-  const labelRight = timeLabelCenter + (Array.from(timeLabel).length * 18) / 2
-  const availableWidth = width - 10 - labelRight - 8
-  return availableWidth >= paginationWidth ? 16 : 40
+/** Keep compact chart height stable regardless of pagination width or page count. */
+export function resolveCompactPaginationBand(visible: boolean): 0 | 16 {
+  return visible ? 16 : 0
 }