feat(chart): support fixed y-axis domains

src/components/core/fixedYDomainLayout.test.ts

@@ -0,0 +1,116 @@
+import { zoomIdentity } from 'd3'
+import { describe, expect, it } from 'vitest'
+
+import { DEFAULT_WAVEFORM_RENDERING_OPTIONS } from '../../core'
+import type { DisplaySeries, DisplayTrack } from './types'
+import { buildTrackLayouts, resolveYAxisSeriesGroups } from './layout'
+
+function series(id: string, minimum: number, maximum: number): DisplaySeries {
+  return {
+    id,
+    name: id,
+    color: '#1677ff',
+    lineType: 'linear',
+    lineStyle: 'solid',
+    pointType: 'none',
+    errorBar: { visible: false, width: 1.5, capWidth: 8 },
+    points: [
+      { x: 0, y: minimum },
+      { x: 1, y: maximum },
+    ],
+    xDomain: [0, 1],
+    yDomain: [minimum, maximum],
+    hasErrorPoints: false,
+  }
+}
+
+function track(seriesList: DisplaySeries[]): DisplayTrack {
+  return {
+    id: 'track',
+    series: seriesList,
+    visibleSeries: seriesList,
+    xDomain: [0, 1],
+    yDomain: [0, 100],
+  }
+}
+
+describe('fixed Y-domain layout', () => {
+  it('uses an exact global fixed domain without applying nice bounds', () => {
+    const sourceTrack = track([series('a', 0, 100)])
+    const result = buildTrackLayouts({
+      cells: [
+        {
+          slotIndex: 0,
+          row: 0,
+          column: 0,
+          left: 0,
+          top: 0,
+          width: 120,
+          height: 100,
+          plotHeight: 100,
+          cellHeight: 130,
+          xAxisBand: 30,
+          series: sourceTrack,
+        },
+      ],
+      grid: { rowCount: 1, columnCount: 1, showPagination: false, trackLines: {} },
+      displayMode: 'independent',
+      overlayMode: 'single-axis',
+      independentTransforms: [zoomIdentity],
+      sharedZoomDomain: [0, 1],
+      fixedYDomain: [3, 97],
+      timeUnit: 'ms',
+      rendering: DEFAULT_WAVEFORM_RENDERING_OPTIONS,
+      hideSecondaryLabels: false,
+      yAxisLabelX: -50,
+      showCompactEmptyTracks: false,
+    })[0]
+
+    expect(result?.yScale.domain()).toEqual([3, 97])
+    expect(result?.yAxes[0]?.tickValues).toContain(3)
+    expect(result?.yAxes[0]?.tickValues).toContain(97)
+    expect(result?.seriesPaths[0]?.yScale.domain()).toEqual([3, 97])
+  })
+
+  it('resolves track, series, and global fixed-domain precedence', () => {
+    const sourceTrack = track([series('a', 0, 10), series('b', 20, 30)])
+
+    expect(
+      resolveYAxisSeriesGroups(sourceTrack, 'single-axis', [-5, 5], {
+        a: [-10, 10],
+        track: [300, 100],
+      })[0]?.domain,
+    ).toEqual([100, 300])
+
+    expect(
+      resolveYAxisSeriesGroups(sourceTrack, 'single-axis', [-5, 5], {
+        a: [-10, 10],
+      })[0]?.domain,
+    ).toEqual([-10, 10])
+  })
+
+  it('keeps per-series fixed domains on separate axes and merges axis overflow', () => {
+    const sourceTrack = track([
+      series('a', 0, 1),
+      series('b', 10, 11),
+      series('c', 20, 21),
+      series('d', 30, 31),
+      series('e', 40, 41),
+    ])
+    const groups = resolveYAxisSeriesGroups(sourceTrack, 'multi-axis', undefined, {
+      a: [-1, 1],
+      b: [-2, 2],
+      c: [-3, 3],
+      d: [-4, 4],
+      e: [-5, 5],
+    })
+
+    expect(groups.map((group) => group.domain)).toEqual([
+      [-1, 1],
+      [-2, 2],
+      [-3, 3],
+      [-5, 5],
+    ])
+    expect(groups.every((group) => group.fixed)).toBe(true)
+  })
+})

src/components/core/layout.ts

@@ -4,6 +4,12 @@ import type { WaveformOverlayMode } from '../../types'
 import { formatScientificAxisExponent, formatScientificAxisLabel, paddedDomain } from '../../utils'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
 import { MAX_MULTI_Y_AXIS_COUNT, Y_AXIS_EXPONENT_GAP } from './constants'
+import {
+  mergeYDomains,
+  resolveSeriesFixedYDomain,
+  resolveTrackFixedYDomain,
+  type WaveformYDomain,
+} from './yDomain'
 
 // 导出常量供外部使用
 export { MAX_MULTI_Y_AXIS_COUNT, Y_AXIS_EXPONENT_GAP } from './constants'
@@ -14,11 +20,12 @@ const Y_AXIS_OUTER_PADDING = 4
 const Y_AXIS_LABEL_GAP = 6
 const Y_AXIS_LABEL_BAND_WIDTH = 24
 
-interface YAxisSeriesGroup {
+export interface YAxisSeriesGroup {
   index: number
   side: 'left' | 'right'
   seriesList: DisplaySeries[]
   domain: [number, number]
+  fixed: boolean
 }
 
 function resolveAxisSides(axisCount: number): Array<'left' | 'right'> {
@@ -53,6 +60,7 @@ export function buildYAxisSeriesGroups(
     side: sides[index],
     seriesList: [] as DisplaySeries[],
     domain: [0, 1] as [number, number],
+    fixed: false,
   }))
 
   track.visibleSeries.forEach((series, index) => {
@@ -72,12 +80,35 @@ export function buildYAxisSeriesGroups(
   return grouped
 }
 
-export function axisTextMetrics(domain: [number, number]): {
+export function resolveYAxisSeriesGroups(
+  track: DisplayTrack,
+  overlayMode: WaveformOverlayMode,
+  yDomain?: WaveformYDomain,
+  yDomains?: Record<string, WaveformYDomain>,
+): YAxisSeriesGroup[] {
+  const trackDomain = resolveTrackFixedYDomain(track, yDomains)
+  return buildYAxisSeriesGroups(track, overlayMode).map((group) => {
+    if (trackDomain) return { ...group, domain: trackDomain, fixed: true }
+    const seriesDomains = group.seriesList.map(
+      (series) => resolveSeriesFixedYDomain(series, yDomain, yDomains) ?? series.yDomain,
+    )
+    const fixed = group.seriesList.some((series) =>
+      resolveSeriesFixedYDomain(series, yDomain, yDomains),
+    )
+    return fixed ? { ...group, domain: mergeYDomains(seriesDomains), fixed } : group
+  })
+}
+
+export function axisTextMetrics(
+  domain: [number, number],
+  nice = true,
+): {
   exponentLabel: string | null
   exponentWidth: number
   tickTextWidth: number
 } {
-  const scale = scaleLinear(domain, [1, 0]).nice()
+  const scale = scaleLinear(domain, [1, 0])
+  if (nice) scale.nice()
   const [axisMin, axisMax] = scale.domain()
   const values = scale.ticks(10)
   const maximumTickCharacters = Math.max(
@@ -92,15 +123,15 @@ export function axisTextMetrics(domain: [number, number]): {
   }
 }
 
-function axisExponentClearance(domain: [number, number]): number {
-  const { exponentLabel, exponentWidth } = axisTextMetrics(domain)
+function axisExponentClearance(domain: [number, number], nice: boolean): number {
+  const { exponentLabel, exponentWidth } = axisTextMetrics(domain, nice)
   return exponentLabel ? exponentWidth + Y_AXIS_EXPONENT_GAP : 0
 }
 
 export function measureYAxisGroupClearance(group: YAxisSeriesGroup): number {
   return (
-    axisTextMetrics(group.domain).tickTextWidth +
-    axisExponentClearance(group.domain) +
+    axisTextMetrics(group.domain, !group.fixed).tickTextWidth +
+    axisExponentClearance(group.domain, !group.fixed) +
     Y_AXIS_TICK_PADDING +
     Y_AXIS_LABEL_GAP +
     Y_AXIS_LABEL_BAND_WIDTH +
@@ -110,8 +141,8 @@ export function measureYAxisGroupClearance(group: YAxisSeriesGroup): number {
 
 function measureYAxisGroupTickClearance(group: YAxisSeriesGroup): number {
   return (
-    axisTextMetrics(group.domain).tickTextWidth +
-    axisExponentClearance(group.domain) +
+    axisTextMetrics(group.domain, !group.fixed).tickTextWidth +
+    axisExponentClearance(group.domain, !group.fixed) +
     Y_AXIS_TICK_PADDING +
     Y_AXIS_OUTER_PADDING
   )
@@ -120,8 +151,10 @@ function measureYAxisGroupTickClearance(group: YAxisSeriesGroup): number {
 export function measureTrackYAxisClearance(
   track: DisplayTrack,
   overlayMode: WaveformOverlayMode,
+  yDomain?: WaveformYDomain,
+  yDomains?: Record<string, WaveformYDomain>,
 ): { left: number; right: number } {
-  return buildYAxisSeriesGroups(track, overlayMode).reduce(
+  return resolveYAxisSeriesGroups(track, overlayMode, yDomain, yDomains).reduce(
     (clearance, group) => {
       clearance[group.side] +=
         overlayMode === 'multi-axis' || track.visibleSeries.length === 1

src/components/core/trackLayoutBuilder.ts

@@ -19,7 +19,7 @@ import {
   type GridCellGeometry,
   type NormalizedWaveformGridOptions,
 } from './grid'
-import { axisTextMetrics, buildYAxisSeriesGroups } from './layout'
+import { axisTextMetrics, resolveYAxisSeriesGroups } from './layout'
 import type { DisplaySeries, DisplayTrack, TrackLayout, WaveformYAxisLayout } from './types'
 import { Y_AXIS_EXPONENT_GAP } from './constants'
 import {
@@ -42,6 +42,8 @@ export interface BuildTrackLayoutsOptions {
   sharedZoomDomain: [number, number]
   initialXDomain?: [number, number]
   initialXDomains?: Record<string, [number, number]>
+  fixedYDomain?: [number, number]
+  fixedYDomains?: Record<string, [number, number]>
   yDomains?: Record<string, [number, number]>
   timeUnit: 's' | 'ms'
   rendering: ResolvedWaveformRenderingOptions
@@ -94,13 +96,18 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
         : zoomIdentity
     const xScale = transform.rescaleX(baseXScale)
     const configuredYDomain = options.yDomains?.[displayTrack.id]
-    const yAxisGroups = buildYAxisSeriesGroups(displayTrack, options.overlayMode).map((group) => ({
-      ...group,
-      domain: configuredYDomain ?? group.domain,
-    }))
+    const yAxisGroups = resolveYAxisSeriesGroups(
+      displayTrack,
+      options.overlayMode,
+      options.fixedYDomain,
+      options.fixedYDomains,
+    ).map((group) =>
+      !group.fixed && configuredYDomain ? { ...group, domain: configuredYDomain } : group,
+    )
     const sideOffsets = { left: 0, right: 0 }
     const yAxes: WaveformYAxisLayout[] = yAxisGroups.map((group) => {
-      const scale = scaleLinear(group.domain, [cell.plotHeight, 0]).nice()
+      const scale = scaleLinear(group.domain, [cell.plotHeight, 0])
+      if (!group.fixed) scale.nice()
       const majorTicks = scale.ticks(Math.max(2, Math.floor(cell.plotHeight / 55)))
       const [axisStart, axisEnd] = scale.domain()
       const showAxisEnd = options.displayMode !== 'compact' || cell.row === 0
@@ -110,7 +117,10 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
       const tickValues = Array.from(
         new Set([axisStart, ...visibleMajorTicks, ...(showAxisEnd ? [axisEnd] : [])]),
       )
-      const { exponentLabel, exponentWidth, tickTextWidth } = axisTextMetrics(group.domain)
+      const { exponentLabel, exponentWidth, tickTextWidth } = axisTextMetrics(
+        group.domain,
+        !group.fixed,
+      )
       const exponentClearance = exponentLabel ? exponentWidth + Y_AXIS_EXPONENT_GAP : 0
       const clearance =
         tickTextWidth +

src/components/core/useWaveformChartController.ts

@@ -6,6 +6,7 @@ import {
   shallowReactive,
   shallowRef,
   toRefs,
+  watch,
   watchEffect,
   type ComponentPublicInstance,
   type Ref,
@@ -68,6 +69,15 @@ export function useWaveformChartController(
   const annotationInteraction = useWaveformAnnotationInteraction()
   const editorSeriesOptions = ref<AnnotationSeriesCandidate[]>([])
   const hoverThrottle = useAnimationFrameThrottle()
+
+  watch(
+    [() => props.yDomain, () => props.yDomains],
+    () => {
+      sharedYDomains.value = {}
+      independentYDomains.value = {}
+    },
+    { deep: true },
+  )
   const selection = ref<ViewportSelectionState | null>(null)
   const spacePressed = ref(false)
   const pointerInsideChart = ref(false)

src/components/core/useWaveformLayout.ts

@@ -26,7 +26,12 @@ import {
   resolveGridCellGeometry,
   X_AXIS_BAND,
 } from './grid'
-import { buildTrackLayouts, measureTrackYAxisClearance, Y_AXIS_EXPONENT_GAP } from './layout'
+import {
+  buildTrackLayouts,
+  measureTrackYAxisClearance,
+  resolveYAxisSeriesGroups,
+  Y_AXIS_EXPONENT_GAP,
+} from './layout'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
 import type { PreparedWaveformSeries } from './useWaveformData'
 import type { ResolvedWaveformChartProps } from './waveformChartTypes'
@@ -104,8 +109,12 @@ export function useWaveformLayout(context: LayoutContext) {
   const yAxisMetrics = computed(() => {
     const axisText = chartTracks.value
       .filter((track) => track.visibleSeries.length > 0)
-      .map((track) => {
-        const scale = scaleLinear(track.yDomain, [1, 0]).nice()
+      .flatMap((track) =>
+        resolveYAxisSeriesGroups(track, props.overlayMode, props.yDomain, props.yDomains),
+      )
+      .map((group) => {
+        const scale = scaleLinear(group.domain, [1, 0])
+        if (!group.fixed) scale.nice()
         const [axisMin, axisMax] = scale.domain()
         return {
           exponentLabel: formatScientificAxisExponent(axisMin, axisMax),
@@ -165,7 +174,12 @@ export function useWaveformLayout(context: LayoutContext) {
   const multiAxisClearance = computed(() =>
     chartTracks.value.reduce(
       (maximum, track) => {
-        const clearance = measureTrackYAxisClearance(track, props.overlayMode)
+        const clearance = measureTrackYAxisClearance(
+          track,
+          props.overlayMode,
+          props.yDomain,
+          props.yDomains,
+        )
         return {
           left: Math.max(maximum.left, clearance.left),
           right: Math.max(maximum.right, clearance.right),
@@ -281,6 +295,8 @@ export function useWaveformLayout(context: LayoutContext) {
       sharedZoomDomain: sharedZoomDomain.value,
       initialXDomain: props.initialXDomain ? initialXDomain.value : undefined,
       initialXDomains: props.initialXDomains,
+      fixedYDomain: props.yDomain,
+      fixedYDomains: props.yDomains,
       yDomains:
         props.displayMode === 'independent'
           ? Object.fromEntries(

src/components/core/waveformChartTypes.ts

@@ -31,6 +31,8 @@ export interface WaveformChartProps {
   minVisiblePoints?: number
   initialXDomain?: [number, number]
   initialXDomains?: Record<string, [number, number]>
+  yDomain?: [number, number]
+  yDomains?: Record<string, [number, number]>
   timeUnit?: 's' | 'ms'
   frameNumber?: string | number
   frameStyle?: WaveformFrameStyle

src/components/core/yDomain.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+
+import type { DisplayTrack } from './types'
+import { hasFixedYDomainForTrack, mergeYDomains, normalizeYDomain } from './yDomain'
+
+const track: DisplayTrack = {
+  id: 'shared-track',
+  series: [],
+  visibleSeries: [
+    {
+      id: 'channel-a',
+      name: 'A',
+      color: '#1677ff',
+      lineType: 'linear',
+      lineStyle: 'solid',
+      pointType: 'none',
+      errorBar: { visible: false, width: 1.5, capWidth: 8 },
+      points: [],
+      xDomain: [0, 1],
+      yDomain: [0, 1],
+      hasErrorPoints: false,
+    },
+  ],
+  xDomain: [0, 1],
+  yDomain: [0, 1],
+}
+
+describe('fixed Y domains', () => {
+  it('normalizes valid reversed domains', () => {
+    expect(normalizeYDomain([97, 3])).toEqual([3, 97])
+    expect(normalizeYDomain([-10, 10])).toEqual([-10, 10])
+  })
+
+  it.each([undefined, [1, 1], [Number.NaN, 1], [0, Number.POSITIVE_INFINITY]])(
+    'rejects an invalid domain: %j',
+    (domain) => {
+      expect(normalizeYDomain(domain as [number, number] | undefined)).toBeUndefined()
+    },
+  )
+
+  it('detects valid track, series, and global configuration only', () => {
+    expect(hasFixedYDomainForTrack(track, [-1, 1])).toBe(true)
+    expect(hasFixedYDomainForTrack(track, undefined, { 'shared-track': [-2, 2] })).toBe(true)
+    expect(hasFixedYDomainForTrack(track, undefined, { 'channel-a': [-3, 3] })).toBe(true)
+    expect(hasFixedYDomainForTrack(track, [0, 0], { 'channel-a': [1, 1] })).toBe(false)
+  })
+
+  it('merges configured and automatic series domains without padding', () => {
+    expect(
+      mergeYDomains([
+        [3, 97],
+        [-20, 40],
+      ]),
+    ).toEqual([-20, 97])
+  })
+})

src/components/core/yDomain.ts

@@ -0,0 +1,50 @@
+import type { DisplaySeries, DisplayTrack } from './types'
+
+export type WaveformYDomain = [number, number]
+
+export function normalizeYDomain(
+  domain: readonly [number, number] | undefined,
+): WaveformYDomain | undefined {
+  if (
+    !domain ||
+    !Number.isFinite(domain[0]) ||
+    !Number.isFinite(domain[1]) ||
+    domain[0] === domain[1]
+  ) {
+    return undefined
+  }
+  return domain[0] < domain[1] ? [domain[0], domain[1]] : [domain[1], domain[0]]
+}
+
+export function resolveTrackFixedYDomain(
+  track: Pick<DisplayTrack, 'id'>,
+  yDomains?: Record<string, WaveformYDomain>,
+): WaveformYDomain | undefined {
+  return normalizeYDomain(yDomains?.[track.id])
+}
+
+export function resolveSeriesFixedYDomain(
+  series: Pick<DisplaySeries, 'id'>,
+  yDomain?: WaveformYDomain,
+  yDomains?: Record<string, WaveformYDomain>,
+): WaveformYDomain | undefined {
+  return normalizeYDomain(yDomains?.[series.id]) ?? normalizeYDomain(yDomain)
+}
+
+export function hasFixedYDomainForTrack(
+  track: Pick<DisplayTrack, 'id' | 'visibleSeries'>,
+  yDomain?: WaveformYDomain,
+  yDomains?: Record<string, WaveformYDomain>,
+): boolean {
+  return Boolean(
+    resolveTrackFixedYDomain(track, yDomains) ||
+    track.visibleSeries.some((series) => resolveSeriesFixedYDomain(series, yDomain, yDomains)),
+  )
+}
+
+export function mergeYDomains(domains: readonly WaveformYDomain[]): WaveformYDomain {
+  return [
+    Math.min(...domains.map((domain) => domain[0])),
+    Math.max(...domains.map((domain) => domain[1])),
+  ]
+}