@classic-homes/theme-svelte 1.2.2 → 1.3.0

package/dist/lib/components/media/internal/MediaTile.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { MediaAspectRatio, MediaItem } from '../../../types/components.js';
+interface Props {
+    /** Item to represent */
+    item: MediaItem;
+    /** Zero-based position, used for the fallback accessible name */
+    index: number;
+    /** Aspect ratio of the tile. Omit to let the thumbnail set its own height. */
+    ratio?: MediaAspectRatio | number;
+    /** Marks the tile as the current item (carousel dots, thumbnail strips) */
+    selected?: boolean;
+    /** Participates in a roving tabindex container */
+    roving?: boolean;
+    /** Click and keyboard activation handler */
+    onselect?: (index: number) => void;
+    /** Additional classes */
+    class?: string;
+    /** Any other attribute is forwarded to the button (tabindex, data-*, …) */
+    [key: string]: unknown;
+}
+declare const MediaTile: import("svelte").Component<Props, {}, "">;
+type MediaTile = ReturnType<typeof MediaTile>;
+export default MediaTile;

package/dist/lib/composables/index.d.ts

@@ -32,3 +32,6 @@ export { useRovingTabindex, type UseRovingTabindexOptions } from './useRovingTab
 export { useAnnounce, type UseAnnounceOptions, type UseAnnounceReturn, } from './useAnnounce.svelte.js';
 export { useEscapeKey, type UseEscapeKeyOptions } from './useEscapeKey.svelte.js';
 export { useClickOutside, clickOutsideAction, type UseClickOutsideOptions, } from './useClickOutside.svelte.js';
+export { useMediaPlayer, type UseMediaPlayerOptions, type MediaPlayerApi, type MediaTimeRange, type MediaTrackInfo, } from './useMediaPlayer.svelte.js';
+export { useMediaZoom, type UseMediaZoomOptions, type MediaZoomApi, } from './useMediaZoom.svelte.js';
+export { useHlsSource, type UseHlsSourceOptions, type HlsSourceApi, type HlsStatus, } from './useHlsSource.svelte.js';

package/dist/lib/composables/index.js

@@ -35,3 +35,7 @@ export { useRovingTabindex } from './useRovingTabindex.svelte.js';
 export { useAnnounce, } from './useAnnounce.svelte.js';
 export { useEscapeKey } from './useEscapeKey.svelte.js';
 export { useClickOutside, clickOutsideAction, } from './useClickOutside.svelte.js';
+// Media composables
+export { useMediaPlayer, } from './useMediaPlayer.svelte.js';
+export { useMediaZoom, } from './useMediaZoom.svelte.js';
+export { useHlsSource, } from './useHlsSource.svelte.js';

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

@@ -0,0 +1,70 @@
+/**
+ * Composable that plays an HLS stream through a media element.
+ *
+ * Safari and iOS play HLS natively, in which case the playlist is simply set
+ * as the element's source. Everywhere else this attaches `hls.js`, which is an
+ * optional peer dependency — see `utils/hls.ts` for how to provide it.
+ *
+ * Used by `Video` for Cloudflare Stream and any other HLS source. Exported so
+ * applications can build their own players on the same behaviour.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useHlsSource } from '@classic-homes/theme-svelte';
+ *
+ *   let el = $state<HTMLVideoElement | null>(null);
+ *   const hls = useHlsSource(() => el, { src: () => streamUrl });
+ * </script>
+ *
+ * <video bind:this={el}></video>
+ * {#if hls.status === 'unsupported'}
+ *   <p>This browser needs hls.js to play adaptive streams.</p>
+ * {/if}
+ * ```
+ */
+import { type HlsLoader } from '../utils/hls.js';
+/** How the stream is currently being played. */
+export type HlsStatus = 'idle' | 'loading' | 'native' | 'attached'
+/** hls.js is needed but was neither registered nor supported */
+ | 'unsupported' | 'error';
+/** Options accepted by {@link useHlsSource}. */
+export interface UseHlsSourceOptions {
+    /**
+     * The HLS playlist to play, or `null` when the current source is not HLS.
+     * A getter, so the stream can change without re-creating the composable.
+     */
+    src: () => string | null;
+    /**
+     * Per-instance `hls.js` loader, overriding any globally registered one.
+     * A getter, matching `src`, so a prop-supplied loader stays reactive.
+     */
+    loader?: () => HlsLoader | undefined;
+    /** Extra hls.js configuration */
+    config?: () => Record<string, unknown> | undefined;
+    /**
+     * Whether to start downloading as soon as the stream is attached
+     * (default `true`).
+     *
+     * hls.js fetches through its own loader, so it ignores the media element's
+     * `preload` attribute. Pass `false` to mirror `preload="none"` and hold off
+     * until {@link HlsSourceApi.startLoad} is called.
+     */
+    autoStartLoad?: () => boolean;
+    /** Called when the stream cannot be played */
+    onError?: (error: Error) => void;
+}
+/** Reactive state returned by {@link useHlsSource}. */
+export interface HlsSourceApi {
+    readonly status: HlsStatus;
+    /** True when the browser is playing HLS without hls.js */
+    readonly native: boolean;
+    /** Last fatal error, if any */
+    readonly error: Error | null;
+    /**
+     * Begin downloading when `autoStartLoad` was disabled. Safe to call more
+     * than once, and a no-op on the native path.
+     */
+    startLoad(): void;
+}
+export declare function useHlsSource(getElement: () => HTMLMediaElement | null | undefined, options: UseHlsSourceOptions): HlsSourceApi;

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

@@ -0,0 +1,119 @@
+/**
+ * Composable that plays an HLS stream through a media element.
+ *
+ * Safari and iOS play HLS natively, in which case the playlist is simply set
+ * as the element's source. Everywhere else this attaches `hls.js`, which is an
+ * optional peer dependency — see `utils/hls.ts` for how to provide it.
+ *
+ * Used by `Video` for Cloudflare Stream and any other HLS source. Exported so
+ * applications can build their own players on the same behaviour.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useHlsSource } from '@classic-homes/theme-svelte';
+ *
+ *   let el = $state<HTMLVideoElement | null>(null);
+ *   const hls = useHlsSource(() => el, { src: () => streamUrl });
+ * </script>
+ *
+ * <video bind:this={el}></video>
+ * {#if hls.status === 'unsupported'}
+ *   <p>This browser needs hls.js to play adaptive streams.</p>
+ * {/if}
+ * ```
+ */
+import { canPlayHlsNatively, loadHls, } from '../utils/hls.js';
+export function useHlsSource(getElement, options) {
+    let status = $state('idle');
+    let error = $state(null);
+    // Held outside the effect so startLoad() can reach the live instance, and so
+    // a call that arrives while hls.js is still loading is not dropped.
+    let current = null;
+    let loadRequested = false;
+    $effect(() => {
+        const media = getElement();
+        const src = options.src();
+        if (!media || !src) {
+            status = 'idle';
+            return;
+        }
+        error = null;
+        // Native playback needs no library; hand the playlist straight over.
+        if (canPlayHlsNatively(media)) {
+            media.src = src;
+            status = 'native';
+            return () => {
+                media.removeAttribute('src');
+                media.load();
+            };
+        }
+        status = 'loading';
+        // The effect cannot await, so track cancellation explicitly: the source
+        // may change or the component unmount while hls.js is still loading.
+        let cancelled = false;
+        let instance = null;
+        const autoStartLoad = options.autoStartLoad?.() ?? true;
+        const config = { autoStartLoad, ...options.config?.() };
+        loadRequested = autoStartLoad;
+        loadHls(options.loader?.()).then((Hls) => {
+            if (cancelled)
+                return;
+            if (!Hls || !Hls.isSupported()) {
+                status = 'unsupported';
+                const failure = new Error('Playing an HLS stream in this browser requires hls.js. Install it and register a loader: setHlsLoader(() => import("hls.js").then((m) => m.default)).');
+                error = failure;
+                options.onError?.(failure);
+                return;
+            }
+            instance = new Hls(config);
+            instance.on(Hls.Events.ERROR, (_event, data) => {
+                if (!data?.fatal)
+                    return;
+                // hls.js can recover from network and media errors; only a fatal
+                // error of another type is truly terminal.
+                if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
+                    instance?.startLoad();
+                    return;
+                }
+                if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
+                    instance?.recoverMediaError();
+                    return;
+                }
+                status = 'error';
+                const failure = new Error(`HLS playback failed: ${data.details ?? 'unknown error'}`);
+                error = failure;
+                options.onError?.(failure);
+            });
+            instance.loadSource(src);
+            instance.attachMedia(media);
+            current = instance;
+            status = 'attached';
+            // A play request that arrived while hls.js was still loading.
+            if (loadRequested && !autoStartLoad)
+                instance.startLoad();
+        });
+        return () => {
+            cancelled = true;
+            instance?.destroy();
+            instance = null;
+            current = null;
+        };
+    });
+    function startLoad() {
+        loadRequested = true;
+        current?.startLoad();
+    }
+    return {
+        get status() {
+            return status;
+        },
+        get native() {
+            return status === 'native';
+        },
+        get error() {
+            return error;
+        },
+        startLoad,
+    };
+}

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

@@ -0,0 +1,114 @@
+/**
+ * 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>
+ * ```
+ */
+/** A buffered or seekable range, in seconds. */
+export interface MediaTimeRange {
+    start: number;
+    end: number;
+}
+/** A text track exposed to the captions menu. */
+export interface MediaTrackInfo {
+    index: number;
+    label: string;
+    language: string;
+    kind: string;
+    active: boolean;
+}
+/**
+ * Options accepted by {@link useMediaPlayer}.
+ *
+ * `volume` and `muted` are getters so they stay reactive — a plain value would
+ * be captured once when the composable is called and never follow the prop.
+ */
+export interface UseMediaPlayerOptions {
+    /** Volume, 0–1 (default `1`) */
+    volume?: () => number;
+    /** Whether the media is muted (default `false`) */
+    muted?: () => boolean;
+    /** Called when playback reaches the end */
+    onEnded?: () => void;
+    /** Called when the element reports an error */
+    onError?: (error: MediaError | null) => void;
+    /** Called on every `timeupdate` with the current time in seconds */
+    onTimeUpdate?: (currentTime: number) => void;
+}
+/** Reactive state and commands returned by {@link useMediaPlayer}. */
+export interface MediaPlayerApi {
+    readonly element: HTMLMediaElement | null;
+    readonly playing: boolean;
+    readonly paused: boolean;
+    readonly ended: boolean;
+    readonly currentTime: number;
+    readonly duration: number;
+    /** Playback progress as a fraction, 0–1 */
+    readonly progress: number;
+    readonly buffered: MediaTimeRange[];
+    /** How much of the media is buffered ahead of the playhead, as a fraction 0–1 */
+    readonly bufferedProgress: number;
+    readonly volume: number;
+    readonly muted: boolean;
+    readonly playbackRate: number;
+    /**
+     * True while the element has reported that it is stalled.
+     *
+     * Prefer {@link MediaPlayerApi.buffering} for showing a spinner: browsers
+     * emit `waiting` on paused elements too, where it means nothing to the
+     * viewer.
+     */
+    readonly waiting: boolean;
+    /**
+     * True only while playback is actually held up waiting for data.
+     *
+     * A paused player is never buffering, however many `waiting` events the
+     * browser emits.
+     */
+    readonly buffering: boolean;
+    /** True until metadata (and therefore duration) is known */
+    readonly loading: boolean;
+    readonly error: MediaError | null;
+    readonly fullscreen: boolean;
+    readonly pip: boolean;
+    readonly textTracks: MediaTrackInfo[];
+    /** Index of the showing text track, or `null` when captions are off */
+    readonly activeTextTrack: number | null;
+    play(): Promise<void>;
+    pause(): void;
+    toggle(): Promise<void>;
+    seek(seconds: number): void;
+    seekBy(delta: number): void;
+    /** Seek to a fraction of the duration, 0–1 */
+    seekToFraction(fraction: number): void;
+    setVolume(volume: number): void;
+    adjustVolume(delta: number): void;
+    toggleMute(): void;
+    setPlaybackRate(rate: number): void;
+    toggleFullscreen(container?: HTMLElement | null): Promise<void>;
+    togglePictureInPicture(): Promise<void>;
+    /** Show one text track, or pass `null` to turn captions off */
+    setTextTrack(index: number | null): void;
+    toggleCaptions(): void;
+}
+export declare function useMediaPlayer(getElement: () => HTMLMediaElement | null | undefined, options?: UseMediaPlayerOptions): MediaPlayerApi;