svelte-p5-components 0.3.0 → 0.4.0

package/dist/TimelineScrubber.svelte

@@ -0,0 +1,214 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import TimelineTrack, {
+		type TimelineSegment,
+		type TimelineViewWindow
+	} from './TimelineTrack.svelte';
+
+	// Full timeline widget: scrub track + play/pause + speed picker + time
+	// display. For apps that want the standard canvas-app timeline shape
+	// without reinventing controls.
+	//
+	// TimelineScrubber layers on top of <TimelineTrack> — reach for the track
+	// directly if you want custom chrome around it.
+	//
+	// Bindable: currentTime, isPlaying, speed, viewWindow. The consumer owns
+	// the animation loop that advances currentTime when isPlaying is true —
+	// this component just displays state and surfaces user intent.
+	//
+	// `speedLocked` (with an optional reason) is the UX-disclosure hook for
+	// video-driven playback, where the speed multiplier is effectively
+	// ignored. Set it to true and the speed button renders muted with a
+	// title-tip.
+	//
+	// See the package README for usage examples.
+
+	interface Props {
+		duration: number;
+		currentTime?: number;
+		isPlaying?: boolean;
+		speed?: number;
+		/** Available speed presets. Default: [1, 2, 4, 8, 16]. */
+		speedOptions?: number[];
+		/** Render speed as disabled / muted. Use when video playback overrides it. */
+		speedLocked?: boolean;
+		/** Title/tooltip shown when `speedLocked` is true. */
+		speedLockedReason?: string;
+		/** Optional zoomed view window; bindable. */
+		viewWindow?: TimelineViewWindow;
+		segments?: TimelineSegment[];
+		/** Format `currentTime` and `duration` for display. Default: mm:ss. */
+		formatTime?: (seconds: number) => string;
+		onSeek?: (time: number) => void;
+		onPlayToggle?: (nowPlaying: boolean) => void;
+		onSpeedChange?: (speed: number) => void;
+		onSegmentClick?: (segment: TimelineSegment) => void;
+		/** Snippet rendered above the hovered time, e.g. for a turn-preview tooltip. */
+		hoverIndicator?: Snippet<[{ time: number; left: number }]>;
+		class?: string;
+	}
+
+	let {
+		duration,
+		currentTime = $bindable(0),
+		isPlaying = $bindable(false),
+		speed = $bindable(1),
+		speedOptions = [1, 2, 4, 8, 16],
+		speedLocked = false,
+		speedLockedReason,
+		viewWindow = $bindable(undefined),
+		segments = [],
+		formatTime = defaultFormatTime,
+		onSeek,
+		onPlayToggle,
+		onSpeedChange,
+		onSegmentClick,
+		hoverIndicator,
+		class: className = ''
+	}: Props = $props();
+
+	function defaultFormatTime(seconds: number): string {
+		if (!isFinite(seconds)) return '00:00';
+		const m = Math.floor(seconds / 60);
+		const s = Math.floor(seconds % 60);
+		return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+	}
+
+	function togglePlay() {
+		isPlaying = !isPlaying;
+		onPlayToggle?.(isPlaying);
+	}
+
+	function cycleSpeed() {
+		if (speedLocked) return;
+		if (speedOptions.length === 0) return;
+		const idx = speedOptions.indexOf(speed);
+		const next = speedOptions[(idx + 1) % speedOptions.length] ?? speedOptions[0] ?? 1;
+		speed = next;
+		onSpeedChange?.(next);
+	}
+</script>
+
+<div class="timeline-scrubber {className}">
+	<div class="timeline-scrubber__track">
+		<span class="timeline-scrubber__time" aria-label="start"
+			>{formatTime(viewWindow?.start ?? 0)}</span
+		>
+		<TimelineTrack
+			{duration}
+			bind:currentTime
+			bind:viewWindow
+			{segments}
+			{onSeek}
+			{onSegmentClick}
+			{hoverIndicator}
+		/>
+		<span class="timeline-scrubber__time" aria-label="end">
+			{formatTime(viewWindow?.end ?? duration)}
+		</span>
+	</div>
+
+	<div class="timeline-scrubber__controls">
+		<button
+			type="button"
+			class="timeline-scrubber__btn"
+			aria-pressed={isPlaying}
+			aria-label={isPlaying ? 'Pause' : 'Play'}
+			onclick={togglePlay}
+		>
+			{isPlaying ? '❚❚' : '▶'}
+		</button>
+
+		<button
+			type="button"
+			class="timeline-scrubber__btn timeline-scrubber__btn--speed"
+			class:is-locked={speedLocked}
+			aria-label="Playback speed: {speed}x{speedLocked
+				? ` (locked${speedLockedReason ? ': ' + speedLockedReason : ''})`
+				: ''}"
+			title={speedLocked ? (speedLockedReason ?? 'Speed locked') : 'Click to change speed'}
+			disabled={speedLocked}
+			onclick={cycleSpeed}
+		>
+			{speed}×{speedLocked ? ' ·' : ''}
+		</button>
+
+		<span class="timeline-scrubber__currtime" aria-label="Current time">
+			{formatTime(currentTime)}
+		</span>
+	</div>
+</div>
+
+<style>
+	.timeline-scrubber {
+		display: flex;
+		flex-direction: column;
+		gap: 4px;
+		font:
+			12px/1 system-ui,
+			-apple-system,
+			Segoe UI,
+			sans-serif;
+	}
+
+	.timeline-scrubber__track {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+	}
+
+	.timeline-scrubber__track :global(.timeline-track) {
+		flex: 1 1 auto;
+		min-width: 0;
+	}
+
+	.timeline-scrubber__time {
+		font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+		font-size: 11px;
+		color: #6b7280;
+		min-width: 3.5em;
+		text-align: center;
+	}
+
+	.timeline-scrubber__controls {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		justify-content: center;
+	}
+
+	.timeline-scrubber__btn {
+		background: #fff;
+		border: 1px solid #e5e7eb;
+		border-radius: 4px;
+		padding: 4px 10px;
+		cursor: pointer;
+		font: inherit;
+		line-height: 1;
+	}
+
+	.timeline-scrubber__btn:hover:not(:disabled) {
+		background: #f3f4f6;
+	}
+
+	.timeline-scrubber__btn:disabled {
+		cursor: not-allowed;
+	}
+
+	.timeline-scrubber__btn--speed {
+		min-width: 3em;
+		font-variant-numeric: tabular-nums;
+	}
+
+	.timeline-scrubber__btn--speed.is-locked {
+		opacity: 0.5;
+	}
+
+	.timeline-scrubber__currtime {
+		font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+		font-size: 12px;
+		color: #111;
+		min-width: 4em;
+		text-align: right;
+	}
+</style>

package/dist/TimelineScrubber.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { Snippet } from 'svelte';
+import { type TimelineSegment, type TimelineViewWindow } from './TimelineTrack.svelte';
+interface Props {
+    duration: number;
+    currentTime?: number;
+    isPlaying?: boolean;
+    speed?: number;
+    /** Available speed presets. Default: [1, 2, 4, 8, 16]. */
+    speedOptions?: number[];
+    /** Render speed as disabled / muted. Use when video playback overrides it. */
+    speedLocked?: boolean;
+    /** Title/tooltip shown when `speedLocked` is true. */
+    speedLockedReason?: string;
+    /** Optional zoomed view window; bindable. */
+    viewWindow?: TimelineViewWindow;
+    segments?: TimelineSegment[];
+    /** Format `currentTime` and `duration` for display. Default: mm:ss. */
+    formatTime?: (seconds: number) => string;
+    onSeek?: (time: number) => void;
+    onPlayToggle?: (nowPlaying: boolean) => void;
+    onSpeedChange?: (speed: number) => void;
+    onSegmentClick?: (segment: TimelineSegment) => void;
+    /** Snippet rendered above the hovered time, e.g. for a turn-preview tooltip. */
+    hoverIndicator?: Snippet<[{
+        time: number;
+        left: number;
+    }]>;
+    class?: string;
+}
+declare const TimelineScrubber: import("svelte").Component<Props, {}, "currentTime" | "viewWindow" | "isPlaying" | "speed">;
+type TimelineScrubber = ReturnType<typeof TimelineScrubber>;
+export default TimelineScrubber;

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

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

package/dist/TimelineScrubber.test.svelte.js

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import TimelineScrubber from './TimelineScrubber.svelte';
+describe('<TimelineScrubber>', () => {
+    it('shows the play icon when paused and pause when playing', () => {
+        const { container: paused } = render(TimelineScrubber, {
+            props: { duration: 60, currentTime: 0, isPlaying: false }
+        });
+        expect(paused.querySelector('[aria-label="Play"]')).not.toBeNull();
+        const { container: playing } = render(TimelineScrubber, {
+            props: { duration: 60, currentTime: 0, isPlaying: true }
+        });
+        expect(playing.querySelector('[aria-label="Pause"]')).not.toBeNull();
+    });
+    it('clicking the play button fires onPlayToggle with the new state', async () => {
+        const onPlayToggle = vi.fn();
+        const { container } = render(TimelineScrubber, {
+            props: { duration: 60, isPlaying: false, onPlayToggle }
+        });
+        const btn = container.querySelector('[aria-label="Play"]');
+        await fireEvent.click(btn);
+        expect(onPlayToggle).toHaveBeenCalledWith(true);
+    });
+    it('cycles through the default speed presets on each speed-button click', async () => {
+        const onSpeedChange = vi.fn();
+        const { container } = render(TimelineScrubber, {
+            props: { duration: 60, speed: 1, onSpeedChange }
+        });
+        const btn = container.querySelector('.timeline-scrubber__btn--speed');
+        await fireEvent.click(btn);
+        expect(onSpeedChange).toHaveBeenLastCalledWith(2);
+    });
+    it('speedLocked disables the speed button and surfaces the reason via title', () => {
+        const { container } = render(TimelineScrubber, {
+            props: {
+                duration: 60,
+                speed: 8,
+                speedLocked: true,
+                speedLockedReason: 'Video is playing'
+            }
+        });
+        const btn = container.querySelector('.timeline-scrubber__btn--speed');
+        expect(btn.disabled).toBe(true);
+        expect(btn.classList.contains('is-locked')).toBe(true);
+        expect(btn.getAttribute('title')).toContain('Video is playing');
+    });
+    it('clicking a locked speed button does NOT emit onSpeedChange', async () => {
+        const onSpeedChange = vi.fn();
+        const { container } = render(TimelineScrubber, {
+            props: { duration: 60, speed: 2, speedLocked: true, onSpeedChange }
+        });
+        const btn = container.querySelector('.timeline-scrubber__btn--speed');
+        await fireEvent.click(btn);
+        expect(onSpeedChange).not.toHaveBeenCalled();
+    });
+    it('uses the custom formatTime prop for both edge labels and the current-time readout', () => {
+        const formatTime = (s) => `[${Math.round(s)}s]`;
+        const { container } = render(TimelineScrubber, {
+            props: { duration: 120, currentTime: 42, formatTime }
+        });
+        const text = container.textContent ?? '';
+        expect(text).toContain('[0s]');
+        expect(text).toContain('[120s]');
+        expect(text).toContain('[42s]');
+    });
+});

package/dist/TimelineTrack.svelte

@@ -0,0 +1,376 @@
+<script lang="ts" module>
+	/**
+	 * 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;
+	}
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { onDestroy } from 'svelte';
+
+	// Low-level timeline primitive: a horizontal track with a movable playhead,
+	// optional view window (zoom range with draggable handles), optional
+	// segment overlays, and seek/hover/segment-click event callbacks.
+	//
+	// This component is unopinionated about playback — it doesn't know how
+	// currentTime changes, only how to display it and how to collect user
+	// seek/hover input. Pair with <TimelineScrubber> (which adds play/pause
+	// and speed) or drive directly from your own animation loop.
+	//
+	// Units are arbitrary (seconds, frames, steps) — TimelineTrack just works
+	// in the same unit you pass in as `duration`.
+	//
+	// See the package README for usage examples.
+
+	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;
+	}
+
+	let {
+		duration,
+		currentTime = $bindable(0),
+		viewWindow = $bindable(undefined),
+		segments = [],
+		showViewWindowHandles = true,
+		showPlayhead = true,
+		onSeek,
+		onViewWindowChange,
+		onSegmentClick,
+		onHover,
+		hoverIndicator,
+		class: className = ''
+	}: Props = $props();
+
+	let trackEl: HTMLDivElement | null = $state(null);
+	let dragging = $state<null | 'playhead' | 'window-start' | 'window-end'>(null);
+	let hoverX = $state<number | null>(null);
+
+	const effectiveStart = $derived(viewWindow?.start ?? 0);
+	const effectiveEnd = $derived(viewWindow?.end ?? duration);
+	const effectiveRange = $derived(Math.max(0.0001, effectiveEnd - effectiveStart));
+
+	function timeToPercent(t: number): number {
+		return ((t - effectiveStart) / effectiveRange) * 100;
+	}
+
+	function eventToTime(event: PointerEvent): number | null {
+		if (!trackEl) return null;
+		const rect = trackEl.getBoundingClientRect();
+		const x = event.clientX - rect.left;
+		const pct = Math.max(0, Math.min(1, x / rect.width));
+		return effectiveStart + pct * effectiveRange;
+	}
+
+	function eventToClientX(event: PointerEvent): number | null {
+		if (!trackEl) return null;
+		const rect = trackEl.getBoundingClientRect();
+		return Math.max(0, Math.min(rect.width, event.clientX - rect.left));
+	}
+
+	function handleTrackPointerDown(event: PointerEvent) {
+		// Ignore clicks on segment buttons / handles (they handle themselves).
+		if ((event.target as HTMLElement).closest('[data-skip-seek]')) return;
+
+		const time = eventToTime(event);
+		if (time === null) return;
+
+		currentTime = time;
+		onSeek?.(time);
+		dragging = 'playhead';
+		document.addEventListener('pointermove', handleDocPointerMove);
+		document.addEventListener('pointerup', handleDocPointerUp);
+	}
+
+	function handleDocPointerMove(event: PointerEvent) {
+		if (!dragging) return;
+		const time = eventToTime(event);
+		if (time === null) return;
+
+		if (dragging === 'playhead') {
+			currentTime = time;
+			onSeek?.(time);
+		} else if (dragging === 'window-start' && viewWindow) {
+			const next = {
+				start: Math.max(0, Math.min(viewWindow.end - 0.1, time)),
+				end: viewWindow.end
+			};
+			viewWindow = next;
+			onViewWindowChange?.(next);
+		} else if (dragging === 'window-end' && viewWindow) {
+			const next = {
+				start: viewWindow.start,
+				end: Math.min(duration, Math.max(viewWindow.start + 0.1, time))
+			};
+			viewWindow = next;
+			onViewWindowChange?.(next);
+		}
+	}
+
+	function handleDocPointerUp() {
+		dragging = null;
+		document.removeEventListener('pointermove', handleDocPointerMove);
+		document.removeEventListener('pointerup', handleDocPointerUp);
+	}
+
+	function handleHandlePointerDown(which: 'window-start' | 'window-end', event: PointerEvent) {
+		event.stopPropagation();
+		dragging = which;
+		document.addEventListener('pointermove', handleDocPointerMove);
+		document.addEventListener('pointerup', handleDocPointerUp);
+	}
+
+	function handleTrackPointerMove(event: PointerEvent) {
+		if (dragging) return;
+		const x = eventToClientX(event);
+		const time = eventToTime(event);
+		hoverX = x;
+		onHover?.(time);
+	}
+
+	function handleTrackPointerLeave() {
+		if (dragging) return;
+		hoverX = null;
+		onHover?.(null);
+	}
+
+	function handleSegmentClick(segment: TimelineSegment, event: MouseEvent) {
+		event.stopPropagation();
+		onSegmentClick?.(segment);
+	}
+
+	const hoveredTime = $derived.by(() => {
+		if (hoverX === null || !trackEl) return null;
+		const rect = trackEl.getBoundingClientRect();
+		const pct = Math.max(0, Math.min(1, hoverX / rect.width));
+		return effectiveStart + pct * effectiveRange;
+	});
+
+	onDestroy(() => {
+		if (typeof document !== 'undefined') {
+			document.removeEventListener('pointermove', handleDocPointerMove);
+			document.removeEventListener('pointerup', handleDocPointerUp);
+		}
+	});
+</script>
+
+<div
+	bind:this={trackEl}
+	class="timeline-track {className}"
+	class:is-dragging={dragging !== null}
+	onpointerdown={handleTrackPointerDown}
+	onpointermove={handleTrackPointerMove}
+	onpointerleave={handleTrackPointerLeave}
+	role="slider"
+	aria-valuemin={effectiveStart}
+	aria-valuemax={effectiveEnd}
+	aria-valuenow={currentTime}
+	tabindex="0"
+>
+	<div class="timeline-track__rail"></div>
+
+	{#each segments as segment (segment.id)}
+		{@const left = timeToPercent(segment.start)}
+		{@const width = timeToPercent(segment.end) - left}
+		{#if width > 0 && left < 100 && left + width > 0}
+			<button
+				type="button"
+				data-skip-seek
+				class="timeline-track__segment"
+				style:left="{Math.max(0, left)}%"
+				style:width="{Math.min(100, left + width) - Math.max(0, left)}%"
+				style:background-color={segment.color ??
+					'var(--timeline-segment-bg, rgba(59, 130, 246, 0.18))'}
+				title={segment.label ?? `${segment.start.toFixed(1)}–${segment.end.toFixed(1)}`}
+				onclick={(e) => handleSegmentClick(segment, e)}
+			>
+				{#if segment.label}<span class="timeline-track__segment-label">{segment.label}</span>{/if}
+			</button>
+		{/if}
+	{/each}
+
+	{#if viewWindow && showViewWindowHandles}
+		<div
+			data-skip-seek
+			class="timeline-track__handle timeline-track__handle--start"
+			style:left="0%"
+			onpointerdown={(e) => handleHandlePointerDown('window-start', e)}
+			role="slider"
+			aria-label="View window start"
+			aria-valuenow={viewWindow.start}
+			aria-valuemin={0}
+			aria-valuemax={viewWindow.end}
+			tabindex="0"
+		></div>
+		<div
+			data-skip-seek
+			class="timeline-track__handle timeline-track__handle--end"
+			style:left="100%"
+			onpointerdown={(e) => handleHandlePointerDown('window-end', e)}
+			role="slider"
+			aria-label="View window end"
+			aria-valuenow={viewWindow.end}
+			aria-valuemin={viewWindow.start}
+			aria-valuemax={duration}
+			tabindex="0"
+		></div>
+	{/if}
+
+	{#if showPlayhead}
+		<div
+			class="timeline-track__playhead"
+			style:left="{timeToPercent(currentTime)}%"
+			aria-hidden="true"
+		></div>
+	{/if}
+
+	{#if hoverIndicator && hoveredTime !== null && hoverX !== null}
+		<div
+			class="timeline-track__hover-indicator"
+			style:left="{timeToPercent(hoveredTime)}%"
+			aria-hidden="true"
+		>
+			{@render hoverIndicator({ time: hoveredTime, left: hoverX })}
+		</div>
+	{/if}
+</div>
+
+<style>
+	.timeline-track {
+		position: relative;
+		width: 100%;
+		height: var(--timeline-track-height, 32px);
+		user-select: none;
+		touch-action: none;
+		cursor: pointer;
+
+		--timeline-rail-bg: #e5e7eb;
+		--timeline-rail-height: 6px;
+		--timeline-playhead-color: #ef4444;
+		--timeline-playhead-width: 2px;
+		--timeline-handle-color: #6b7280;
+		--timeline-handle-width: 4px;
+	}
+
+	.timeline-track:focus-visible {
+		outline: 2px solid #3b82f6;
+		outline-offset: 2px;
+	}
+
+	.timeline-track__rail {
+		position: absolute;
+		top: 50%;
+		left: 0;
+		right: 0;
+		height: var(--timeline-rail-height);
+		transform: translateY(-50%);
+		background: var(--timeline-rail-bg);
+		border-radius: calc(var(--timeline-rail-height) / 2);
+		pointer-events: none;
+	}
+
+	.timeline-track__segment {
+		position: absolute;
+		top: 50%;
+		transform: translateY(-50%);
+		height: calc(var(--timeline-rail-height) + 6px);
+		padding: 0 4px;
+		border: none;
+		border-radius: 3px;
+		cursor: pointer;
+		font:
+			10px/1 system-ui,
+			sans-serif;
+		color: #1f2937;
+		overflow: hidden;
+		white-space: nowrap;
+	}
+
+	.timeline-track__segment:hover {
+		filter: brightness(0.92);
+	}
+
+	.timeline-track__segment-label {
+		opacity: 0.75;
+	}
+
+	.timeline-track__playhead {
+		position: absolute;
+		top: 15%;
+		bottom: 15%;
+		width: var(--timeline-playhead-width);
+		margin-left: calc(var(--timeline-playhead-width) / -2);
+		background: var(--timeline-playhead-color);
+		pointer-events: none;
+		border-radius: 1px;
+	}
+
+	.timeline-track__handle {
+		position: absolute;
+		top: 0;
+		bottom: 0;
+		width: 10px;
+		margin-left: -5px;
+		cursor: ew-resize;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.timeline-track__handle::before {
+		content: '';
+		display: block;
+		width: var(--timeline-handle-width);
+		height: 100%;
+		background: var(--timeline-handle-color);
+		border-radius: 2px;
+	}
+
+	.timeline-track__handle:focus-visible {
+		outline: 2px solid #3b82f6;
+		outline-offset: 2px;
+	}
+
+	.timeline-track__hover-indicator {
+		position: absolute;
+		bottom: 100%;
+		pointer-events: none;
+	}
+</style>