waveform-analysis 0.1.73 → 0.1.75

package/src/animation/presets/lineDrawing.ts

@@ -0,0 +1,51 @@
+import type { AnimationConfig } from '../core/types'
+import type {
+  AnimationBinding,
+  ClipAnimationState,
+  LineDrawingOptions,
+  StaggeredLineDrawingOptions,
+} from '../types'
+import { clampProgress, presetConfig, validateBinding } from './shared'
+
+export function createLineDrawingAnimation(
+  binding: AnimationBinding<ClipAnimationState>,
+  width: number,
+  options: LineDrawingOptions = {},
+): AnimationConfig {
+  validateBinding(binding)
+  if (!Number.isFinite(width) || width < 0)
+    throw new RangeError('Width must be finite and nonnegative')
+  const direction = options.direction ?? 'left-to-right'
+  if (!['left-to-right', 'right-to-left', 'center-out'].includes(direction))
+    throw new TypeError('Invalid drawing direction')
+  const state = (p: number): ClipAnimationState => ({
+    x:
+      direction === 'right-to-left'
+        ? width * (1 - p)
+        : direction === 'center-out'
+          ? (width * (1 - p)) / 2
+          : 0,
+    width: width * p,
+  })
+  return presetConfig(
+    { ...options, duration: options.duration ?? 1000 },
+    {
+      delay: options.delay ?? 0,
+      initialize: () => binding.write(state(0)),
+      during: (p, frame) => binding.write(state(frame.terminal ? 1 : clampProgress(p))),
+    },
+  )
+}
+export function createStaggeredLineDrawingAnimations(
+  series: readonly { binding: AnimationBinding<ClipAnimationState>; width: number }[],
+  options: StaggeredLineDrawingOptions = {},
+): AnimationConfig[] {
+  const stagger = options.staggerDelay ?? 100
+  if (!Number.isFinite(stagger) || stagger < 0) throw new RangeError('Invalid stagger delay')
+  return series.map((item, index) =>
+    createLineDrawingAnimation(item.binding, item.width, {
+      ...options,
+      delay: (options.delay ?? 0) + index * stagger,
+    }),
+  )
+}

package/src/animation/presets/shared.ts

@@ -0,0 +1,58 @@
+import type { AnimationConfig, AnimationValue } from '../core/types'
+import { copyAnimationValue, validateAnimationConfig } from '../core/validation'
+import type {
+  AnimationBinding,
+  AnnotationAnimationType,
+  DataUpdateOptions,
+  NumericGeometry,
+} from '../types'
+
+export const annotationEasing = {
+  'fade-in': 'cubicOut',
+  scale: 'backOut',
+  'slide-in': 'cubicOut',
+  bounce: 'bounceOut',
+} as const
+export function isAnnotationEffect(value: unknown): value is AnnotationAnimationType {
+  return typeof value === 'string' && Object.hasOwn(annotationEasing, value)
+}
+
+export const clampProgress = (p: number) => Math.max(0, Math.min(1, p))
+export function validateBinding<T>(binding: AnimationBinding<T>): void {
+  if (!binding || typeof binding.read !== 'function' || typeof binding.write !== 'function') {
+    throw new TypeError('Animation binding requires read and write functions')
+  }
+}
+export function presetConfig(options: DataUpdateOptions, config: AnimationConfig): AnimationConfig {
+  const result = {
+    duration: options.duration ?? 300,
+    easing: options.easing ?? 'cubicInOut',
+    done: options.onComplete,
+    aborted: options.onAbort,
+    force: true,
+    ...config,
+  } satisfies AnimationConfig
+  validateAnimationConfig(result)
+  return result
+}
+function freezeValue(value: AnimationValue): AnimationValue {
+  if (Array.isArray(value)) {
+    value.forEach((item) => {
+      if (Array.isArray(item)) Object.freeze(item)
+    })
+    Object.freeze(value)
+  }
+  return value
+}
+export function copyGeometry(input: NumericGeometry): NumericGeometry {
+  if (!input || typeof input !== 'object' || Array.isArray(input))
+    throw new TypeError('Invalid geometry')
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(input).map(([key, value]) => [key, freezeValue(copyAnimationValue(value))]),
+    ),
+  )
+}
+export function validDomain(domain: readonly number[]): boolean {
+  return domain.length === 2 && domain.every(Number.isFinite) && domain[0] < domain[1]
+}

package/src/animation/presets/transitions.ts

@@ -0,0 +1,77 @@
+import type { AnimationConfig } from '../core/types'
+import { sameShape } from '../core/validation'
+import { interpolateValue, equalValues } from '../core/values'
+import type {
+  AnimationBinding,
+  DataUpdateOptions,
+  GeometryTransitionInput,
+  GeometryTransitionFrame,
+} from '../types'
+import { clampProgress, copyGeometry, presetConfig, validDomain, validateBinding } from './shared'
+
+export function createPathTransitionAnimation(
+  input: GeometryTransitionInput,
+  write: (frame: GeometryTransitionFrame) => void,
+  options: DataUpdateOptions = {},
+): AnimationConfig {
+  const compatible = input.compatible
+  if (typeof write !== 'function' || typeof compatible !== 'boolean')
+    throw new TypeError('Invalid geometry transition')
+  const from = copyGeometry(input.from),
+    to = copyGeometry(input.to)
+  const keys = Object.keys(to)
+  if (compatible) {
+    if (keys.length !== Object.keys(from).length || keys.some((key) => !Object.hasOwn(from, key))) {
+      throw new TypeError('Compatible geometry requires identical channels')
+    }
+    if (keys.some((key) => !sameShape(from[key], to[key])))
+      throw new TypeError('Track values must have identical shapes')
+  }
+  const unchanged = compatible && keys.every((key) => equalValues(from[key], to[key]))
+  return presetConfig(options, {
+    duration: unchanged ? 0 : (options.duration ?? 300),
+    during: (p, frame) => {
+      if (frame.terminal) write({ kind: 'settled', values: to })
+      else if (compatible)
+        write({
+          kind: 'interpolate',
+          progress: p,
+          values: Object.fromEntries(
+            keys.map((key) => [key, interpolateValue(from[key], to[key], p)]),
+          ),
+        })
+      else {
+        const q = clampProgress(p)
+        write({ kind: 'crossfade', from, to, fromOpacity: 1 - q, toOpacity: q })
+      }
+    },
+  })
+}
+export function createYAxisScaleAnimation(
+  binding: AnimationBinding<[number, number]>,
+  to: [number, number],
+  options: DataUpdateOptions = {},
+): AnimationConfig {
+  validateBinding(binding)
+  const target: [number, number] = [...to]
+  if (!validDomain(target))
+    throw new RangeError('Target domain must be finite and strictly increasing')
+  let from: [number, number] | undefined
+  return presetConfig(options, {
+    initialize: () => {
+      from = [...binding.read()]
+      if (!validDomain(from))
+        throw new RangeError('Initial domain must be finite and strictly increasing')
+    },
+    during: (p, frame) => {
+      if (frame.terminal) {
+        binding.write([...target])
+        return
+      }
+      const q = clampProgress(p)
+      const start = from ?? target
+      const value = interpolateValue(start, target, q) as [number, number]
+      binding.write(validDomain(value) ? value : [...target])
+    },
+  })
+}

package/src/animation/types.ts

@@ -0,0 +1,81 @@
+import type { AnimationValue, Animator, EasingFunction, EasingType } from './core/types'
+
+export type LineDrawingDirection = 'left-to-right' | 'right-to-left' | 'center-out'
+export type AnnotationAnimationType = 'fade-in' | 'scale' | 'slide-in' | 'bounce'
+export interface LineDrawingOptions {
+  duration?: number
+  delay?: number
+  easing?: EasingType | EasingFunction
+  direction?: LineDrawingDirection
+  onComplete?: () => void
+  onAbort?: () => void
+}
+export interface StaggeredLineDrawingOptions extends LineDrawingOptions {
+  staggerDelay?: number
+}
+export interface DataUpdateOptions {
+  duration?: number
+  easing?: EasingType | EasingFunction
+  onComplete?: () => void
+  onAbort?: () => void
+}
+export interface AnnotationAnimationOptions extends DataUpdateOptions {
+  type?: AnnotationAnimationType
+}
+export interface WaveformEnterAnimationOptions extends StaggeredLineDrawingOptions {
+  enabled?: boolean
+}
+export interface WaveformUpdateAnimationOptions extends DataUpdateOptions {
+  enabled?: boolean
+}
+export interface WaveformAnnotationAnimationOptions extends AnnotationAnimationOptions {
+  enabled?: boolean
+}
+/** Default-on presentation animation; immutable business data and queries remain authoritative. */
+export interface WaveformAnimationProps {
+  animationEnabled?: boolean
+  animation?: WaveformEnterAnimationOptions
+  animationUpdate?: WaveformUpdateAnimationOptions
+  animationAnnotation?: WaveformAnnotationAnimationOptions
+  animationThreshold?: number
+}
+export interface ClipAnimationState {
+  x: number
+  width: number
+}
+export interface AnimationBinding<T> {
+  read(): T
+  write(state: T): void
+}
+export type NumericGeometry = Record<string, AnimationValue>
+export interface GeometryTransitionInput {
+  from: NumericGeometry
+  to: NumericGeometry
+  compatible: boolean
+}
+export type GeometryTransitionFrame =
+  | { kind: 'settled'; values: NumericGeometry }
+  | { kind: 'interpolate'; values: NumericGeometry; progress: number }
+  | {
+      kind: 'crossfade'
+      from: NumericGeometry
+      to: NumericGeometry
+      fromOpacity: number
+      toOpacity: number
+    }
+export interface AnnotationAnimationState {
+  opacity: number
+  scale: number
+  offsetY: number
+}
+export type AnimationScope = 'enter' | 'update' | 'leave' | 'domain'
+export interface AnimationObjectKey {
+  kind: 'series' | 'annotation' | 'axis' | 'custom'
+  id: string
+  scope: AnimationScope
+}
+export interface WaveformAnimationControllerOptions {
+  enabled?: boolean
+  animator?: Animator
+  commitFinalState: () => void
+}

package/src/components/WaveformChart.vue

@@ -8,6 +8,7 @@ import type {
 import WaveformChartView from './WaveformChartView.vue'
 
 const props = withDefaults(defineProps<WaveformChartProps>(), {
+  animationEnabled: true,
   displayMode: 'independent',
   overlayMode: 'single-axis',
   unitDisplayMode: 'axis',

package/src/components/WaveformChartView.vue

@@ -48,6 +48,10 @@ const {
   hasWaveformData,
   requestViewportReset,
   trackLayouts,
+  presentationTracks,
+  presentationAnnotations,
+  paginationOpacity,
+  stabilizeAnimations,
   clipPathId,
   chartTopMargin,
   gridCells,
@@ -73,7 +77,6 @@ const {
   hoverState,
   showTooltip,
   selectionBox,
-  renderedAnnotations,
   annotationsVisible,
   handleExistingAnnotationContextMenu,
   beginAnnotationDrag,
@@ -142,9 +145,14 @@ function handleChartPointerLeave() {
     :data-plot-margin-top="resolvedPlotMargin.top"
     :data-plot-margin-bottom="resolvedPlotMargin.bottom"
     :data-title-area-height="titleAreaHeight"
+    @pointermove.capture="stabilizeAnimations"
+    @pointerdown.capture="stabilizeAnimations"
+    @wheel.capture="stabilizeAnimations"
+    @dblclick.capture="stabilizeAnimations"
+    @contextmenu.capture="stabilizeAnimations"
     @pointerenter="pointerInsideChart = true"
     @pointerleave="handleChartPointerLeave"
-    @contextmenu.capture="handleNativeContextMenu"
+    @contextmenu="handleNativeContextMenu"
   >
     <div
       v-if="titleAreaReserved"
@@ -235,7 +243,8 @@ function handleChartPointerLeave() {
         <WaveformTrack
           v-for="track in trackLayouts"
           :key="`${track.index}-${track.id}`"
-          :track="track"
+          :track="presentationTracks.find((item) => item.id === track.id) ?? track"
+          :pagination-opacity="paginationOpacity"
           :frame-path="
             displayMode === 'compact'
               ? compactFramePath(track, trackLayouts, compactFrameInset)
@@ -291,7 +300,7 @@ function handleChartPointerLeave() {
           :cancel-key="activeInteractionMode"
           :data-version="controller.data"
           v-if="!isCleanView"
-          :annotations="renderedAnnotations"
+          :annotations="presentationAnnotations"
           :visible="annotationsVisible"
           :interactive="!isPresentationMode && activeInteractionMode !== 'none'"
           @contextmenu="handleExistingAnnotationContextMenu"

package/src/components/animation/annotationPresentation.ts

@@ -0,0 +1,145 @@
+import type { RenderedAnnotation } from '../annotation/types'
+import type { ResolvedAnimationProps } from './config'
+import type { WaveformAnnotation } from '@/types'
+import type { AnnotationAnimationState } from '@/animation/types'
+import { WaveformAnimationController } from '@/animation/WaveformAnimationController'
+
+export interface PresentedAnnotation extends RenderedAnnotation {
+  animationStyle?: AnnotationAnimationState
+  leaving?: boolean
+  seriesOpacity?: number
+}
+interface Entry {
+  rendered: RenderedAnnotation
+  style: AnnotationAnimationState
+  leaving: boolean
+  waiting: boolean
+}
+export function createAnnotationPresentation(
+  controller: WaveformAnimationController,
+  invalidate: () => void,
+) {
+  const entries = new Map<string, Entry>()
+  const finalStyle = () => ({ opacity: 1, scale: 1, offsetY: 0 })
+  let options: ResolvedAnimationProps['animationAnnotation']
+  const binding = (id: string, entry: Entry) => ({
+    read: () => entry.style,
+    write: (style: AnnotationAnimationState) => {
+      entry.style = style
+      if (entry.leaving && style.opacity === 0 && entries.get(id) === entry) entries.delete(id)
+      invalidate()
+    },
+  })
+  function appear(id: string, entry: Entry) {
+    entry.waiting = false
+    controller.animateAnnotationAppear(id, binding(id, entry), options)
+  }
+  return {
+    reconcile(
+      rendered: RenderedAnnotation[],
+      controlled: WaveformAnnotation[],
+      config: ResolvedAnimationProps['animationAnnotation'],
+      enabled: boolean,
+      waitingSeries: Set<string>,
+    ) {
+      options = config
+      const visible = new Set(rendered.map((item) => item.annotation.id))
+      const existing = new Set(controlled.map((item) => item.id))
+      for (const [id, entry] of entries)
+        if (!visible.has(id) && (!entry.leaving || !enabled)) {
+          if (!existing.has(id) && enabled) {
+            entry.rendered = Object.freeze({
+              ...entry.rendered,
+              annotation: Object.freeze({
+                ...entry.rendered.annotation,
+                style: entry.rendered.annotation.style
+                  ? Object.freeze({ ...entry.rendered.annotation.style })
+                  : undefined,
+              }),
+              lines: Object.freeze([...entry.rendered.lines]) as unknown as string[],
+              box: Object.freeze({ ...entry.rendered.box }),
+              style: Object.freeze({ ...entry.rendered.style }),
+            })
+            entry.leaving = true
+            entry.waiting = false
+            controller.animateAnnotationDisappear(id, binding(id, entry), options)
+          } else {
+            entries.delete(id)
+            controller.cancel({ kind: 'annotation', id, scope: 'enter' })
+            controller.cancel({ kind: 'annotation', id, scope: 'leave' })
+          }
+        }
+      for (const item of rendered) {
+        const id = item.annotation.id
+        let entry = entries.get(id)
+        if (entry && !entry.leaving) {
+          entry.rendered = item
+          continue
+        }
+        if (entry) {
+          entry.leaving = false
+          controller.cancel({ kind: 'annotation', id, scope: 'leave' })
+          entry.rendered = item
+        } else {
+          entry = {
+            rendered: item,
+            leaving: false,
+            waiting: false,
+            style: enabled
+              ? {
+                  opacity: 0,
+                  scale: options.type === 'scale' || options.type === 'bounce' ? 0 : 1,
+                  offsetY: options.type === 'slide-in' ? 8 : 0,
+                }
+              : finalStyle(),
+          }
+          entries.set(id, entry)
+        }
+        if (enabled) {
+          entry.waiting = waitingSeries.has(item.annotation.seriesId)
+          if (!entry.waiting) appear(id, entry)
+        } else entry.style = finalStyle()
+      }
+      invalidate()
+    },
+    release(seriesId?: string) {
+      for (const [id, entry] of entries)
+        if (entry.waiting && (!seriesId || entry.rendered.annotation.seriesId === seriesId))
+          appear(id, entry)
+      invalidate()
+    },
+    finish(rendered: RenderedAnnotation[]) {
+      entries.clear()
+      for (const item of rendered)
+        entries.set(item.annotation.id, {
+          rendered: item,
+          style: finalStyle(),
+          leaving: false,
+          waiting: false,
+        })
+      invalidate()
+    },
+    project(
+      rendered: RenderedAnnotation[],
+      seriesOpacity: Map<string, number>,
+    ): PresentedAnnotation[] {
+      const current = new Map(rendered.map((item) => [item.annotation.id, item]))
+      return [...entries.values()]
+        .filter((entry) => entry.leaving || current.has(entry.rendered.annotation.id))
+        .map((entry) => {
+          if (!entry.leaving)
+            entry.rendered = current.get(entry.rendered.annotation.id) ?? entry.rendered
+          return {
+            ...entry.rendered,
+            animationStyle: entry.style,
+            leaving: entry.leaving,
+            seriesOpacity: seriesOpacity.get(entry.rendered.annotation.seriesId) ?? 1,
+          }
+        })
+    },
+    clear() {
+      entries.clear()
+      invalidate()
+    },
+  }
+}

package/src/components/animation/chartExportVersion.ts

@@ -0,0 +1,5 @@
+import type { ResolvedWaveformChartProps } from '../core/waveformChartTypes'
+import { chartExportOptions } from '../controls/chartExportOptions'
+export function chartExportVersion(props: ResolvedWaveformChartProps, state: object): unknown[] {
+  return [props.data, JSON.stringify({ ...chartExportOptions(props), ...state })]
+}

package/src/components/animation/config.ts

@@ -0,0 +1,87 @@
+import { getEasingFunction } from '@/animation/core/easing'
+import { annotationEasing, isAnnotationEffect } from '@/animation/presets/shared'
+import type {
+  WaveformAnimationProps,
+  AnnotationAnimationType,
+  LineDrawingDirection,
+} from '@/animation/types'
+
+export function resolveAnimationProps(
+  props: WaveformAnimationProps,
+  warn = (message: string) => {
+    if (import.meta.env.DEV) console.warn(message)
+  },
+) {
+  function field<T>(value: T | undefined, fallback: T, valid: (v: T) => boolean, key: string): T {
+    if (value === undefined) return fallback
+    if (valid(value)) return value
+    if (import.meta.env.DEV) warn(`Invalid animation configuration: ${key}`)
+    return fallback
+  }
+  const nonnegative = (v: number) => typeof v === 'number' && Number.isFinite(v) && v >= 0
+  const boolean = (v: boolean) => typeof v === 'boolean'
+  const easing = (v: unknown) => {
+    try {
+      getEasingFunction(v as never)
+      return true
+    } catch {
+      return false
+    }
+  }
+  const callback = (v: unknown) => typeof v === 'function'
+  function options<
+    T extends {
+      enabled?: boolean
+      duration?: number
+      easing?: unknown
+      onComplete?: () => void
+      onAbort?: () => void
+    },
+  >(input: T | undefined, duration: number, defaultEasing: string) {
+    return {
+      enabled: field(input?.enabled, true, boolean, 'enabled'),
+      duration: field(input?.duration, duration, nonnegative, 'duration'),
+      easing: field(input?.easing, defaultEasing, easing, 'easing') as NonNullable<T['easing']>,
+      onComplete:
+        input?.onComplete === undefined
+          ? undefined
+          : field(input.onComplete, () => {}, callback, 'onComplete'),
+      onAbort:
+        input?.onAbort === undefined
+          ? undefined
+          : field(input.onAbort, () => {}, callback, 'onAbort'),
+    }
+  }
+  const annotationType = field<AnnotationAnimationType>(
+    props.animationAnnotation?.type,
+    'scale',
+    isAnnotationEffect,
+    'annotation.type',
+  )
+  return {
+    animationEnabled: field(props.animationEnabled, true, boolean, 'animationEnabled'),
+    animationThreshold: field(
+      props.animationThreshold,
+      50000,
+      (v) => nonnegative(v) && Number.isInteger(v),
+      'animationThreshold',
+    ),
+    animation: {
+      ...options(props.animation, 1000, 'cubicInOut'),
+      delay: field(props.animation?.delay, 0, nonnegative, 'delay'),
+      staggerDelay: field(props.animation?.staggerDelay, 100, nonnegative, 'staggerDelay'),
+      direction: field<LineDrawingDirection>(
+        props.animation?.direction,
+        'left-to-right',
+        (v) => ['left-to-right', 'right-to-left', 'center-out'].includes(v),
+        'direction',
+      ),
+    },
+    animationUpdate: options(props.animationUpdate, 300, 'cubicInOut'),
+    animationAnnotation: {
+      ...options(props.animationAnnotation, 300, annotationEasing[annotationType]),
+      type: annotationType,
+    },
+  }
+}
+export type ResolvedAnimationProps = ReturnType<typeof resolveAnimationProps>

package/src/components/animation/context.ts

@@ -0,0 +1,56 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue'
+import type { TrackLayout } from '../core/types'
+import type { PreparedWaveformSeries } from '../core/useWaveformData'
+import type { ResolvedWaveformChartProps } from '../core/waveformChartTypes'
+
+export interface AnimationContext {
+  props: ResolvedWaveformChartProps
+  tracks: ComputedRef<TrackLayout[]>
+  currentPage: Ref<number>
+  containerSize: ComputedRef<number[]>
+  preparedSeries: ShallowRef<PreparedWaveformSeries[]>
+  layoutReady: ComputedRef<boolean>
+  innerWidth: ComputedRef<number>
+  innerHeight: ComputedRef<number>
+  sampling: {
+    state: ComputedRef<'pending' | 'success' | 'fallback' | 'error'>
+    requestSignature: ComputedRef<string>
+  }
+}
+
+export function animationLayoutSignature(context: AnimationContext) {
+  const { props, tracks } = context
+  return JSON.stringify({
+    tracks: tracks.value.map((track) => [
+      track.id,
+      track.left,
+      track.top,
+      track.width,
+      track.height,
+      track.seriesList.map((series) => series.id),
+      track.yAxes.map((axis) => axis.seriesList.map((series) => series.id)),
+    ]),
+    width: context.innerWidth.value,
+    height: context.innerHeight.value,
+    mode: props.displayMode,
+    overlay: props.overlayMode,
+    hidden: props.hiddenSeriesIds,
+    clean: props.cleanView,
+    presentation: props.presentationMode,
+    page: tracks.value.map((track) => track.id),
+  })
+}
+
+export function wrapAnimationCommands<T extends object>(commands: T, stabilize: () => void): T {
+  return Object.fromEntries(
+    Object.entries(commands).map(([key, value]) => [
+      key,
+      typeof value === 'function' && key !== 'getControlState'
+        ? (...args: unknown[]) => {
+            stabilize()
+            return value(...args)
+          }
+        : value,
+    ]),
+  ) as T
+}