wavesurfer.js 7.11.0 → 7.12.0

package/dist/reactive/event-stream-emitter.js

@@ -0,0 +1,151 @@
+/**
+ * Event stream emitter - bridges EventEmitter to reactive streams
+ *
+ * Provides reactive stream API on top of traditional EventEmitter.
+ * This allows users to choose between callback-based and stream-based APIs.
+ */
+import { signal } from './store.js';
+/**
+ * Convert an EventEmitter event to a reactive signal/stream
+ *
+ * Creates a signal that updates whenever the event is emitted.
+ * Returns both the signal (for reading values) and cleanup function.
+ *
+ * @example
+ * ```typescript
+ * const { stream, cleanup } = toStream(wavesurfer, 'play')
+ *
+ * // Subscribe to play events
+ * stream.subscribe(() => console.log('Playing!'))
+ *
+ * // Cleanup when done
+ * cleanup()
+ * ```
+ *
+ * @param emitter - EventEmitter instance
+ * @param eventName - Name of the event to stream
+ * @returns Object with stream signal and cleanup function
+ */
+export function toStream(emitter, eventName) {
+    const stream = signal(null);
+    // Listen to event and update signal
+    const handler = (...args) => {
+        stream.set(args);
+    };
+    // @ts-expect-error - EventEmitter on() signature
+    const unsubscribe = emitter.on(eventName, handler);
+    return {
+        stream,
+        cleanup: unsubscribe,
+    };
+}
+/**
+ * Create multiple event streams from an emitter
+ *
+ * Helper to create streams for multiple events at once.
+ *
+ * @example
+ * ```typescript
+ * const streams = toStreams(wavesurfer, ['play', 'pause', 'timeupdate'])
+ *
+ * streams.play.subscribe(() => console.log('Play'))
+ * streams.pause.subscribe(() => console.log('Pause'))
+ * streams.timeupdate.subscribe(([time]) => console.log('Time:', time))
+ *
+ * // Cleanup all
+ * streams.cleanup()
+ * ```
+ *
+ * @param emitter - EventEmitter instance
+ * @param eventNames - Array of event names to stream
+ * @returns Object with streams for each event and cleanup function
+ */
+export function toStreams(emitter, eventNames) {
+    const cleanups = [];
+    const result = {};
+    for (const eventName of eventNames) {
+        const { stream, cleanup } = toStream(emitter, eventName);
+        result[eventName] = stream;
+        cleanups.push(cleanup);
+    }
+    // Add cleanup that removes all event listeners
+    result.cleanup = () => {
+        cleanups.forEach((cleanup) => cleanup());
+    };
+    return result;
+}
+/**
+ * Create a stream that combines multiple events into one
+ *
+ * Useful when you want to react to any of several events.
+ *
+ * @example
+ * ```typescript
+ * const { stream, cleanup } = mergeStreams(wavesurfer, ['play', 'pause'])
+ *
+ * stream.subscribe(({ event, args }) => {
+ *   console.log(`Event ${event} fired with`, args)
+ * })
+ * ```
+ *
+ * @param emitter - EventEmitter instance
+ * @param eventNames - Array of event names to merge
+ * @returns Object with merged stream and cleanup function
+ */
+export function mergeStreams(emitter, eventNames) {
+    const stream = signal(null);
+    const cleanups = [];
+    for (const eventName of eventNames) {
+        // @ts-expect-error - EventEmitter on() signature
+        const unsubscribe = emitter.on(eventName, (...args) => {
+            stream.set({ event: eventName, args });
+        });
+        cleanups.push(unsubscribe);
+    }
+    return {
+        stream,
+        cleanup: () => {
+            cleanups.forEach((cleanup) => cleanup());
+        },
+    };
+}
+/**
+ * Helper to map event stream values
+ *
+ * @example
+ * ```typescript
+ * const { stream: timeStream } = toStream(wavesurfer, 'timeupdate')
+ * const seconds = mapStream(timeStream, ([time]) => Math.floor(time))
+ * ```
+ */
+export function mapStream(source, mapper) {
+    const result = signal(mapper(source.value));
+    const unsubscribe = source.subscribe((value) => {
+        result.set(mapper(value));
+    });
+    result._cleanup = unsubscribe;
+    return result;
+}
+/**
+ * Helper to filter event stream values
+ *
+ * @example
+ * ```typescript
+ * const { stream: timeStream } = toStream(wavesurfer, 'timeupdate')
+ * const afterTenSeconds = filterStream(timeStream, ([time]) => time > 10)
+ * ```
+ */
+export function filterStream(source, predicate) {
+    const initialValue = predicate(source.value) ? source.value : null;
+    const result = signal(initialValue);
+    const unsubscribe = source.subscribe((value) => {
+        if (predicate(value)) {
+            result.set(value);
+        }
+        else {
+            result.set(null);
+        }
+    });
+    result._cleanup = unsubscribe;
+    return result;
+}

package/dist/reactive/event-streams.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Event stream utilities for converting DOM events to reactive signals
+ *
+ * These utilities allow composing event handling using reactive primitives.
+ */
+import { type Signal, type WritableSignal } from './store.js';
+/**
+ * Convert DOM events to a reactive signal
+ *
+ * @example
+ * ```typescript
+ * const clicks = fromEvent(button, 'click')
+ * clicks.subscribe(event => console.log('Clicked!', event))
+ * ```
+ */
+export declare function fromEvent<K extends keyof HTMLElementEventMap>(element: HTMLElement, eventName: K): WritableSignal<HTMLElementEventMap[K] | null>;
+/**
+ * Transform stream values using a mapping function
+ *
+ * @example
+ * ```typescript
+ * const clicks = fromEvent(button, 'click')
+ * const positions = map(clicks, e => e ? e.clientX : 0)
+ * ```
+ */
+export declare function map<T, U>(source: Signal<T>, mapper: (value: T) => U): Signal<U>;
+/**
+ * Filter stream values based on a predicate
+ *
+ * @example
+ * ```typescript
+ * const numbers = signal(5)
+ * const evenOnly = filter(numbers, n => n % 2 === 0)
+ * ```
+ */
+export declare function filter<T>(source: Signal<T>, predicate: (value: T) => boolean): Signal<T | null>;
+/**
+ * Debounce stream updates - wait for quiet period before emitting
+ *
+ * @example
+ * ```typescript
+ * const input = fromEvent(textField, 'input')
+ * const debounced = debounce(input, 300) // Wait 300ms after last input
+ * ```
+ */
+export declare function debounce<T>(source: Signal<T>, delay: number): Signal<T>;
+/**
+ * Throttle stream updates - limit update frequency
+ *
+ * Emits immediately, then waits before allowing next emission.
+ * Different from debounce which waits for quiet period.
+ *
+ * @example
+ * ```typescript
+ * const scroll = fromEvent(window, 'scroll')
+ * const throttled = throttle(scroll, 100) // Max once per 100ms
+ * ```
+ */
+export declare function throttle<T>(source: Signal<T>, delay: number): Signal<T>;
+/**
+ * Cleanup a stream created with event stream utilities
+ *
+ * This removes event listeners and unsubscribes from sources.
+ */
+export declare function cleanup(stream: Signal<any>): void;

package/dist/reactive/event-streams.js

@@ -0,0 +1,146 @@
+/**
+ * Event stream utilities for converting DOM events to reactive signals
+ *
+ * These utilities allow composing event handling using reactive primitives.
+ */
+import { signal } from './store.js';
+/**
+ * Convert DOM events to a reactive signal
+ *
+ * @example
+ * ```typescript
+ * const clicks = fromEvent(button, 'click')
+ * clicks.subscribe(event => console.log('Clicked!', event))
+ * ```
+ */
+export function fromEvent(element, eventName) {
+    const stream = signal(null);
+    const handler = (event) => {
+        stream.set(event);
+    };
+    element.addEventListener(eventName, handler);
+    stream._cleanup = () => {
+        element.removeEventListener(eventName, handler);
+    };
+    return stream;
+}
+/**
+ * Transform stream values using a mapping function
+ *
+ * @example
+ * ```typescript
+ * const clicks = fromEvent(button, 'click')
+ * const positions = map(clicks, e => e ? e.clientX : 0)
+ * ```
+ */
+export function map(source, mapper) {
+    const result = signal(mapper(source.value));
+    const unsubscribe = source.subscribe((value) => {
+        ;
+        result.set(mapper(value));
+    });
+    result._cleanup = unsubscribe;
+    return result;
+}
+/**
+ * Filter stream values based on a predicate
+ *
+ * @example
+ * ```typescript
+ * const numbers = signal(5)
+ * const evenOnly = filter(numbers, n => n % 2 === 0)
+ * ```
+ */
+export function filter(source, predicate) {
+    const initialValue = predicate(source.value) ? source.value : null;
+    const result = signal(initialValue);
+    const unsubscribe = source.subscribe((value) => {
+        if (predicate(value)) {
+            ;
+            result.set(value);
+        }
+        else {
+            ;
+            result.set(null);
+        }
+    });
+    result._cleanup = unsubscribe;
+    return result;
+}
+/**
+ * Debounce stream updates - wait for quiet period before emitting
+ *
+ * @example
+ * ```typescript
+ * const input = fromEvent(textField, 'input')
+ * const debounced = debounce(input, 300) // Wait 300ms after last input
+ * ```
+ */
+export function debounce(source, delay) {
+    const result = signal(source.value);
+    let timeout;
+    const unsubscribe = source.subscribe((value) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            ;
+            result.set(value);
+        }, delay);
+    });
+    result._cleanup = () => {
+        clearTimeout(timeout);
+        unsubscribe();
+    };
+    return result;
+}
+/**
+ * Throttle stream updates - limit update frequency
+ *
+ * Emits immediately, then waits before allowing next emission.
+ * Different from debounce which waits for quiet period.
+ *
+ * @example
+ * ```typescript
+ * const scroll = fromEvent(window, 'scroll')
+ * const throttled = throttle(scroll, 100) // Max once per 100ms
+ * ```
+ */
+export function throttle(source, delay) {
+    const result = signal(source.value);
+    let lastEmit = 0;
+    let timeout;
+    const unsubscribe = source.subscribe((value) => {
+        const now = Date.now();
+        const timeSinceLastEmit = now - lastEmit;
+        if (timeSinceLastEmit >= delay) {
+            // Enough time has passed, emit immediately
+            ;
+            result.set(value);
+            lastEmit = now;
+        }
+        else {
+            // Too soon, schedule for later
+            clearTimeout(timeout);
+            timeout = setTimeout(() => {
+                ;
+                result.set(value);
+                lastEmit = Date.now();
+            }, delay - timeSinceLastEmit);
+        }
+    });
+    result._cleanup = () => {
+        clearTimeout(timeout);
+        unsubscribe();
+    };
+    return result;
+}
+/**
+ * Cleanup a stream created with event stream utilities
+ *
+ * This removes event listeners and unsubscribes from sources.
+ */
+export function cleanup(stream) {
+    const cleanupFn = stream._cleanup;
+    if (typeof cleanupFn === 'function') {
+        cleanupFn();
+    }
+}

package/dist/reactive/media-event-bridge.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Media event bridge utilities
+ *
+ * Bridges HTMLMediaElement events to reactive state updates.
+ * Provides a clean separation between imperative media API and reactive state.
+ */
+import type { WaveSurferActions } from '../state/wavesurfer-state.js';
+/**
+ * Bridge HTMLMediaElement events to WaveSurfer state actions
+ *
+ * This function sets up event listeners on a media element that automatically
+ * update the reactive state through actions. It handles all standard media events
+ * (play, pause, timeupdate, etc.) and keeps state in sync with media.
+ *
+ * @example
+ * ```typescript
+ * const { state, actions } = createWaveSurferState()
+ * const media = document.createElement('audio')
+ *
+ * const cleanup = bridgeMediaEvents(media, actions)
+ *
+ * // Now media events automatically update state
+ * media.play() // → actions.setPlaying(true)
+ * ```
+ *
+ * @param media - HTMLMediaElement to listen to
+ * @param actions - State actions to call on events
+ * @returns Cleanup function that removes all listeners
+ */
+export declare function bridgeMediaEvents(media: HTMLMediaElement, actions: WaveSurferActions): () => void;
+/**
+ * Bridge HTMLMediaElement events with custom handler
+ *
+ * Similar to bridgeMediaEvents but allows custom state update logic.
+ * Useful when you need more control over how events map to state.
+ *
+ * @example
+ * ```typescript
+ * const cleanup = bridgeMediaEventsWithHandler(media, (event, data) => {
+ *   if (event === 'play') {
+ *     actions.setPlaying(true)
+ *     console.log('Started playing')
+ *   }
+ * })
+ * ```
+ *
+ * @param media - HTMLMediaElement to listen to
+ * @param handler - Custom handler function
+ * @returns Cleanup function that removes all listeners
+ */
+export declare function bridgeMediaEventsWithHandler(media: HTMLMediaElement, handler: (event: string, data?: any) => void): () => void;

package/dist/reactive/media-event-bridge.js

@@ -0,0 +1,152 @@
+/**
+ * Media event bridge utilities
+ *
+ * Bridges HTMLMediaElement events to reactive state updates.
+ * Provides a clean separation between imperative media API and reactive state.
+ */
+/**
+ * Bridge HTMLMediaElement events to WaveSurfer state actions
+ *
+ * This function sets up event listeners on a media element that automatically
+ * update the reactive state through actions. It handles all standard media events
+ * (play, pause, timeupdate, etc.) and keeps state in sync with media.
+ *
+ * @example
+ * ```typescript
+ * const { state, actions } = createWaveSurferState()
+ * const media = document.createElement('audio')
+ *
+ * const cleanup = bridgeMediaEvents(media, actions)
+ *
+ * // Now media events automatically update state
+ * media.play() // → actions.setPlaying(true)
+ * ```
+ *
+ * @param media - HTMLMediaElement to listen to
+ * @param actions - State actions to call on events
+ * @returns Cleanup function that removes all listeners
+ */
+export function bridgeMediaEvents(media, actions) {
+    const listeners = [];
+    // Helper to add event listener and track cleanup
+    const addListener = (event, handler, options) => {
+        media.addEventListener(event, handler, options);
+        listeners.push(() => media.removeEventListener(event, handler));
+    };
+    // ============================================================================
+    // Playback State Events
+    // ============================================================================
+    addListener('play', () => {
+        actions.setPlaying(true);
+    });
+    addListener('pause', () => {
+        actions.setPlaying(false);
+    });
+    addListener('ended', () => {
+        actions.setPlaying(false);
+        // Set current time to duration on end
+        if (media.duration) {
+            actions.setCurrentTime(media.duration);
+        }
+    });
+    // ============================================================================
+    // Time and Duration Events
+    // ============================================================================
+    addListener('timeupdate', () => {
+        actions.setCurrentTime(media.currentTime);
+    });
+    addListener('durationchange', () => {
+        if (isFinite(media.duration)) {
+            actions.setDuration(media.duration);
+        }
+    });
+    addListener('loadedmetadata', () => {
+        if (isFinite(media.duration)) {
+            actions.setDuration(media.duration);
+        }
+    });
+    // ============================================================================
+    // Seeking Events
+    // ============================================================================
+    addListener('seeking', () => {
+        actions.setSeeking(true);
+    });
+    addListener('seeked', () => {
+        actions.setSeeking(false);
+    });
+    // ============================================================================
+    // Volume Events
+    // ============================================================================
+    addListener('volumechange', () => {
+        actions.setVolume(media.volume);
+    });
+    // ============================================================================
+    // Playback Rate Events
+    // ============================================================================
+    addListener('ratechange', () => {
+        actions.setPlaybackRate(media.playbackRate);
+    });
+    // Return cleanup function that removes all listeners
+    return () => {
+        listeners.forEach((cleanup) => cleanup());
+    };
+}
+/**
+ * Bridge HTMLMediaElement events with custom handler
+ *
+ * Similar to bridgeMediaEvents but allows custom state update logic.
+ * Useful when you need more control over how events map to state.
+ *
+ * @example
+ * ```typescript
+ * const cleanup = bridgeMediaEventsWithHandler(media, (event, data) => {
+ *   if (event === 'play') {
+ *     actions.setPlaying(true)
+ *     console.log('Started playing')
+ *   }
+ * })
+ * ```
+ *
+ * @param media - HTMLMediaElement to listen to
+ * @param handler - Custom handler function
+ * @returns Cleanup function that removes all listeners
+ */
+export function bridgeMediaEventsWithHandler(media, handler) {
+    const listeners = [];
+    const addListener = (event) => {
+        const listener = (e) => {
+            handler(event, e);
+        };
+        media.addEventListener(event, listener);
+        listeners.push(() => media.removeEventListener(event, listener));
+    };
+    // Add all standard media events
+    const events = [
+        'play',
+        'pause',
+        'ended',
+        'timeupdate',
+        'durationchange',
+        'loadedmetadata',
+        'seeking',
+        'seeked',
+        'volumechange',
+        'ratechange',
+        'waiting',
+        'canplay',
+        'canplaythrough',
+        'loadstart',
+        'progress',
+        'suspend',
+        'abort',
+        'error',
+        'emptied',
+        'stalled',
+        'loadeddata',
+        'playing',
+    ];
+    events.forEach((event) => addListener(event));
+    return () => {
+        listeners.forEach((cleanup) => cleanup());
+    };
+}

package/dist/reactive/render-scheduler.d.ts

@@ -0,0 +1,43 @@
+/**
+ * RenderScheduler batches multiple render requests into a single frame using requestAnimationFrame.
+ * This prevents multiple state changes from triggering redundant renders.
+ */
+export type RenderPriority = 'high' | 'normal' | 'low';
+export declare class RenderScheduler {
+    private pendingRender;
+    private rafId;
+    /**
+     * Schedule a render to occur on the next animation frame.
+     * If a render is already scheduled, this is a no-op.
+     *
+     * @param renderFn - The function to call to perform the render
+     * @param priority - Render priority (high = immediate, normal/low = batched)
+     *
+     * @example
+     * ```typescript
+     * const scheduler = new RenderScheduler()
+     *
+     * // Multiple calls in same frame = single render
+     * scheduler.scheduleRender(() => draw())
+     * scheduler.scheduleRender(() => draw()) // no-op
+     * scheduler.scheduleRender(() => draw()) // no-op
+     * ```
+     */
+    scheduleRender(renderFn: () => void, priority?: RenderPriority): void;
+    /**
+     * Cancel any pending render request.
+     * Useful when unmounting or destroying components.
+     */
+    cancelRender(): void;
+    /**
+     * Force an immediate synchronous render, canceling any pending batched render.
+     * Use for high-priority updates like cursor during playback, or for testing.
+     *
+     * @param renderFn - The function to call to perform the render
+     */
+    flushRender(renderFn: () => void): void;
+    /**
+     * Check if a render is currently scheduled.
+     */
+    isPending(): boolean;
+}

package/dist/reactive/render-scheduler.js

@@ -0,0 +1,75 @@
+/**
+ * RenderScheduler batches multiple render requests into a single frame using requestAnimationFrame.
+ * This prevents multiple state changes from triggering redundant renders.
+ */
+export class RenderScheduler {
+    constructor() {
+        this.pendingRender = false;
+        this.rafId = null;
+    }
+    /**
+     * Schedule a render to occur on the next animation frame.
+     * If a render is already scheduled, this is a no-op.
+     *
+     * @param renderFn - The function to call to perform the render
+     * @param priority - Render priority (high = immediate, normal/low = batched)
+     *
+     * @example
+     * ```typescript
+     * const scheduler = new RenderScheduler()
+     *
+     * // Multiple calls in same frame = single render
+     * scheduler.scheduleRender(() => draw())
+     * scheduler.scheduleRender(() => draw()) // no-op
+     * scheduler.scheduleRender(() => draw()) // no-op
+     * ```
+     */
+    scheduleRender(renderFn, priority = 'normal') {
+        // High priority renders happen immediately
+        if (priority === 'high') {
+            this.flushRender(renderFn);
+            return;
+        }
+        // If already scheduled, don't schedule again
+        if (this.pendingRender)
+            return;
+        this.pendingRender = true;
+        this.rafId = requestAnimationFrame(() => {
+            try {
+                renderFn();
+            }
+            finally {
+                // Always clean up, even if render throws
+                this.pendingRender = false;
+                this.rafId = null;
+            }
+        });
+    }
+    /**
+     * Cancel any pending render request.
+     * Useful when unmounting or destroying components.
+     */
+    cancelRender() {
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+            this.pendingRender = false;
+        }
+    }
+    /**
+     * Force an immediate synchronous render, canceling any pending batched render.
+     * Use for high-priority updates like cursor during playback, or for testing.
+     *
+     * @param renderFn - The function to call to perform the render
+     */
+    flushRender(renderFn) {
+        this.cancelRender();
+        renderFn();
+    }
+    /**
+     * Check if a render is currently scheduled.
+     */
+    isPending() {
+        return this.pendingRender;
+    }
+}