waveform-analysis 0.1.73 → 0.1.75

package/src/components/core/trackLayoutBuilder.ts

@@ -1,15 +1,8 @@
+import { generateWaveformPath } from '../animation/geometry'
 import { withMaximumTick, type YAxisPaddingOptions } from './yAxisPadding'
 import { selectSeriesRenderSourcePoints } from '../../core/rendering'
 import { pointSourceFromPoints } from '../../core/waveformPointSource'
-import {
-  curveStep,
-  curveStepAfter,
-  curveStepBefore,
-  line,
-  scaleLinear,
-  zoomIdentity,
-  type ZoomTransform,
-} from 'd3'
+import { scaleLinear, zoomIdentity, type ZoomTransform } from 'd3'
 
 import { type ResolvedWaveformRenderingOptions } from '../../core/rendering'
 import type {
@@ -170,7 +163,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
           ? group.minimumTick
           : undefined
       const tickValues = withMaximumTick(majorTicks, maximumTick, minimumTick)
-      const { tickTextWidth } = axisTextMetrics(
+      const { tickTextWidth, titleTextWidth } = axisTextMetrics(
         scale.domain() as [number, number],
         false,
         tickValues,
@@ -178,10 +171,13 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
         tickCount,
       )
       const clearance =
-        tickTextWidth +
+        Math.max(
+          tickTextWidth,
+          titleTextWidth +
+            Y_AXIS_LABEL_GAP +
+            resolveYAxisLabelBandWidth(options.yAxisPadding?.labelTextStyle),
+        ) +
         Y_AXIS_TICK_PADDING +
-        Y_AXIS_LABEL_GAP +
-        resolveYAxisLabelBandWidth(options.yAxisPadding?.labelTextStyle) +
         Y_AXIS_OUTER_PADDING
       const slot = options.yAxisSlots?.find(
         (candidate) => candidate.side === group.side && candidate.sideIndex === sideIndex,
@@ -192,7 +188,7 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
           ? -sideOffsets.left
           : cell.width + sideOffsets.right
       const labelDistance =
-        tickTextWidth +
+        titleTextWidth +
         Y_AXIS_TICK_PADDING +
         Y_AXIS_LABEL_GAP +
         resolveYAxisLabelBandWidth(options.yAxisPadding?.labelTextStyle) / 2
@@ -261,17 +257,15 @@ export function buildTrackLayouts(options: BuildTrackLayoutsOptions): TrackLayou
           hasErrorPoints: trackSeries.hasErrorPoints,
         },
       )
-      const pathGenerator = line<WaveformPoint>()
-        .x((point) => xScale(point.x))
-        .y((point) => seriesYScale(point.y))
-      if (trackSeries.lineType === 'step-start') pathGenerator.curve(curveStepBefore)
-      if (trackSeries.lineType === 'step-middle') pathGenerator.curve(curveStep)
-      if (trackSeries.lineType === 'step-end' || trackSeries.lineType === 'step-after') {
-        pathGenerator.curve(curveStepAfter)
-      }
       return {
         series: trackSeries,
-        path: renderPoints.linePoints.length ? pathGenerator(renderPoints.linePoints) : null,
+        path: generateWaveformPath(
+          renderPoints.linePoints,
+          trackSeries.lineType,
+          xScale,
+          seriesYScale,
+        ),
+        lineRenderPoints: renderPoints.linePoints,
         pointRenderPoints: renderPoints.pointRenderPoints,
         errorBarRenderPoints: renderPoints.errorBarRenderPoints,
         yScale: seriesYScale,

package/src/components/core/types.ts

@@ -47,6 +47,10 @@ export interface DisplayTrack {
 export interface TrackSeriesPath {
   series: DisplaySeries
   path: string | null
+  lineRenderPoints?: WaveformPoint[]
+  presentationKey?: string
+  opacity?: number
+  animationClip?: { id: string; x: number; width: number }
   pointRenderPoints: WaveformPoint[]
   errorBarRenderPoints: WaveformPoint[]
   yScale: ScaleLinear<number, number>

package/src/components/core/useWaveformChartController.ts

@@ -1,4 +1,6 @@
-import { chartExportOptions } from '../controls/chartExportOptions'
+import { assignElement } from '../utils/assignElement'
+import { chartExportVersion } from '../animation/chartExportVersion'
+import { useWaveformAnimations } from '../animation/useWaveformAnimations'
 import { useChartImageExport } from '../controls/useChartImageExport'
 import { useControlMode } from '../controls/useControlMode'
 import { useChartCommands } from '../controls/useChartCommands'
@@ -16,9 +18,7 @@ import {
   watch,
   watchEffect,
   type ComponentPublicInstance,
-  type Ref,
 } from 'vue'
-
 import { useWaveformInstanceId } from '../../utils/waveformId'
 import { useWaveformAnnotationInteraction, type AnnotationSeriesCandidate } from '../annotation'
 import { useWaveformChartAnnotations } from '../annotation/useWaveformChartAnnotations'
@@ -41,14 +41,6 @@ import type {
   ViewportSelectionState,
   WaveformChartEmit,
 } from './waveformChartTypes'
-
-function assignElement<T extends Element>(
-  target: Ref<T | undefined>,
-  element: Element | ComponentPublicInstance | null,
-) {
-  target.value = element instanceof Element ? (element as T) : undefined
-}
-
 export function useWaveformChartController(
   inputProps: ResolvedWaveformChartProps,
   emit: WaveformChartEmit,
@@ -186,7 +178,17 @@ export function useWaveformChartController(
     renderingOptions,
     linePointOverrides,
   })
-
+  const animations = useWaveformAnimations({
+    props,
+    currentPage,
+    containerSize: computed(() => [observedWidth.value, observedHeight.value]),
+    layoutReady: computed(() => observedWidth.value > 0 && observedHeight.value > 0),
+    tracks: trackLayouts,
+    preparedSeries,
+    innerWidth,
+    innerHeight: presentation.innerHeight,
+    sampling,
+  })
   const paginationVisible = computed(
     () => gridOptions.value.showPagination && pageCount.value > 1 && !isCleanView.value,
   )
@@ -389,10 +391,8 @@ export function useWaveformChartController(
       height: chartHeight.value,
       titleHeight: titleAreaHeight.value,
     }),
-    version: () => [
-      props.data,
-      JSON.stringify({
-        ...chartExportOptions(props),
+    version: () =>
+      chartExportVersion(props, {
         hidden: [...hiddenSeriesIdSet.value],
         width: chartWidth.value,
         height: chartHeight.value,
@@ -404,7 +404,8 @@ export function useWaveformChartController(
         independentY: independentYDomains.value,
         boundaries: boundaries.value,
       }),
-    ],
+    prepare: animations.prepareExport,
+    release: animations.releaseExport,
     ready: sampling.ready,
   })
 
@@ -418,7 +419,11 @@ export function useWaveformChartController(
     ...annotations,
     ...viewport,
     ...hover,
-    ...commands,
+    ...animations.wrap(commands),
+    presentationTracks: animations.presentationTracks,
+    presentationAnnotations: animations.presentationAnnotations,
+    paginationOpacity: animations.paginationOpacity,
+    stabilizeAnimations: animations.stabilizeAnimations,
     ...imageExport,
     margin,
     getPageSize,
@@ -431,7 +436,7 @@ export function useWaveformChartController(
     contextMenu: annotationInteraction.contextMenu,
     editorSeriesOptions,
     clipPathId,
-    goToPage: lifecycle.goToPage,
+    goToPage: animations.wrapPagination(lifecycle.goToPage, pageCount),
     setContainer: (element: Element | ComponentPublicInstance | null) =>
       assignElement(container, element),
     setSvgElement: (element: Element | ComponentPublicInstance | null) =>
@@ -442,5 +447,4 @@ export function useWaveformChartController(
       assignElement(sharedOverlayElement, element),
   })
 }
-
 export type WaveformChartController = ReturnType<typeof useWaveformChartController>

package/src/components/core/useWaveformLayout.ts

@@ -281,7 +281,9 @@ export function useWaveformLayout(context: LayoutContext) {
     }),
   )
   useExtremaTickViewport(
-    () => props.axes?.y?.extremaTicksVisible !== false,
+    () =>
+      Number(props.axes?.y?.maximumTickVisible !== false) * 2 +
+      Number(props.axes?.y?.minimumTickVisible !== false),
     innerWidth,
     trackLayouts,
     sharedTransform,

package/src/components/core/useWaveformRenderSampling.ts

@@ -103,6 +103,7 @@ function errorPayload(
 }
 
 export function useWaveformRenderSampling(context: SamplingContext) {
+  const resultState = shallowRef<'success' | 'fallback' | 'error'>('success')
   const settledSignature = shallowRef<string>()
   const dataEpoch = shallowRef(0)
   const session = createWaveformSamplingSession()
@@ -292,10 +293,14 @@ export function useWaveformRenderSampling(context: SamplingContext) {
         requestId: ++session.requestId,
         series: batch,
       })
-      if (result.type !== 'sample-viewport-response') return
+      if (result.type !== 'sample-viewport-response') {
+        if (samplingScheduler.isCurrent(token)) resultState.value = 'error'
+        return
+      }
       response = result
     } catch (error) {
       if (!samplingScheduler.isCurrent(token)) return
+      resultState.value = 'error'
       emitErrorOnce(
         errorPayload(
           error instanceof Error ? error.message : String(error),
@@ -310,8 +315,18 @@ export function useWaveformRenderSampling(context: SamplingContext) {
       return
     }
     if (!samplingScheduler.isCurrent(token)) return
+    if (response.workerError || client.workerFailureReason) resultState.value = 'fallback'
     const sourceById = new Map(sampledTargets.map((target) => [target.series.id, target.source]))
+    if (
+      sampledTargets.some(
+        (target) =>
+          !response.results.some((result) => result.seriesId === target.series.id && result.output),
+      )
+    )
+      resultState.value = 'error'
     response.results.forEach((result) => {
+      if (result.status !== 'ok' && resultState.value !== 'error')
+        resultState.value = result.output ? 'fallback' : 'error'
       const source = sourceById.get(result.seriesId)
       const selected = source ? sourcePoints(result, source) : undefined
       if (selected && (result.status === 'ok' || result.status === 'wasm-unavailable')) {
@@ -369,6 +384,7 @@ export function useWaveformRenderSampling(context: SamplingContext) {
   const scheduleSampling = (hysteresis: boolean) => {
     settledSignature.value = undefined
     const signature = targetSignature.value
+    resultState.value = 'success'
     samplingScheduler.schedule(async (token) => {
       try {
         await runSampling(token, hysteresis)
@@ -410,6 +426,12 @@ export function useWaveformRenderSampling(context: SamplingContext) {
   onScopeDispose(() => session.dispose())
 
   return {
+    requestSignature: targetSignature,
+    state: computed(() =>
+      settledSignature.value === targetSignature.value && !session.autoModeSettleTimer
+        ? resultState.value
+        : 'pending',
+    ),
     linePointOverrides: context.linePointOverrides,
     ready: () => settledSignature.value === targetSignature.value && !session.autoModeSettleTimer,
   }

package/src/components/core/waveformChartTypes.ts

@@ -1,3 +1,4 @@
+import type { WaveformAnimationProps } from '../../animation/types'
 import type { WaveformToolbarOptions, WaveformControlState } from '../../types/controls'
 import type {
   WaveformAnnotation,
@@ -26,7 +27,7 @@ import type {
 } from '../data/types'
 import type { WaveformGridOptions } from './grid'
 
-export interface WaveformChartProps {
+export interface WaveformChartProps extends WaveformAnimationProps {
   toolbar?: boolean | WaveformToolbarOptions
   data: WaveformData
   displayMode?: WaveformDisplayMode

package/src/components/core/yAxisLayoutMetrics.ts

@@ -60,29 +60,37 @@ export function resolveYAxisLayoutMetrics(
         padding,
       ),
     )
-    .map(
-      (group) =>
-        axisTextMetrics(
-          group.domain,
-          nice,
-          undefined,
-          showUnits ? group.seriesList[0]?.unit : undefined,
-          tickCount,
-          compact,
-          measureTextWidth,
-          group.maximumTick,
-          group.minimumTick,
-        ).tickTextWidth,
+    .map((group) =>
+      axisTextMetrics(
+        group.domain,
+        nice,
+        undefined,
+        showUnits ? group.seriesList[0]?.unit : undefined,
+        tickCount,
+        compact,
+        measureTextWidth,
+        group.maximumTick,
+        group.minimumTick,
+      ),
     )
-  const tickTextWidth = Math.max(Y_AXIS_CHARACTER_WIDTH, ...axisText)
+  const tickTextWidth = Math.max(
+    Y_AXIS_CHARACTER_WIDTH,
+    ...axisText.map((text) => text.tickTextWidth),
+  )
+  const titleTextWidth = Math.max(
+    Y_AXIS_CHARACTER_WIDTH,
+    ...axisText.map((text) => text.titleTextWidth),
+  )
   const tickClearance = tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_OUTER_PADDING
   const labelCenterX = -(
     Y_AXIS_TICK_PADDING +
-    tickTextWidth +
+    titleTextWidth +
     Y_AXIS_LABEL_GAP +
     labelBandWidth / 2
   )
   const fullClearance =
-    tickTextWidth + Y_AXIS_TICK_PADDING + Y_AXIS_LABEL_GAP + labelBandWidth + Y_AXIS_OUTER_PADDING
+    Math.max(tickTextWidth, titleTextWidth + Y_AXIS_LABEL_GAP + labelBandWidth) +
+    Y_AXIS_TICK_PADDING +
+    Y_AXIS_OUTER_PADDING
   return { tickClearance, fullClearance, labelCenterX }
 }

package/src/components/core/yAxisPadding.ts

@@ -15,7 +15,7 @@ export function applyYAxisPadding(
   options: YAxisPaddingOptions | number,
 ): YAxisSeriesGroup {
   const config = typeof options === 'number' ? { upperPaddingRatio: options } : options
-  if (group.fixed) return withYAxisExtremaTicks(group, config?.extremaTicksVisible)
+  if (group.fixed) return withYAxisExtremaTicks(group, config)
   const upper = paddingRatio(config?.upperPaddingEnabled, config?.upperPaddingRatio)
   const lower = paddingRatio(config?.lowerPaddingEnabled, config?.lowerPaddingRatio)
   const [a, b] = group.domain
@@ -27,11 +27,14 @@ export function applyYAxisPadding(
       ...group,
       domain: viewport ?? [Number.isFinite(min) ? min : a, Number.isFinite(max) ? max : b],
     },
-    config?.extremaTicksVisible,
+    config,
   )
 }
 
-function withYAxisExtremaTicks(group: YAxisSeriesGroup, visible = true): YAxisSeriesGroup {
+function withYAxisExtremaTicks(
+  group: YAxisSeriesGroup,
+  options: YAxisPaddingOptions,
+): YAxisSeriesGroup {
   const maxima = group.seriesList.flatMap((series) =>
     Number.isFinite(series.rawYMaximum) ? [series.rawYMaximum!] : [],
   )
@@ -40,8 +43,10 @@ function withYAxisExtremaTicks(group: YAxisSeriesGroup, visible = true): YAxisSe
   )
   return {
     ...group,
-    maximumTick: visible && maxima.length ? Math.max(...maxima) : undefined,
-    minimumTick: visible && minima.length ? Math.min(...minima) : undefined,
+    maximumTick:
+      options?.maximumTickVisible !== false && maxima.length ? Math.max(...maxima) : undefined,
+    minimumTick:
+      options?.minimumTickVisible !== false && minima.length ? Math.min(...minima) : undefined,
   }
 }
 

package/src/components/core/yAxisTitleLayout.ts

@@ -1,13 +1,9 @@
 import { formatYAxisTickLayoutLabel } from './layout'
 import type { TrackLayout, WaveformYAxisLayout } from './types'
 import type { WaveformYAxisLabelTextStyle } from '../../types'
-import { resolveYAxisLabelBandWidth, resolveYAxisLabelFontSize } from './yAxisLabelStyle'
+import { resolveYAxisLabelBandWidth } from './yAxisLabelStyle'
 import { Y_AXIS_CHARACTER_WIDTH, Y_AXIS_TICK_PADDING } from './yAxisConstants'
 
-// Match the 11px ticks in WaveformTrack.css.
-const TICK_FONT_SIZE = 11
-const TEXT_GAP = 2
-
 interface TitleLayoutOptions {
   labelTextStyle?: WaveformYAxisLabelTextStyle
   showUnits?: boolean
@@ -15,52 +11,20 @@ interface TitleLayoutOptions {
   measureTextWidth?: (text: string) => number
 }
 
-function estimateTitleWidth(title: string, fontSize: number): number {
-  return Array.from(title).reduce((width, character) => {
-    // Latin labels average well below one em; full-width characters occupy one em.
-    const em = /[\u2e80-\u9fff\uf900-\ufaff\uff01-\uff60]/u.test(character)
-      ? 1
-      : /[MW@%]/u.test(character)
-        ? 0.95
-        : /[ilI1., :;|'!]/u.test(character)
-          ? 0.4
-          : 0.65
-    return width + em * fontSize
-  }, 0)
-}
-
 type TitleTrack = Pick<TrackLayout, 'height' | 'column' | 'yAxes'>
 
-function titleDistance(
-  track: TitleTrack,
-  axis: WaveformYAxisLayout,
-  yLabel: string | undefined,
-  options: TitleLayoutOptions,
-): number {
+function titleDistance(axis: WaveformYAxisLayout, options: TitleLayoutOptions): number {
   const series = axis.seriesList[0]
-  const title = series?.name.trim() || yLabel || ''
-  const halfTitleHeight =
-    estimateTitleWidth(title, resolveYAxisLabelFontSize(options.labelTextStyle)) / 2
-  const titleTop = track.height / 2 - halfTitleHeight - TEXT_GAP
-  const titleBottom = track.height / 2 + halfTitleHeight + TEXT_GAP
-  const lowestTick = Math.min(...axis.tickValues)
-  const highestTick = Math.max(...axis.tickValues)
-  const tickWidths = axis.tickValues.flatMap((value) => {
-    // D3 places ticks at scale(value) + 0.5. The lowest label is bottom-aligned;
-    // all other labels are vertically centered using dy="0.32em".
-    const y = axis.scale(value) + 0.5
-    const isTopAligned = options.compact && value === highestTick
-    const top = y - (value === lowestTick ? TICK_FONT_SIZE : isTopAligned ? 0 : TICK_FONT_SIZE / 2)
-    const bottom =
-      value === lowestTick ? y : y + (isTopAligned ? TICK_FONT_SIZE : TICK_FONT_SIZE / 2)
-    if (bottom < titleTop || top > titleBottom) return []
+  // Reserve the widest tick, including extrema, regardless of the frame height.
+  // The layout formatter excludes scientific multipliers but retains the numeric label.
+  const tickWidths = axis.tickValues.map((value) => {
     const text = formatYAxisTickLayoutLabel(
       value,
       axis.scale.domain() as [number, number],
       axis.tickValues,
       options.showUnits === false ? undefined : series?.unit,
     )
-    return [options.measureTextWidth?.(text) ?? text.length * Y_AXIS_CHARACTER_WIDTH]
+    return options.measureTextWidth?.(text) ?? text.length * Y_AXIS_CHARACTER_WIDTH
   })
   // The title band leaves 4px beside each glyph.
   return (
@@ -72,7 +36,7 @@ function titleDistance(
 
 export function alignLeftYAxisTitles(
   layouts: TitleTrack[],
-  yLabel?: string,
+  _yLabel?: string,
   options: TitleLayoutOptions = {},
 ): void {
   const distances = new Map<string, number>()
@@ -81,11 +45,8 @@ export function alignLeftYAxisTitles(
     for (const axis of track.yAxes) {
       if (axis.side !== 'left') continue
       const key = `${track.column}:${leftIndex++}`
-      const distance = titleDistance(track, axis, yLabel, options)
-      // Compact slots already reserve every tick. Only move names inward, so
-      // alignment can never push them beyond the space reserved at the chart edge.
-      const boundedDistance = options.compact ? Math.min(axis.x - axis.labelX, distance) : distance
-      distances.set(key, Math.max(distances.get(key) ?? 0, boundedDistance))
+      const distance = titleDistance(axis, options)
+      distances.set(key, Math.max(distances.get(key) ?? 0, distance))
     }
   }
   for (const track of layouts) {

package/src/components/interaction/useExtremaTickViewport.ts

@@ -5,7 +5,7 @@ import type { TrackLayout } from '../core/types'
 
 /** Keep X coordinates stable when toggling extrema changes the reserved Y-label width. */
 export function useExtremaTickViewport(
-  visible: () => boolean,
+  visible: () => number,
   innerWidth: ComputedRef<number>,
   tracks: ComputedRef<TrackLayout[]>,
   sharedTransform: ShallowRef<ZoomTransform>,

package/src/components/rendering/WaveformSeriesLayer.vue

@@ -7,6 +7,7 @@ import { waveformLineDasharray, waveformPointSeriesPath } from './seriesStyle'
 
 const props = defineProps<{
   track: TrackLayout
+  paginationOpacity?: number
   clipPathId: string
 }>()
 
@@ -51,11 +52,22 @@ const renderedSeriesPaths = computed<RenderedSeriesPath[]>(() =>
   >
     <g
       v-for="seriesPath in renderedSeriesPaths"
-      :key="seriesPath.series.id"
+      :key="seriesPath.presentationKey ?? seriesPath.series.id"
+      :opacity="(seriesPath.opacity ?? 1) * (paginationOpacity ?? 1)"
+      :clip-path="seriesPath.animationClip ? `url(#${seriesPath.animationClip.id})` : undefined"
       class="waveform-track__series-item waveform-chart__series"
       :data-series-id="seriesPath.series.id"
       :data-series-name="seriesPath.series.name || undefined"
     >
+      <defs v-if="seriesPath.animationClip">
+        <clipPath :id="seriesPath.animationClip.id" clipPathUnits="userSpaceOnUse">
+          <rect
+            :x="seriesPath.animationClip.x"
+            :width="seriesPath.animationClip.width"
+            :height="track.height"
+          />
+        </clipPath>
+      </defs>
       <path
         v-if="seriesPath.path"
         class="waveform-track__line waveform-chart__line"

package/src/components/rendering/WaveformTrack.vue

@@ -12,6 +12,7 @@ import WaveformTrackBackdrop from './WaveformTrackBackdrop.vue'
 
 interface Props {
   track: TrackLayout
+  paginationOpacity?: number
   clipPathId: string
   innerWidth: number
   zoomable: boolean
@@ -136,7 +137,11 @@ const frameInset = computed(() =>
       aria-hidden="true"
     />
 
-    <WaveformSeriesLayer :track="track" :clip-path-id="clipPathId" />
+    <WaveformSeriesLayer
+      :track="track"
+      :clip-path-id="clipPathId"
+      :pagination-opacity="paginationOpacity"
+    />
     <WaveformZeroLines
       :track="track"
       :clip-path-id="clipPathId"