@classic-homes/theme-svelte 1.2.2 → 1.3.0

package/dist/lib/components/media/Video.svelte

@@ -0,0 +1,455 @@
+<script lang="ts">
+  /**
+   * Video - Video player with themed controls
+   *
+   * Features:
+   * - Custom control bar: play/pause, seek, volume, speed, captions, PiP, fullscreen
+   * - Full keyboard control (Space/K, arrows, J/L, M, F, C, Home/End, 0-9)
+   * - Controls auto-hide during playback and stay visible while paused or focused
+   * - Buffering spinner and an inline error state with retry
+   * - Honours `prefers-reduced-motion` by never fading the controls away
+   *
+   * @example
+   * ```svelte
+   * <Video
+   *   src="/clip.mp4"
+   *   poster="/clip.jpg"
+   *   label="Product walkthrough"
+   *   tracks={[{ src: '/clip.en.vtt', srclang: 'en', label: 'English', default: true }]}
+   * />
+   * ```
+   */
+  import type { Snippet } from 'svelte';
+  import { useHlsSource } from '../../composables/useHlsSource.svelte.js';
+  import { useMediaPlayer } from '../../composables/useMediaPlayer.svelte.js';
+  import { useReducedMotion } from '../../composables/useReducedMotion.svelte.js';
+  import type {
+    MediaAspectRatio,
+    MediaFit,
+    MediaSource,
+    MediaTextTrack,
+    VideoMediaItem,
+  } from '../../types/components.js';
+  import { cn } from '../../utils.js';
+  import type { HlsLoader } from '../../utils/hls.js';
+  import { isHlsSource, resolveAspectRatio, toMediaSources } from '../../utils/media.js';
+  import Icon from '../Icon.svelte';
+  import Spinner from '../Spinner.svelte';
+  import MediaControls from './internal/MediaControls.svelte';
+
+  /** How long the controls stay up after the last pointer movement */
+  const CONTROLS_HIDE_DELAY = 3000;
+
+  interface Props {
+    /**
+     * A video media item supplying `src`, `poster`, `tracks`, and the label.
+     * Individual props still win when both are given.
+     *
+     * Pairs with `cloudflareStream()` to play a Cloudflare Stream video.
+     */
+    item?: VideoMediaItem;
+    /** A single URL, or several sources for format fallback */
+    src?: string | MediaSource[];
+    /** Poster image shown before playback starts */
+    poster?: string;
+    /** Caption and subtitle tracks — required for WCAG 1.2.2 on recorded content */
+    tracks?: MediaTextTrack[];
+    /** Accessible name for the player region */
+    label?: string;
+    /** Constrain the player to an aspect ratio (default `video`) */
+    ratio?: MediaAspectRatio | number | null;
+    /** How the video fills its box */
+    fit?: MediaFit;
+    /** Start playing automatically — requires `muted`, and browsers may still refuse */
+    autoplay?: boolean;
+    /** Start muted */
+    muted?: boolean;
+    /** Loop playback */
+    loop?: boolean;
+    /** Initial volume, 0–1 */
+    volume?: number;
+    /** How much to preload (default `metadata`, enough for duration without fetching the file) */
+    preload?: 'none' | 'metadata' | 'auto';
+    /** Hide the control bar entirely — the player is then keyboard-only */
+    hideControls?: boolean;
+    /** Show the picture-in-picture button */
+    showPictureInPicture?: boolean;
+    /** Show the fullscreen button */
+    showFullscreen?: boolean;
+    /** Called when playback ends */
+    onEnded?: () => void;
+    /** Called on each time update, with seconds elapsed */
+    onTimeUpdate?: (currentTime: number) => void;
+    /**
+     * How to load `hls.js` for this player, overriding any loader registered
+     * with `setHlsLoader`. Only consulted for HLS sources in browsers without
+     * native HLS support.
+     *
+     * @example hlsLoader={() => import('hls.js').then((m) => m.default)}
+     */
+    hlsLoader?: HlsLoader;
+    /** Extra hls.js configuration */
+    hlsConfig?: Record<string, unknown>;
+    /** Content overlaid on the video, above the controls */
+    overlay?: Snippet;
+    /** Additional classes for the player container */
+    class?: string;
+  }
+
+  let {
+    item,
+    src,
+    poster,
+    tracks,
+    label,
+    ratio = 'video',
+    fit = 'contain',
+    autoplay = false,
+    muted = false,
+    loop = false,
+    volume = 1,
+    preload = 'metadata',
+    hideControls = false,
+    showPictureInPicture = true,
+    showFullscreen = true,
+    onEnded,
+    onTimeUpdate,
+    hlsLoader,
+    hlsConfig,
+    overlay,
+    class: className,
+  }: Props = $props();
+
+  let videoElement = $state<HTMLVideoElement | null>(null);
+  let container = $state<HTMLDivElement | null>(null);
+  let pointerActive = $state(false);
+  let hideTimer: ReturnType<typeof setTimeout> | undefined;
+
+  // Explicit props win over the item, so a single field can be overridden
+  // without unpacking the whole thing.
+  const resolvedSrc = $derived(src ?? item?.src ?? []);
+  const resolvedPoster = $derived(poster ?? item?.poster);
+  const resolvedTracks = $derived(tracks ?? item?.tracks ?? []);
+  const resolvedLabel = $derived(label ?? item?.title ?? 'Video player');
+
+  const reducedMotion = useReducedMotion();
+  const player = useMediaPlayer(() => videoElement, {
+    volume: () => volume,
+    // Autoplay is only permitted while muted, so requesting it implies muting.
+    muted: () => muted || autoplay,
+    onEnded: () => onEnded?.(),
+    onTimeUpdate: (currentTime) => onTimeUpdate?.(currentTime),
+  });
+
+  const sources = $derived(toMediaSources(resolvedSrc));
+  const hlsSource = $derived(sources.find((source) => isHlsSource(source)) ?? null);
+
+  const hls = useHlsSource(() => videoElement, {
+    src: () => hlsSource?.src ?? null,
+    loader: () => hlsLoader,
+    config: () => hlsConfig,
+    // hls.js downloads through its own loader and ignores the element's
+    // `preload`, so mirror it here or a `preload="none"` stream would still
+    // pull segments the moment it mounts.
+    autoStartLoad: () => preload !== 'none',
+  });
+
+  /** Play, first releasing the stream loader when `preload="none"` held it back. */
+  function requestPlay() {
+    hls.startLoad();
+    return player.play();
+  }
+
+  function togglePlayback() {
+    if (player.paused) return requestPlay();
+    return player.toggle();
+  }
+
+  /**
+   * An HLS playlist is only rendered as a `<source>` when the browser can
+   * play it natively. Everywhere else hls.js sets the element's source, and
+   * leaving a `<source>` the browser cannot decode would make it report an
+   * error before hls.js ever attaches.
+   */
+  const elementSources = $derived(
+    hlsSource && !hls.native ? sources.filter((source) => !isHlsSource(source)) : sources
+  );
+
+  /** hls.js is required but unavailable, and there is no other playable source. */
+  const hlsUnavailable = $derived(
+    hlsSource !== null &&
+      (hls.status === 'unsupported' || hls.status === 'error') &&
+      elementSources.length === 0
+  );
+
+  // Controls stay up unless the video is actually playing and the pointer has
+  // gone idle. Keyboard users never lose them, because `focus-within` on the
+  // container keeps `pointerActive` irrelevant while focus is inside.
+  const controlsVisible = $derived(!player.playing || pointerActive || player.buffering);
+
+  const fitClass = $derived(
+    (
+      {
+        cover: 'object-cover',
+        contain: 'object-contain',
+        fill: 'object-fill',
+        none: 'object-none',
+        'scale-down': 'object-scale-down',
+      } as const
+    )[fit]
+  );
+
+  function scheduleHide() {
+    clearTimeout(hideTimer);
+    pointerActive = true;
+    hideTimer = setTimeout(() => {
+      pointerActive = false;
+    }, CONTROLS_HIDE_DELAY);
+  }
+
+  function handlePointerLeave() {
+    clearTimeout(hideTimer);
+    pointerActive = false;
+  }
+
+  $effect(() => () => clearTimeout(hideTimer));
+
+  /** Typing in a field inside the overlay must not be swallowed as a shortcut. */
+  function isTextEntry(target: EventTarget | null): boolean {
+    if (!(target instanceof HTMLElement)) return false;
+    return (
+      target.isContentEditable ||
+      ['INPUT', 'TEXTAREA', 'SELECT'].includes(target.tagName) ||
+      // The Bits UI slider thumb has its own arrow-key handling.
+      target.getAttribute('role') === 'slider'
+    );
+  }
+
+  function handleKeyDown(event: KeyboardEvent) {
+    if (isTextEntry(event.target) || event.metaKey || event.ctrlKey || event.altKey) return;
+
+    scheduleHide();
+
+    switch (event.key) {
+      case ' ':
+      case 'k':
+      case 'K':
+        event.preventDefault();
+        togglePlayback();
+        break;
+      case 'ArrowLeft':
+        event.preventDefault();
+        player.seekBy(-5);
+        break;
+      case 'ArrowRight':
+        event.preventDefault();
+        player.seekBy(5);
+        break;
+      case 'j':
+      case 'J':
+        event.preventDefault();
+        player.seekBy(-10);
+        break;
+      case 'l':
+      case 'L':
+        event.preventDefault();
+        player.seekBy(10);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        player.adjustVolume(0.1);
+        break;
+      case 'ArrowDown':
+        event.preventDefault();
+        player.adjustVolume(-0.1);
+        break;
+      case 'm':
+      case 'M':
+        event.preventDefault();
+        player.toggleMute();
+        break;
+      case 'f':
+      case 'F':
+        if (!showFullscreen) return;
+        event.preventDefault();
+        player.toggleFullscreen(container);
+        break;
+      case 'c':
+      case 'C':
+        event.preventDefault();
+        player.toggleCaptions();
+        break;
+      case 'Home':
+        event.preventDefault();
+        player.seek(0);
+        break;
+      case 'End':
+        event.preventDefault();
+        player.seek(player.duration);
+        break;
+      default:
+        if (/^[0-9]$/.test(event.key)) {
+          event.preventDefault();
+          player.seekToFraction(Number(event.key) / 10);
+        }
+    }
+  }
+
+  function retry() {
+    videoElement?.load();
+  }
+
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+    $effect(() => {
+      // HLS carries its own subtitle tracks inside the playlist, so an empty
+      // `tracks` prop is expected and not a captions failure there.
+      if (resolvedTracks.length === 0 && !hlsSource) {
+        console.warn(
+          'Video: No caption tracks provided. Pre-recorded video needs captions to meet WCAG 1.2.2 — pass `tracks` with at least one WebVTT file.'
+        );
+      }
+      if (hls.status === 'unsupported') {
+        console.warn(
+          'Video: This browser cannot play HLS natively and no hls.js loader is available. Install hls.js and call setHlsLoader(() => import("hls.js").then((m) => m.default)) once at app startup, or pass an `hlsLoader` prop.'
+        );
+      }
+      if (autoplay && !muted) {
+        console.warn(
+          'Video: `autoplay` without `muted` is blocked by every major browser. Set `muted` as well, or drop `autoplay`.'
+        );
+      }
+    });
+  }
+</script>
+
+<!--
+  The container is the keyboard target and the fullscreen element. Player
+  shortcuts are bound here rather than on <video>, so they work while focus is
+  on any control inside.
+-->
+<!--
+  `tabindex="0"` is deliberate: the player region has to be reachable so the
+  playback shortcuts below work, which is the pattern the WAI media player
+  guidance calls for.
+-->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div
+  bind:this={container}
+  role="region"
+  aria-label={resolvedLabel}
+  tabindex="0"
+  class={cn(
+    'group/player relative isolate flex w-full flex-col overflow-hidden rounded-lg bg-black outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    className
+  )}
+  style={ratio ? `aspect-ratio: ${resolveAspectRatio(ratio)}` : undefined}
+  onkeydown={handleKeyDown}
+  onpointermove={scheduleHide}
+  onpointerdown={scheduleHide}
+  onpointerleave={handlePointerLeave}
+>
+  <!-- svelte-ignore a11y_media_has_caption -- tracks are supplied via the `tracks` prop -->
+  <video
+    bind:this={videoElement}
+    class={cn('h-full w-full', fitClass)}
+    poster={resolvedPoster}
+    {autoplay}
+    {loop}
+    muted={muted || autoplay}
+    {preload}
+    playsinline
+    controls={false}
+    onclick={() => togglePlayback()}
+  >
+    {#each elementSources as source (source.src)}
+      <source src={source.src} type={source.type} />
+    {/each}
+    {#each resolvedTracks as track (track.src)}
+      <track
+        src={track.src}
+        kind={track.kind ?? 'subtitles'}
+        srclang={track.srclang}
+        label={track.label}
+        default={track.default}
+      />
+    {/each}
+    Your browser does not support embedded video.
+  </video>
+
+  {#if hlsUnavailable}
+    <div
+      class="absolute inset-0 z-20 flex flex-col items-center justify-center gap-2 bg-black/80 p-6 text-center text-white"
+      role="alert"
+    >
+      <Icon name="video" size={32} />
+      <p class="text-sm">This browser cannot play adaptive streams.</p>
+      <p class="max-w-sm text-xs text-white/70">
+        Playing HLS outside Safari needs hls.js. Install it and register a loader once at app
+        startup.
+      </p>
+    </div>
+  {:else if player.error}
+    <div
+      class="absolute inset-0 z-20 flex flex-col items-center justify-center gap-3 bg-black/80 p-6 text-center text-white"
+      role="alert"
+    >
+      <Icon name="video" size={32} />
+      <p class="text-sm">This video could not be played.</p>
+      <button
+        type="button"
+        class="rounded-md bg-white/15 px-3 py-1.5 text-sm font-medium hover:bg-white/25 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
+        onclick={retry}
+      >
+        Try again
+      </button>
+    </div>
+  {:else}
+    {#if player.buffering}
+      <div class="pointer-events-none absolute inset-0 z-10 flex items-center justify-center">
+        <Spinner size="lg" class="text-white" />
+      </div>
+    {:else if !player.playing && (player.currentTime === 0 || player.ended)}
+      <button
+        type="button"
+        class="absolute inset-0 z-10 flex items-center justify-center bg-black/20 outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-white"
+        onclick={() => requestPlay()}
+        aria-label={player.ended ? 'Replay video' : 'Play video'}
+      >
+        <span
+          class="flex h-16 w-16 items-center justify-center rounded-full bg-black/60 text-white shadow-lg"
+        >
+          <Icon name="play" size={32} />
+        </span>
+      </button>
+    {/if}
+
+    {#if overlay}
+      {@render overlay()}
+    {/if}
+
+    {#if !hideControls}
+      <div
+        class={cn(
+          'absolute inset-x-0 bottom-0 z-20',
+          // Reduced motion keeps the bar permanently visible rather than fading it.
+          reducedMotion.value
+            ? ''
+            : cn(
+                'transition-opacity duration-200 focus-within:opacity-100',
+                controlsVisible ? 'opacity-100' : 'opacity-0'
+              )
+        )}
+      >
+        <MediaControls
+          {player}
+          variant="video"
+          {showPictureInPicture}
+          {showFullscreen}
+          fullscreenTarget={container}
+          onTogglePlay={togglePlayback}
+        />
+      </div>
+    {/if}
+  {/if}
+</div>

package/dist/lib/components/media/Video.svelte.d.ts

@@ -0,0 +1,81 @@
+/**
+   * Video - Video player with themed controls
+   *
+   * Features:
+   * - Custom control bar: play/pause, seek, volume, speed, captions, PiP, fullscreen
+   * - Full keyboard control (Space/K, arrows, J/L, M, F, C, Home/End, 0-9)
+   * - Controls auto-hide during playback and stay visible while paused or focused
+   * - Buffering spinner and an inline error state with retry
+   * - Honours `prefers-reduced-motion` by never fading the controls away
+   *
+   * @example
+   * ```svelte
+   * <Video
+   *   src="/clip.mp4"
+   *   poster="/clip.jpg"
+   *   label="Product walkthrough"
+   *   tracks={[{ src: '/clip.en.vtt', srclang: 'en', label: 'English', default: true }]}
+   * />
+   * ```
+   */
+import type { Snippet } from 'svelte';
+import type { MediaAspectRatio, MediaFit, MediaSource, MediaTextTrack, VideoMediaItem } from '../../types/components.js';
+import type { HlsLoader } from '../../utils/hls.js';
+interface Props {
+    /**
+     * A video media item supplying `src`, `poster`, `tracks`, and the label.
+     * Individual props still win when both are given.
+     *
+     * Pairs with `cloudflareStream()` to play a Cloudflare Stream video.
+     */
+    item?: VideoMediaItem;
+    /** A single URL, or several sources for format fallback */
+    src?: string | MediaSource[];
+    /** Poster image shown before playback starts */
+    poster?: string;
+    /** Caption and subtitle tracks — required for WCAG 1.2.2 on recorded content */
+    tracks?: MediaTextTrack[];
+    /** Accessible name for the player region */
+    label?: string;
+    /** Constrain the player to an aspect ratio (default `video`) */
+    ratio?: MediaAspectRatio | number | null;
+    /** How the video fills its box */
+    fit?: MediaFit;
+    /** Start playing automatically — requires `muted`, and browsers may still refuse */
+    autoplay?: boolean;
+    /** Start muted */
+    muted?: boolean;
+    /** Loop playback */
+    loop?: boolean;
+    /** Initial volume, 0–1 */
+    volume?: number;
+    /** How much to preload (default `metadata`, enough for duration without fetching the file) */
+    preload?: 'none' | 'metadata' | 'auto';
+    /** Hide the control bar entirely — the player is then keyboard-only */
+    hideControls?: boolean;
+    /** Show the picture-in-picture button */
+    showPictureInPicture?: boolean;
+    /** Show the fullscreen button */
+    showFullscreen?: boolean;
+    /** Called when playback ends */
+    onEnded?: () => void;
+    /** Called on each time update, with seconds elapsed */
+    onTimeUpdate?: (currentTime: number) => void;
+    /**
+     * How to load `hls.js` for this player, overriding any loader registered
+     * with `setHlsLoader`. Only consulted for HLS sources in browsers without
+     * native HLS support.
+     *
+     * @example hlsLoader={() => import('hls.js').then((m) => m.default)}
+     */
+    hlsLoader?: HlsLoader;
+    /** Extra hls.js configuration */
+    hlsConfig?: Record<string, unknown>;
+    /** Content overlaid on the video, above the controls */
+    overlay?: Snippet;
+    /** Additional classes for the player container */
+    class?: string;
+}
+declare const Video: import("svelte").Component<Props, {}, "">;
+type Video = ReturnType<typeof Video>;
+export default Video;

package/dist/lib/components/media/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Media Components
+ *
+ * Presentation components for images, video, audio, and third-party embeds,
+ * plus collection views and a full-screen lightbox.
+ */
+export { default as AspectRatio } from './AspectRatio.svelte';
+export { default as Image } from './Image.svelte';
+export { default as Video } from './Video.svelte';
+export { default as Audio } from './Audio.svelte';
+export { default as MediaEmbed } from './MediaEmbed.svelte';
+export { default as MediaGrid } from './MediaGrid.svelte';
+export { default as MediaCarousel } from './MediaCarousel.svelte';
+export { default as Lightbox } from './Lightbox.svelte';

package/dist/lib/components/media/index.js

@@ -0,0 +1,14 @@
+/**
+ * Media Components
+ *
+ * Presentation components for images, video, audio, and third-party embeds,
+ * plus collection views and a full-screen lightbox.
+ */
+export { default as AspectRatio } from './AspectRatio.svelte';
+export { default as Image } from './Image.svelte';
+export { default as Video } from './Video.svelte';
+export { default as Audio } from './Audio.svelte';
+export { default as MediaEmbed } from './MediaEmbed.svelte';
+export { default as MediaGrid } from './MediaGrid.svelte';
+export { default as MediaCarousel } from './MediaCarousel.svelte';
+export { default as Lightbox } from './Lightbox.svelte';