wavesurfer.js 7.11.1 → 7.12.1

package/dist/reactive/__tests__/store.test.js

@@ -0,0 +1,271 @@
+import { signal, computed, effect } from '../store';
+describe('signal', () => {
+    it('should create a signal with initial value', () => {
+        const count = signal(0);
+        expect(count.value).toBe(0);
+    });
+    it('should update value with set()', () => {
+        const count = signal(0);
+        count.set(5);
+        expect(count.value).toBe(5);
+    });
+    it('should update value with update()', () => {
+        const count = signal(0);
+        count.update((n) => n + 1);
+        expect(count.value).toBe(1);
+    });
+    it('should notify subscribers when value changes', () => {
+        const count = signal(0);
+        const callback = jest.fn();
+        count.subscribe(callback);
+        count.set(5);
+        expect(callback).toHaveBeenCalledWith(5);
+        expect(callback).toHaveBeenCalledTimes(1);
+    });
+    it('should not notify if value does not change', () => {
+        const count = signal(0);
+        const callback = jest.fn();
+        count.subscribe(callback);
+        count.set(0); // Same value
+        expect(callback).not.toHaveBeenCalled();
+    });
+    it('should support multiple subscribers', () => {
+        const count = signal(0);
+        const callback1 = jest.fn();
+        const callback2 = jest.fn();
+        count.subscribe(callback1);
+        count.subscribe(callback2);
+        count.set(5);
+        expect(callback1).toHaveBeenCalledWith(5);
+        expect(callback2).toHaveBeenCalledWith(5);
+    });
+    it('should unsubscribe correctly', () => {
+        const count = signal(0);
+        const callback = jest.fn();
+        const unsubscribe = count.subscribe(callback);
+        count.set(1);
+        expect(callback).toHaveBeenCalledTimes(1);
+        unsubscribe();
+        count.set(2);
+        expect(callback).toHaveBeenCalledTimes(1); // Should not be called again
+    });
+    it('should work with object values', () => {
+        const state = signal({ count: 0 });
+        const callback = jest.fn();
+        state.subscribe(callback);
+        state.set({ count: 1 });
+        expect(callback).toHaveBeenCalledWith({ count: 1 });
+    });
+    it('should detect reference equality for objects', () => {
+        const obj = { count: 0 };
+        const state = signal(obj);
+        const callback = jest.fn();
+        state.subscribe(callback);
+        state.set(obj); // Same reference
+        expect(callback).not.toHaveBeenCalled();
+    });
+});
+describe('computed', () => {
+    it('should compute initial value', () => {
+        const count = signal(5);
+        const doubled = computed(() => count.value * 2, [count]);
+        expect(doubled.value).toBe(10);
+    });
+    it('should recompute when dependency changes', () => {
+        const count = signal(5);
+        const doubled = computed(() => count.value * 2, [count]);
+        count.set(10);
+        expect(doubled.value).toBe(20);
+    });
+    it('should work with multiple dependencies', () => {
+        const a = signal(2);
+        const b = signal(3);
+        const sum = computed(() => a.value + b.value, [a, b]);
+        expect(sum.value).toBe(5);
+        a.set(5);
+        expect(sum.value).toBe(8);
+        b.set(7);
+        expect(sum.value).toBe(12);
+    });
+    it('should notify subscribers when computed value changes', () => {
+        const count = signal(5);
+        const doubled = computed(() => count.value * 2, [count]);
+        const callback = jest.fn();
+        doubled.subscribe(callback);
+        count.set(10);
+        expect(callback).toHaveBeenCalledWith(20);
+    });
+    it('should not notify if computed value does not change', () => {
+        const count = signal(5);
+        const isPositive = computed(() => count.value > 0, [count]);
+        const callback = jest.fn();
+        isPositive.subscribe(callback);
+        count.set(10); // Still positive
+        expect(callback).not.toHaveBeenCalled();
+    });
+    it('should support nested computed values', () => {
+        const count = signal(5);
+        const doubled = computed(() => count.value * 2, [count]);
+        const quadrupled = computed(() => doubled.value * 2, [doubled]);
+        expect(quadrupled.value).toBe(20);
+        count.set(10);
+        expect(quadrupled.value).toBe(40);
+    });
+    it('should cleanup subscriptions when computed is unsubscribed', () => {
+        const count = signal(5);
+        const doubled = computed(() => count.value * 2, [count]);
+        const callback = jest.fn();
+        const unsubscribe = doubled.subscribe(callback);
+        count.set(10);
+        expect(callback).toHaveBeenCalledTimes(1);
+        unsubscribe();
+        count.set(15);
+        expect(callback).toHaveBeenCalledTimes(1);
+    });
+    it('should be read-only (no set method)', () => {
+        const count = signal(5);
+        const doubled = computed(() => count.value * 2, [count]);
+        expect(doubled.set).toBeUndefined();
+        expect(doubled.update).toBeUndefined();
+    });
+});
+describe('effect', () => {
+    it('should run immediately', () => {
+        const fn = jest.fn();
+        const count = signal(0);
+        effect(fn, [count]);
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    it('should run when dependency changes', () => {
+        const fn = jest.fn();
+        const count = signal(0);
+        effect(fn, [count]);
+        expect(fn).toHaveBeenCalledTimes(1);
+        count.set(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        count.set(2);
+        expect(fn).toHaveBeenCalledTimes(3);
+    });
+    it('should run with multiple dependencies', () => {
+        const fn = jest.fn();
+        const a = signal(0);
+        const b = signal(0);
+        effect(fn, [a, b]);
+        expect(fn).toHaveBeenCalledTimes(1);
+        a.set(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        b.set(1);
+        expect(fn).toHaveBeenCalledTimes(3);
+    });
+    it('should run cleanup before re-running effect', () => {
+        const cleanup = jest.fn();
+        const fn = jest.fn(() => cleanup);
+        const count = signal(0);
+        effect(fn, [count]);
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(cleanup).not.toHaveBeenCalled();
+        count.set(1);
+        expect(cleanup).toHaveBeenCalledTimes(1); // Cleanup from first run
+        expect(fn).toHaveBeenCalledTimes(2);
+        count.set(2);
+        expect(cleanup).toHaveBeenCalledTimes(2); // Cleanup from second run
+        expect(fn).toHaveBeenCalledTimes(3);
+    });
+    it('should run cleanup on unsubscribe', () => {
+        const cleanup = jest.fn();
+        const fn = jest.fn(() => cleanup);
+        const count = signal(0);
+        const unsubscribe = effect(fn, [count]);
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(cleanup).not.toHaveBeenCalled();
+        unsubscribe();
+        expect(cleanup).toHaveBeenCalledTimes(1);
+    });
+    it('should stop running after unsubscribe', () => {
+        const fn = jest.fn();
+        const count = signal(0);
+        const unsubscribe = effect(fn, [count]);
+        expect(fn).toHaveBeenCalledTimes(1);
+        count.set(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        unsubscribe();
+        count.set(2);
+        expect(fn).toHaveBeenCalledTimes(2); // Should not increase
+    });
+    it('should work with computed dependencies', () => {
+        const fn = jest.fn();
+        const count = signal(0);
+        const doubled = computed(() => count.value * 2, [count]);
+        effect(fn, [doubled]);
+        expect(fn).toHaveBeenCalledTimes(1);
+        count.set(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+    it('should handle effects without cleanup', () => {
+        const fn = jest.fn();
+        const count = signal(0);
+        const unsubscribe = effect(fn, [count]);
+        count.set(1);
+        expect(() => unsubscribe()).not.toThrow();
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+    it('should handle accessing signal values in effect', () => {
+        const values = [];
+        const count = signal(0);
+        effect(() => {
+            values.push(count.value);
+        }, [count]);
+        count.set(1);
+        count.set(2);
+        expect(values).toEqual([0, 1, 2]);
+    });
+});
+describe('integration tests', () => {
+    it('should work with signal -> computed -> effect chain', () => {
+        const values = [];
+        const count = signal(0);
+        const doubled = computed(() => count.value * 2, [count]);
+        effect(() => {
+            values.push(doubled.value);
+        }, [doubled]);
+        count.set(5);
+        count.set(10);
+        expect(values).toEqual([0, 10, 20]);
+    });
+    it('should handle complex dependency graphs', () => {
+        const a = signal(1);
+        const b = signal(2);
+        const sum = computed(() => a.value + b.value, [a, b]);
+        const product = computed(() => a.value * b.value, [a, b]);
+        const combined = computed(() => sum.value + product.value, [sum, product]);
+        expect(combined.value).toBe(5); // (1+2) + (1*2) = 3 + 2 = 5
+        a.set(3);
+        expect(combined.value).toBe(11); // (3+2) + (3*2) = 5 + 6 = 11
+        b.set(4);
+        expect(combined.value).toBe(19); // (3+4) + (3*4) = 7 + 12 = 19
+    });
+    it('should not create memory leaks with many subscriptions', () => {
+        const count = signal(0);
+        const unsubscribes = [];
+        // Create 1000 subscriptions
+        for (let i = 0; i < 1000; i++) {
+            unsubscribes.push(count.subscribe(() => { }));
+        }
+        // Unsubscribe all
+        unsubscribes.forEach((unsub) => unsub());
+        // Signal should still work
+        count.set(5);
+        expect(count.value).toBe(5);
+    });
+    it('should handle rapid updates correctly', () => {
+        const count = signal(0);
+        const callback = jest.fn();
+        count.subscribe(callback);
+        // Rapid updates
+        for (let i = 1; i <= 100; i++) {
+            count.set(i);
+        }
+        expect(callback).toHaveBeenCalledTimes(100);
+        expect(count.value).toBe(100);
+    });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * Reactive drag stream utilities
+ *
+ * Provides declarative drag handling using reactive streams.
+ * Automatically handles mouseup cleanup and supports constraints.
+ */
+import { type Signal } from './store.js';
+export interface DragEvent {
+    type: 'start' | 'move' | 'end';
+    x: number;
+    y: number;
+    deltaX?: number;
+    deltaY?: number;
+}
+export interface DragStreamOptions {
+    /** Minimum distance to move before dragging starts (default: 3) */
+    threshold?: number;
+    /** Mouse button to listen for (default: 0 = left button) */
+    mouseButton?: number;
+    /** Delay before touch drag starts in ms (default: 100) */
+    touchDelay?: number;
+}
+/**
+ * Create a reactive drag stream from an element
+ *
+ * Emits drag events (start, move, end) as the user drags the element.
+ * Automatically handles pointer capture, multi-touch prevention, and cleanup.
+ *
+ * @example
+ * ```typescript
+ * const dragSignal = createDragStream(element)
+ *
+ * effect(() => {
+ *   const drag = dragSignal.value
+ *   if (drag?.type === 'move') {
+ *     console.log('Dragging:', drag.deltaX, drag.deltaY)
+ *   }
+ * }, [dragSignal])
+ * ```
+ *
+ * @param element - Element to make draggable
+ * @param options - Drag configuration options
+ * @returns Signal emitting drag events and cleanup function
+ */
+export declare function createDragStream(element: HTMLElement, options?: DragStreamOptions): {
+    signal: Signal<DragEvent | null>;
+    cleanup: () => void;
+};

package/dist/reactive/drag-stream.js

@@ -0,0 +1,146 @@
+/**
+ * Reactive drag stream utilities
+ *
+ * Provides declarative drag handling using reactive streams.
+ * Automatically handles mouseup cleanup and supports constraints.
+ */
+import { signal } from './store.js';
+import { cleanup } from './event-streams.js';
+/**
+ * Create a reactive drag stream from an element
+ *
+ * Emits drag events (start, move, end) as the user drags the element.
+ * Automatically handles pointer capture, multi-touch prevention, and cleanup.
+ *
+ * @example
+ * ```typescript
+ * const dragSignal = createDragStream(element)
+ *
+ * effect(() => {
+ *   const drag = dragSignal.value
+ *   if (drag?.type === 'move') {
+ *     console.log('Dragging:', drag.deltaX, drag.deltaY)
+ *   }
+ * }, [dragSignal])
+ * ```
+ *
+ * @param element - Element to make draggable
+ * @param options - Drag configuration options
+ * @returns Signal emitting drag events and cleanup function
+ */
+export function createDragStream(element, options = {}) {
+    const { threshold = 3, mouseButton = 0, touchDelay = 100 } = options;
+    const dragSignal = signal(null);
+    const activePointers = new Map();
+    const isTouchDevice = matchMedia('(pointer: coarse)').matches;
+    let unsubscribeDocument = () => void 0;
+    const onPointerDown = (event) => {
+        if (event.button !== mouseButton)
+            return;
+        activePointers.set(event.pointerId, event);
+        if (activePointers.size > 1) {
+            return;
+        }
+        let startX = event.clientX;
+        let startY = event.clientY;
+        let isDragging = false;
+        const touchStartTime = Date.now();
+        const rect = element.getBoundingClientRect();
+        const { left, top } = rect;
+        const onPointerMove = (event) => {
+            if (event.defaultPrevented || activePointers.size > 1) {
+                return;
+            }
+            if (isTouchDevice && Date.now() - touchStartTime < touchDelay)
+                return;
+            const x = event.clientX;
+            const y = event.clientY;
+            const dx = x - startX;
+            const dy = y - startY;
+            if (isDragging || Math.abs(dx) > threshold || Math.abs(dy) > threshold) {
+                event.preventDefault();
+                event.stopPropagation();
+                if (!isDragging) {
+                    // Emit start event
+                    dragSignal.set({
+                        type: 'start',
+                        x: startX - left,
+                        y: startY - top,
+                    });
+                    isDragging = true;
+                }
+                // Emit move event
+                dragSignal.set({
+                    type: 'move',
+                    x: x - left,
+                    y: y - top,
+                    deltaX: dx,
+                    deltaY: dy,
+                });
+                startX = x;
+                startY = y;
+            }
+        };
+        const onPointerUp = (event) => {
+            activePointers.delete(event.pointerId);
+            if (isDragging) {
+                const x = event.clientX;
+                const y = event.clientY;
+                // Emit end event
+                dragSignal.set({
+                    type: 'end',
+                    x: x - left,
+                    y: y - top,
+                });
+            }
+            unsubscribeDocument();
+        };
+        const onPointerLeave = (e) => {
+            activePointers.delete(e.pointerId);
+            if (!e.relatedTarget || e.relatedTarget === document.documentElement) {
+                onPointerUp(e);
+            }
+        };
+        const onClick = (event) => {
+            if (isDragging) {
+                event.stopPropagation();
+                event.preventDefault();
+            }
+        };
+        const onTouchMove = (event) => {
+            if (event.defaultPrevented || activePointers.size > 1) {
+                return;
+            }
+            if (isDragging) {
+                event.preventDefault();
+            }
+        };
+        document.addEventListener('pointermove', onPointerMove);
+        document.addEventListener('pointerup', onPointerUp);
+        document.addEventListener('pointerout', onPointerLeave);
+        document.addEventListener('pointercancel', onPointerLeave);
+        document.addEventListener('touchmove', onTouchMove, { passive: false });
+        document.addEventListener('click', onClick, { capture: true });
+        unsubscribeDocument = () => {
+            document.removeEventListener('pointermove', onPointerMove);
+            document.removeEventListener('pointerup', onPointerUp);
+            document.removeEventListener('pointerout', onPointerLeave);
+            document.removeEventListener('pointercancel', onPointerLeave);
+            document.removeEventListener('touchmove', onTouchMove);
+            setTimeout(() => {
+                document.removeEventListener('click', onClick, { capture: true });
+            }, 10);
+        };
+    };
+    element.addEventListener('pointerdown', onPointerDown);
+    const cleanupFn = () => {
+        unsubscribeDocument();
+        element.removeEventListener('pointerdown', onPointerDown);
+        activePointers.clear();
+        cleanup(dragSignal);
+    };
+    return {
+        signal: dragSignal,
+        cleanup: cleanupFn,
+    };
+}

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

@@ -0,0 +1,104 @@
+/**
+ * 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 { type Signal } from './store.js';
+import type EventEmitter from '../event-emitter.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 declare function toStream<T extends Record<string, any[]>, K extends keyof T>(emitter: EventEmitter<T>, eventName: K): {
+    stream: Signal<T[K] | null>;
+    cleanup: () => void;
+};
+/**
+ * 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 declare function toStreams<T extends Record<string, any[]>, K extends keyof T>(emitter: EventEmitter<T>, eventNames: K[]): {
+    [P in K]: Signal<T[P] | null>;
+} & {
+    cleanup: () => void;
+};
+/**
+ * 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 declare function mergeStreams<T extends Record<string, any[]>, K extends keyof T>(emitter: EventEmitter<T>, eventNames: K[]): {
+    stream: Signal<{
+        event: K;
+        args: T[K];
+    } | null>;
+    cleanup: () => void;
+};
+/**
+ * Helper to map event stream values
+ *
+ * @example
+ * ```typescript
+ * const { stream: timeStream } = toStream(wavesurfer, 'timeupdate')
+ * const seconds = mapStream(timeStream, ([time]) => Math.floor(time))
+ * ```
+ */
+export declare function mapStream<T, U>(source: Signal<T>, mapper: (value: T) => U): Signal<U>;
+/**
+ * Helper to filter event stream values
+ *
+ * @example
+ * ```typescript
+ * const { stream: timeStream } = toStream(wavesurfer, 'timeupdate')
+ * const afterTenSeconds = filterStream(timeStream, ([time]) => time > 10)
+ * ```
+ */
+export declare function filterStream<T>(source: Signal<T>, predicate: (value: T) => boolean): Signal<T | null>;