svelte-p5-components 0.3.0 → 0.4.0

package/dist/TimelineTrack.svelte.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A named region on the timeline. Rendered as a tinted band; clicking
+ * it emits `onSegmentClick` with the full segment.
+ */
+export interface TimelineSegment {
+    id: string;
+    start: number;
+    end: number;
+    label?: string;
+    color?: string;
+}
+export interface TimelineViewWindow {
+    start: number;
+    end: number;
+}
+import type { Snippet } from 'svelte';
+interface Props {
+    /** Total timeline length in your chosen unit. */
+    duration: number;
+    /** Current playhead position. Bindable. */
+    currentTime?: number;
+    /**
+     * Optional zoomed view window. When set, only this range is visible on
+     * the track; clicks and hover map into this window. Bindable.
+     */
+    viewWindow?: TimelineViewWindow;
+    /** Highlighted regions rendered as labeled bands. */
+    segments?: TimelineSegment[];
+    /** Show draggable handles for the view window when it's set. Default: true. */
+    showViewWindowHandles?: boolean;
+    /** Show a vertical playhead line. Default: true. */
+    showPlayhead?: boolean;
+    /** Called when the user clicks or drags the playhead. */
+    onSeek?: (time: number) => void;
+    /** Called when the user drags a view window handle. */
+    onViewWindowChange?: (window: TimelineViewWindow) => void;
+    /** Called when the user clicks a segment band. */
+    onSegmentClick?: (segment: TimelineSegment) => void;
+    /** Called whenever the mouse moves over or leaves the track. `null` on leave. */
+    onHover?: (time: number | null) => void;
+    /** Snippet rendered above the hovered-time position. Use for preview tooltips. */
+    hoverIndicator?: Snippet<[{
+        time: number;
+        left: number;
+    }]>;
+    class?: string;
+}
+declare const TimelineTrack: import("svelte").Component<Props, {}, "currentTime" | "viewWindow">;
+type TimelineTrack = ReturnType<typeof TimelineTrack>;
+export default TimelineTrack;

package/dist/TimelineTrack.test.svelte.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/TimelineTrack.test.svelte.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import TimelineTrack, {} from './TimelineTrack.svelte';
+describe('<TimelineTrack>', () => {
+    it('renders a playhead at the correct percent for the currentTime', () => {
+        const { container } = render(TimelineTrack, {
+            props: { duration: 100, currentTime: 25 }
+        });
+        const playhead = container.querySelector('.timeline-track__playhead');
+        expect(playhead).not.toBeNull();
+        expect(playhead.style.left).toBe('25%');
+    });
+    it('omits the playhead when showPlayhead is false', () => {
+        const { container } = render(TimelineTrack, {
+            props: { duration: 100, currentTime: 50, showPlayhead: false }
+        });
+        expect(container.querySelector('.timeline-track__playhead')).toBeNull();
+    });
+    it('renders one band per segment with the correct width percent', () => {
+        const segments = [
+            { id: 's1', start: 0, end: 20 },
+            { id: 's2', start: 40, end: 60, label: 'Middle' }
+        ];
+        const { container } = render(TimelineTrack, {
+            props: { duration: 100, segments }
+        });
+        const bands = container.querySelectorAll('.timeline-track__segment');
+        expect(bands).toHaveLength(2);
+        expect(bands[0]?.style.left).toBe('0%');
+        expect(bands[0]?.style.width).toBe('20%');
+        expect(bands[1]?.style.left).toBe('40%');
+        expect(bands[1]?.style.width).toBe('20%');
+        expect(bands[1]?.textContent).toContain('Middle');
+    });
+    it('onSegmentClick fires the full segment when a band is clicked', async () => {
+        const segments = [{ id: 's1', start: 0, end: 20, label: 'Intro' }];
+        const onSegmentClick = vi.fn();
+        const { container } = render(TimelineTrack, {
+            props: { duration: 100, segments, onSegmentClick }
+        });
+        const band = container.querySelector('.timeline-track__segment');
+        await fireEvent.click(band);
+        expect(onSegmentClick).toHaveBeenCalledTimes(1);
+        expect(onSegmentClick.mock.calls[0]?.[0]?.id).toBe('s1');
+    });
+    it('view window handles render when viewWindow is provided', () => {
+        const { container } = render(TimelineTrack, {
+            props: { duration: 100, currentTime: 50, viewWindow: { start: 20, end: 80 } }
+        });
+        expect(container.querySelectorAll('.timeline-track__handle')).toHaveLength(2);
+    });
+    it('view window handles hidden when showViewWindowHandles=false', () => {
+        const { container } = render(TimelineTrack, {
+            props: {
+                duration: 100,
+                viewWindow: { start: 20, end: 80 },
+                showViewWindowHandles: false
+            }
+        });
+        expect(container.querySelectorAll('.timeline-track__handle')).toHaveLength(0);
+    });
+    it('has role=slider with aria-valuemin/max/now reflecting view window', () => {
+        const { container } = render(TimelineTrack, {
+            props: { duration: 100, currentTime: 30, viewWindow: { start: 10, end: 90 } }
+        });
+        const track = container.querySelector('.timeline-track');
+        expect(track.getAttribute('role')).toBe('slider');
+        expect(track.getAttribute('aria-valuemin')).toBe('10');
+        expect(track.getAttribute('aria-valuemax')).toBe('90');
+        expect(track.getAttribute('aria-valuenow')).toBe('30');
+    });
+});

package/dist/createMediaSync.svelte.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Sync a timeline's `currentTime` with an HTMLMediaElement (video or audio).
+ *
+ * The "speed multiplier quietly becomes a no-op while video is playing" bug
+ * appears in every app that wires a timeline to a video player without
+ * thinking about it carefully. `createMediaSync` handles the branch
+ * explicitly:
+ *
+ * - If the media element is playing, `isLocked === true` — the timeline
+ *   should display the video's currentTime and should *not* advance
+ *   currentTime from its own animation loop. Surface `isLocked` to the user
+ *   (see `<TimelineScrubber speedLocked>`) so the speed multiplier's
+ *   inactivity is visible rather than silent.
+ *
+ * - If the media element is paused or unloaded, the timeline is free to run
+ *   its own animation loop and the consumer's speed multiplier applies.
+ *
+ * Consumers own the animation loop (an rAF tick that advances currentTime
+ * by `speed * deltaMs / 1000`). `createMediaSync` only bridges the
+ * media→timeline direction and surfaces the lock signal.
+ *
+ * Use `.seek(time)` to write the other direction (timeline→media) — the
+ * helper clamps to the media's duration and guards against NaN.
+ *
+ * @example
+ * ```ts
+ * const sync = createMediaSync();
+ *
+ * $effect(() => { sync.attach(videoElement); });
+ *
+ * // In your rAF loop:
+ * if (sync.isLocked) currentTime = sync.mediaTime;
+ * else currentTime += speed * dt / 1000;
+ *
+ * // When user scrubs the timeline:
+ * sync.seek(newTime);
+ * ```
+ */
+export interface MediaSync {
+    /** The media element's currentTime, when attached. */
+    readonly mediaTime: number;
+    /** The media element's duration (possibly Infinity for streams). */
+    readonly mediaDuration: number;
+    /** True when the media is playing — timeline should follow, not drive. */
+    readonly isLocked: boolean;
+    /** Attach the sync to an HTMLMediaElement. Re-attaching switches to the new one. */
+    attach(el: HTMLMediaElement | null): void;
+    /** Remove listeners; idempotent. Called automatically when `attach(null)`. */
+    detach(): void;
+    /** Seek the attached media to `time`, clamped into [0, duration]. */
+    seek(time: number): void;
+}
+export declare function createMediaSync(): MediaSync;

package/dist/createMediaSync.svelte.js

@@ -0,0 +1,115 @@
+/**
+ * Sync a timeline's `currentTime` with an HTMLMediaElement (video or audio).
+ *
+ * The "speed multiplier quietly becomes a no-op while video is playing" bug
+ * appears in every app that wires a timeline to a video player without
+ * thinking about it carefully. `createMediaSync` handles the branch
+ * explicitly:
+ *
+ * - If the media element is playing, `isLocked === true` — the timeline
+ *   should display the video's currentTime and should *not* advance
+ *   currentTime from its own animation loop. Surface `isLocked` to the user
+ *   (see `<TimelineScrubber speedLocked>`) so the speed multiplier's
+ *   inactivity is visible rather than silent.
+ *
+ * - If the media element is paused or unloaded, the timeline is free to run
+ *   its own animation loop and the consumer's speed multiplier applies.
+ *
+ * Consumers own the animation loop (an rAF tick that advances currentTime
+ * by `speed * deltaMs / 1000`). `createMediaSync` only bridges the
+ * media→timeline direction and surfaces the lock signal.
+ *
+ * Use `.seek(time)` to write the other direction (timeline→media) — the
+ * helper clamps to the media's duration and guards against NaN.
+ *
+ * @example
+ * ```ts
+ * const sync = createMediaSync();
+ *
+ * $effect(() => { sync.attach(videoElement); });
+ *
+ * // In your rAF loop:
+ * if (sync.isLocked) currentTime = sync.mediaTime;
+ * else currentTime += speed * dt / 1000;
+ *
+ * // When user scrubs the timeline:
+ * sync.seek(newTime);
+ * ```
+ */
+export function createMediaSync() {
+    let el = null;
+    let mediaTime = $state(0);
+    let mediaDuration = $state(0);
+    let isLocked = $state(false);
+    function onTimeUpdate() {
+        if (el)
+            mediaTime = el.currentTime;
+    }
+    function onDurationChange() {
+        if (el)
+            mediaDuration = isFinite(el.duration) ? el.duration : 0;
+    }
+    function onPlay() {
+        isLocked = true;
+    }
+    function onPause() {
+        isLocked = false;
+    }
+    function onEnded() {
+        isLocked = false;
+    }
+    function detachInner() {
+        if (!el)
+            return;
+        el.removeEventListener('timeupdate', onTimeUpdate);
+        el.removeEventListener('durationchange', onDurationChange);
+        el.removeEventListener('play', onPlay);
+        el.removeEventListener('pause', onPause);
+        el.removeEventListener('ended', onEnded);
+        el = null;
+    }
+    return {
+        get mediaTime() {
+            return mediaTime;
+        },
+        get mediaDuration() {
+            return mediaDuration;
+        },
+        get isLocked() {
+            return isLocked;
+        },
+        attach(next) {
+            detachInner();
+            el = next;
+            if (!el) {
+                mediaTime = 0;
+                mediaDuration = 0;
+                isLocked = false;
+                return;
+            }
+            mediaTime = el.currentTime;
+            mediaDuration = isFinite(el.duration) ? el.duration : 0;
+            isLocked = !el.paused && !el.ended;
+            el.addEventListener('timeupdate', onTimeUpdate);
+            el.addEventListener('durationchange', onDurationChange);
+            el.addEventListener('play', onPlay);
+            el.addEventListener('pause', onPause);
+            el.addEventListener('ended', onEnded);
+        },
+        detach() {
+            detachInner();
+            mediaTime = 0;
+            mediaDuration = 0;
+            isLocked = false;
+        },
+        seek(time) {
+            if (!el)
+                return;
+            const dur = isFinite(el.duration) ? el.duration : Number.MAX_SAFE_INTEGER;
+            const clamped = Math.max(0, Math.min(dur, time));
+            if (!isFinite(clamped))
+                return;
+            el.currentTime = clamped;
+        }
+    };
+}

package/dist/index.d.ts

@@ -3,3 +3,10 @@ export { default as FPSMonitor } from './FPSMonitor.svelte';
 export { default as SketchDebug } from './SketchDebug.svelte';
 export { default as DraggableWindow } from './DraggableWindow.svelte';
 export { default as DraggableSketch } from './DraggableSketch.svelte';
+export { default as CanvasFrame } from './CanvasFrame.svelte';
+export { default as SplitPane } from './SplitPane.svelte';
+export { default as HoverTooltip } from './HoverTooltip.svelte';
+export { default as EntityToggleList, type Entity } from './EntityToggleList.svelte';
+export { default as TimelineTrack, type TimelineSegment, type TimelineViewWindow } from './TimelineTrack.svelte';
+export { default as TimelineScrubber } from './TimelineScrubber.svelte';
+export { createMediaSync, type MediaSync } from './createMediaSync.svelte.js';

package/dist/index.js

@@ -3,3 +3,10 @@ export { default as FPSMonitor } from './FPSMonitor.svelte';
 export { default as SketchDebug } from './SketchDebug.svelte';
 export { default as DraggableWindow } from './DraggableWindow.svelte';
 export { default as DraggableSketch } from './DraggableSketch.svelte';
+export { default as CanvasFrame } from './CanvasFrame.svelte';
+export { default as SplitPane } from './SplitPane.svelte';
+export { default as HoverTooltip } from './HoverTooltip.svelte';
+export { default as EntityToggleList } from './EntityToggleList.svelte';
+export { default as TimelineTrack } from './TimelineTrack.svelte';
+export { default as TimelineScrubber } from './TimelineScrubber.svelte';
+export { createMediaSync } from './createMediaSync.svelte.js';

package/dist/tests/setup.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/dist/tests/setup.js

@@ -0,0 +1,26 @@
+import '@testing-library/jest-dom/vitest';
+// happy-dom doesn't ship a ResizeObserver stub out of the box — components
+// that use it (Sketch, HoverTooltip) expect the constructor to exist.
+// Provide a no-op implementation so mounts don't throw; tests that care
+// about resize behavior replace it per-case.
+if (typeof globalThis.ResizeObserver === 'undefined') {
+    globalThis.ResizeObserver = class {
+        observe() { }
+        unobserve() { }
+        disconnect() { }
+    };
+}
+// Same story for PointerEvent — happy-dom implements it partially in some
+// releases. Ensure constructor works so pointer-driven tests (SplitPane drag,
+// TimelineTrack seek) can dispatch events.
+if (typeof globalThis.PointerEvent === 'undefined') {
+    globalThis.PointerEvent = class extends MouseEvent {
+        pointerId;
+        pointerType;
+        constructor(type, init = {}) {
+            super(type, init);
+            this.pointerId = init.pointerId ?? 0;
+            this.pointerType = init.pointerType ?? 'mouse';
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-p5-components",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Higher-level Svelte 5 components built on svelte-p5: responsive canvas, FPS monitor, sketch debug overlay, draggable windows",
   "keywords": [
     "svelte",
@@ -46,7 +46,9 @@
   "scripts": {
     "build": "svelte-package -o dist && publint",
     "typecheck": "svelte-check --tsconfig ./tsconfig.json",
-    "test": "echo \"no tests yet\" && exit 0"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@neodrag/svelte": "3.0.0-next.8"
@@ -60,11 +62,18 @@
     "svelte-p5": "workspace:*",
     "@sveltejs/package": "catalog:",
     "@sveltejs/vite-plugin-svelte": "catalog:",
+    "@testing-library/jest-dom": "catalog:",
+    "@testing-library/svelte": "catalog:",
+    "@testing-library/user-event": "catalog:",
     "@types/p5": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "happy-dom": "catalog:",
     "p5": "catalog:",
     "publint": "catalog:",
     "svelte": "catalog:",
     "svelte-check": "catalog:",
-    "typescript": "catalog:"
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
   }
 }