waveform-analysis 0.1.39 → 0.1.41

package/dist/types/components/core/layout.d.ts

@@ -2,6 +2,7 @@ import type { WaveformOverlayMode } from '../../types';
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types';
 import { type WaveformYDomain } from './yDomain';
 export { MAX_MULTI_Y_AXIS_COUNT } from './constants';
+export declare function resolveYAxisTickCount(_plotHeight: number, splitNumber?: number): number;
 export interface YAxisSeriesGroup {
     index: number;
     side: 'left' | 'right';
@@ -11,11 +12,11 @@ export interface YAxisSeriesGroup {
 }
 export declare function buildYAxisSeriesGroups(track: DisplayTrack, overlayMode: WaveformOverlayMode): YAxisSeriesGroup[];
 export declare function resolveYAxisSeriesGroups(track: DisplayTrack, overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>): YAxisSeriesGroup[];
-export declare function axisTextMetrics(domain: [number, number], nice?: boolean, tickValues?: number[]): {
+export declare function axisTextMetrics(domain: [number, number], nice?: boolean, tickValues?: number[], unit?: string, tickCount?: number): {
     tickTextWidth: number;
 };
-export declare function measureYAxisGroupClearance(group: YAxisSeriesGroup): number;
-export declare function measureTrackYAxisClearance(track: DisplayTrack, overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>): {
+export declare function measureYAxisGroupClearance(group: YAxisSeriesGroup, tickCount?: number): number;
+export declare function measureTrackYAxisClearance(track: DisplayTrack, overlayMode: WaveformOverlayMode, yDomain?: WaveformYDomain, yDomains?: Record<string, WaveformYDomain>, tickCount?: number): {
     left: number;
     right: number;
 };

package/dist/types/components/core/trackLayoutBuilder.d.ts

@@ -21,6 +21,7 @@ export interface BuildTrackLayoutsOptions {
     yDomains?: Record<string, [number, number]>;
     timeUnit: 's' | 'ms';
     xAxisLabelFormatter?: WaveformXAxisLabelFormatter;
+    yAxisSplitNumber?: number;
     rendering: ResolvedWaveformRenderingOptions;
     hideSecondaryLabels: boolean;
     yAxisLabelX: number;

package/dist/types/types/chart.d.ts

@@ -150,6 +150,8 @@ export interface WaveformAxesOptions {
     };
     y?: {
         lineVisible?: boolean;
+        /** Target total number of equal Y-axis ticks, including endpoints. Defaults to 5. */
+        splitNumber?: number;
     };
 }
 /** Styling and visibility options for the horizontal zero-value reference line. */

package/dist/types/utils/formatters.d.ts

@@ -9,6 +9,7 @@ export interface ScientificAxisLabelOptions {
     axisMin?: number;
     axisMax?: number;
     topTickValue?: number;
+    unit?: string;
 }
 /** @deprecated Use ScientificAxisLabelOptions. */
 export type ScientificYAxisLabelOptions = ScientificAxisLabelOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waveform-analysis",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",

package/src/components/core/fixedYDomainLayout.test.ts

@@ -35,7 +35,7 @@ function track(seriesList: DisplaySeries[]): DisplayTrack {
 }
 
 describe('fixed Y-domain layout', () => {
-  it('uses an exact global fixed domain without applying nice bounds', () => {
+  it('expands a global fixed domain to nice equal intervals', () => {
     const sourceTrack = track([series('a', 0, 100)])
     const result = buildTrackLayouts({
       cells: [
@@ -66,10 +66,80 @@ describe('fixed Y-domain layout', () => {
       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])
+    expect(result?.yScale.domain()).toEqual([0, 100])
+    expect(result?.yAxes[0]?.tickValues).toContain(0)
+    expect(result?.yAxes[0]?.tickValues).toContain(100)
+    expect(result?.seriesPaths[0]?.yScale.domain()).toEqual([0, 100])
+  })
+
+  it('uses the configured split number for fixed domains', () => {
+    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: track([series('a', 0, 100)]),
+        },
+      ],
+      grid: { rowCount: 1, columnCount: 1, showPagination: false, trackLines: {} },
+      displayMode: 'independent',
+      overlayMode: 'single-axis',
+      independentTransforms: [zoomIdentity],
+      sharedZoomDomain: [0, 1],
+      fixedYDomain: [3, 97],
+      yAxisSplitNumber: 5,
+      timeUnit: 'ms',
+      rendering: DEFAULT_WAVEFORM_RENDERING_OPTIONS,
+      hideSecondaryLabels: false,
+      yAxisLabelX: -50,
+      showCompactEmptyTracks: false,
+    })[0]
+
+    expect(result?.yAxes[0]?.majorTicks).toEqual([0, 25, 50, 75, 100])
+  })
+
+  it('defaults to five ticks and supports a two-tick axis', () => {
+    const build = (splitNumber?: number) =>
+      buildTrackLayouts({
+        cells: [
+          {
+            slotIndex: 0,
+            row: 0,
+            column: 0,
+            left: 0,
+            top: 0,
+            width: 120,
+            height: 100,
+            plotHeight: 100,
+            cellHeight: 130,
+            xAxisBand: 30,
+            series: track([series('a', 3, 97)]),
+          },
+        ],
+        grid: { rowCount: 1, columnCount: 1, showPagination: false, trackLines: {} },
+        displayMode: 'independent',
+        overlayMode: 'single-axis',
+        independentTransforms: [zoomIdentity],
+        sharedZoomDomain: [0, 1],
+        fixedYDomain: [3, 97],
+        yAxisSplitNumber: splitNumber,
+        timeUnit: 'ms',
+        rendering: DEFAULT_WAVEFORM_RENDERING_OPTIONS,
+        hideSecondaryLabels: false,
+        yAxisLabelX: -50,
+        showCompactEmptyTracks: false,
+      })[0]?.yAxes[0]?.majorTicks
+
+    expect(build()).toHaveLength(5)
+    expect(build(2)).toEqual([0, 100])
   })
 
   it('resolves track, series, and global fixed-domain precedence', () => {

package/src/components/core/layout.test.ts

@@ -9,6 +9,7 @@ import {
   findClosestTrackAtPointer,
   MAX_MULTI_Y_AXIS_COUNT,
   measureYAxisGroupClearance,
+  resolveYAxisTickCount,
 } from './layout'
 
 function series(id: string, minimum: number, maximum: number): DisplaySeries {
@@ -119,8 +120,15 @@ describe('multi-value Y-axis grouping', () => {
       showCompactEmptyTracks: false,
     })[0]
 
-    expect(result?.yScale.domain()).toEqual([25, 75])
-    expect(result?.seriesPaths[0]?.yScale.domain()).toEqual([25, 75])
+    expect(result?.yScale.domain()).toEqual([20, 80])
+    expect(result?.seriesPaths[0]?.yScale.domain()).toEqual([20, 80])
+  })
+
+  it('normalizes configured Y-axis split counts', () => {
+    expect(resolveYAxisTickCount(100, 0)).toBe(2)
+    expect(resolveYAxisTickCount(100, 4.8)).toBe(4)
+    expect(resolveYAxisTickCount(100, Number.NaN)).toBe(5)
+    expect(resolveYAxisTickCount(220)).toBe(5)
   })
 
   it('keeps every overlaid series on one axis in single-axis mode', () => {

package/src/components/core/layout.ts

@@ -20,6 +20,13 @@ const Y_AXIS_OUTER_PADDING = 4
 const Y_AXIS_LABEL_GAP = 6
 const Y_AXIS_LABEL_BAND_WIDTH = 24
 
+export function resolveYAxisTickCount(_plotHeight: number, splitNumber?: number): number {
+  if (typeof splitNumber === 'number' && Number.isFinite(splitNumber)) {
+    return Math.max(2, Math.floor(splitNumber))
+  }
+  return 5
+}
+
 export interface YAxisSeriesGroup {
   index: number
   side: 'left' | 'right'
@@ -103,16 +110,22 @@ export function axisTextMetrics(
   domain: [number, number],
   nice = true,
   tickValues?: number[],
+  unit?: string,
+  tickCount = 10,
 ): { tickTextWidth: number } {
+  const effectiveTickCount =
+    typeof tickCount === 'number' && Number.isFinite(tickCount)
+      ? Math.max(2, Math.floor(tickCount))
+      : 10
   const scale = scaleLinear(domain, [1, 0])
-  if (nice) scale.nice()
+  if (nice) scale.nice(effectiveTickCount)
   const [axisMin, axisMax] = scale.domain()
-  const values = tickValues ?? Array.from(new Set([axisMin, ...scale.ticks(10), axisMax]))
+  const values = tickValues ?? scale.ticks(effectiveTickCount)
   const topTickValue = Math.max(...values)
   const maximumTickCharacters = Math.max(
     1,
     ...values.map(
-      (value) => formatScientificAxisLabel(value, { axisMin, axisMax, topTickValue }).length,
+      (value) => formatScientificAxisLabel(value, { axisMin, axisMax, topTickValue, unit }).length,
     ),
   )
   return {
@@ -120,9 +133,10 @@ export function axisTextMetrics(
   }
 }
 
-export function measureYAxisGroupClearance(group: YAxisSeriesGroup): number {
+export function measureYAxisGroupClearance(group: YAxisSeriesGroup, tickCount?: number): number {
   return (
-    axisTextMetrics(group.domain, !group.fixed).tickTextWidth +
+    axisTextMetrics(group.domain, true, undefined, group.seriesList[0]?.unit, tickCount)
+      .tickTextWidth +
     Y_AXIS_TICK_PADDING +
     Y_AXIS_LABEL_GAP +
     Y_AXIS_LABEL_BAND_WIDTH +
@@ -130,9 +144,10 @@ export function measureYAxisGroupClearance(group: YAxisSeriesGroup): number {
   )
 }
 
-function measureYAxisGroupTickClearance(group: YAxisSeriesGroup): number {
+function measureYAxisGroupTickClearance(group: YAxisSeriesGroup, tickCount?: number): number {
   return (
-    axisTextMetrics(group.domain, !group.fixed).tickTextWidth +
+    axisTextMetrics(group.domain, true, undefined, group.seriesList[0]?.unit, tickCount)
+      .tickTextWidth +
     Y_AXIS_TICK_PADDING +
     Y_AXIS_OUTER_PADDING
   )
@@ -143,13 +158,14 @@ export function measureTrackYAxisClearance(
   overlayMode: WaveformOverlayMode,
   yDomain?: WaveformYDomain,
   yDomains?: Record<string, WaveformYDomain>,
+  tickCount?: number,
 ): { left: number; right: number } {
   return resolveYAxisSeriesGroups(track, overlayMode, yDomain, yDomains).reduce(
     (clearance, group) => {
       clearance[group.side] +=
         overlayMode === 'multi-axis' || track.visibleSeries.length === 1
-          ? measureYAxisGroupClearance(group)
-          : measureYAxisGroupTickClearance(group)
+          ? measureYAxisGroupClearance(group, tickCount)
+          : measureYAxisGroupTickClearance(group, tickCount)
       return clearance
     },
     { left: 0, right: 0 },

package/src/components/core/trackLayoutBuilder.ts

@@ -25,7 +25,7 @@ import {
   type GridCellGeometry,
   type NormalizedWaveformGridOptions,
 } from './grid'
-import { axisTextMetrics, resolveYAxisSeriesGroups } from './layout'
+import { axisTextMetrics, resolveYAxisSeriesGroups, resolveYAxisTickCount } from './layout'
 import type { DisplaySeries, DisplayTrack, TrackLayout, WaveformYAxisLayout } from './types'
 import { applyXDomainStrategy } from './xDomain'
 import {
@@ -54,6 +54,7 @@ export interface BuildTrackLayoutsOptions {
   yDomains?: Record<string, [number, number]>
   timeUnit: 's' | 'ms'
   xAxisLabelFormatter?: WaveformXAxisLabelFormatter
+  yAxisSplitNumber?: number
   rendering: ResolvedWaveformRenderingOptions
   hideSecondaryLabels: boolean
   yAxisLabelX: number
@@ -124,18 +125,27 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
     )
     const sideOffsets = { left: 0, right: 0 }
     const yAxes: WaveformYAxisLayout[] = yAxisGroups.map((group) => {
+      const tickCount = resolveYAxisTickCount(cell.plotHeight, options.yAxisSplitNumber)
+      const niceCount = Math.max(1, tickCount - 1)
       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)))
+      scale.nice(niceCount)
       const [axisStart, axisEnd] = scale.domain()
+      const majorTicks = Array.from(
+        { length: tickCount },
+        (_, index) => axisStart + ((axisEnd - axisStart) * index) / (tickCount - 1),
+      )
       const showAxisEnd = options.displayMode !== 'compact' || cell.row === 0
       const visibleMajorTicks = showAxisEnd
         ? majorTicks
         : majorTicks.filter((tick) => tick !== axisEnd)
-      const tickValues = Array.from(
-        new Set([axisStart, ...visibleMajorTicks, ...(showAxisEnd ? [axisEnd] : [])]),
+      const tickValues = visibleMajorTicks
+      const { tickTextWidth } = axisTextMetrics(
+        scale.domain() as [number, number],
+        false,
+        tickValues,
+        group.seriesList[0]?.unit,
+        tickCount,
       )
-      const { tickTextWidth } = axisTextMetrics(group.domain, !group.fixed, tickValues)
       const clearance =
         tickTextWidth +
         Y_AXIS_TICK_PADDING +

package/src/components/core/useWaveformLayout.ts

@@ -112,7 +112,16 @@ export function useWaveformLayout(context: LayoutContext) {
       .flatMap((track) =>
         resolveYAxisSeriesGroups(track, props.overlayMode, props.yDomain, props.yDomains),
       )
-      .map((group) => axisTextMetrics(group.domain, !group.fixed).tickTextWidth)
+      .map(
+        (group) =>
+          axisTextMetrics(
+            group.domain,
+            true,
+            undefined,
+            group.seriesList[0]?.unit,
+            props.axes?.y?.splitNumber,
+          ).tickTextWidth,
+      )
     const tickTextWidth = Math.max(Y_AXIS_CHARACTER_WIDTH, ...axisText)
     const tickClearance = tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_OUTER_PADDING
     const labelCenterX = -(
@@ -157,6 +166,7 @@ export function useWaveformLayout(context: LayoutContext) {
           props.overlayMode,
           props.yDomain,
           props.yDomains,
+          props.axes?.y?.splitNumber,
         )
         return {
           left: Math.max(maximum.left, clearance.left),
@@ -298,6 +308,7 @@ export function useWaveformLayout(context: LayoutContext) {
           : sharedYDomains.value,
       timeUnit: props.timeUnit,
       xAxisLabelFormatter: props.axes?.x?.labelFormatter,
+      yAxisSplitNumber: props.axes?.y?.splitNumber,
       rendering: renderingOptions.value,
       hideSecondaryLabels: isCleanView.value || yAxisLayout.value.hideSecondaryLabels,
       yAxisLabelX: yAxisMetrics.value.labelCenterX,

package/src/components/rendering/WaveformTrackAxes.vue

@@ -44,9 +44,10 @@ function renderAxes() {
     if (!element) return
     const [axisMin, axisMax] = axis.scale.domain()
     const topTickValue = Math.max(...axis.tickValues)
+    const unit = axis.seriesList[0]?.unit
     const yAxis = (axis.side === 'left' ? axisLeft(axis.scale) : axisRight(axis.scale))
       .tickFormat((value) =>
-        formatScientificAxisLabel(Number(value), { axisMin, axisMax, topTickValue }),
+        formatScientificAxisLabel(Number(value), { axisMin, axisMax, topTickValue, unit }),
       )
       .tickSize(-4)
       .tickPadding(7)

package/src/components/waveformChartCases/compactAndSharedHover.test.ts

@@ -65,9 +65,9 @@ describe('WaveformChart', () => {
     )
 
     expect(endTicks[0]).toHaveLength(1)
-    expect(Number(endTicks[0][0].text())).toBe(0.9)
+    expect(Number(endTicks[0][0].text())).toBe(1)
     expect(endTicks[1]).toHaveLength(1)
-    expect(Number(endTicks[1][0].text())).toBe(1.9)
+    expect(Number(endTicks[1][0].text())).toBe(2)
     expect(endTicks[2]).toHaveLength(0)
     expect(endTicks[3]).toHaveLength(0)
   })

package/src/components/waveformChartCases/dataLifecycle.test.ts

@@ -158,6 +158,12 @@ describe('WaveformChart', () => {
     expect(paths[0].attributes('data-series-name')).toBe('BT2_2M')
     const yAxisLabels = wrapper.findAll('.waveform-chart__y-axis-label')
     expect(yAxisLabels.map((label) => label.text())).toEqual(['BT2_2M', 'BT1_2M'])
+    expect(
+      wrapper
+        .findAll('.waveform-chart__axis--y .tick text')
+        .map((label) => label.text())
+        .some((label) => label.includes('(T)')),
+    ).toBe(true)
     expect(yAxisLabels.map((label) => label.attributes('fill'))).toEqual(['#0960bd', '#ff7f0e'])
     const labelX = Number(
       yAxisLabels[0].attributes('transform')?.match(/^translate\(([-\d.]+),/)?.[1],
@@ -255,7 +261,7 @@ describe('WaveformChart', () => {
       })
 
       expect(startTicks).toHaveLength(1)
-      expect(Number(startTicks[0].text())).toBe(0.1)
+      expect(Number(startTicks[0].text())).toBe(0)
     },
   )
 
@@ -291,7 +297,7 @@ describe('WaveformChart', () => {
         { displayMode },
       )
 
-      const expectedEndValues = [0.9, 4.9]
+      const expectedEndValues = [1, 5]
       wrapper.findAll('.waveform-chart__track').forEach((track, index) => {
         const endTicks = track.findAll('.waveform-chart__axis--y .tick').filter((tick) => {
           const match = tick.attributes('transform')?.match(/translate\(0,\s*([\d.]+)\)/)

package/src/components/waveformChartCases/layoutAndDomains.test.ts

@@ -6,6 +6,26 @@ import { resizeObservers } from '../../test/setup'
 import { gridSeries, mountSizedChart } from '../../test/waveformChart'
 
 describe('WaveformChart', () => {
+  it('applies the configured Y-axis split number', async () => {
+    const wrapper = await mountSizedChart(
+      {
+        kind: 'points',
+        points: [
+          { x: 0, y: 3 },
+          { x: 1, y: 97 },
+        ],
+      },
+      { axes: { y: { splitNumber: 5 } } },
+    )
+
+    expect(
+      wrapper
+        .get('.waveform-chart__axis--y')
+        .findAll('.tick text')
+        .map((tick) => tick.text()),
+    ).toEqual(['0', '25', '50', '75', '100'])
+  })
+
   it('expands the Y-axis label gutter for signed values and long exponents', async () => {
     const wrapper = await mountSizedChart(
       {
@@ -296,7 +316,7 @@ describe('WaveformChart', () => {
     expect(wrapper.get('.waveform-chart__axis-endpoint--end').text()).toBe('1000')
   })
 
-  it('reacts to exact fixed Y-domain props and returns to automatic bounds', async () => {
+  it('reacts to nice fixed Y-domain props and returns to automatic bounds', async () => {
     const wrapper = await mountSizedChart({
       kind: 'points',
       points: [
@@ -312,8 +332,8 @@ describe('WaveformChart', () => {
 
     await wrapper.setProps({ yDomain: [3, 97] })
     await flushPromises()
-    expect(yTickLabels()).toContain('3')
-    expect(yTickLabels()).toContain('97')
+    expect(yTickLabels()).toContain('0')
+    expect(yTickLabels()).toContain('100')
 
     await wrapper.setProps({ yDomain: undefined })
     await flushPromises()

package/src/components/waveformChartCases/multiAxisAndPagination.test.ts

@@ -15,6 +15,7 @@ describe('WaveformChart', () => {
           {
             trackId: 'shared-frame',
             name: '普通量程',
+            unit: 'V',
             data: {
               kind: 'points',
               points: [
@@ -26,6 +27,7 @@ describe('WaveformChart', () => {
           {
             trackId: 'shared-frame',
             name: '大量程',
+            unit: 'A',
             data: {
               kind: 'points',
               points: [
@@ -37,6 +39,7 @@ describe('WaveformChart', () => {
           {
             trackId: 'shared-frame',
             name: '小量程',
+            unit: 'T',
             data: {
               kind: 'points',
               points: [
@@ -57,7 +60,11 @@ describe('WaveformChart', () => {
           .map((label) => label.text())
           .filter((label) => label.startsWith('E')),
       ),
-    ).toEqual([[], [expect.stringMatching(/^E\+03 /)], [expect.stringMatching(/^E-04 /)]])
+    ).toEqual([
+      [],
+      [expect.stringMatching(/^E\+03 \(A\) /)],
+      [expect.stringMatching(/^E-04 \(T\) /)],
+    ])
   })
 
   it('reprojects annotations with the Y axis assigned to their series', async () => {

package/src/types/chart.ts

@@ -174,6 +174,8 @@ export interface WaveformAxesOptions {
   }
   y?: {
     lineVisible?: boolean
+    /** Target total number of equal Y-axis ticks, including endpoints. Defaults to 5. */
+    splitNumber?: number
   }
 }
 

package/src/utils/formatters.test.ts

@@ -40,6 +40,15 @@ describe('waveform number formatters', () => {
     expect(formatScientificAxisExponent(0.0001, 0.0003)).toBe('E-04')
   })
 
+  it('appends a unit to the top tick with or without scientific notation', () => {
+    expect(formatScientificAxisLabel(3000, { axisMin: 1000, axisMax: 3000, unit: 'V' })).toBe(
+      'E+03 (V) 3',
+    )
+    expect(formatScientificAxisLabel(3, { axisMin: 0, axisMax: 3, unit: 'A' })).toBe('(A) 3')
+    expect(formatScientificAxisLabel(2, { axisMin: 0, axisMax: 3, unit: 'A' })).toBe('2')
+    expect(formatScientificAxisLabel(3, { axisMin: 0, axisMax: 3, unit: '  ' })).toBe('3')
+  })
+
   it('derives the exponent from the largest absolute endpoint', () => {
     expect(resolveScientificAxisExponent(-9000, -1000)).toBe(3)
     expect(resolveScientificAxisExponent(-100_000, -3000)).toBe(5)

package/src/utils/formatters.ts

@@ -11,6 +11,7 @@ export interface ScientificAxisLabelOptions {
   axisMin?: number
   axisMax?: number
   topTickValue?: number
+  unit?: string
 }
 
 /** @deprecated Use ScientificAxisLabelOptions. */
@@ -71,9 +72,11 @@ export function formatScientificAxisLabel(
   const scaledValue = exponent === null ? value : value / 10 ** exponent
   const formattedValue = formatYAxisNumber(scaledValue)
   const topTickValue = options.topTickValue ?? options.axisMax
-  return exponent !== null && value === topTickValue
-    ? `${formatExponent(exponent)} ${formattedValue}`
-    : formattedValue
+  if (value !== topTickValue) return formattedValue
+  const unit = options.unit?.trim()
+  const unitLabel = unit ? `(${unit}) ` : ''
+  const exponentLabel = exponent === null ? '' : `${formatExponent(exponent)} `
+  return `${exponentLabel}${unitLabel}${formattedValue}`
 }
 
 /** Return the shared E-style multiplier for an axis, or null for a plain axis. */