wavesurfer.js 7.11.0 → 7.12.0

package/dist/reactive/scroll-stream.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Reactive scroll stream utilities
+ *
+ * Provides declarative scroll handling using reactive streams.
+ * Automatically handles scroll event optimization and cleanup.
+ */
+import { type Signal } from './store.js';
+export interface ScrollData {
+    /** Current scroll position in pixels */
+    scrollLeft: number;
+    /** Total scrollable width in pixels */
+    scrollWidth: number;
+    /** Visible viewport width in pixels */
+    clientWidth: number;
+}
+export interface ScrollPercentages {
+    /** Start position as percentage (0-1) */
+    startX: number;
+    /** End position as percentage (0-1) */
+    endX: number;
+}
+/**
+ * Calculate visible percentages from scroll data
+ * Pure function - no side effects
+ *
+ * @param scrollData - Current scroll dimensions
+ * @returns Start and end positions as percentages (0-1)
+ */
+export declare function calculateScrollPercentages(scrollData: ScrollData): ScrollPercentages;
+/**
+ * Calculate scroll bounds in pixels
+ * Pure function - no side effects
+ *
+ * @param scrollData - Current scroll dimensions
+ * @returns Left and right scroll bounds in pixels
+ */
+export declare function calculateScrollBounds(scrollData: ScrollData): {
+    left: number;
+    right: number;
+};
+export interface ScrollStream {
+    /** Signal containing current scroll data */
+    scrollData: Signal<ScrollData>;
+    /** Computed signal with visible percentages */
+    percentages: Signal<ScrollPercentages>;
+    /** Computed signal with scroll bounds */
+    bounds: Signal<{
+        left: number;
+        right: number;
+    }>;
+    /** Cleanup function to remove listeners */
+    cleanup: () => void;
+}
+/**
+ * Create a reactive scroll stream from an element
+ *
+ * Emits scroll data as the user scrolls the element.
+ * Automatically computes derived values (percentages, bounds).
+ *
+ * @example
+ * ```typescript
+ * const scrollStream = createScrollStream(container)
+ *
+ * effect(() => {
+ *   const { startX, endX } = scrollStream.percentages.value
+ *   console.log('Visible:', startX, 'to', endX)
+ * }, [scrollStream.percentages])
+ *
+ * scrollStream.cleanup()
+ * ```
+ *
+ * @param element - Scrollable element
+ * @returns Scroll stream with signals and cleanup
+ */
+export declare function createScrollStream(element: HTMLElement): ScrollStream;
+/**
+ * Create a scroll stream that automatically updates external state
+ *
+ * This is a convenience wrapper that connects scroll events to a state action.
+ *
+ * @example
+ * ```typescript
+ * const scrollStream = createScrollStreamWithAction(
+ *   container,
+ *   (scrollLeft) => actions.setScrollPosition(scrollLeft)
+ * )
+ * ```
+ *
+ * @param element - Scrollable element
+ * @param onScrollChange - Action to call when scroll changes
+ * @returns Scroll stream with signals and cleanup
+ */
+export declare function createScrollStreamWithAction(element: HTMLElement, onScrollChange: (scrollLeft: number) => void): ScrollStream;

package/dist/reactive/scroll-stream.js

@@ -0,0 +1,131 @@
+/**
+ * Reactive scroll stream utilities
+ *
+ * Provides declarative scroll handling using reactive streams.
+ * Automatically handles scroll event optimization and cleanup.
+ */
+import { signal, computed, effect } from './store.js';
+import { cleanup } from './event-streams.js';
+// ============================================================================
+// Pure Scroll Calculation Functions
+// ============================================================================
+/**
+ * Calculate visible percentages from scroll data
+ * Pure function - no side effects
+ *
+ * @param scrollData - Current scroll dimensions
+ * @returns Start and end positions as percentages (0-1)
+ */
+export function calculateScrollPercentages(scrollData) {
+    const { scrollLeft, scrollWidth, clientWidth } = scrollData;
+    if (scrollWidth === 0) {
+        return { startX: 0, endX: 1 };
+    }
+    const startX = scrollLeft / scrollWidth;
+    const endX = (scrollLeft + clientWidth) / scrollWidth;
+    return {
+        startX: Math.max(0, Math.min(1, startX)),
+        endX: Math.max(0, Math.min(1, endX)),
+    };
+}
+/**
+ * Calculate scroll bounds in pixels
+ * Pure function - no side effects
+ *
+ * @param scrollData - Current scroll dimensions
+ * @returns Left and right scroll bounds in pixels
+ */
+export function calculateScrollBounds(scrollData) {
+    return {
+        left: scrollData.scrollLeft,
+        right: scrollData.scrollLeft + scrollData.clientWidth,
+    };
+}
+/**
+ * Create a reactive scroll stream from an element
+ *
+ * Emits scroll data as the user scrolls the element.
+ * Automatically computes derived values (percentages, bounds).
+ *
+ * @example
+ * ```typescript
+ * const scrollStream = createScrollStream(container)
+ *
+ * effect(() => {
+ *   const { startX, endX } = scrollStream.percentages.value
+ *   console.log('Visible:', startX, 'to', endX)
+ * }, [scrollStream.percentages])
+ *
+ * scrollStream.cleanup()
+ * ```
+ *
+ * @param element - Scrollable element
+ * @returns Scroll stream with signals and cleanup
+ */
+export function createScrollStream(element) {
+    // Create signals
+    const scrollData = signal({
+        scrollLeft: element.scrollLeft,
+        scrollWidth: element.scrollWidth,
+        clientWidth: element.clientWidth,
+    });
+    // Computed derived values
+    const percentages = computed(() => {
+        return calculateScrollPercentages(scrollData.value);
+    }, [scrollData]);
+    const bounds = computed(() => {
+        return calculateScrollBounds(scrollData.value);
+    }, [scrollData]);
+    // Update scroll data on scroll event
+    const onScroll = () => {
+        scrollData.set({
+            scrollLeft: element.scrollLeft,
+            scrollWidth: element.scrollWidth,
+            clientWidth: element.clientWidth,
+        });
+    };
+    // Attach scroll listener
+    element.addEventListener('scroll', onScroll, { passive: true });
+    // Cleanup function
+    const cleanupFn = () => {
+        element.removeEventListener('scroll', onScroll);
+        cleanup(scrollData);
+    };
+    return {
+        scrollData,
+        percentages,
+        bounds,
+        cleanup: cleanupFn,
+    };
+}
+/**
+ * Create a scroll stream that automatically updates external state
+ *
+ * This is a convenience wrapper that connects scroll events to a state action.
+ *
+ * @example
+ * ```typescript
+ * const scrollStream = createScrollStreamWithAction(
+ *   container,
+ *   (scrollLeft) => actions.setScrollPosition(scrollLeft)
+ * )
+ * ```
+ *
+ * @param element - Scrollable element
+ * @param onScrollChange - Action to call when scroll changes
+ * @returns Scroll stream with signals and cleanup
+ */
+export function createScrollStreamWithAction(element, onScrollChange) {
+    const stream = createScrollStream(element);
+    // Effect to update external state
+    const unsubscribe = effect(() => {
+        onScrollChange(stream.scrollData.value.scrollLeft);
+    }, [stream.scrollData]);
+    // Wrap cleanup to include effect cleanup
+    const originalCleanup = stream.cleanup;
+    stream.cleanup = () => {
+        unsubscribe();
+        originalCleanup();
+    };
+    return stream;
+}

package/dist/reactive/state-event-emitter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * State-driven event emission utilities
+ *
+ * Automatically emit events when reactive state changes.
+ * Ensures events are always in sync with state and removes manual emit() calls.
+ */
+import { type Signal } from './store.js';
+import type { WaveSurferState } from '../state/wavesurfer-state.js';
+export type EventEmitter = {
+    emit(event: string, ...args: any[]): void;
+};
+/**
+ * Setup automatic event emission from state changes
+ *
+ * This function subscribes to all relevant state signals and automatically
+ * emits corresponding events when state changes. This ensures:
+ * - Events are always in sync with state
+ * - No manual emit() calls needed
+ * - Can't forget to emit an event
+ * - Clear event sources (state changes)
+ *
+ * @example
+ * ```typescript
+ * const { state } = createWaveSurferState()
+ * const wavesurfer = new WaveSurfer()
+ *
+ * const cleanup = setupStateEventEmission(state, wavesurfer)
+ *
+ * // Now state changes automatically emit events
+ * state.isPlaying.set(true) // → wavesurfer.emit('play')
+ * ```
+ *
+ * @param state - Reactive state to observe
+ * @param emitter - Event emitter to emit events on
+ * @returns Cleanup function that removes all subscriptions
+ */
+export declare function setupStateEventEmission(state: WaveSurferState, emitter: EventEmitter): () => void;
+/**
+ * Setup custom event emission from signal changes
+ *
+ * This is a lower-level utility for setting up custom event emission
+ * from any signal. Useful when you need more control over event emission logic.
+ *
+ * @example
+ * ```typescript
+ * const volumeSignal = signal(1)
+ *
+ * const cleanup = setupSignalEventEmission(
+ *   volumeSignal,
+ *   emitter,
+ *   (volume) => ['volume', volume]
+ * )
+ * ```
+ *
+ * @param signal - Signal to observe
+ * @param emitter - Event emitter
+ * @param getEventData - Function that returns [eventName, ...args]
+ * @returns Cleanup function
+ */
+export declare function setupSignalEventEmission<T>(signal: Signal<T>, emitter: EventEmitter, getEventData: (value: T) => [string, ...any[]]): () => void;
+/**
+ * Setup event emission with debouncing
+ *
+ * Useful for high-frequency events like scroll or timeupdate.
+ *
+ * @example
+ * ```typescript
+ * const cleanup = setupDebouncedEventEmission(
+ *   state.scrollPosition,
+ *   emitter,
+ *   (pos) => ['scroll', pos],
+ *   100 // debounce 100ms
+ * )
+ * ```
+ *
+ * @param signal - Signal to observe
+ * @param emitter - Event emitter
+ * @param getEventData - Function that returns [eventName, ...args]
+ * @param debounceMs - Debounce delay in milliseconds
+ * @returns Cleanup function
+ */
+export declare function setupDebouncedEventEmission<T>(signal: Signal<T>, emitter: EventEmitter, getEventData: (value: T) => [string, ...any[]], debounceMs: number): () => void;
+/**
+ * Setup conditional event emission
+ *
+ * Only emit events when a condition is met.
+ *
+ * @example
+ * ```typescript
+ * // Only emit finish event when playing stops at end
+ * const cleanup = setupConditionalEventEmission(
+ *   state.isPlaying,
+ *   emitter,
+ *   (isPlaying) => !isPlaying && state.currentTime.value >= state.duration.value,
+ *   () => ['finish']
+ * )
+ * ```
+ *
+ * @param signal - Signal to observe
+ * @param emitter - Event emitter
+ * @param condition - Function that returns true when event should emit
+ * @param getEventData - Function that returns [eventName, ...args]
+ * @returns Cleanup function
+ */
+export declare function setupConditionalEventEmission<T>(signal: Signal<T>, emitter: EventEmitter, condition: (value: T) => boolean, getEventData: (value: T) => [string, ...any[]]): () => void;

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

@@ -0,0 +1,213 @@
+/**
+ * State-driven event emission utilities
+ *
+ * Automatically emit events when reactive state changes.
+ * Ensures events are always in sync with state and removes manual emit() calls.
+ */
+import { effect } from './store.js';
+/**
+ * Setup automatic event emission from state changes
+ *
+ * This function subscribes to all relevant state signals and automatically
+ * emits corresponding events when state changes. This ensures:
+ * - Events are always in sync with state
+ * - No manual emit() calls needed
+ * - Can't forget to emit an event
+ * - Clear event sources (state changes)
+ *
+ * @example
+ * ```typescript
+ * const { state } = createWaveSurferState()
+ * const wavesurfer = new WaveSurfer()
+ *
+ * const cleanup = setupStateEventEmission(state, wavesurfer)
+ *
+ * // Now state changes automatically emit events
+ * state.isPlaying.set(true) // → wavesurfer.emit('play')
+ * ```
+ *
+ * @param state - Reactive state to observe
+ * @param emitter - Event emitter to emit events on
+ * @returns Cleanup function that removes all subscriptions
+ */
+export function setupStateEventEmission(state, emitter) {
+    const cleanups = [];
+    // ============================================================================
+    // Play/Pause Events
+    // ============================================================================
+    // Emit play/pause events when playing state changes
+    cleanups.push(effect(() => {
+        const isPlaying = state.isPlaying.value;
+        emitter.emit(isPlaying ? 'play' : 'pause');
+    }, [state.isPlaying]));
+    // ============================================================================
+    // Time Update Events
+    // ============================================================================
+    // Emit timeupdate when current time changes
+    cleanups.push(effect(() => {
+        const currentTime = state.currentTime.value;
+        emitter.emit('timeupdate', currentTime);
+        // Also emit audioprocess when playing
+        if (state.isPlaying.value) {
+            emitter.emit('audioprocess', currentTime);
+        }
+    }, [state.currentTime, state.isPlaying]));
+    // ============================================================================
+    // Seeking Events
+    // ============================================================================
+    // Emit seeking event when seeking state changes to true
+    cleanups.push(effect(() => {
+        const isSeeking = state.isSeeking.value;
+        if (isSeeking) {
+            emitter.emit('seeking', state.currentTime.value);
+        }
+    }, [state.isSeeking, state.currentTime]));
+    // ============================================================================
+    // Ready Event
+    // ============================================================================
+    // Emit ready when state becomes ready
+    let wasReady = false;
+    cleanups.push(effect(() => {
+        const isReady = state.isReady.value;
+        if (isReady && !wasReady) {
+            wasReady = true;
+            emitter.emit('ready', state.duration.value);
+        }
+    }, [state.isReady, state.duration]));
+    // ============================================================================
+    // Finish Event
+    // ============================================================================
+    // Emit finish when playback ends (reached duration and stopped)
+    let wasPlayingAtEnd = false;
+    cleanups.push(effect(() => {
+        const isPlaying = state.isPlaying.value;
+        const currentTime = state.currentTime.value;
+        const duration = state.duration.value;
+        // Check if we're at the end
+        const isAtEnd = duration > 0 && currentTime >= duration;
+        // Emit finish when we were playing at end and now stopped
+        if (wasPlayingAtEnd && !isPlaying && isAtEnd) {
+            emitter.emit('finish');
+        }
+        // Track if we're playing at the end
+        wasPlayingAtEnd = isPlaying && isAtEnd;
+    }, [state.isPlaying, state.currentTime, state.duration]));
+    // ============================================================================
+    // Zoom Events
+    // ============================================================================
+    // Emit zoom when zoom level changes
+    cleanups.push(effect(() => {
+        const zoom = state.zoom.value;
+        if (zoom > 0) {
+            emitter.emit('zoom', zoom);
+        }
+    }, [state.zoom]));
+    // Return cleanup function
+    return () => {
+        cleanups.forEach((cleanup) => cleanup());
+    };
+}
+/**
+ * Setup custom event emission from signal changes
+ *
+ * This is a lower-level utility for setting up custom event emission
+ * from any signal. Useful when you need more control over event emission logic.
+ *
+ * @example
+ * ```typescript
+ * const volumeSignal = signal(1)
+ *
+ * const cleanup = setupSignalEventEmission(
+ *   volumeSignal,
+ *   emitter,
+ *   (volume) => ['volume', volume]
+ * )
+ * ```
+ *
+ * @param signal - Signal to observe
+ * @param emitter - Event emitter
+ * @param getEventData - Function that returns [eventName, ...args]
+ * @returns Cleanup function
+ */
+export function setupSignalEventEmission(signal, emitter, getEventData) {
+    return effect(() => {
+        const value = signal.value;
+        const [eventName, ...args] = getEventData(value);
+        emitter.emit(eventName, ...args);
+    }, [signal]);
+}
+/**
+ * Setup event emission with debouncing
+ *
+ * Useful for high-frequency events like scroll or timeupdate.
+ *
+ * @example
+ * ```typescript
+ * const cleanup = setupDebouncedEventEmission(
+ *   state.scrollPosition,
+ *   emitter,
+ *   (pos) => ['scroll', pos],
+ *   100 // debounce 100ms
+ * )
+ * ```
+ *
+ * @param signal - Signal to observe
+ * @param emitter - Event emitter
+ * @param getEventData - Function that returns [eventName, ...args]
+ * @param debounceMs - Debounce delay in milliseconds
+ * @returns Cleanup function
+ */
+export function setupDebouncedEventEmission(signal, emitter, getEventData, debounceMs) {
+    let timeoutId = null;
+    const cleanup = effect(() => {
+        const value = signal.value;
+        // Clear previous timeout
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        // Set new timeout
+        timeoutId = setTimeout(() => {
+            const [eventName, ...args] = getEventData(value);
+            emitter.emit(eventName, ...args);
+            timeoutId = null;
+        }, debounceMs);
+    }, [signal]);
+    // Return cleanup that also clears pending timeout
+    return () => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        cleanup();
+    };
+}
+/**
+ * Setup conditional event emission
+ *
+ * Only emit events when a condition is met.
+ *
+ * @example
+ * ```typescript
+ * // Only emit finish event when playing stops at end
+ * const cleanup = setupConditionalEventEmission(
+ *   state.isPlaying,
+ *   emitter,
+ *   (isPlaying) => !isPlaying && state.currentTime.value >= state.duration.value,
+ *   () => ['finish']
+ * )
+ * ```
+ *
+ * @param signal - Signal to observe
+ * @param emitter - Event emitter
+ * @param condition - Function that returns true when event should emit
+ * @param getEventData - Function that returns [eventName, ...args]
+ * @returns Cleanup function
+ */
+export function setupConditionalEventEmission(signal, emitter, condition, getEventData) {
+    return effect(() => {
+        const value = signal.value;
+        if (condition(value)) {
+            const [eventName, ...args] = getEventData(value);
+            emitter.emit(eventName, ...args);
+        }
+    }, [signal]);
+}

package/dist/reactive/store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Reactive primitives for managing state in WaveSurfer
+ *
+ * This module provides signal-based reactivity similar to SolidJS signals.
+ * Signals are reactive values that notify subscribers when they change.
+ */
+/**
+ * A reactive value that can be read and subscribed to
+ */
+export interface Signal<T> {
+    /** Get the current value */
+    get value(): T;
+    /** Subscribe to changes. Returns an unsubscribe function. */
+    subscribe(callback: (value: T) => void): () => void;
+}
+/**
+ * A writable reactive value that can be updated
+ */
+export interface WritableSignal<T> extends Signal<T> {
+    /** Set a new value. Only notifies if value changed. */
+    set(value: T): void;
+    /** Update value using a function. */
+    update(fn: (current: T) => T): void;
+}
+/**
+ * Create a reactive signal that notifies subscribers when its value changes
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0)
+ * count.subscribe(val => console.log('Count:', val))
+ * count.set(5) // Logs: Count: 5
+ * ```
+ */
+export declare function signal<T>(initialValue: T): WritableSignal<T>;
+/**
+ * Create a computed value that automatically updates when its dependencies change
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0)
+ * const doubled = computed(() => count.value * 2, [count])
+ * console.log(doubled.value) // 0
+ * count.set(5)
+ * console.log(doubled.value) // 10
+ * ```
+ */
+export declare function computed<T>(fn: () => T, dependencies: Signal<any>[]): Signal<T>;
+/**
+ * Run a side effect automatically when dependencies change
+ *
+ * @param fn - Effect function. Can return a cleanup function.
+ * @param dependencies - Signals that trigger the effect when they change
+ * @returns Unsubscribe function that stops the effect and runs cleanup
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0)
+ * effect(() => {
+ *   console.log('Count is:', count.value)
+ *   return () => console.log('Cleanup')
+ * }, [count])
+ * count.set(5) // Logs: Cleanup, Count is: 5
+ * ```
+ */
+export declare function effect(fn: () => void | (() => void), dependencies: Signal<any>[]): () => void;