refactor(plugins): Migrate to reactive streams and signal-based state (#4254)

katspaugh · web-flow · commit 970df1e368a3 · 2025-11-27T20:12:22.000+01:00
* refactor(plugins): migrate to reactive streams and signal-based state

- Refactor Hover plugin to use fromEvent() and effect() for reactive event handling
- Refactor Timeline plugin to react to state.duration changes automatically
- Refactor Zoom plugin to integrate with state.zoom and state.duration signals
- Refactor Minimap plugin to react to state.audioBuffer changes
- Replace manual event listener cleanup with unified subscriptions array
- Eliminate custom unsubscribe functions in favor of BasePlugin pattern
- Integrate plugins with WaveSurfer reactive state signals

Benefits:
- Consistent reactive patterns across all plugins
- Declarative state-driven updates
- Automatic cleanup prevents memory leaks
- Better TypeScript integration with signals
- Reduced boilerplate code

All tests pass. No breaking changes to public APIs.

* fix(Timeline): prevent timeline disappearing on scroll

The scroll listener was being re-registered on every initTimeline() call,
causing multiple listeners to reference stale timeline DOM elements.

Solution:
- Register scroll listener once in onInit() instead of in initTimeline()
- Store reference to current timeline element
- Update scroll listener to use the stored reference

This prevents memory leaks and ensures the timeline remains visible when scrolling.

* fix(Minimap): restore rendering by using duration state instead of audioBuffer

The audioBuffer state is never set in WaveSurfer core, so the reactive effect
was never triggered. The minimap requires decoded data to initialize, which
is available after the duration is set.

Solution:
- React to state.duration changes instead of state.audioBuffer
- Check that decoded data exists before initializing minimap
- This effectively replaces the 'decode' event with reactive state observation

The minimap now renders correctly on audio load.

* refactor(Zoom): convert addEventListener to reactive fromEvent streams

Replace manual event listener management with reactive event streams:
- Use fromEvent() for wheel, touchstart, touchmove, touchend, touchcancel
- Use effect() to react to event stream changes
- Remove manual removeEventListener calls in destroy()
- Cleanup now handled automatically through subscriptions array

Benefits:
- Consistent reactive pattern across all DOM event handling
- Automatic cleanup prevents memory leaks
- More declarative event handling

* fix(Minimap): revert to using decode event instead of reactive state

The previous reactive approach had a race condition where state.duration
could be set before decoded data was available, causing the minimap to not
render. The 'decode' event is the correct trigger as it fires exactly when
audio data is decoded and ready.

Changes:
- Revert from effect(state.duration) back to on('decode')
- Remove unused effect import
- Simplify onScroll to use getDuration() directly

This restores the original working behavior while maintaining the
subscriptions array pattern for automatic cleanup.
diff --git a/src/plugins/hover.ts b/src/plugins/hover.ts
@@ -4,6 +4,8 @@
 
 import BasePlugin, { type BasePluginEvents } from '../base-plugin.js'
 import createElement from '../dom.js'
+import { fromEvent } from '../reactive/event-streams.js'
+import { effect } from '../reactive/store.js'
 
 export type HoverPluginOptions = {
   /** The hover cursor color (playback cursor and progress mask colors used as falllback in this order)
@@ -53,7 +55,6 @@ class HoverPlugin extends BasePlugin<HoverPluginEvents, HoverPluginOptions> {
   private wrapper: HTMLElement
   private label: HTMLElement
   private lastPointerPosition: { clientX: number; clientY: number } | null = null
-  private unsubscribe: () => void = () => undefined
 
   constructor(options?: HoverPluginOptions) {
     super(options || {})
@@ -109,66 +110,82 @@ class HoverPlugin extends BasePlugin<HoverPluginEvents, HoverPluginOptions> {
     const container = this.wavesurfer.getWrapper()
     container.appendChild(this.wrapper)
 
-    // When zoom or scroll happens, re-run the pointer move logic
-    // with the last known mouse position
+    // Get reactive state
+    const state = this.wavesurfer.getState()
+
+    // Create event streams for pointer events
+    const pointerMove = fromEvent(container, 'pointermove')
+    const pointerLeave = fromEvent(container, 'pointerleave')
+
+    // React to pointer movement
+    this.subscriptions.push(
+      effect(() => {
+        const e = pointerMove.value
+        if (!e || !this.wavesurfer) return
+
+        // Store only the position data needed for zoom/scroll updates
+        this.lastPointerPosition = { clientX: e.clientX, clientY: e.clientY }
+
+        // Position
+        const bbox = this.wavesurfer.getWrapper().getBoundingClientRect()
+        const { width } = bbox
+        const offsetX = e.clientX - bbox.left
+        const relX = Math.min(1, Math.max(0, offsetX / width))
+        const posX = Math.min(width - this.options.lineWidth - 1, offsetX)
+        this.wrapper.style.transform = `translateX(${posX}px)`
+        this.wrapper.style.opacity = '1'
+
+        // Timestamp
+        const duration = state.duration.value
+        this.label.textContent = this.options.formatTimeCallback(duration * relX)
+        const labelWidth = this.label.offsetWidth
+        const transformCondition = this.options.labelPreferLeft ? posX - labelWidth > 0 : posX + labelWidth > width
+        this.label.style.transform = transformCondition ? `translateX(-${labelWidth + this.options.lineWidth}px)` : ''
+
+        // Emit a hover event with the relative X position
+        this.emit('hover', relX)
+      }, [pointerMove, state.duration]),
+    )
+
+    // React to pointer leave
+    this.subscriptions.push(
+      effect(() => {
+        const e = pointerLeave.value
+        if (!e) return
+
+        this.wrapper.style.opacity = '0'
+        this.lastPointerPosition = null
+      }, [pointerLeave]),
+    )
+
+    // When zoom or scroll happens, re-run the pointer move logic with the last known mouse position
     const onUpdate = () => {
-      if (this.lastPointerPosition) {
-        // Recreate a minimal PointerEvent-like object
-        this.onPointerMove(this.lastPointerPosition as PointerEvent)
+      if (this.lastPointerPosition && this.wavesurfer) {
+        // Position
+        const bbox = this.wavesurfer.getWrapper().getBoundingClientRect()
+        const { width } = bbox
+        const offsetX = this.lastPointerPosition.clientX - bbox.left
+        const relX = Math.min(1, Math.max(0, offsetX / width))
+        const posX = Math.min(width - this.options.lineWidth - 1, offsetX)
+        this.wrapper.style.transform = `translateX(${posX}px)`
+
+        // Timestamp
+        const duration = state.duration.value
+        this.label.textContent = this.options.formatTimeCallback(duration * relX)
+        const labelWidth = this.label.offsetWidth
+        const transformCondition = this.options.labelPreferLeft ? posX - labelWidth > 0 : posX + labelWidth > width
+        this.label.style.transform = transformCondition ? `translateX(-${labelWidth + this.options.lineWidth}px)` : ''
       }
     }
 
-    // Create unsubscribe function for wavesurfer events
-    const unsubscribeZoom = this.wavesurfer.on('zoom', onUpdate)
-    const unsubscribeScroll = this.wavesurfer.on('scroll', onUpdate)
-
-    // Attach pointer events and create complete unsubscribe function
-    container.addEventListener('pointermove', this.onPointerMove)
-    container.addEventListener('pointerleave', this.onPointerLeave)
-
-    this.unsubscribe = () => {
-      container.removeEventListener('pointermove', this.onPointerMove)
-      container.removeEventListener('pointerleave', this.onPointerLeave)
-      unsubscribeZoom()
-      unsubscribeScroll()
-    }
-  }
-
-  private onPointerMove = (e: PointerEvent) => {
-    if (!this.wavesurfer) return
-
-    // Store only the position data needed for zoom/scroll updates
-    this.lastPointerPosition = { clientX: e.clientX, clientY: e.clientY }
-
-    // Position
-    const bbox = this.wavesurfer.getWrapper().getBoundingClientRect()
-    const { width } = bbox
-    const offsetX = e.clientX - bbox.left
-    const relX = Math.min(1, Math.max(0, offsetX / width))
-    const posX = Math.min(width - this.options.lineWidth - 1, offsetX)
-    this.wrapper.style.transform = `translateX(${posX}px)`
-    this.wrapper.style.opacity = '1'
-
-    // Timestamp
-    const duration = this.wavesurfer.getDuration() || 0
-    this.label.textContent = this.options.formatTimeCallback(duration * relX)
-    const labelWidth = this.label.offsetWidth
-    const transformCondition = this.options.labelPreferLeft ? posX - labelWidth > 0 : posX + labelWidth > width
-    this.label.style.transform = transformCondition ? `translateX(-${labelWidth + this.options.lineWidth}px)` : ''
-
-    // Emit a hover event with the relative X position
-    this.emit('hover', relX)
-  }
-
-  private onPointerLeave = () => {
-    this.wrapper.style.opacity = '0'
-    this.lastPointerPosition = null
+    // Subscribe to zoom and scroll events
+    this.subscriptions.push(this.wavesurfer.on('zoom', onUpdate))
+    this.subscriptions.push(this.wavesurfer.on('scroll', onUpdate))
   }
 
   /** Unmount */
   public destroy() {
     super.destroy()
-    this.unsubscribe()
     this.wrapper.remove()
   }
 }
diff --git a/src/plugins/minimap.ts b/src/plugins/minimap.ts
@@ -244,6 +244,7 @@ class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions
   private initWaveSurferEvents() {
     if (!this.wavesurfer) return
 
+    // Subscribe to decode, scroll and redraw events
     this.subscriptions.push(
       this.wavesurfer.on('decode', () => {
         this.initMinimap()
diff --git a/src/plugins/timeline.ts b/src/plugins/timeline.ts
@@ -4,6 +4,7 @@
 
 import BasePlugin, { type BasePluginEvents } from '../base-plugin.js'
 import createElement from '../dom.js'
+import { effect } from '../reactive/store.js'
 
 export type TimelinePluginOptions = {
   /** The height of the timeline in pixels, defaults to 20 */
@@ -56,9 +57,9 @@ export type TimelinePluginEvents = BasePluginEvents & {
 
 class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOptions> {
   private timelineWrapper: HTMLElement
-  private unsubscribeNotches: (() => void)[] = []
   protected options: TimelinePluginOptions & typeof defaultOptions
   private notchElements: Map<HTMLElement, { start: number; width: number; wasVisible: boolean }> = new Map()
+  private currentTimeline: HTMLElement | null = null
 
   constructor(options?: TimelinePluginOptions) {
     super(options || {})
@@ -95,17 +96,37 @@ class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOpti
       container.appendChild(this.timelineWrapper)
     }
 
+    // Get reactive state
+    const state = this.wavesurfer.getState()
+
+    // React to duration changes and redraw events to initialize timeline
+    this.subscriptions.push(
+      effect(() => {
+        const duration = state.duration.value
+        if (duration > 0 || this.options.duration) {
+          this.initTimeline()
+        }
+      }, [state.duration]),
+    )
+
     this.subscriptions.push(this.wavesurfer.on('redraw', () => this.initTimeline()))
 
+    // Add single scroll listener for all notches (register once, not on every redraw)
+    this.subscriptions.push(
+      this.wavesurfer.on('scroll', (_start, _end, scrollLeft, scrollRight) => {
+        if (this.currentTimeline) {
+          this.updateVisibleNotches(scrollLeft, scrollRight, this.currentTimeline)
+        }
+      }),
+    )
+
     if (this.wavesurfer?.getDuration() || this.options.duration) {
       this.initTimeline()
     }
   }
 
   /** Unmount */
   public destroy() {
-    this.unsubscribeNotches.forEach((unsubscribe) => unsubscribe())
-    this.unsubscribeNotches = []
     this.timelineWrapper.remove()
     super.destroy()
   }
@@ -188,8 +209,6 @@ class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOpti
   }
 
   private initTimeline() {
-    this.unsubscribeNotches.forEach((unsubscribe) => unsubscribe())
-    this.unsubscribeNotches = []
     this.notchElements.clear()
 
     const duration = this.wavesurfer?.getDuration() ?? this.options.duration ?? 0
@@ -272,15 +291,7 @@ class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOpti
 
     this.timelineWrapper.innerHTML = ''
     this.timelineWrapper.appendChild(timeline)
-
-    // Add single scroll listener for all notches (instead of one per notch)
-    if (this.wavesurfer) {
-      this.unsubscribeNotches.push(
-        this.wavesurfer.on('scroll', (_start, _end, scrollLeft, scrollRight) => {
-          this.updateVisibleNotches(scrollLeft, scrollRight, timeline)
-        }),
-      )
-    }
+    this.currentTimeline = timeline
 
     this.emit('ready')
   }
diff --git a/src/plugins/zoom.ts b/src/plugins/zoom.ts
@@ -22,6 +22,8 @@
  */
 
 import { BasePlugin, BasePluginEvents } from '../base-plugin.js'
+import { effect } from '../reactive/store.js'
+import { fromEvent } from '../reactive/event-streams.js'
 
 export type ZoomPluginOptions = {
   /**
@@ -95,16 +97,72 @@ class ZoomPlugin extends BasePlugin<ZoomPluginEvents, ZoomPluginOptions> {
     }
     this.container = this.wrapper.parentElement as HTMLElement
 
-    this.container.addEventListener('wheel', this.onWheel)
-    this.container.addEventListener('touchstart', this.onTouchStart, { passive: false, capture: true })
-    this.container.addEventListener('touchmove', this.onTouchMove, { passive: false, capture: true })
-    this.container.addEventListener('touchend', this.onTouchEnd, { passive: false, capture: true })
-    this.container.addEventListener('touchcancel', this.onTouchEnd, { passive: false, capture: true })
-
     if (typeof this.options.maxZoom === 'undefined') {
       this.options.maxZoom = this.container.clientWidth
     }
     this.endZoom = this.options.maxZoom
+
+    // Get reactive state
+    const state = this.wavesurfer?.getState()
+
+    // React to zoom state changes to update internal state
+    if (state) {
+      this.subscriptions.push(
+        effect(() => {
+          const zoom = state.zoom.value
+          if (zoom > 0 && this.startZoom === 0 && this.options.exponentialZooming) {
+            const duration = state.duration.value
+            if (duration > 0 && this.container) {
+              this.startZoom = this.container.clientWidth / duration
+            }
+          }
+        }, [state.zoom, state.duration]),
+      )
+    }
+
+    // Create event streams
+    const wheelStream = fromEvent(this.container, 'wheel')
+    const touchStartStream = fromEvent(this.container, 'touchstart')
+    const touchMoveStream = fromEvent(this.container, 'touchmove')
+    const touchEndStream = fromEvent(this.container, 'touchend')
+    const touchCancelStream = fromEvent(this.container, 'touchcancel')
+
+    // React to wheel events
+    this.subscriptions.push(
+      effect(() => {
+        const e = wheelStream.value
+        if (e) this.onWheel(e)
+      }, [wheelStream]),
+    )
+
+    // React to touch events
+    this.subscriptions.push(
+      effect(() => {
+        const e = touchStartStream.value
+        if (e) this.onTouchStart(e)
+      }, [touchStartStream]),
+    )
+
+    this.subscriptions.push(
+      effect(() => {
+        const e = touchMoveStream.value
+        if (e) this.onTouchMove(e)
+      }, [touchMoveStream]),
+    )
+
+    this.subscriptions.push(
+      effect(() => {
+        const e = touchEndStream.value
+        if (e) this.onTouchEnd(e)
+      }, [touchEndStream]),
+    )
+
+    this.subscriptions.push(
+      effect(() => {
+        const e = touchCancelStream.value
+        if (e) this.onTouchEnd(e)
+      }, [touchCancelStream]),
+    )
   }
 
   private onWheel = (e: WheelEvent) => {
@@ -248,13 +306,6 @@ class ZoomPlugin extends BasePlugin<ZoomPluginEvents, ZoomPluginOptions> {
   }
 
   destroy() {
-    if (this.container) {
-      this.container.removeEventListener('wheel', this.onWheel)
-      this.container.removeEventListener('touchstart', this.onTouchStart)
-      this.container.removeEventListener('touchmove', this.onTouchMove)
-      this.container.removeEventListener('touchend', this.onTouchEnd)
-      this.container.removeEventListener('touchcancel', this.onTouchEnd)
-    }
     super.destroy()
   }
 }
