@classic-homes/theme-svelte 1.2.3 → 1.3.0

package/dist/lib/composables/useMediaPlayer.svelte.js

@@ -0,0 +1,422 @@
+/**
+ * Composable that mirrors an `HTMLMediaElement`'s state into runes and exposes
+ * imperative playback commands.
+ *
+ * Drives both `Video` and `Audio`, and is exported so applications can build
+ * their own player chrome on top of the same behaviour.
+ *
+ * The element is passed as a getter rather than a value, because the element
+ * does not exist on the first call — `bind:this` populates it after mount.
+ * Reading it inside the effect keeps the subscription reactive.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMediaPlayer } from '@classic-homes/theme-svelte';
+ *
+ *   let el = $state<HTMLVideoElement | null>(null);
+ *   const player = useMediaPlayer(() => el);
+ * </script>
+ *
+ * <video bind:this={el} src="/clip.mp4"></video>
+ * <button onclick={() => player.toggle()}>
+ *   {player.playing ? 'Pause' : 'Play'}
+ * </button>
+ * ```
+ */
+import { clamp, timeRangesToArray } from '../utils/media.js';
+export function useMediaPlayer(getElement, options = {}) {
+    let element = $state(null);
+    let playing = $state(false);
+    let paused = $state(true);
+    let ended = $state(false);
+    let currentTime = $state(0);
+    let duration = $state(0);
+    let buffered = $state([]);
+    let volume = $state(1);
+    let muted = $state(false);
+    let playbackRate = $state(1);
+    let waiting = $state(false);
+    let loading = $state(true);
+    let error = $state(null);
+    let fullscreen = $state(false);
+    let pip = $state(false);
+    let textTracks = $state([]);
+    let activeTextTrack = $state(null);
+    function readTextTracks(media) {
+        const list = media.textTracks;
+        const tracks = [];
+        let active = null;
+        for (let i = 0; i < list.length; i += 1) {
+            const track = list[i];
+            // `metadata` and `chapters` tracks are not user-facing captions
+            if (track.kind !== 'subtitles' && track.kind !== 'captions')
+                continue;
+            const isActive = track.mode === 'showing';
+            if (isActive)
+                active = i;
+            tracks.push({
+                index: i,
+                label: track.label || track.language || `Track ${i + 1}`,
+                language: track.language,
+                kind: track.kind,
+                active: isActive,
+            });
+        }
+        textTracks = tracks;
+        activeTextTrack = active;
+    }
+    $effect(() => {
+        const media = getElement();
+        if (!media) {
+            element = null;
+            return;
+        }
+        element = media;
+        const syncTime = () => {
+            currentTime = media.currentTime;
+            options.onTimeUpdate?.(media.currentTime);
+        };
+        const syncDuration = () => {
+            duration = Number.isFinite(media.duration) ? media.duration : 0;
+            loading = false;
+            readTextTracks(media);
+        };
+        const syncBuffered = () => {
+            buffered = timeRangesToArray(media.buffered);
+        };
+        const syncVolume = () => {
+            volume = media.volume;
+            muted = media.muted;
+        };
+        const handlePlay = () => {
+            playing = true;
+            paused = false;
+            ended = false;
+        };
+        const handlePause = () => {
+            playing = false;
+            paused = true;
+            // A paused element is not buffering, whatever it reported a moment ago.
+            waiting = false;
+        };
+        const handleEnded = () => {
+            playing = false;
+            paused = true;
+            ended = true;
+            waiting = false;
+            options.onEnded?.();
+        };
+        const handleWaiting = () => {
+            waiting = true;
+        };
+        const handlePlaying = () => {
+            waiting = false;
+            playing = true;
+            paused = false;
+        };
+        /**
+         * Any event that means the element has enough data again clears the stall.
+         * Listening only for `playing` leaves a paused element stuck reporting a
+         * stall forever, because `playing` never fires until playback resumes.
+         */
+        const handleReady = () => {
+            waiting = false;
+        };
+        const handleError = () => {
+            error = media.error;
+            loading = false;
+            waiting = false;
+            options.onError?.(media.error);
+        };
+        const handleRateChange = () => {
+            playbackRate = media.playbackRate;
+        };
+        const handleSeeking = () => {
+            currentTime = media.currentTime;
+        };
+        const handleFullscreenChange = () => {
+            fullscreen = document.fullscreenElement !== null;
+        };
+        const handleEnterPip = () => {
+            pip = true;
+        };
+        const handleLeavePip = () => {
+            pip = false;
+        };
+        const handleTrackChange = () => readTextTracks(media);
+        media.addEventListener('timeupdate', syncTime);
+        media.addEventListener('durationchange', syncDuration);
+        media.addEventListener('loadedmetadata', syncDuration);
+        media.addEventListener('progress', syncBuffered);
+        media.addEventListener('volumechange', syncVolume);
+        media.addEventListener('play', handlePlay);
+        media.addEventListener('pause', handlePause);
+        media.addEventListener('ended', handleEnded);
+        media.addEventListener('waiting', handleWaiting);
+        media.addEventListener('playing', handlePlaying);
+        media.addEventListener('canplay', handleReady);
+        media.addEventListener('canplaythrough', handleReady);
+        media.addEventListener('loadeddata', handleReady);
+        media.addEventListener('error', handleError);
+        media.addEventListener('ratechange', handleRateChange);
+        media.addEventListener('seeking', handleSeeking);
+        media.addEventListener('seeked', handleSeeking);
+        media.addEventListener('enterpictureinpicture', handleEnterPip);
+        media.addEventListener('leavepictureinpicture', handleLeavePip);
+        media.textTracks?.addEventListener?.('change', handleTrackChange);
+        document.addEventListener('fullscreenchange', handleFullscreenChange);
+        // The element may already be past these events when the effect runs
+        // (cached media, or an `autoplay` that resolved during hydration).
+        syncVolume();
+        syncBuffered();
+        if (media.readyState >= 1)
+            syncDuration();
+        paused = media.paused;
+        if (!media.paused)
+            handlePlay();
+        return () => {
+            media.removeEventListener('timeupdate', syncTime);
+            media.removeEventListener('durationchange', syncDuration);
+            media.removeEventListener('loadedmetadata', syncDuration);
+            media.removeEventListener('progress', syncBuffered);
+            media.removeEventListener('volumechange', syncVolume);
+            media.removeEventListener('play', handlePlay);
+            media.removeEventListener('pause', handlePause);
+            media.removeEventListener('ended', handleEnded);
+            media.removeEventListener('waiting', handleWaiting);
+            media.removeEventListener('playing', handlePlaying);
+            media.removeEventListener('canplay', handleReady);
+            media.removeEventListener('canplaythrough', handleReady);
+            media.removeEventListener('loadeddata', handleReady);
+            media.removeEventListener('error', handleError);
+            media.removeEventListener('ratechange', handleRateChange);
+            media.removeEventListener('seeking', handleSeeking);
+            media.removeEventListener('seeked', handleSeeking);
+            media.removeEventListener('enterpictureinpicture', handleEnterPip);
+            media.removeEventListener('leavepictureinpicture', handleLeavePip);
+            media.textTracks?.removeEventListener?.('change', handleTrackChange);
+            document.removeEventListener('fullscreenchange', handleFullscreenChange);
+        };
+    });
+    // Volume and mute live in their own effect so changing them does not tear
+    // down and re-register every media listener.
+    $effect(() => {
+        const media = getElement();
+        if (!media)
+            return;
+        const nextVolume = options.volume?.();
+        if (nextVolume !== undefined)
+            media.volume = clamp(nextVolume, 0, 1);
+        const nextMuted = options.muted?.();
+        if (nextMuted !== undefined)
+            media.muted = nextMuted;
+    });
+    async function play() {
+        const media = getElement();
+        if (!media)
+            return;
+        try {
+            await media.play();
+        }
+        catch (err) {
+            // A play() promise rejects when autoplay is blocked, or when the call is
+            // superseded by a pause(). Neither is an error worth surfacing.
+            if (err instanceof DOMException &&
+                (err.name === 'AbortError' || err.name === 'NotAllowedError')) {
+                return;
+            }
+            throw err;
+        }
+    }
+    function pause() {
+        getElement()?.pause();
+    }
+    async function toggle() {
+        const media = getElement();
+        if (!media)
+            return;
+        if (media.paused)
+            await play();
+        else
+            media.pause();
+    }
+    function seek(seconds) {
+        const media = getElement();
+        if (!media)
+            return;
+        const max = Number.isFinite(media.duration) ? media.duration : seconds;
+        media.currentTime = clamp(seconds, 0, max);
+        currentTime = media.currentTime;
+    }
+    function seekBy(delta) {
+        const media = getElement();
+        if (!media)
+            return;
+        seek(media.currentTime + delta);
+    }
+    function seekToFraction(fraction) {
+        const media = getElement();
+        if (!media || !Number.isFinite(media.duration))
+            return;
+        seek(clamp(fraction, 0, 1) * media.duration);
+    }
+    function setVolume(next) {
+        const media = getElement();
+        if (!media)
+            return;
+        media.volume = clamp(next, 0, 1);
+        // Raising the volume from a muted state should unmute, matching how
+        // native players and YouTube behave.
+        if (media.volume > 0 && media.muted)
+            media.muted = false;
+    }
+    function adjustVolume(delta) {
+        const media = getElement();
+        if (!media)
+            return;
+        setVolume(media.volume + delta);
+    }
+    function toggleMute() {
+        const media = getElement();
+        if (!media)
+            return;
+        media.muted = !media.muted;
+    }
+    function setPlaybackRate(rate) {
+        const media = getElement();
+        if (!media)
+            return;
+        media.playbackRate = rate;
+    }
+    async function toggleFullscreen(container) {
+        const target = container ?? getElement();
+        if (!target)
+            return;
+        if (document.fullscreenElement) {
+            await document.exitFullscreen();
+            return;
+        }
+        if (typeof target.requestFullscreen === 'function') {
+            await target.requestFullscreen();
+            return;
+        }
+        // iOS Safari exposes fullscreen only on the video element itself.
+        const media = getElement();
+        media?.webkitEnterFullscreen?.();
+    }
+    async function togglePictureInPicture() {
+        const media = getElement();
+        if (!media || !(media instanceof HTMLVideoElement))
+            return;
+        if (!document.pictureInPictureEnabled)
+            return;
+        if (document.pictureInPictureElement) {
+            await document.exitPictureInPicture();
+        }
+        else {
+            await media.requestPictureInPicture();
+        }
+    }
+    function setTextTrack(index) {
+        const media = getElement();
+        if (!media)
+            return;
+        for (let i = 0; i < media.textTracks.length; i += 1) {
+            const track = media.textTracks[i];
+            if (track.kind !== 'subtitles' && track.kind !== 'captions')
+                continue;
+            track.mode = i === index ? 'showing' : 'disabled';
+        }
+        readTextTracks(media);
+    }
+    function toggleCaptions() {
+        if (activeTextTrack !== null) {
+            setTextTrack(null);
+        }
+        else if (textTracks.length > 0) {
+            setTextTrack(textTracks[0].index);
+        }
+    }
+    return {
+        get element() {
+            return element;
+        },
+        get playing() {
+            return playing;
+        },
+        get paused() {
+            return paused;
+        },
+        get ended() {
+            return ended;
+        },
+        get currentTime() {
+            return currentTime;
+        },
+        get duration() {
+            return duration;
+        },
+        get progress() {
+            return duration > 0 ? clamp(currentTime / duration, 0, 1) : 0;
+        },
+        get buffered() {
+            return buffered;
+        },
+        get bufferedProgress() {
+            if (duration <= 0)
+                return 0;
+            // Only the range containing the playhead matters for the scrub bar.
+            const active = buffered.find((r) => r.start <= currentTime && r.end >= currentTime);
+            const end = active?.end ?? (buffered.length > 0 ? buffered[buffered.length - 1].end : 0);
+            return clamp(end / duration, 0, 1);
+        },
+        get volume() {
+            return volume;
+        },
+        get muted() {
+            return muted;
+        },
+        get playbackRate() {
+            return playbackRate;
+        },
+        get waiting() {
+            return waiting;
+        },
+        get buffering() {
+            return waiting && !paused;
+        },
+        get loading() {
+            return loading;
+        },
+        get error() {
+            return error;
+        },
+        get fullscreen() {
+            return fullscreen;
+        },
+        get pip() {
+            return pip;
+        },
+        get textTracks() {
+            return textTracks;
+        },
+        get activeTextTrack() {
+            return activeTextTrack;
+        },
+        play,
+        pause,
+        toggle,
+        seek,
+        seekBy,
+        seekToFraction,
+        setVolume,
+        adjustVolume,
+        toggleMute,
+        setPlaybackRate,
+        toggleFullscreen,
+        togglePictureInPicture,
+        setTextTrack,
+        toggleCaptions,
+    };
+}

package/dist/lib/composables/useMediaZoom.svelte.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Composable providing zoom and pan for a single element, used by the
+ * Lightbox image viewer.
+ *
+ * Deliberately avoids `setPointerCapture`: capturing on a container swallows
+ * click events destined for buttons rendered over it, which would break the
+ * lightbox close and navigation controls. Dragging is tracked with plain
+ * pointer events plus an explicit pointer-id check instead.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMediaZoom } from '@classic-homes/theme-svelte';
+ *
+ *   const zoom = useMediaZoom();
+ * </script>
+ *
+ * <div use:zoom.action class="overflow-hidden">
+ *   <img src={src} alt={alt} style={zoom.transform} />
+ * </div>
+ * ```
+ */
+/** Options accepted by {@link useMediaZoom}. */
+export interface UseMediaZoomOptions {
+    /** Smallest allowed scale (default `1`) */
+    minScale?: number;
+    /** Largest allowed scale (default `4`) */
+    maxScale?: number;
+    /** Multiplier applied by the zoom-in and zoom-out commands (default `1.5`) */
+    step?: number;
+    /** Scale jumped to by a double-click or double-tap (default `2.5`) */
+    doubleTapScale?: number;
+    /** Called whenever the scale changes */
+    onScaleChange?: (scale: number) => void;
+}
+/** Reactive state and commands returned by {@link useMediaZoom}. */
+export interface MediaZoomApi {
+    readonly scale: number;
+    readonly x: number;
+    readonly y: number;
+    /** True while the user is dragging the content */
+    readonly panning: boolean;
+    /** True when the content is zoomed in past its natural size */
+    readonly zoomed: boolean;
+    /** Ready-to-use CSS `transform` value */
+    readonly transform: string;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Reset scale and offset back to their defaults */
+    reset(): void;
+    /** Toggle between reset and the double-tap scale */
+    toggle(): void;
+    panBy(dx: number, dy: number): void;
+    /** Svelte action applied to the element that should receive gestures */
+    action(node: HTMLElement): {
+        destroy(): void;
+    };
+}
+export declare function useMediaZoom(options?: UseMediaZoomOptions): MediaZoomApi;

package/dist/lib/composables/useMediaZoom.svelte.js

@@ -0,0 +1,199 @@
+/**
+ * Composable providing zoom and pan for a single element, used by the
+ * Lightbox image viewer.
+ *
+ * Deliberately avoids `setPointerCapture`: capturing on a container swallows
+ * click events destined for buttons rendered over it, which would break the
+ * lightbox close and navigation controls. Dragging is tracked with plain
+ * pointer events plus an explicit pointer-id check instead.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMediaZoom } from '@classic-homes/theme-svelte';
+ *
+ *   const zoom = useMediaZoom();
+ * </script>
+ *
+ * <div use:zoom.action class="overflow-hidden">
+ *   <img src={src} alt={alt} style={zoom.transform} />
+ * </div>
+ * ```
+ */
+import { clamp } from '../utils/media.js';
+export function useMediaZoom(options = {}) {
+    // Plain locals: only read imperatively from event handlers, never tracked
+    const minScale = options.minScale ?? 1;
+    const maxScale = options.maxScale ?? 4;
+    const step = options.step ?? 1.5;
+    const doubleTapScale = options.doubleTapScale ?? 2.5;
+    const onScaleChange = options.onScaleChange;
+    let scale = $state(1);
+    let x = $state(0);
+    let y = $state(0);
+    let panning = $state(false);
+    /** Active pointers, so a two-finger pinch can be measured. */
+    const pointers = new Map();
+    let dragPointerId = null;
+    let dragOrigin = { x: 0, y: 0, offsetX: 0, offsetY: 0 };
+    let pinchStartDistance = 0;
+    let pinchStartScale = 1;
+    function setScale(next) {
+        const clamped = clamp(next, minScale, maxScale);
+        if (clamped === scale)
+            return;
+        scale = clamped;
+        if (clamped === minScale) {
+            x = 0;
+            y = 0;
+        }
+        onScaleChange?.(clamped);
+    }
+    function zoomIn() {
+        setScale(scale * step);
+    }
+    function zoomOut() {
+        setScale(scale / step);
+    }
+    function reset() {
+        x = 0;
+        y = 0;
+        if (scale !== 1) {
+            scale = 1;
+            onScaleChange?.(1);
+        }
+    }
+    function toggle() {
+        if (scale > minScale)
+            reset();
+        else
+            setScale(doubleTapScale);
+    }
+    function panBy(dx, dy) {
+        if (scale <= minScale)
+            return;
+        x += dx;
+        y += dy;
+    }
+    function distanceBetweenPointers() {
+        const [a, b] = [...pointers.values()];
+        if (!a || !b)
+            return 0;
+        return Math.hypot(a.x - b.x, a.y - b.y);
+    }
+    function action(node) {
+        let lastTapTime = 0;
+        function handlePointerDown(event) {
+            pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+            if (pointers.size === 2) {
+                pinchStartDistance = distanceBetweenPointers();
+                pinchStartScale = scale;
+                dragPointerId = null;
+                panning = false;
+                return;
+            }
+            if (scale > minScale) {
+                dragPointerId = event.pointerId;
+                panning = true;
+                dragOrigin = { x: event.clientX, y: event.clientY, offsetX: x, offsetY: y };
+            }
+        }
+        function handlePointerMove(event) {
+            if (!pointers.has(event.pointerId))
+                return;
+            pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+            if (pointers.size === 2 && pinchStartDistance > 0) {
+                event.preventDefault();
+                const ratio = distanceBetweenPointers() / pinchStartDistance;
+                setScale(pinchStartScale * ratio);
+                return;
+            }
+            if (dragPointerId !== event.pointerId || !panning)
+                return;
+            event.preventDefault();
+            x = dragOrigin.offsetX + (event.clientX - dragOrigin.x);
+            y = dragOrigin.offsetY + (event.clientY - dragOrigin.y);
+        }
+        function endPointer(event) {
+            pointers.delete(event.pointerId);
+            if (dragPointerId === event.pointerId) {
+                dragPointerId = null;
+                panning = false;
+            }
+            if (pointers.size < 2)
+                pinchStartDistance = 0;
+        }
+        function handleWheel(event) {
+            // Only intercept deliberate zoom gestures; a plain wheel should still
+            // scroll whatever is underneath.
+            if (!event.ctrlKey && !event.metaKey && scale === minScale)
+                return;
+            event.preventDefault();
+            setScale(scale * (event.deltaY < 0 ? 1.1 : 1 / 1.1));
+        }
+        function handleDoubleClick(event) {
+            event.preventDefault();
+            toggle();
+        }
+        /** Touch devices do not fire dblclick, so tap timing is measured directly. */
+        function handlePointerUpTap(event) {
+            if (event.pointerType !== 'touch')
+                return;
+            const now = event.timeStamp;
+            if (now - lastTapTime < 300) {
+                toggle();
+                lastTapTime = 0;
+            }
+            else {
+                lastTapTime = now;
+            }
+        }
+        node.addEventListener('pointerdown', handlePointerDown);
+        node.addEventListener('pointermove', handlePointerMove);
+        node.addEventListener('pointerup', endPointer);
+        node.addEventListener('pointerup', handlePointerUpTap);
+        node.addEventListener('pointercancel', endPointer);
+        node.addEventListener('pointerleave', endPointer);
+        node.addEventListener('wheel', handleWheel, { passive: false });
+        node.addEventListener('dblclick', handleDoubleClick);
+        return {
+            destroy() {
+                node.removeEventListener('pointerdown', handlePointerDown);
+                node.removeEventListener('pointermove', handlePointerMove);
+                node.removeEventListener('pointerup', endPointer);
+                node.removeEventListener('pointerup', handlePointerUpTap);
+                node.removeEventListener('pointercancel', endPointer);
+                node.removeEventListener('pointerleave', endPointer);
+                node.removeEventListener('wheel', handleWheel);
+                node.removeEventListener('dblclick', handleDoubleClick);
+                pointers.clear();
+            },
+        };
+    }
+    return {
+        get scale() {
+            return scale;
+        },
+        get x() {
+            return x;
+        },
+        get y() {
+            return y;
+        },
+        get panning() {
+            return panning;
+        },
+        get zoomed() {
+            return scale > minScale;
+        },
+        get transform() {
+            return `translate(${x}px, ${y}px) scale(${scale})`;
+        },
+        zoomIn,
+        zoomOut,
+        reset,
+        toggle,
+        panBy,
+        action,
+    };
+}