@juspay/svelte-ui-components 4.1.2 → 4.2.0

package/dist/MediaPlayer/MediaPlayer.svelte

@@ -5,6 +5,9 @@
   import pauseSvg from '../assets/pause.svg?raw';
   import volumeSvg from '../assets/volume.svg?raw';
   import muteSvg from '../assets/mute.svg?raw';
+  import fullscreenSvg from '../assets/fullscreen.svg?raw';
+  import exitFullscreenSvg from '../assets/exit-fullscreen.svg?raw';
+  import Slider from '../Slider/Slider.svelte';
   import type { MediaPlayerProperties } from './properties';
 
   let {
@@ -24,14 +27,62 @@
     captionsSrc,
     captionsLabel,
     captionsSrcLang,
+    seekBar = false,
+    timeDisplay = false,
+    fullscreenButton = false,
+    fullscreenIcon,
+    exitFullscreenIcon,
+    currentTime = $bindable(0),
+    duration = $bindable(0),
     onplay,
     onpause,
     onvolumechange,
+    onseek,
+    ontimeupdate,
+    onfullscreenchange,
     testId,
     classes
   }: MediaPlayerProperties = $props();
 
+  // HTMLMediaElement.HAVE_METADATA. Named rather than inlined as 1, because `readyState >= 1`
+  // at a call site reads like a truthiness check rather than a specific media state.
+  const HAVE_METADATA = 1;
+  // Below one frame at 60fps: small enough that a real host write always clears it, large
+  // enough that float drift between the element's clock and the bound copy does not.
+  const SEEK_EPSILON = 0.01;
+  // The last position this component wrote to `currentTime`; see the sync effect below.
+  let syncedTime = 0;
+  // A host write that arrived before the element could accept it; applied once metadata is.
+  let pendingSeek: number | null = null;
+
   let videoPlayer: HTMLVideoElement | null = $state(null);
+  let container: HTMLDivElement | null = $state(null);
+  let isFullscreen = $state(false);
+
+  // Any of the three new controls puts something in the bottom row beyond the mute
+  // button, which is what decides whether that row needs to lay out as a bar.
+  const hasTransportRow = $derived(seekBar || timeDisplay || fullscreenButton);
+
+  /**
+   * `m:ss`, widening to `h:mm:ss` only once the media actually runs past an hour, so a
+   * 40-second clip does not read `0:00:40`. A media element reports NaN for duration
+   * until metadata arrives and Infinity for an open-ended stream; both format as `--:--`
+   * rather than leaking the raw value into the UI.
+   */
+  function formatTime(seconds: number): string {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+      return '--:--';
+    }
+    const whole = Math.floor(seconds);
+    const hours = Math.floor(whole / 3600);
+    const minutes = Math.floor((whole % 3600) / 60);
+    const secs = whole % 60;
+    const padded = secs.toString().padStart(2, '0');
+    if (hours > 0) {
+      return `${hours}:${minutes.toString().padStart(2, '0')}:${padded}`;
+    }
+    return `${minutes}:${padded}`;
+  }
 
   function togglePlayback(): void {
     if (videoPlayer === null) {
@@ -83,9 +134,158 @@
       togglePlayback();
     }
   }
+
+  function handleTimeUpdate(): void {
+    if (videoPlayer === null) {
+      return;
+    }
+    currentTime = videoPlayer.currentTime;
+    syncedTime = currentTime;
+    ontimeupdate?.(currentTime, duration);
+  }
+
+  function handleLoadedMetadata(): void {
+    if (videoPlayer === null) {
+      return;
+    }
+    duration = Number.isFinite(videoPlayer.duration) ? videoPlayer.duration : 0;
+  }
+
+  // `loadedmetadata` is a one-shot event, and a cached or fast-loading file reaches
+  // HAVE_METADATA before hydration attaches the handler above -- measured, not supposed:
+  // the element reported readyState 4 and duration 4 while the component still held 0.
+  // Nothing fires it again, so a seek bar and clock that only listened would stay dead
+  // for exactly the media that loaded well. Adopting what the element already knows when
+  // it binds covers that case; the handler covers the slower one.
+  // eslint-disable-next-line no-restricted-syntax
+  $effect(() => {
+    if (videoPlayer === null || videoPlayer.readyState < HAVE_METADATA) {
+      return;
+    }
+    if (duration === 0 && Number.isFinite(videoPlayer.duration)) {
+      duration = videoPlayer.duration;
+    }
+    if (pendingSeek !== null) {
+      const length = duration > 0 ? duration : videoPlayer.duration;
+      const clamped = Number.isFinite(length)
+        ? Math.min(Math.max(pendingSeek, 0), length)
+        : Math.max(pendingSeek, 0);
+      pendingSeek = null;
+      syncedTime = clamped;
+      currentTime = clamped;
+      videoPlayer.currentTime = clamped;
+    }
+  });
+
+  /**
+   * `currentTime` is bindable in both directions. Playback and scrubbing push outward
+   * through the two functions above; this carries a host's own write inward, which is
+   * what makes restoring a saved position work rather than merely look bound.
+   *
+   * `syncedTime` is a plain `let`, not `$state`, so writing it here does not re-run this
+   * effect. Without that, every outward update would read back as an inward one and the
+   * element would be re-seeked to the position it just reported -- a feedback loop that
+   * stutters playback. Comparing against it means only a value this component did not
+   * itself produce counts as a host write. `onseek` deliberately does not fire: a host
+   * restoring a position is not a user scrubbing.
+   */
+  // eslint-disable-next-line no-restricted-syntax
+  $effect(() => {
+    const requested = currentTime;
+    if (videoPlayer === null || Math.abs(requested - syncedTime) < SEEK_EPSILON) {
+      return;
+    }
+    // Before HAVE_METADATA the element has no timeline to seek within: the length is
+    // unknown, so the value cannot be clamped, and assigning currentTime is specified to
+    // set a default start position rather than seek -- and throws outright in some
+    // engines. Hold it and apply it when metadata arrives, which is the moment a restored
+    // position becomes meaningful anyway.
+    if (videoPlayer.readyState < HAVE_METADATA) {
+      pendingSeek = requested;
+      return;
+    }
+    const clamped =
+      duration > 0 ? Math.min(Math.max(requested, 0), duration) : Math.max(requested, 0);
+    syncedTime = clamped;
+    videoPlayer.currentTime = clamped;
+  });
+
+  /**
+   * Seeking writes the element directly rather than waiting for the bound value to
+   * settle, so a drag scrubs while the pointer is still down. `onseek` fires only from
+   * here, which is what separates a deliberate scrub from playback advancing on its own.
+   */
+  function handleSeek(value: number): void {
+    if (videoPlayer === null || duration <= 0) {
+      return;
+    }
+    const clamped = Math.min(Math.max(value, 0), duration);
+    videoPlayer.currentTime = clamped;
+    currentTime = clamped;
+    syncedTime = clamped;
+    onseek?.(clamped);
+  }
+
+  /**
+   * The fullscreen element as seen from wherever this component actually lives. In the
+   * web-component build the container sits inside a shadow root, and `document`
+   * retargets `fullscreenElement` to the host (`<sui-media-player>`), never the container
+   * itself -- so a plain document check reads false while genuinely fullscreen, leaving
+   * the icon stuck and `onfullscreenchange` silent. A ShadowRoot exposes the same
+   * accessor scoped to its own tree, which does resolve to the container.
+   */
+  function activeFullscreenElement(): Element | null {
+    const root = container?.getRootNode();
+    if (root instanceof ShadowRoot) {
+      return root.fullscreenElement;
+    }
+    return document.fullscreenElement;
+  }
+
+  /**
+   * Fullscreen is requested on the container, not the `<video>`. A fullscreen video
+   * element paints over everything, taking the overlay's play, mute and seek controls
+   * with it; the container keeps them on top of the media where they are usable.
+   */
+  async function toggleFullscreen(): Promise<void> {
+    if (container === null) {
+      return;
+    }
+    try {
+      if (activeFullscreenElement() === null) {
+        await container.requestFullscreen();
+      } else {
+        await document.exitFullscreen();
+      }
+    } catch {
+      // A rejected request (denied by the browser, or no user gesture behind it) leaves
+      // the player exactly as it was. `fullscreenchange` never fires, so `isFullscreen`
+      // still describes reality and the button still offers the action that failed.
+    }
+  }
+
+  // The only reliable signal for leaving fullscreen is the document's own event: Escape
+  // and the browser's chrome both exit without going through the button above.
+  // eslint-disable-next-line no-restricted-syntax
+  $effect(() => {
+    function syncFullscreen(): void {
+      const nowFullscreen = container !== null && activeFullscreenElement() === container;
+      if (nowFullscreen !== isFullscreen) {
+        isFullscreen = nowFullscreen;
+        onfullscreenchange?.(nowFullscreen);
+      }
+    }
+    document.addEventListener('fullscreenchange', syncFullscreen);
+    return () => document.removeEventListener('fullscreenchange', syncFullscreen);
+  });
 </script>
 
-<div class="media-player {classes ?? ''}" data-pw={typeof testId === 'string' ? testId : null}>
+<div
+  bind:this={container}
+  class="media-player {classes ?? ''}"
+  class:fullscreen={isFullscreen}
+  data-pw={typeof testId === 'string' ? testId : null}
+>
   {#if type === 'image'}
     <span class="media-image">
       <Img {src} {alt} {fallback} />
@@ -100,8 +300,11 @@
       {autoplay}
       {loop}
       playsinline
+      preload={hasTransportRow ? 'metadata' : null}
       onplay={handlePlay}
       onpause={handlePause}
+      ontimeupdate={handleTimeUpdate}
+      onloadedmetadata={handleLoadedMetadata}
       onclick={controls ? null : togglePlayback}
       onkeydown={controls ? null : handleVideoKeydown}
       role={controls ? null : 'button'}
@@ -139,7 +342,26 @@
             </Button>
           </div>
         </div>
-        <div class="bottom-controls">
+        <div class="bottom-controls" class:transport={hasTransportRow}>
+          {#if seekBar}
+            <div class="seek" data-pw={typeof testId === 'string' ? `${testId}-seek` : null}>
+              <Slider
+                value={currentTime}
+                min={0}
+                max={duration > 0 ? duration : 1}
+                step={0.1}
+                disabled={duration <= 0}
+                oninput={handleSeek}
+                onchange={handleSeek}
+                ariaLabel="Seek"
+              />
+            </div>
+          {/if}
+          {#if timeDisplay}
+            <span class="time" data-pw={typeof testId === 'string' ? `${testId}-time` : null}>
+              {formatTime(currentTime)} / {formatTime(duration)}
+            </span>
+          {/if}
           <div class="control bottom-control">
             <Button onclick={toggleMute} ariaLabel={muted ? 'Unmute' : 'Mute'}>
               {#if muted}
@@ -157,6 +379,31 @@
               {/if}
             </Button>
           </div>
+          {#if fullscreenButton}
+            <div
+              class="control bottom-control"
+              data-pw={typeof testId === 'string' ? `${testId}-fullscreen` : null}
+            >
+              <Button
+                onclick={toggleFullscreen}
+                ariaLabel={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+              >
+                {#if isFullscreen}
+                  {#if typeof exitFullscreenIcon === 'function'}
+                    {@render exitFullscreenIcon()}
+                  {:else}
+                    <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+                    {@html exitFullscreenSvg}
+                  {/if}
+                {:else if typeof fullscreenIcon === 'function'}
+                  {@render fullscreenIcon()}
+                {:else}
+                  <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+                  {@html fullscreenSvg}
+                {/if}
+              </Button>
+            </div>
+          {/if}
         </div>
       </div>
     {/if}
@@ -241,6 +488,44 @@
     visibility: var(--bottom-controls-visibility);
   }
 
+  /* With a seek bar, time or fullscreen present the row becomes a transport bar: the
+     seek bar takes the free space and the rest sit beside it, centred on each other. */
+  .bottom-controls.transport {
+    justify-content: var(--media-player-transport-justify, flex-start);
+    align-items: center;
+    gap: var(--media-player-transport-gap, 12px);
+  }
+
+  .seek {
+    flex: 1;
+    min-width: 0;
+    --slider-track-color: var(--media-player-seek-track-color, #ffffff59);
+    --slider-fill-color: var(--media-player-seek-fill-color, #ffffff);
+    --slider-thumb-color: var(--media-player-seek-thumb-color, #ffffff);
+  }
+
+  .time {
+    flex-shrink: 0;
+    font-family: var(--media-player-time-font-family, inherit);
+    font-size: var(--media-player-time-font-size, 12px);
+    font-variant-numeric: tabular-nums;
+    color: var(--media-player-time-color, #ffffff);
+    white-space: nowrap;
+  }
+
+  /* In fullscreen the container is the fullscreen element, so it must fill the screen
+     rather than keep the fixed height a page layout gave it. */
+  .media-player.fullscreen {
+    height: 100%;
+    width: 100%;
+    background: var(--media-player-fullscreen-background, #000000);
+  }
+
+  .media-player.fullscreen .media {
+    height: 100%;
+    width: 100%;
+  }
+
   .control {
     --button-padding: var(--media-player-control-padding, 0px);
     --button-border: var(--media-player-control-border, none);

package/dist/MediaPlayer/MediaPlayer.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { MediaPlayerProperties } from './properties';
-declare const MediaPlayer: import("svelte").Component<MediaPlayerProperties, {}, "playing" | "muted">;
+declare const MediaPlayer: import("svelte").Component<MediaPlayerProperties, {}, "duration" | "playing" | "muted" | "currentTime">;
 type MediaPlayer = ReturnType<typeof MediaPlayer>;
 export default MediaPlayer;

package/dist/MediaPlayer/properties.d.ts

@@ -24,6 +24,42 @@ export type OptionalMediaPlayerProperties = {
     captionsLabel?: string;
     /** BCP 47 language tag for the captions track, e.g. "en". Only meaningful with captionsSrc. */
     captionsSrcLang?: string;
+    /**
+     * Render a seek bar in the bottom controls. Video only. The bar is a library
+     * `Slider` bound to the media's position, so dragging it scrubs and playback
+     * moves the handle. Off by default: a player that was showing only play and mute
+     * keeps showing only play and mute.
+     *
+     * Turning any of the three on also sets `preload="metadata"` on the media, because a
+     * seek bar and a clock are unusable until the length is known and a paused player is
+     * not otherwise obliged to fetch it.
+     */
+    seekBar?: boolean;
+    /**
+     * Render elapsed and total time beside the controls, as `m:ss`, or `h:mm:ss` once
+     * the media runs past an hour. Video only, off by default.
+     */
+    timeDisplay?: boolean;
+    /**
+     * Render a button that takes the player in and out of fullscreen. Video only, off
+     * by default. Fullscreen is requested on the player's own container rather than on
+     * the `<video>`, so the overlay controls stay usable while fullscreen.
+     */
+    fullscreenButton?: boolean;
+    /** Replaces the default icon on the fullscreen button while not fullscreen. */
+    fullscreenIcon?: Snippet;
+    /** Replaces the default icon on the fullscreen button while fullscreen. */
+    exitFullscreenIcon?: Snippet;
+    /**
+     * Playback position in seconds. Bindable, and writable: setting it seeks, which is
+     * how a host can restore a saved position or drive its own scrubber.
+     */
+    currentTime?: number;
+    /**
+     * Media length in seconds, 0 until metadata loads. Bindable for reading; writing it
+     * does not resize the media.
+     */
+    duration?: number;
     testId?: string;
     classes?: string;
 };
@@ -31,4 +67,14 @@ export type MediaPlayerEventProperties = {
     onplay?: (event: Event) => void;
     onpause?: (event: Event) => void;
     onvolumechange?: (muted: boolean) => void;
+    /**
+     * The viewer moved the seek bar. Carries the position seeked to, in seconds.
+     * Fires only for a deliberate scrub, not for playback advancing on its own —
+     * `ontimeupdate` is the one that fires continuously.
+     */
+    onseek?: (currentTime: number) => void;
+    /** Playback position advanced. Carries the position and the length, both in seconds. */
+    ontimeupdate?: (currentTime: number, duration: number) => void;
+    /** The player entered or left fullscreen. Carries the state it is now in. */
+    onfullscreenchange?: (isFullscreen: boolean) => void;
 };

package/dist/Slider/Slider.svelte

@@ -9,6 +9,7 @@
     disabled = false,
     showValue = false,
     labelFormatter,
+    ariaLabel,
     testId,
     onchange,
     oninput,
@@ -42,6 +43,7 @@
     {step}
     {value}
     {disabled}
+    aria-label={typeof ariaLabel === 'string' ? ariaLabel : null}
     data-pw={typeof testId === 'string' ? testId : null}
     testID={typeof testId === 'string' ? testId : null}
     oninput={handleInput}

package/dist/Slider/properties.d.ts

@@ -9,6 +9,11 @@ export type OptionalSliderProperties = {
     disabled?: boolean;
     showValue?: boolean;
     labelFormatter?: (value: number) => string;
+    /**
+     * Names the range input for assistive tech. A bare slider announces only its value,
+     * so a control whose purpose is not carried by adjacent visible text needs this.
+     */
+    ariaLabel?: string;
     testId?: string;
     classes?: string;
 };

package/dist/assets/exit-fullscreen.svg

@@ -0,0 +1,6 @@
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <path d="M9 4v3.5A1.5 1.5 0 0 1 7.5 9H4" />
+  <path d="M20 9h-3.5A1.5 1.5 0 0 1 15 7.5V4" />
+  <path d="M15 20v-3.5a1.5 1.5 0 0 1 1.5-1.5H20" />
+  <path d="M4 15h3.5A1.5 1.5 0 0 1 9 16.5V20" />
+</svg>

package/dist/assets/fullscreen.svg

@@ -0,0 +1,6 @@
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <path d="M4 9V5.5A1.5 1.5 0 0 1 5.5 4H9" />
+  <path d="M15 4h3.5A1.5 1.5 0 0 1 20 5.5V9" />
+  <path d="M20 15v3.5a1.5 1.5 0 0 1-1.5 1.5H15" />
+  <path d="M9 20H5.5A1.5 1.5 0 0 1 4 18.5V15" />
+</svg>