waveform-analysis 0.1.57 → 0.1.59

package/src/components/core/useWaveformLayout.ts

@@ -31,6 +31,7 @@ import {
   resolveYAxisSeriesGroups,
 } from './layout'
 import type { DisplaySeries, DisplayTrack, TrackLayout } from './types'
+import { createFrameNumberResolver, resolvePageableTracks } from './trackPagination'
 import type { PreparedWaveformSeries } from './useWaveformData'
 import type { ResolvedWaveformChartProps } from './waveformChartTypes'
 import { applyXDomainStrategy } from './xDomain'
@@ -107,9 +108,12 @@ export function useWaveformLayout(context: LayoutContext) {
     })
   })
   const renderingOptions = computed(() => resolveWaveformRenderingOptions(props.rendering))
-  const pageCount = computed(() => getPageCount(chartTracks.value.length, gridOptions.value))
+  const pageableTracks = computed(() =>
+    resolvePageableTracks(chartTracks.value, gridOptions.value.hideEmptyTracks),
+  )
+  const pageCount = computed(() => getPageCount(pageableTracks.value.length, gridOptions.value))
   const pagedTracks = computed(() =>
-    paginateSeries(chartTracks.value, currentPage.value, gridOptions.value),
+    paginateSeries(pageableTracks.value, currentPage.value, gridOptions.value),
   )
   const layoutTracks = computed(() => {
     const tracksWithSeries = pagedTracks.value.filter((track) => track.series.length > 0)
@@ -357,16 +361,15 @@ export function useWaveformLayout(context: LayoutContext) {
         }
       : undefined
   })
-  const resolveFrameNumber = (trackIndex: number): string | number | undefined => {
-    if (props.frameNumber === undefined || props.frameNumber === null) return undefined
-    if (chartTracks.value.length === 1) return props.frameNumber
-    return typeof props.frameNumber === 'number'
-      ? props.frameNumber + trackIndex
-      : `${props.frameNumber}-${trackIndex + 1}`
-  }
+  const resolveFrameNumber = createFrameNumberResolver(
+    () => props.frameNumber,
+    () => props.frameNumbers,
+    () => chartTracks.value,
+  )
   return {
     chartSeries,
     chartTracks,
+    pageableTracks,
     renderingOptions,
     gridOptions,
     pageCount,

package/src/components/core/waveformChartTypes.ts

@@ -16,6 +16,7 @@ import type {
   WaveformTitleOptions,
   WaveformXDomainStrategy,
   WaveformZeroLineOptions,
+  WaveformZoomIntentPayload,
   WaveformZoomEndPayload,
   WaveformZoomResetPayload,
 } from '../data/types'
@@ -43,6 +44,8 @@ export interface WaveformChartProps {
   yDomains?: Record<string, [number, number]>
   timeUnit?: 's' | 'ms'
   frameNumber?: string | number
+  /** Per-track frame watermark overrides, keyed by stable trackId. */
+  frameNumbers?: Record<string, string | number>
   frameStyle?: WaveformFrameStyle
   axes?: WaveformAxesOptions
   annotations?: WaveformAnnotation[]
@@ -88,6 +91,7 @@ export type ResolvedWaveformChartProps = Readonly<
 
 export interface WaveformChartEmit {
   (event: 'point-hover', point: WaveformPoint | null): void
+  (event: 'zoom-intent', payload: WaveformZoomIntentPayload): void
   (event: 'zoom-change', domain: [number, number]): void
   (event: 'zoom-end', payload: WaveformZoomEndPayload): void
   (event: 'zoom-reset', payload: WaveformZoomResetPayload): void

package/src/components/data/types.ts

@@ -10,6 +10,7 @@ export type {
   WaveformOverlayMode,
   WaveformInteractionMode,
   WaveformXDomainStrategy,
+  WaveformZoomIntentPayload,
   WaveformZoomEndPayload,
   WaveformZoomResetPayload,
   WaveformAnnotationStyle,

package/src/components/index.ts

@@ -7,6 +7,7 @@ export type {
   WaveformDisplayMode,
   WaveformOverlayMode,
   WaveformInteractionMode,
+  WaveformZoomIntentPayload,
   WaveformZoomEndPayload,
   WaveformAnnotationStyle,
   WaveformAnnotation,

package/src/components/interaction/useWaveformViewport.ts

@@ -10,6 +10,7 @@ import { tryReleasePointerCapture } from './pointerCapture'
 import { transitionViewportInteraction } from './viewportInteractionState'
 import { createViewportDomainSetter } from './viewportDomain'
 import { constrainZoomDomain, transformForDomain } from './zoomConstraints'
+import { emitBoxZoomIntent } from './zoomEventPayload'
 interface ViewportContext {
   props: ResolvedWaveformChartProps
   emit: WaveformChartEmit
@@ -254,6 +255,7 @@ export function useWaveformViewport(context: ViewportContext) {
     } else {
       sharedTransform.value = transformForDomain(xDomain, baseXDomain, innerWidth.value)
     }
+    emitBoxZoomIntent(emit, xDomain, track, active.independent)
     const targets = active.independent
       ? [track]
       : trackLayouts.value.filter((target) => target.hasVisibleSeries)

package/src/components/interaction/useWaveformZoom.ts

@@ -21,6 +21,11 @@ import {
   transformForDomain,
   type ZoomSeriesGroup,
 } from './zoomConstraints'
+import {
+  emitIndependentWheelZoomEnds,
+  emitSharedWheelZoomEnd,
+  seriesIdentity,
+} from './zoomEventPayload'
 
 interface ZoomContext {
   props: ResolvedWaveformChartProps
@@ -70,9 +75,10 @@ export function useWaveformZoom(context: ZoomContext) {
   let lastSharedZoomGesture: ZoomGestureKind | null = null
   const pendingIndependentZoomTransforms = new Map<number, ZoomTransform>()
   const pendingIndependentZoomGestures = new Map<number, ZoomGestureKind>()
-  const lastIndependentZoomGestures = new Map<number, ZoomGestureKind>()
-  const lastZoomedTrackIndexes = new Set<number>()
+  const lastIndependentWheelSeriesIds = new Map<string, string[]>()
   let wheelZoomEndTimer: ReturnType<typeof setTimeout> | undefined
+  let preservePendingWheelDuringDataRebind = false
+  let zoomBindingEpoch = 0
 
   const scheduleZoomCommit = () => zoomThrottle.schedule(commitPendingZoom)
   const handleSharedZoom = (event: D3ZoomEvent<SVGRectElement, unknown>) => {
@@ -80,8 +86,12 @@ export function useWaveformZoom(context: ZoomContext) {
     cancelPendingHover()
     pendingSharedZoomTransform = event.transform
     pendingSharedZoomGesture = 'wheel'
-    scheduleZoomCommit()
     scheduleWheelZoomEnd()
+    const domain = event.transform
+      .rescaleX(scaleLinear(initialXDomain.value, [0, innerWidth.value]))
+      .domain()
+    emit('zoom-intent', { start: domain[0], end: domain[1], gesture: 'wheel' })
+    scheduleZoomCommit()
   }
   const handleIndependentZoom = (
     event: D3ZoomEvent<SVGRectElement, unknown>,
@@ -91,8 +101,21 @@ export function useWaveformZoom(context: ZoomContext) {
     cancelPendingHover()
     pendingIndependentZoomTransforms.set(trackIndex, event.transform)
     pendingIndependentZoomGestures.set(trackIndex, 'wheel')
-    scheduleZoomCommit()
     scheduleWheelZoomEnd()
+    const track = trackLayouts.value.find((item) => item.index === trackIndex)
+    if (track) {
+      const domain = event.transform
+        .rescaleX(scaleLinear(resolveInitialTrackDomain(track), [0, track.width]))
+        .domain()
+      emit('zoom-intent', {
+        start: domain[0],
+        end: domain[1],
+        trackIndex,
+        seriesIds: track.seriesList.map((series) => series.id),
+        gesture: 'wheel',
+      })
+    }
+    scheduleZoomCommit()
   }
   function commitPendingZoom() {
     if (isPresentationMode.value) {
@@ -113,12 +136,7 @@ export function useWaveformZoom(context: ZoomContext) {
     if (!pendingIndependentZoomTransforms.size) return
     const nextTransforms = [...independentTransforms.value]
     const changedTrackIndexes = Array.from(pendingIndependentZoomTransforms.keys())
-    lastZoomedTrackIndexes.clear()
-    changedTrackIndexes.forEach((trackIndex) => lastZoomedTrackIndexes.add(trackIndex))
-    changedTrackIndexes.forEach((trackIndex) => {
-      const gesture = pendingIndependentZoomGestures.get(trackIndex)
-      if (gesture) lastIndependentZoomGestures.set(trackIndex, gesture)
-    })
+    const changedGestures = new Map(pendingIndependentZoomGestures)
     pendingIndependentZoomTransforms.forEach((transform, trackIndex) => {
       nextTransforms[trackIndex] = transform
     })
@@ -129,69 +147,37 @@ export function useWaveformZoom(context: ZoomContext) {
     changedTrackIndexes.forEach((trackIndex) => {
       const track = tracksByIndex.get(trackIndex)
       if (!track) return
+      if (changedGestures.get(trackIndex) === 'wheel') {
+        const seriesIds = track.seriesList.map((series) => series.id)
+        lastIndependentWheelSeriesIds.set(seriesIdentity(seriesIds), seriesIds)
+      }
       const domain = track.xScale.domain()
       emit('zoom-change', [domain[0], domain[1]])
     })
   }
   const emitZoomEnd = () => {
     if (props.displayMode === 'independent') {
-      const tracksByIndex = new Map(trackLayouts.value.map((track) => [track.index, track]))
-      lastZoomedTrackIndexes.forEach((trackIndex) => {
-        if (lastIndependentZoomGestures.get(trackIndex) !== 'wheel') return
-        const track = tracksByIndex.get(trackIndex)
-        if (!track) return
-        const domain = track.xScale.domain() as [number, number]
-        const yDomain = track.yScale.domain()
-        emit('zoom-end', {
-          start: domain[0],
-          end: domain[1],
-          yStart: yDomain[0],
-          yEnd: yDomain[1],
-          trackIndex,
-          seriesIds: track.seriesList.map((series) => series.id),
-          gesture: 'wheel',
-        })
-      })
-      lastZoomedTrackIndexes.clear()
-      lastIndependentZoomGestures.clear()
+      emitIndependentWheelZoomEnds(emit, trackLayouts.value, lastIndependentWheelSeriesIds.values())
+      lastIndependentWheelSeriesIds.clear()
       return
     }
     if (lastSharedZoomGesture !== 'wheel') {
       lastSharedZoomGesture = null
       return
     }
-    const domain = sharedZoomDomain.value
-    const visibleTracks = trackLayouts.value.filter((track) => track.hasVisibleSeries)
-    if (visibleTracks.length === 1) {
-      const yDomain = visibleTracks[0]?.yScale.domain()
-      emit('zoom-end', {
-        start: domain[0],
-        end: domain[1],
-        yStart: yDomain?.[0],
-        yEnd: yDomain?.[1],
-        gesture: 'wheel',
-      })
-    } else {
-      emit('zoom-end', {
-        start: domain[0],
-        end: domain[1],
-        yRanges: Object.fromEntries(
-          visibleTracks.map((track) => [
-            track.series?.trackId ?? track.series?.id ?? track.id,
-            track.yScale.domain() as [number, number],
-          ]),
-        ),
-        gesture: 'wheel',
-      })
-    }
+    emitSharedWheelZoomEnd(emit, sharedZoomDomain.value, trackLayouts.value)
     lastSharedZoomGesture = null
   }
   const flushPendingZoom = () => {
     zoomThrottle.flush()
     commitPendingZoom()
-    if (lastSharedZoomGesture === 'wheel' || lastIndependentZoomGestures.size) return
+    if (lastSharedZoomGesture === 'wheel' || lastIndependentWheelSeriesIds.size) return
     emitZoomEnd()
   }
+  const handleD3ZoomEnd = (bindingEpoch: number) => {
+    if (bindingEpoch !== zoomBindingEpoch) return
+    flushPendingZoom()
+  }
   function scheduleWheelZoomEnd() {
     if (wheelZoomEndTimer !== undefined) clearTimeout(wheelZoomEndTimer)
     wheelZoomEndTimer = setTimeout(() => {
@@ -199,24 +185,32 @@ export function useWaveformZoom(context: ZoomContext) {
       zoomThrottle.flush()
       commitPendingZoom()
       emitZoomEnd()
+      preservePendingWheelDuringDataRebind = false
     }, WHEEL_ZOOM_DEBOUNCE_MS)
   }
+  const prepareForDataChange = () => {
+    if (wheelZoomEndTimer === undefined) return
+    zoomThrottle.flush()
+    commitPendingZoom()
+    preservePendingWheelDuringDataRebind = true
+  }
   const cancelPendingZoom = () => {
     pendingSharedZoomTransform = null
     pendingSharedZoomGesture = null
     lastSharedZoomGesture = null
     pendingIndependentZoomTransforms.clear()
     pendingIndependentZoomGestures.clear()
-    lastZoomedTrackIndexes.clear()
-    lastIndependentZoomGestures.clear()
+    lastIndependentWheelSeriesIds.clear()
     zoomThrottle.cancel()
+    preservePendingWheelDuringDataRebind = false
     if (wheelZoomEndTimer !== undefined) {
       clearTimeout(wheelZoomEndTimer)
       wheelZoomEndTimer = undefined
     }
   }
-  const clearZoomBindings = () => {
-    cancelPendingZoom()
+  const clearZoomBindings = (preservePendingWheel = false) => {
+    zoomBindingEpoch += 1
+    if (!preservePendingWheel) cancelPendingZoom()
     svgElement.value
       ?.querySelectorAll<SVGRectElement>('.waveform-chart__overlay')
       .forEach((overlay) => select(overlay).on('.zoom', null))
@@ -268,7 +262,9 @@ export function useWaveformZoom(context: ZoomContext) {
     return false
   }
   const configureZoom = () => {
-    clearZoomBindings()
+    const preservePendingWheel = preservePendingWheelDuringDataRebind
+    clearZoomBindings(preservePendingWheel)
+    const bindingEpoch = zoomBindingEpoch
     if (
       isPresentationMode.value ||
       !props.zoomable ||
@@ -303,7 +299,7 @@ export function useWaveformZoom(context: ZoomContext) {
             [track.width, track.height],
           ])
           .on('zoom', (event) => handleIndependentZoom(event, track.index))
-          .on('end', flushPendingZoom)
+          .on('end', () => handleD3ZoomEnd(bindingEpoch))
         zoomBehaviors.set(track.index, behavior)
         synchronizingZoomTransform = true
         try {
@@ -337,7 +333,7 @@ export function useWaveformZoom(context: ZoomContext) {
         [innerWidth.value, innerHeight.value],
       ])
       .on('zoom', handleSharedZoom)
-      .on('end', flushPendingZoom)
+      .on('end', () => handleD3ZoomEnd(bindingEpoch))
     zoomBehaviors.set('shared', behavior)
     synchronizingZoomTransform = true
     try {
@@ -356,5 +352,6 @@ export function useWaveformZoom(context: ZoomContext) {
     canZoomTrack,
     canZoomSharedTracks,
     configureZoom,
+    prepareForDataChange,
   }
 }

package/src/components/interaction/zoomEventPayload.ts

@@ -0,0 +1,88 @@
+import type { TrackLayout } from '../core/types'
+import type { WaveformChartEmit } from '../core/waveformChartTypes'
+
+export function seriesIdentity(seriesIds: readonly string[]) {
+  return [...seriesIds].sort().join('\u0000')
+}
+
+export function findTrackBySeriesIds(
+  trackLayouts: readonly TrackLayout[],
+  seriesIds: readonly string[],
+) {
+  const identity = seriesIdentity(seriesIds)
+  return trackLayouts.find(
+    (track) => seriesIdentity(track.seriesList.map((series) => series.id)) === identity,
+  )
+}
+
+export function emitBoxZoomIntent(
+  emit: WaveformChartEmit,
+  domain: [number, number],
+  track: TrackLayout,
+  independent: boolean,
+) {
+  emit(
+    'zoom-intent',
+    independent
+      ? {
+          start: domain[0],
+          end: domain[1],
+          trackIndex: track.index,
+          seriesIds: track.seriesList.map((series) => series.id),
+          gesture: 'box',
+        }
+      : { start: domain[0], end: domain[1], gesture: 'box' },
+  )
+}
+
+export function emitIndependentWheelZoomEnds(
+  emit: WaveformChartEmit,
+  trackLayouts: readonly TrackLayout[],
+  pendingSeriesIds: Iterable<readonly string[]>,
+) {
+  for (const seriesIds of pendingSeriesIds) {
+    const track = findTrackBySeriesIds(trackLayouts, seriesIds)
+    if (!track) continue
+    const domain = track.xScale.domain() as [number, number]
+    const yDomain = track.yScale.domain()
+    emit('zoom-end', {
+      start: domain[0],
+      end: domain[1],
+      yStart: yDomain[0],
+      yEnd: yDomain[1],
+      trackIndex: track.index,
+      seriesIds: [...seriesIds],
+      gesture: 'wheel',
+    })
+  }
+}
+
+export function emitSharedWheelZoomEnd(
+  emit: WaveformChartEmit,
+  domain: [number, number],
+  trackLayouts: readonly TrackLayout[],
+) {
+  const visibleTracks = trackLayouts.filter((track) => track.hasVisibleSeries)
+  if (visibleTracks.length === 1) {
+    const yDomain = visibleTracks[0]?.yScale.domain()
+    emit('zoom-end', {
+      start: domain[0],
+      end: domain[1],
+      yStart: yDomain?.[0],
+      yEnd: yDomain?.[1],
+      gesture: 'wheel',
+    })
+    return
+  }
+  emit('zoom-end', {
+    start: domain[0],
+    end: domain[1],
+    yRanges: Object.fromEntries(
+      visibleTracks.map((track) => [
+        track.series?.trackId ?? track.series?.id ?? track.id,
+        track.yScale.domain() as [number, number],
+      ]),
+    ),
+    gesture: 'wheel',
+  })
+}

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

@@ -104,6 +104,68 @@ describe('WaveformChart track order', () => {
     expect(wrapper.findAll('.waveform-chart__crosshair line')).toHaveLength(2)
   })
 
+  it('keeps incremental watermarks stable when empty ordered tracks are hidden', async () => {
+    const wrapper = await mountSizedChart(mergedFourTrackSeries(), {
+      frameNumber: 1,
+      grid: {
+        rowCount: 2,
+        columnCount: 1,
+        hideEmptyTracks: true,
+        trackOrder: ['frame-1', 'frame-2', 'frame-3', 'frame-4'],
+      },
+    })
+
+    expect(
+      wrapper.findAll('.waveform-chart__track').map((track) => track.attributes('data-track-id')),
+    ).toEqual(['frame-1', 'frame-3'])
+    expect(
+      wrapper.findAll('.waveform-chart__watermark').map((watermark) => watermark.text()),
+    ).toEqual(['1', '3'])
+
+    await wrapper.get('.ant-pagination-next button').trigger('click')
+
+    expect(
+      wrapper.findAll('.waveform-chart__track').map((track) => track.attributes('data-track-id')),
+    ).toEqual(['frame-4'])
+    expect(
+      wrapper.findAll('.waveform-chart__watermark').map((watermark) => watermark.text()),
+    ).toEqual(['4'])
+  })
+
+  it('uses stable track IDs for explicit frame watermark overrides', async () => {
+    const wrapper = await mountSizedChart(mergedFourTrackSeries(), {
+      frameNumber: 1,
+      frameNumbers: { 'frame-1': 'A', 'frame-3': 'C', 'frame-4': 'D' },
+      grid: {
+        rowCount: 2,
+        columnCount: 1,
+        hideEmptyTracks: true,
+        trackOrder: ['frame-1', 'frame-2', 'frame-3', 'frame-4'],
+      },
+    })
+
+    expect(
+      wrapper.findAll('.waveform-chart__watermark').map((watermark) => watermark.text()),
+    ).toEqual(['A', 'C'])
+
+    await wrapper.get('.ant-pagination-next button').trigger('click')
+
+    expect(
+      wrapper.findAll('.waveform-chart__watermark').map((watermark) => watermark.text()),
+    ).toEqual(['D'])
+  })
+
+  it('keeps the existing incremental watermark fallback when frame mappings are absent', async () => {
+    const wrapper = await mountSizedChart(orderedSeries(['frame-1', 'frame-2']), {
+      frameNumber: 7,
+      grid: { rowCount: 2, columnCount: 1 },
+    })
+
+    expect(
+      wrapper.findAll('.waveform-chart__watermark').map((watermark) => watermark.text()),
+    ).toEqual(['7', '8'])
+  })
+
   it('appends data tracks absent from trackOrder in input order', async () => {
     const wrapper = await mountSizedChart(
       {