waveform-analysis 0.1.71 → 0.1.73

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/trackLayoutBuilder.ts

@@ -1,3 +1,6 @@
+import { withMaximumTick, type YAxisPaddingOptions } from './yAxisPadding'
+import { selectSeriesRenderSourcePoints } from '../../core/rendering'
+import { pointSourceFromPoints } from '../../core/waveformPointSource'
 import {
   curveStep,
   curveStepAfter,
@@ -8,10 +11,7 @@ import {
   type ZoomTransform,
 } from 'd3'
 
-import {
-  selectSeriesRenderPoints,
-  type ResolvedWaveformRenderingOptions,
-} from '../../core/rendering'
+import { type ResolvedWaveformRenderingOptions } from '../../core/rendering'
 import type {
   WaveformDisplayMode,
   WaveformOverlayMode,
@@ -36,6 +36,7 @@ import type { DisplayTrack, TrackLayout, WaveformYAxisLayout } from './types'
 import { applyXDomainStrategy } from './xDomain'
 import { alignLeftYAxisTitles } from './yAxisTitleLayout'
 import { measureYAxisTextWidth } from './yAxisTextWidth'
+import { resolveYAxisLabelBandWidth } from './yAxisLabelStyle'
 import {
   alignIntegerZoomDomain,
   normalizeIntegerZoomDomain,
@@ -43,7 +44,6 @@ import {
   formatIntegerZoomLabel,
 } from '../interaction/integerZoom'
 import {
-  Y_AXIS_LABEL_BAND_WIDTH,
   Y_AXIS_LABEL_GAP,
   Y_AXIS_OUTER_PADDING,
   Y_AXIS_RIGHT_LABEL_OFFSET,
@@ -61,6 +61,7 @@ export interface BuildTrackLayoutsOptions {
   overlayMode: WaveformOverlayMode
   independentTransforms: ZoomTransform[]
   sharedZoomDomain: [number, number]
+  effectiveXDomains?: Record<string, [number, number]>
   initialXDomain?: [number, number]
   initialXDomains?: Record<string, [number, number]>
   xDomainStrategy?: WaveformXDomainStrategy
@@ -72,6 +73,7 @@ export interface BuildTrackLayoutsOptions {
   xAxisLabelFormatter?: WaveformXAxisLabelFormatter
   yAxisSplitNumber?: number
   yAxisNice?: boolean
+  yAxisPadding?: YAxisPaddingOptions
   yAxisUpperPaddingRatio?: number
   rendering: ResolvedWaveformRenderingOptions
   /** Latest sampling result for SVG lines only; source series remain complete for interaction. */
@@ -80,7 +82,7 @@ export interface BuildTrackLayoutsOptions {
   yAxisLabelX: number
   yLabel?: string
   yAxisSlots?: readonly YAxisSlot[]
-  showCompactEmptyTracks: boolean
+  showEmptyTracks: boolean
   useNonEmptyBottomTracks?: boolean
   compactYAxisLayout?: boolean
   showAxisUnits?: boolean
@@ -91,6 +93,7 @@ function resolveIndependentXDomain(
   seriesId: string,
   options: BuildTrackLayoutsOptions,
 ): [number, number] {
+  if (options.effectiveXDomains?.[track.id]) return options.effectiveXDomains[track.id]
   const strategy = options.xDomainStrategy ?? { type: 'data' }
   const explicitDomain =
     options.initialXDomains?.[track.id] ??
@@ -115,13 +118,12 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
 
   const layouts: TrackLayout[] = visibleCells.flatMap((cell, index) => {
     const isEmpty = !cell.series || cell.series.series.length === 0
-    if (!cell.series && (options.displayMode !== 'compact' || !options.showCompactEmptyTracks))
-      return []
+    if (!cell.series && !options.showEmptyTracks) return []
     const displayTrack: DisplayTrack = cell.series ?? {
       id: `empty-grid-slot-${cell.slotIndex}`,
       series: [],
       visibleSeries: [],
-      xDomain: [0, 1],
+      xDomain: options.initialXDomain ?? options.sharedZoomDomain,
       yDomain: [0, 1],
     }
     const hasVisibleSeries = !isEmpty && displayTrack.visibleSeries.length > 0
@@ -145,7 +147,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
       options.fixedYDomain,
       options.fixedYDomains,
       options.yDomains,
-      options.yAxisUpperPaddingRatio,
+      options.yAxisPadding ?? options.yAxisUpperPaddingRatio,
     )
     const sideIndexes = { left: 0, right: 0 }
     const sideOffsets = { left: 0, right: 0 }
@@ -155,7 +157,19 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
       const resolvedTicks = resolveYAxisTicks(group.domain, tickCount, options.yAxisNice !== false)
       const scale = scaleLinear(resolvedTicks.domain, [cell.plotHeight, 0])
       const majorTicks = resolvedTicks.values
-      const tickValues = majorTicks
+      const maximumTick =
+        group.maximumTick !== undefined &&
+        group.maximumTick >= resolvedTicks.domain[0] &&
+        group.maximumTick <= resolvedTicks.domain[1]
+          ? group.maximumTick
+          : undefined
+      const minimumTick =
+        group.minimumTick !== undefined &&
+        group.minimumTick >= resolvedTicks.domain[0] &&
+        group.minimumTick <= resolvedTicks.domain[1]
+          ? group.minimumTick
+          : undefined
+      const tickValues = withMaximumTick(majorTicks, maximumTick, minimumTick)
       const { tickTextWidth } = axisTextMetrics(
         scale.domain() as [number, number],
         false,
@@ -167,7 +181,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
         tickTextWidth +
         Y_AXIS_TICK_PADDING +
         Y_AXIS_LABEL_GAP +
-        Y_AXIS_LABEL_BAND_WIDTH +
+        resolveYAxisLabelBandWidth(options.yAxisPadding?.labelTextStyle) +
         Y_AXIS_OUTER_PADDING
       const slot = options.yAxisSlots?.find(
         (candidate) => candidate.side === group.side && candidate.sideIndex === sideIndex,
@@ -178,7 +192,10 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
           ? -sideOffsets.left
           : cell.width + sideOffsets.right
       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 +
+        resolveYAxisLabelBandWidth(options.yAxisPadding?.labelTextStyle) / 2
       const labelX =
         (slot
           ? (group.side === 'left' ? 0 : cell.width) + slot.labelOffset
@@ -191,6 +208,8 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
         x,
         labelX,
         scale,
+        maximumTick,
+        minimumTick,
         majorTicks,
         minorTicks: buildMinorTicks(majorTicks, 2),
         tickValues,
@@ -207,7 +226,11 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
     )
     const xAxisLabelFormatter =
       options.xAxisLabelFormatter ?? (options.integerZoom ? formatIntegerZoomLabel : undefined)
-    const yMajorTicks = yAxes[0]?.majorTicks ?? []
+    const yMajorTicks =
+      yAxes[0]?.majorTicks ??
+      (isEmpty
+        ? fallbackYScale.ticks(resolveYAxisTickCount(cell.plotHeight, options.yAxisSplitNumber))
+        : [])
     const yAxisTickValues = yAxes[0]?.tickValues ?? []
     const domain = xScale.domain() as [number, number]
     const endpointLabels = {
@@ -225,8 +248,8 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
         axis.seriesList.some((series) => series.id === trackSeries.id),
       )
       const seriesYScale = yAxis?.scale ?? yScale
-      const renderPoints = selectSeriesRenderPoints(
-        trackSeries.points,
+      const renderPoints = selectSeriesRenderSourcePoints(
+        trackSeries.source ?? pointSourceFromPoints(trackSeries.points),
         domain,
         cell.width,
         options.rendering,
@@ -278,7 +301,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
       xAxisLabelFormatter,
       xMinorTicks: buildMinorTicks(xMajorTicks, 3, domain),
       yMajorTicks,
-      yMinorTicks: yAxes[0]?.minorTicks ?? [],
+      yMinorTicks: yAxes[0]?.minorTicks ?? (isEmpty ? buildMinorTicks(yMajorTicks, 2) : []),
       yAxisTickValues,
       xAxisTickValues,
       endpointLabels,
@@ -297,6 +320,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
   })
 
   alignLeftYAxisTitles(layouts, options.yLabel, {
+    labelTextStyle: options.yAxisPadding?.labelTextStyle,
     showUnits: options.showAxisUnits,
     compact: options.compactYAxisLayout,
     measureTextWidth: options.compactYAxisLayout ? measureYAxisTextWidth : undefined,

package/src/components/core/trackPagination.ts

@@ -27,14 +27,14 @@ export const createFrameNumberResolver =
     getFrameNumbers: () => Record<string, string | number> | undefined,
     getTracks: () => DisplayTrack[],
   ) =>
-  (trackId: string): string | number | undefined => {
+  (trackId: string, slotIndex = 0): string | number | undefined => {
     const tracks = getTracks()
     const trackIndex = tracks.findIndex((track) => track.id === trackId)
     return resolveTrackFrameNumber(
       getFrameNumber(),
       getFrameNumbers(),
-      tracks.length,
-      trackIndex >= 0 ? trackIndex : 0,
+      Math.max(tracks.length, slotIndex + 1),
+      trackIndex >= 0 ? trackIndex : slotIndex,
       trackId,
     )
   }

package/src/components/core/types.ts

@@ -27,6 +27,8 @@ export interface DisplaySeries {
   points: WaveformPoint[]
   source?: WaveformPointSource
   xDomain: [number, number]
+  rawYMaximum?: number
+  rawYMinimum?: number
   yDomain: [number, number]
   hasErrorPoints: boolean
 }
@@ -38,6 +40,7 @@ export interface DisplayTrack {
   /** Series currently participating in layout, rendering, and interaction. */
   visibleSeries: DisplaySeries[]
   xDomain: [number, number]
+  rawYMaximum?: number
   yDomain: [number, number]
 }
 
@@ -51,6 +54,8 @@ export interface TrackSeriesPath {
 }
 
 export interface WaveformYAxisLayout {
+  maximumTick?: number
+  minimumTick?: number
   index: number
   side: 'left' | 'right'
   x: number

package/src/components/core/useWaveformChartController.ts

@@ -1,7 +1,13 @@
+import { chartExportOptions } from '../controls/chartExportOptions'
+import { useChartImageExport } from '../controls/useChartImageExport'
+import { useControlMode } from '../controls/useControlMode'
+import { useChartCommands } from '../controls/useChartCommands'
 import { zoomIdentity, type ZoomTransform } from 'd3'
 import {
   computed,
   reactive,
+  nextTick,
+  onBeforeUnmount,
   markRaw,
   ref,
   shallowReactive,
@@ -44,9 +50,15 @@ function assignElement<T extends Element>(
 }
 
 export function useWaveformChartController(
-  props: ResolvedWaveformChartProps,
+  inputProps: ResolvedWaveformChartProps,
   emit: WaveformChartEmit,
 ) {
+  const mode = useControlMode(inputProps, emit)
+  const props = reactive({
+    ...toRefs(inputProps),
+    interactionMode: mode.mode,
+  }) as ResolvedWaveformChartProps
+  const boundaries = shallowRef<Record<string, [number, number]>>({})
   const container = ref<HTMLDivElement>()
   const svgElement = ref<SVGSVGElement>()
   const titleMeasureElement = ref<HTMLSpanElement>()
@@ -137,6 +149,7 @@ export function useWaveformChartController(
     independentYDomains,
     annotationInteraction: markRaw(annotationInteraction),
     linePointOverrides,
+    boundaries,
   })
   const {
     chartSeries,
@@ -164,7 +177,7 @@ export function useWaveformChartController(
     presentation.titleAreaStyle,
   )
 
-  useWaveformRenderSampling({
+  const sampling = useWaveformRenderSampling({
     props,
     emit,
     instanceId: clipPathId,
@@ -229,6 +242,7 @@ export function useWaveformChartController(
   })
 
   const viewport = useWaveformViewport({
+    clearBoundaries: (index) => commands.clearBoundaries(index),
     props,
     emit,
     selection,
@@ -272,7 +286,50 @@ export function useWaveformChartController(
     resolveTrackAtPointer: annotations.resolveTrackAtPointer,
   })
 
+  const cancelControls = () => {
+    viewport.cancelViewportDrag()
+    zoom.cancelPendingZoom()
+    hover.clearHover()
+    annotations.cancelAnnotation()
+  }
+  const commands = useChartCommands({
+    props,
+    emit,
+    layout,
+    mode,
+    boundaries,
+    independentTransforms,
+    sharedTransform,
+    independentYDomains,
+    sharedYDomains,
+    cancel: cancelControls,
+    configure: zoom.configureZoom,
+    legacyReset: viewport.resetViewport,
+    legacySet: viewport.setViewportDomain,
+  })
+  watch(
+    [mode.mode, () => props.zoomable, () => props.pannable, () => props.annotationsVisible],
+    cancelControls,
+    { flush: 'sync' },
+  )
+  watch([currentPage, () => props.displayMode], () => {
+    boundaries.value = {}
+    cancelControls()
+  })
+  watch(
+    [
+      () => props.initialXDomain,
+      () => props.initialXDomains,
+      hiddenSeriesIdSet,
+      () => props.xDomainStrategy,
+    ],
+    commands.restoreInitialBoundaries,
+    { deep: true },
+  )
+  onBeforeUnmount(cancelControls)
+
   const lifecycle = useWaveformChartLifecycle({
+    preserveFullViewport: () => Object.keys(boundaries.value).length > 0,
     props,
     emit,
     container,
@@ -317,7 +374,39 @@ export function useWaveformChartController(
     clearZoomBindings: zoom.clearZoomBindings,
   })
   handleBeforeDataReferenceChange = lifecycle.handleBeforeDataReferenceChange
-  handleDataReferenceChange = lifecycle.handleDataReferenceChange
+  handleDataReferenceChange = () => {
+    boundaries.value = {}
+    viewport.cancelViewportDrag()
+    lifecycle.handleDataReferenceChange()
+    void nextTick(zoom.configureZoom)
+  }
+
+  const imageExport = useChartImageExport({
+    container: () => container.value,
+    svg: () => svgElement.value,
+    size: () => ({
+      width: chartWidth.value,
+      height: chartHeight.value,
+      titleHeight: titleAreaHeight.value,
+    }),
+    version: () => [
+      props.data,
+      JSON.stringify({
+        ...chartExportOptions(props),
+        hidden: [...hiddenSeriesIdSet.value],
+        width: chartWidth.value,
+        height: chartHeight.value,
+        titleHeight: titleAreaHeight.value,
+        page: currentPage.value,
+        shared: sharedTransform.value,
+        independent: independentTransforms.value,
+        sharedY: sharedYDomains.value,
+        independentY: independentYDomains.value,
+        boundaries: boundaries.value,
+      }),
+    ],
+    ready: sampling.ready,
+  })
 
   return reactive({
     ...toRefs(props),
@@ -329,6 +418,8 @@ export function useWaveformChartController(
     ...annotations,
     ...viewport,
     ...hover,
+    ...commands,
+    ...imageExport,
     margin,
     getPageSize,
     currentPage,